Uploading protocol

File layout

The layout of a .hbs (Hexabus binary state machine image) file:

• 16 bytes: Target IP address
• 64 bytes: Device name
• 16 bytes: State machine ID
• 1520 bytes: Actual state machine data
  • 1 byte: Condition table size
  • 511 bytes: Contitin table
  • 1 byte: Date/time transition table size
  • 511 bytes: Date/time transition table
  • 1 byte: Transition table size
  • 495 bytes: Transition table

Target IP address

The target IP address is used by Hexaupload. This is the address the program will be upload to when the file is handed to hexaupload. It can be overridden by giving the -i command line parameter.

Device name

This is the name the device will appear under in hexinfo, and in other interfaces which will be available in the future.

State machine ID

The state machine ID is needed for state machines that were generated from the Hexabus Compiler. If one state machine should be running on multiple Hexabus devices, all of these devices must have a program with the same state machine ID. It is used for keeping the state machines synchronized: Should one of the devices lose power and restart (or reboot for any other reason), the other devices will be notified using the state machine ID, so that the whole distributed state machine can be reset to its initial state---otherwise different parts of the machine could end up in different states. This ID is auto-generated by the Hexabus Compiler, it is the MD5 hash of the state machine name in the Hexabus Compiler program. When manually writing Hexabus Assembler programs, any 16 byte long hexadecimal string can be used (if the auto-reset mechanism should be active), or a 0 can be entered as a state machine ID, which disables the auto-reset mechanism.

Actual state machine data

The first byte of each table denotes the number of entries. The rest of the table is filled with the binary representation of the data structures the state machine uses. These data structures are defined in the state machine folder of the firmware source code.

The uploading process

Endpoints

• 9: State machine control
• 10: State machine upload receiver
• 11: State machine upload ack/nak

The process

First, the state machine interpreter on the Hexabus device is halted via the state machine control endpoint. Then the data is uploaded.

The uploading is done in chunks of 64 bytes. Except for the first 16 bytes, which hold the target IP address, the whole hbs-file is tranferred to the device.

This is done using Hexabus packets of the 66BYTE variety which are sent to the state machine upload receiver endpoint. The first byte of the packet's payload is the chunk ID. The rest of the payload (64 bytes) is actual data.

The first chunk (chunk ID 0) carries only the device name. It is only written to the EEPROM if the first byte is not zero. Otherwise the previous contents of the EEPROM are kept, making it possible to change the state machine running on a device without changing its name. Since this goes to a different part of the EEPROM, and the EEPROM only has 30 bytes of space for the state machine name, the first 30 bytes of this chunk are stored there, and the rest is discarded. The reason for this special treatment of the first chunk lies in the EEPROM layout: The address of the device name was defined long before the state machine interpreter was implemented. It is followed by other data, for instance the calibration data of the power meter of the Hexabus Plug+. All the Plug+s are calibrated, and if the calibration data is accidentally overwritten, they need to be recalibrated. Moving the calibration data in the EEPROM to a different location can also lead to errors, e.g. when the firmware is upgraded and the EEPROM is not adapted accordingly. To avoid having to recalibrate the power meters, all the previously defined EEPROM contents were left in the same location when implementing the state machine upload process. This limits the device name to 30 bytes and makes it necessary to store a part of the image (the part that contains the device name) in a different location.

All other chunks can be consecutively stored in the state machine's EEPROM area.

Upon receiving a chunk, the firmware replies with an ACK from the state machine upload ack/nak endpoint if the chunk was stored correctly to the EEPROM, or with a NAK if the chunk ID was outside of the permissible range or some other error occured.

When the upload was finished successfully, the state machine interpreter on the device is restarted from the initial state using the state machine control endpoint.