domo/doc/specification.md

# 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.