From e58e9ac2577b718268eb884807f367b2ac0bbf8e Mon Sep 17 00:00:00 2001
From: Samuel Sadok <samuel.sadok@bluewin.ch>
Date: Wed, 20 May 2020 19:15:01 +0200
Subject: [PATCH] clarify documentation on CRC calculation

---
 Firmware/fibre/python/fibre/protocol.py |  5 ++---
 docs/protocol.md                        | 28 ++++++++++++++++++++-----
 2 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/Firmware/fibre/python/fibre/protocol.py b/Firmware/fibre/python/fibre/protocol.py
index 851ad457..c9d65735 100644
--- a/Firmware/fibre/python/fibre/protocol.py
+++ b/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
diff --git a/docs/protocol.md b/docs/protocol.md
index 6e8809d6..fd244e65 100644
--- a/docs/protocol.md
+++ b/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.