domo/doc/proto.md

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	packet_id	This is the unique identifier of the packet	0xFAB1B39D
0x0D	4 bytes	reply_to	This describes what this packet is replying to, if initial message, value is 0x0	0x00000000
0x09	1 byte	command	This describes what kind of command is sent	0x00
0x11	2 bytes	data_length	This describes the length of the data in bytes	0x0001
0x13	<0x11-0x12:data_length>	data	This is the data of the command	0x00

Request / Response

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.

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
0x13	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
0x13	32 bytes	property_name	The name of the property as a UTF-8 string.	no	"Power"
0x33	1 byte	data_type	The type of data; see "Data types".	no	0x01
0x34	1 bit	read_only	Whether the property is readonly.	no	0b0

0x04 - Remove property

Command data

offset	size	name	description	reserved	example
0x13	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
0x13	1 byte	error_code	error code; check 'Error codes'	0x00
0x14	2 bytes	metadata_length	metadata length	0x0000
0x16	<0x14-0x15:metadata_length>	metadata	metadata

Error codes

status_code	name	description
0x00	net_duplicate_packet	reply_to packet is invalid because another packet was sent recently with same packet_id.
0x01	net_broken_packet	recent packet was broken.
0x1*	errc_*	Client errors
0x10	errc_not_registered	client is not registered
0x2*	errs_*	Server errors

0x1* - Properties control

0x10 - Get property

Get a properties value

Command data

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

0x11 - Set property

Command data

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

0x12 - Reset property

Command data

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