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	dest	This describes who the packet is for a.k.a. destination device id	0xAABBCCDD
0x05	4 bytes	src	This describes who sent the packet a.k.a. source 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
0x11	1 byte	command	This describes what kind of command is sent	0x00
0x12	2 bytes	data_length	This describes the length of the data in bytes	0x0001
0x14	<0x11-0x12:data_length>	data	This is the data of the command	0x0000
0x14 + <0x11-0x12:data_length>	4 bytes	checksum	This is the CRC32 checksum of the packet without the checksum.	0x00000000

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*				Meta
0x00	None	0 bytes	Nothing	Nothing, mostly used internally or as example.
0x01	Vec<DataType>	2+ bytes	Array	An array of DataTypes. first two bytes is the u16 length
0x1*				Simple
0x10	bool	1 byte	Switch	A simple switch with two states. 0x00 = off, 0x01 = on, 0x02 = toggle
0x11	u8	1 byte	Slider	A simple slider with u8 precision.
0x12	[u8; 256]	256 bytes	Text	A simple bit of text.
0x2*				Cosmetic
0x20	[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.

Dynamic data (dynamic_data)

Dynamic data is a data snippet with a prop_data_type byte and the data next to it.

Note

: this section uses relative offset

offset	size	name	description	example
0x00	1 byte	prop_data_type	Describes the data type	0x00
0x01	depending on prop_data_type	data	The data

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.

You can try to register as a node with a specific device_id but this might result in an error 0x03.
Leave 0 to get a random id.

Command data

offset	size	name	description	reserved	example
0x14	4 bytes	device_id	the device identifier. leave 0x00000000 to get random id	no	0x00000000

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
0x14	32 bytes	property_name	The name of the property as a UTF-8 string.	no	"Power"
0x34	1 byte	data_type	The type of data; see "Data types".	no	0x01
0x35	1 byte	read_only	Whether the property is readonly. (0x00 = no, 0x01 = yes)	no	0x00

0x04 - Remove property

Command data

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

Error codes

status_code	name	description	recoverable
0x1*	net_*	Network errors
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
0x03	net_addr_in_use	the addr requested is in use already	register with another id or 0
0x1*	errc_*	Client errors
0x10	errc_not_registered	client is not registered	register client
0x2*	errs_*	Server errors
0x20	errs_not_delivered	server could not deliver packet.	depends on situation

0x1* - Properties control

0x10 - Get property

Get a properties value

Command data

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

0x11 - Set property

Command data

offset	size	name	description	reserved	example
0x14	32 bytes	property_name	The name of the property as a UTF-8 string.	no	"Power"
0x34	1 byte	dynamic_data	Dynamic data snippet	no	0x0100

0x12 - Reset property

Command data

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