3.3 KiB
Protocol Design
In this document I will define how this document is designed and how it should be implemented.
Prelude
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL", "NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
"node" or "nodes" are referring to a device that implements the Domo protocol.
Transactions
All interactions between 2 nodes is called a transaction; a request and response.
The initial packet sent in the transaction is called the "origin packet".
A initial packet MUST NOT have a reply_to.
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).
This MAY contain error data.
To mark a success, you MUST send back the request packet altered with the data specified in the protocol.
Reserved addresses
Broadcast (0xFFFFFFFF)
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.
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
If the CRC32 doesn't match up the destination node MUST send a 0x0E (error) packet to the origin node.
The error code 0x01/net_broken_packet MUST be used. The metadata MAY contain some textual info on what went wrong.
The master MUST not track the broken packet's packet_id, so the slave can send it again.