diff --git a/content/en/docs/Standards/sao/_index.md b/content/en/docs/Standards/sao/_index.md index 4143ba3..23ee7c4 100644 --- a/content/en/docs/Standards/sao/_index.md +++ b/content/en/docs/Standards/sao/_index.md @@ -54,9 +54,9 @@ Ignoring the first byte read from the EEPROM is done to allow for identifying ad ### Header identifiers -| 1 | 2 | 3 | 4 | Description | -|---|---|---|---|----------------------| -| L | I | F | E | Binary descriptor | -| J | S | O | N | JSON text descriptor | -| T | E | A | M | Reserved :smile: | +| 1 | 2 | 3 | 4 | Description | Documentation | +|---|---|---|---|-----------------------------|------------------------------------| +| L | I | F | E | Binary descriptor | [On this site](binary_descriptor) | +| J | S | O | N | JSON text descriptor | | +| T | E | A | M | Reserved for Badge.team use | | diff --git a/content/en/docs/Standards/sao/binary_descriptor.md b/content/en/docs/Standards/sao/binary_descriptor.md new file mode 100644 index 0000000..947052a --- /dev/null +++ b/content/en/docs/Standards/sao/binary_descriptor.md @@ -0,0 +1,64 @@ +--- +title: "Binary SAO descriptor" +nodateline: true +weight: 30 +--- + +This document describes the header format used in the identification EEPROM at address 0x50. + +## Header + +The header contains a magic value to identify the SAO as having a binary header. This header is always the ASCII characters for "LIFE". We recommend badges only check the last three bytes ("IFE") to identify small EEPROM chips which got their first byte corrupted. In case the first byte is found to be corrupted we recommend the badge corrects the faulty first byte by writing an "L" to address 0. + +Then follows the length of the SAOs name as a single byte. The name itself follows directly after the header. as ASCII text, the name can be at most 255 characters long. We recommend to only use visible 7-bit ASCII characters in the name to ensure compatiblity. + +The functions of the SAO can be described using drivers. The drivers supported vary between different badges. If an unsupported driver gets detected it can be ignored by the badge. The identifier of the first driver is described in a similar way to the name of the SAO itself: a length byte. The name itself follows after the SAO name as ASCII text. + +The last field of the header tells the badge the number of additional drivers available on the SAO. Not all badges support additional drivers. If no additional drivers are available for the SAO this field must be set to 0. Additional driver data is appended after the main header. + +### Example + + + + + + + + +
Offset012345678910111213141516171819
DescriptionMagicName lengthDriver name lengthDriver data lengthNumber of extra driversNameDriver nameDriver data
HEX4C4946450504030048454C4C4F74657374010203
ASCIILIFE    HELLOtest   
+ +This header defines a SAO named "HELLO" which has support for driver "test". The SAO contains three bytes of information for use by the "test" driver, namely `0x01 0x02 0x03`. There are no additional drivers. + +## Additional drivers + +Additional drivers add extra header fields describing each driver. + + + + + + +
Offset012345678
DescriptionDriver name lengthDriver data lengthDriver nameDriver data
HEX040374657374010203
ASCII  test   
+ +# Drivers + +The following drivers are supported by the MCH2022 badge: + + - Storage: describes the unused EEPROM memory available on the SAO + - Basic I/O: describes buttons and LEDs connected to the SAO GPIO pins + - Neopixel: describes addressable LEDs connected to the SAO GPIO pins + - ssd1306: describes an SSD1306 OLED display connected to the I2C bus + - ntag: describes an NTAG NFC tag connected to the I2C bus + - app: describes the name of a companion app + + +Documentation for these drivers has yet to be written. More information can be found in the firmware source code here: [Github](https://github.com/badgeteam/mch2022-firmware-esp32/blob/master/main/include/sao_eeprom.h)