Submitted by shutterdrone on Sun, 04/04/2010 - 23:00
Posted in
The TimeLapse Engine Serial Protocol
All communications with the TimeLapse Engine via a computer or connected device utilize a standard serial protocol that enables parameters and commands to be sent, and provides the ability to read data back from the engine.
Command Format
For all communications, a command or response byte is sent, followed by a data length byte, and then the specified number of bytes of data. Some commands and responses require no data, so the minimum number of bytes that is considered a valid communication is two (command/response + data length of zero).
Commands flow to the Engine from a connected device, and have the following structure:
| Command Byte | Data Length Byte | Data Byte 1 | Data Byte 2 | ... | Data Byte n |
Please note, that '0' (binary zero, or 0x00) is an invalid command byte value - all valid commands must be a positive value (1-255).
The data length byte's value should always exclude the two bytes used for command and data length, it is used to express how many bytes follow the data length byte.
Response Format
After a command has been executed, a response is returned by the engine, the response has the following structure:
| Response Value Byte | Data Length Byte | Data Byte 1 | Data Byte 2 | ... | Data Byte n |
By default, the engine always uses a response value of zero (0x00) to indicate that a command failed, or was unknown, and a response value of one (0x01) to indicate the command succeeded.
Whenever the engine returns zero as the response byte value, the data length byte will be zero.
The following table describes common responses:
| Response | Response Value Byte | Data Length Byte | Data Byte 1 | Data Byte 2 |
|---|---|---|---|---|
| error | 0 | 0 | n/a | n/a |
success (no data) | 1 | 0 | n/a | n/a |
| success (one byte of data) | 1 | 1 | byte | n/a |
| success (16-bit response) | 1 | 2 | 16-bit integer MSB | 16-bit integer LSB |
Please note that in the above responses, there is nothing to indicate whether multiple types of data are being sent, or what the sign of the provided data type is. The consuming software is expected to be aware of the responses they anticipate to certain commands, and deal with them appropriately.
Basic Commands
Each command has several sub-commands, these sub-commands are sent as the first data byte. Therefore, all valid commands will have a data length of at least one byte.
Please remember, that all values used in the TimeLapse Engine protocol are binary, and should be communicated as the data type specified, not the ASCII representation of that data. The data types used in this documentation should be mapped against the Arduino data types, e.g.: int is a 16-bit value.
All multi-byte values must be sent in Big-Endian format, meaning the most significant byte comes first, and the least significant comes last.
The following table lists the basic commands, click on the command name for documentation:
| Command | Command Byte Value |
|---|---|
| Engine Control | 1 |
| Set Program Information | 2 |