Module riot_coap_handler_demos::ping

Available on crate feature ping only.

An implementation of Ping, with focus on using little RAM and producing output suitable to a (possibly polling, especially for lack of implemented observations) data retreival method.

This works on a static list of potential pingings (always 4, to be configurable when const generic defaults are usable in RIOT’s used nightly).

This is losely based on the sc_gnrc_icmpv6_echo implementation in RIOT.

Usage

When registered under /ping (see ping_tree help for why this is essential right now unfortunately), send POST requests with an address to /ping/, fetch from the indicated location with GET, and remove the obtained data with DELETE to free up resources again:

$ aiocoap-client 'coap://[2001:db8::1]/ping/' -m POST --content-format 0 --payload 2001:db8::2
Location options indicate new resource: /ping/47
$ aiocoap-client 'coap://[2001:db8::1]/ping/47' --accept 0
Pinging 2001:db8::2. Sending 19 of 20, received 19.
$ aiocoap-client 'coap://[2001:db8::1]/ping/47' -m DELETE

Pings do not measure time (apart from marking a packet as “late” if it’s more than 16 seconds behind), and are not configurable in terms of ping interval (which is currently 1 second independent of the arrival of any packets).

Rough plans for extensibility include logging of delay as minimum (possibly with time stamps from the network interface), average and maximum (all of which can be done in constant space), finer granularity of time reporting (the current API only measures times in numbers packets sent between then and now), reporting in user-defined bins, and retention of responding addresses (useful in multicast pings). Possibly, those would be mutually exclusive to keep space small (eg. you can get a list of address-count pairs or a fine-grained histogram). Further extensions could also set the TTL, or vary it across pings for effectively a traceroute (which would best be combined with the return address retention already proposed for multicast).

Interface

In CoAP resource discovery, a resource behaving like this can be recognized by the interface type if=tag:chrysn@fsfe.org,2024-09-16:ping. Any such resource can receive POSTs with content-format application/cbor containing a single IP address (possibly with zone identifier) tagged 54.

A successful POST gives the location of the ping job, which should be DELETEd when not used.

The job’s status can be received in content format application/cbor, whose CDDL is roughly

;# include rfc9164
job = [address, stop_after, stats]
stats = [sent, latest, seen, repeats_in_time, later]

address = ip-address-or-prefix ; Target IP address
stop_after = uint              ; Number of pings to be sent in total

sent = uint                    ; Number of requests that have been sent
latest = uint                  ; 16-bit bitfield where the LSB indicates that the most recently
                               ; sent request was received (at most `sent` bits are set)
seen = uint                    ; Number of responses that have been received in time (this is
                               ; always at last as many as there are bits in latest, and more
                               ; more than 16 requests have been sent)
repeat = uint                  ; Number of duplicates received in time
later = uint                   ; Number of responses or duplicates that arrived too late

Compatible updates to this interface can happen by including items in the top or inner arrays; incompatible updates will use a different interface description.

Structs

• PingCallback
  Wrapper around a [&'static PingPool] that is not constructed publicly, but used as part of the type required to pass in to PingPool::register().
• PingJob 🔒
• PingPool
  Container for a number of ping jobs
• PingPoolView 🔒
  A view on a PingPool that, when encoded through minicbor, gives bare CRI reference links
• PingStats 🔒

Enums

• Accept 🔒

Constants

• FORMAT_CBOR 🔒
• FORMAT_PLAIN 🔒
• PREFIX 🔒
  The path prefix that, where we can not get it from the request, we assume to have been present.

Functions

• ping_tree
  A resource tree representing a set of launchable pings.

Type Aliases

• Count 🔒
  Type used for all counts of pings. Makes sense as u16 because that’s how wide the sequence number field is (but in principle there shouldn’t be anything wrong with going larger and spreading identifier and sequence number into the payload).
• Field 🔒
  Receive window type. Going for u16 just because it works well alignment-wise when mixed with Count values. (Should work just as well with u128, though).