domo/doc/proto.md

10 KiB

Version: 1
Authored by: Raine <raine@ixvd.net>
Status: planning

Prelude

Version 1 has zero security on itself. This can be changed with something like TLS but that's up to the implementer.

Structure

Packets are sent in big endian.

offset size name description example
0x00 1 byte version This describes the version of the packet 0x01
0x01 4 bytes src This describes who sent the packet a.k.a. source device id 0xAABBCCDD
0x05 4 bytes dest This describes who the packet is for a.k.a. destination device id 0xAABBCCDD
0x09 4 bytes checksum This is the CRC32 checksum of the whole packet. 0x00000000
0x0D 4 bytes packet_id This is the unique identifier of the packet 0xFAB1B39D
0x11 4 bytes reply_to This describes what this packet is replying to, if initial message, value is 0x0 0x00000000
0x12 1 byte command This describes what kind of command is sent 0x00
0x13 2 bytes data_length This describes the length of the data in bytes 0x0001
0x15 <0x11-0x12:data_length> data This is the data of the command 0x00

Packets in practice

Statuses

When an error occurs the response should be a 0x0E (error command).
This can contain error data.

To mark a success, you should just send back the expected response.

Reserved fields

The "reserved" column (if present) will state what should be filled in by each side.

  • "no": this should be filled in by both sides. (default)
  • "request": this should only be filled in the request.
  • "response": this should only be filled in the response.

Error checking

If the CRC32 doesn't match up the receiver will send a 0x0E (error) packet to the probable source.
The error code 0x01/net_broken_packet should be used. The metadata may contain some textual info on what went wrong.
The master will not track the broken packet's packet_id, so the slave can send it again.

Data types

Domo has a data framework reliant on data types. These define what kind of data the property holds.

data_type physical type (rust types) size virtual type description
0x0* Basic
0x00 None 0 bytes Nothing Nothing, mostly used internally or as example.
0x01 bool 1 bit Switch A simple switch with two states.
0x02 u8 1 byte Slider A simple slider with u8 precision.
0x03 [u8; 256] 256 bytes Text A simple bit of text.
0x1* Cosmetic
0x10 [u8; 3] 3 bytes Color An RGB value.
0x9* Time & Space
0x90 u64 8 bytes Seconds A simple value that is in seconds.
0xF* Domo types
0xF0 [u8; 4] 4 bytes Domo node reference A reference to a node.

Commands

These are the default commands. All Domo nodes should support these.

Note: all offsets are absolute.

0x0* - Node management

These are commands specifically for management of the nodes.

0x00 - Ping

Check to see if a node is up.

Command data

there is no command data.

0x01 - Register node

This command will register a node.

Command data

offset size name description example
0x15 4 bytes device_id the device identifier. (reserved for response) 0x00000000

Example request

source should be 0xFFFFFFFF or MASTER's device id

0x00000000

Example response

0x0A001001

0x02 - Remove node

Remove node from network

Command data

there is no extra data required.

0x03 - Register property

Command data

offset size name description reserved example
0x15 32 bytes property_name The name of the property as a UTF-8 string. no "Power"
0x35 1 byte data_type The type of data; see "Data types". no 0x01
0x36 1 bit read_only Whether the property is readonly. no 0b0

0x04 - Remove property

Command data

offset size name description reserved example
0x15 32 bytes property_name The name of the property as a UTF-8 string. no "Power"

0x0E - Error

Send a packet to state an error occurred.

Command data

offset size name description example
0x15 1 byte error_code error code; check 'Error codes' 0x00
0x16 2 bytes metadata_length metadata length 0x0000
0x18 <0x14-0x15:metadata_length> metadata metadata

Error codes

status_code name description recoverable
0x00 net_duplicate_packet reply_to packet is invalid because another packet was sent recently with same packet_id. resend with different packet_id
0x01 net_broken_packet recent packet was broken. resend packet
0x02 net_invalid_packet the packet sent is not valid send packet with proper values
0x1* errc_* Client errors
0x10 errc_not_registered client is not registered register client
0x2* errs_* Server errors

0x1* - Properties control

0x10 - Get property

Get a properties value

Command data

offset size name description reserved example
0x15 32 bytes property_name The name of the property as a UTF-8 string. no "Power"
0x35 1 byte data_type The type of the data. response 0x00
0x36 determined by data type data The actual data. response

0x11 - Set property

Command data

offset size name description reserved example
0x15 32 bytes property_name The name of the property as a UTF-8 string. no "Power"
0x35 1 byte data_type The type of the data. no 0x00
0x36 determined by data type data The actual data. no

0x12 - Reset property

Command data

offset size name description reserved example
0x15 32 bytes property_name The name of the property as a UTF-8 string. no "Power"