-
Notifications
You must be signed in to change notification settings - Fork 15
New Hexabus Protocol
This page is supposed to describe "how stuff should work" in the New Hexabus Protocol.
If you want to make a new Hexabus device, for basic compatibility the functionality described herein should be implemented.
Note that this document is only an overview and not a complete guide to the Hexabus protocol. For an exact definition of what the different packet types on the Hexabus network do and how to react to them, please refer to New Hexabus Packet Format. The Hexabus Device software is work in progress, so this document may be out of sync with the code.
A Hexabus device offers several functions called endpoints. They consist of a pair (VID (value ID); Value). Everything the device is able to do (Hexabus-wise) is represented as an endpoint.
Each value can be directly set by sending a WRITE packet to the device. The device shall then react accordingly: Either by executing some command, or by sending an error packet if the value is nonexistent or can not be written.
On the Hexabus Socket, WRITE is handled by the udp_handler process: Upon receiving a setvalue packet, it checks for VID 1 (the Socket's power switch), and calls relay_on() or relay_off(). Note that the normally closed contact of the relay is used, to relay_on() switches the power to the socket off.
QUERY packets are also handled by udp_handler: For VID 0, an INFO packet with the device descriptor is returned. When VID 1 is queried, relay_get_state() is used to determine whether the power is switched on or off, and for VID 2, metering_get_power is used to get the current power consumption. The make_value_packet() function constructs the packet (as defined in New Hexabus Packet Format and hexabus_packet.h), which is then sent by the send_packet() function back to the host that sent the QUERY.
For now, each device should broadcast those of its values that may be of interest for other devices. The Hexabus Socket broadcasts its power measurement every 60+(rand()%60) seconds. This is done by the value_broadcast process. The main part of the process just handles the timers. A function named send_packet is called by the timer. This function uses metering_get_power() to get the current power consumption of the socket, and sends out a HXB_INFO packet to the link-local multicast address.
When udp_handler receives a HXB_INFO packet, it posts a hxb_broadcast_received_event. The event comes with a pointer to a hxb_data_... structure. This structure is defined in hexabus_packet.h and contains the IP adress of the broadcast sender, the datatype, VID and value of the data received.
This event is caught by hxb_broadcast_handler. The software which handles the reaction to events, rule-based switching etc. is yet to be implemented.