-
Notifications
You must be signed in to change notification settings - Fork 0
Home
The protocol is packet based with varying length packets. Each packet takes the form:
0x0F 0x0F <PAYLOAD> 0x04
Every packet begins with 0x0F 0x0F and ends with 0x04. The total length of the packet cannot exceed 255 bytes in length excluding escape characters.
The payload contains the command and data of the packet. All payload takes the form:
<command> <len> [Address] [Data] <checksum>
- Command is always one byte long is any of the commands available by the protocol.
- Len is also one byte and its meaning varies depending on the command. Must not be 0×00 or a reset will occur.
- Address is only used by some commands, but when used is 3 bytes long in little endian format.
- Data is also only used by certain commands in different ways. It can be anywhere from 0 to X bytes long.
- Checksum is the negative sum of all the bytes in the PAYLOAD section, excluding any escape characters.
The bytes 0x0F, 0x05, and 0x04 all carry a special meaning and must be escaped by 0x05 if they occur in the PAYLOAD portion of the packet.
The maximum size of the PAYLOAD is 256 bytes. This excludes any escape characters.
NOTE: Checksums not shown in the command description.
0x00 0x02
The entire command and response is:
–» 0x0F 0x0F 0x00 0x02 0xFE 0x04
«– 0x0F 0x0F 0x00 0x02 0x01 0x01 0xFC 0x04
In this case, 0x00 0x02 is a repeat of the command and length. 0x01 0x01 indicates version 1.1 and 0xFC is the checksum for the PAYLOAD portion of the returned packet. 0x04 signals the end of the packet in both cases.
0x01 <len> <Address>
The read command will tell the controller to read len bytes starting at address and send them back. It can be used to read from any valid memory location. len must not cause the return packet PAYLOAD to exceed 256 bytes.
Example to read Device ID:
–» 0x0F 0x0F 0x01 0x02 0xFE 0xFF 0x3F 0xC1 0x04
«– 0x0F 0x0F 0x01 0x02 0xFE 0xFF 0x3F 0x20 0x14 0x8D 0x04
The first packet requests 0x02 bytes to be read from address 0x3FFFFE. NOTE: The address is sent to the controller in little endian format.
The response packet once again echos the command, len, and address. After the address, the data portion contains the actual bytes (in this case 2: 0x20 0x14) of data read from the controller. These are the bytes that were read sequentially from the requested memory location. I.E. 0x20 was read from location 0x3FFFFE and 0x14 was read from 0x3FFFFF.
The data in the return packet will always be len bytes long (ignoring escape characters).
0x02 <len> <Address> <data>
The write command will write len bytes of data starting at address to the controller. len must not exceed 31 because of buffer limitations on the bootloader.
Write data example:
–» 0x0F 0x0F 0x02 0x10 0x05 0x04 0x08 0x00 0x04
«– 0x0F 0x0F 0x02 0xFE 0x04
The first packet tells the controller to write 0x10`` (16) blocks of data starting at address 0x000804. A block is 8 bytes. (Note: notice the 0x05 before 0x04to escape the special character0x04``` because it is not meant to end the packet). data must contain len blocks (excluding escape characters). In this case data would be 128 bytes long.
If the write comman was received successfully, then the controller sends back 0x0F 0x0F 0x02 0xFE 0x04. This does not verify that the data was written successfully; it is only an ACK to the write command. If you want to verify the data, you must use the read command to read the bytes from the controller and verify them client side.
0x08 0x40
Run user code:
–» 0x0F 0x0F 0x08 0x40 0xB8 0x04
«– 0xAA 0x55 0xFF 0x01 0x01 0x40
The first packet tells the controller to leave program mode and run the user code. The response from the controller is always 0xAA 0x55 0xFF 0x01 0x01 followed by an echo of the len byte (0x40) from the command. This signals that the controller has returned to user code.
Note: The response is not a real packet and once it is sent the controller begins to run the user code.
0x09 <len low> <Address> <len high>
Erase Program memeory example:
–» 0x0F 0x0F 0x09 0x10 0x05 0x05 0x08 0x00 0x00 0xDA 0x04
«– 0x0F 0x0F 0x09 0xF7 0x04
The first packet tells the controller to erase [len high][len low] -» 0x0010 (16) blocks of memory. A block of memory is 64 bytes in length, and in the example 16 blocks will erase 1024 bytes of program memory starting at address 0x000805.
Notice again that the 0x05 part of the memory address has been escaped by 0x05 because 0x05 is the escape character and must also be escaped when used. Ommiting the 0x05 will cause the receiver to think that the 0x05 for the address is escaping the 0x08 which is not the case.
There are three special bytes that must be treated specially when used in the PAYLOAD section of the packet: 0x0F 0x04 0x05
The 0x0F is for starting packets, 0x04 is for ending them, and 0x05 is the escape character/byte. Whenever any of these three occur in any section of the PAYLOAD (this includes the command, len, checksum, etc..) they must be precedeed by the escape character 0x05. The escape character will not be counted as part of the len, address, or data once received by the controller.
0x0F 0x0F 0x01 0x05 0x0F 0x01 0x05 0x05 0x01 0xE9 0x04
In this packet, the len byte was a special character and thus had to be escaped by 0x05. Also, the address 0x010501 contained the special character 0x05 and too had to be preceeded by 0x05.
The checksum is the two’s compliment sum of all the PAYLOAD bytes excluding escape characters. This is analogous to subtracting each byte from 0, and the result will be the checksum.
0 - 0x01 - 0x0F - 0x01 - 0x05 - 0x01 = 0xE9
The checksum is from the escape character example. Note: the escape character bytes were not included in the calculation.