88 lines
3.3 KiB
Markdown
88 lines
3.3 KiB
Markdown
# 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.
|