Home

Welcome to the libfonz wiki!

libfonz is a lightweight packet library for communicating between a high-end system (such as an Intel system) and an Atmel AVR board. It could also be used for other boards such as the PIC but that's left as an exercise for the reader (definitely send us a pull request if you port it).

The packet format is extremely simple: Every packet has a single-byte header (0xce) which is used to initiate communication. The serial receiver ignores all data until the header is seen. Even if the system is already halfway through processing a packet, if a header byte is seen then that is always the start of a packet.

To avoid the header byte being sent in a normal data packet, the escape byte (0xcc) is sent if an attempt is made to send either a header byte or an escape byte. The escape byte is followed by the original byte, with the high bit turned off. So if 0xce were to appear in the data stream, it would appear as 0xcc followed by 0x4e.

The next byte is the command. If the least-significant bit is set, then the command has a two byte argument. Note that the argument is two bytes, not a short. If you want to imply it's a sixteen bit argument then it's up to you to make sure the bytesex issue is agreed.

Following either the command byte or the last of the two arguments, is a single-byte checksum which is just the exclusive-or of the previous bytes.

After the checksum, the system will ignore all data until another header byte is seen. If you wish to send out of band data, such as debug messages, do so between packets.

The packet system is stateless. It is worth thinking a bit about this. There is no explicit response to any packet. You may have a requirement to read a two-byte parameter from an AVR board and you might define the command 0x42 as the command to read these parameters, A and B. By your own convention, the command 0x43 (note that the lower bit is set) would include A and B.

To try and model this a bit more, if the main system wants to read the values A and B from the AVR board, it would send the command 0x42 (no arguments). The AVR board would respond with the command 0x43,A,B. If the main system wants to set the values A and B, it would use the command 0x43,A,B. It is really important to remember that there is no implied response to any packet. In this example, the main system responds to a command 0x43 by noting the values A and B. If it needs to do anything with this data, it can do so. It may decide it needs this data every quantum, so will arrange to enqueue a 0x42 command for transmission, every quantum. The code that handles the 0x43 is asynchronous. There is no guarantee that the next packet received would in fact by a response to this command, as other packets may be enqueued in the interim.

Likewise, the AVR code would respond to a 0x42 command by enqueueing a 0x43 with the A and B parameters, and respond to a 0x43 command by storing the A and B parameters.

No commands are defined by the system. It is up to you to decide how to implement your own protocol, using these notes.