CokeOS v3 serial interface

CokeOS is designed to receive commands from a host computer. The host and the coke controller communicate via a serial port connection, which currently runs at 9600 baud.

The serial interface, or "protocol" if it can be called that, is quick and not overly complicated or bulky, but still provides reasonable protection from accidently executing incorrect commands due to serial errors or unsynchronization.

When the host wants the board to execute a command, it sends:

the STARTCMD character ($02)
the command character
any parameters the command requires

That's it. CokeOS will respond with one of the following characters:

COKE_NAK ('n'): not acknowledged. Either the STARTCMD character was expected and another character was received, or the command character does not correspond to any command currently installed.

COKE_ACK ('a'): acknowledged. The command was executed successfully.

COKE_FAIL ('f'): fail. The command was acknowledged, but could not be executed because of an error. Directly following the COKE_FAIL character is another character which is the error code.

COKE_QUERY ('q'): query response. The command was acknowledged and successful, and is returning data to the host. Directly following the COKE_QUERY character is another character which is the length of the query data, which is followed by that many bytes of the data itself.

In addition to these command responses, there are two characters which CokeOS sends out asynchronously, whenever appropriate:

COKE_MESSAGE ('m'): asynchronous message. Something happened which CokeOS or a module wants the host to be aware of. Directly following the COKE_MESSAGE character is another character which is the message code.

COKE_RESET ('r'): reset has occurred. CokeOS sends this character when it starts up. It means that the board has been reset, and CokeOS is ready for commands.

COKE_NAK ('n'):	not acknowledged. Either the STARTCMD character was expected and another character was received, or the command character does not correspond to any command currently installed.
COKE_ACK ('a'):	acknowledged. The command was executed successfully.
COKE_FAIL ('f'):	fail. The command was acknowledged, but could not be executed because of an error. Directly following the COKE_FAIL character is another character which is the error code.
COKE_QUERY ('q'):	query response. The command was acknowledged and successful, and is returning data to the host. Directly following the COKE_QUERY character is another character which is the length of the query data, which is followed by that many bytes of the data itself.

COKE_MESSAGE ('m'):	asynchronous message. Something happened which CokeOS or a module wants the host to be aware of. Directly following the COKE_MESSAGE character is another character which is the message code.
COKE_RESET ('r'):	reset has occurred. CokeOS sends this character when it starts up. It means that the board has been reset, and CokeOS is ready for commands.