Merge pull request #412 from madcowswe/doc/crc

Clarify documentation on CRC calculation

Firmware/fibre/python/fibre/protocol.py

@@ -28,6 +28,8 @@ CRC16_DEFAULT = 0x3d65 # this must match the polynomial in the C++ implementatio
 
 MAX_PACKET_SIZE = 128
 
+# For more information on the CRC algorithm refer to protocol.md
+
 def calc_crc(remainder, value, polynomial, bitwidth):
     topbit = (1 << (bitwidth - 1))
 
@@ -61,9 +63,6 @@ def calc_crc16(remainder, value):
         remainder = calc_crc(remainder, value, CRC16_DEFAULT, 16)
     return remainder
 
-# Can be verified with http://www.sunshine2k.de/coding/javascript/crc/crc_js.html:
-#print(hex(calc_crc8(0x12, [1, 2, 3, 4, 5, 0x10, 0x13, 0x37])))
-#print(hex(calc_crc16(0xfeef, [1, 2, 3, 4, 5, 0x10, 0x13, 0x37])))
 
 class DeviceInitException(Exception):
     pass

docs/protocol.md

@@ -45,7 +45,7 @@ __Request__
       - The length of the payload is determined by the total packet size. The format of the payload depends on the endpoint type. The endpoint type can be obtained from the JSON definition.
   - __Bytes N-2, N-1__
       - For endpoint 0: Protocol version (currently 1). A server shall ignore packets with other values.
-      - For all other endpoints: The CRC16 calculated over the JSON definition. The CRC16 init value is the protocol version (currently 1). A server shall ignore packets that set this field incorrectly. See protocol.hpp for CRC details.
+      - For all other endpoints: The CRC16 calculated over the JSON definition using the algorithm described below, except that the initial value is set to the protocol version (currently 1). A server shall ignore packets that set this field incorrectly.
 
 __Response__
 
@@ -61,8 +61,26 @@ The stream based format is just a wrapper for the packet format.
   - __Byte 0__ Sync byte `0xAA`
   - __Byte 1__ Packet length
       - Currently both parties shall only emit and accept values of 0 through 127.
-  - __Byte 2__ CRC8 of bytes 0 and 1
-      - See protocol.hpp for CRC details.
+  - __Byte 2__ CRC8 of bytes 0 and 1 (see below for details)
   - __Bytes 3 to N-3__ Packet
-  - __Bytes N-2, N-1__ CRC16
-      - See protocol.hpp for CRC details.
+  - __Bytes N-2, N-1__ CRC16 (see below for details)
+
+## CRC algorithms ##
+
+__CRC8__
+ - Polynomial: `0x37`
+ - Initial value: `0x42`
+ - No input reflection, no result reflection, no final XOR operation
+ - Examples:
+   - `0x01, 0x02, 0x03, 0x04` => `0x61`
+   - `0x05, 0x04, 0x03, 0x02, 0x01` => `0x64`
+
+__CRC16__
+ - Polynomial: `0x3d65`
+ - Initial value: `0x1337` (or `0x0001` for the JSON CRC)
+ - No input reflection, no result reflection, no final XOR operation
+ - Examples:
+   - `0x01, 0x02, 0x03, 0x04` => `0x672E`
+   - `0x05, 0x04, 0x03, 0x02, 0x01` => `0xE251`
+
+You can use the online calculator at http://www.sunshine2k.de/coding/javascript/crc/crc_js.html to verify your implementation.