riot_coap_handler_demos

Module ping_passive

source
Available on crate feature ping only.
Expand description

A monitor resource for incoming pings.

In difficult communication situations, especially with asymmetric communication, the ability to detect whether one ping only was sent or not can make all the difference.

§Setup

The resource handler is most easily used by having a static PingHistoryMutex and hooking it into a CoAP handler tree.

To receive messages through GNRC, a callback slot needs to be allocated and wired up.

static PING_PASSIVE: PingHistoryMutex<{ DEFAULT_SIZE }> = PingHistoryMutex::new();

let handler = coap_message_demos::full_application_tree(None)
    .at(&["pinged"], riot_coap_handler_demos::ping_passive::resource(&PING_PASSIVE))
    .with_wkc()
    ;

static PASSIVE_SLOT: static_cell::StaticCell<riot_wrappers::gnrc::netreg::callback::Slot<&'static PingHistoryMutex<{ DEFAULT_SIZE }>>> =
    static_cell::StaticCell::new();
PING_PASSIVE.register(PASSIVE_SLOT.init(Default::default()));

§Usage

When registered as /pinged, you can run

$ aiocoap-client 'coap://[2001:db8::1]/pinged'
# CBOR message shown in Diagnostic Notation
[0]

and see that no pings have been received in a very rudimentary and likely to change format.

Once you have sent a ping, you will see the change, and using different addresses shows differentiated results:

$ ping fe80::3c63:beff:fe85:ca96%tapbr0 -c1
[...]
$ aiocoap-client 'coap://[2001:db8::1]/pinged'
[0, 54([ip'fe80::f30:40e4:6c93:e17d', null, 6])]
$ ping 2001:db8::3c63:beff:fe85:ca96 -c1
[0, 54([ip'fe80::f30:40e4:6c93:e17d', null, 6]), IP'2001:db8::1']

Once the list of received pings overflows, the number of discarded pings in the first place of the list is incremented.

The state of the handler can be reset using -m DELETE.

§Interface

In CoAP resource discovery, a resource behaving like this can be recognized by the interface description if=tag:chrysn@fsfe.org,2024-09-16:pinged. Any such resource supports the DELETE operation to reset its state, and a GET with the application/cbor content format.

The format may be extended in the future to contain items that are not IPv6 addresses with tag 54. Such items may be ignored by consumers, but can be shown in diagnostic notation. Items that are arrays will contain an IP address (possibly not tagged) as the first item, which may be shown instead; if the array contains more than one item, the trailing items are ignored or shown just like non-IP items.

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§

Constants§

Functions§