From 47da8c1a4cd3649949629d02a10e104c188848e9 Mon Sep 17 00:00:00 2001 From: Raine Date: Wed, 13 Dec 2023 23:42:19 +0100 Subject: [PATCH] doc: added some documentation regarding implementation and behaviour --- doc/specification.md | 48 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/doc/specification.md b/doc/specification.md index 6f3d7f2..fde2f66 100644 --- a/doc/specification.md +++ b/doc/specification.md @@ -20,10 +20,36 @@ A transaction consists of 2 nodes; - "Origin node"; the node who sent the origin packet. - "Destination node"; the node who is marked as the destination by the origin packet. +## Packet terminology + +- "Drop"; ignore packet and OPTIONAL response. + # Behaviour This chapter describes the behaviour of a node. +## Joining a network + +When joining a network, a node MUST send a Register Node command to `0xFFFFFFFF` (the broadcast address). +This ensures that all devices know of the new devices, the master node MUST respond with an appropriate reply; +Return the same packet as response or an error. + +A node MAY send a Ping command to `0xFFFFFFFF` to find other devices. +A node MUST reply to a Ping, if a node fails to do so the node can be considered unreachable. + +## Node discovery + +To keep network traffic less noisy ping broadcasts MAY be intercepted by the master node and the master node SHOULD send a chain of response pings as the registered devices. +This will ensure that the network won't get polluted with ping packets. +This discovery method is OPTIONAL. + +The traditional way is to broadcast the ping over the network and route all responses back to the origin node. + +## Leaving a network + +To gracefully leave a network a node MUST send a Remove node packet, once a reply is received the node can safely close the connection. +A master node MAY remove a node if the connection closes. + ## Statuses When an error occurs on the destination node in result of a request, the response to the origin node MUST be a `0x0E` (error command). @@ -34,10 +60,26 @@ To mark a success, you MUST send back the request packet altered with the data s ### Broadcast (`0xFFFFFFFF`) -Nodes MUST listen to this address. -Owner nodes MUST forward this address to their owners if applicable. +This address is a broadcast address. +All nodes MUST respond to this packet. +To avoid infinite loops, nodes SHOULD keep track of the `packet_id` of the broadcast packet and SHOULD drop it, if it reappears. -# Packet inspection +### Sink (`0x00000000`) + +This address is a sink. +Packets sent to this address MAY be dropped. + +### RECOMMENDED master node address (`0x00000001`) + +This address is RECOMMENDED to be used as master address. + +# Implementing Domo + +## Extending Domo with extra commands + +Domo specifies commands in her protocol. +These MUST NOT be changed, however adding commands is OPTIONAL and allowed. +Nodes MAY drop unrecognised commands. ## Error checking