Merge pull request #6 from emfcamp/hugh/docs-structure

Add some structure to the docs so we can start filling it out
emfcamp · May 6, 2024 · d7db3e1 · d7db3e1
2 parents cfd709c + d693035
commit d7db3e1
Show file tree

Hide file tree

Showing 17 changed files with 229 additions and 89 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -18,8 +18,11 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material
-      - run: mkdocs build
+      - name: Install dependencies
+        uses: VaultVulp/[email protected]
+        with:
+          command: install -d
+      - run: pipenv run mkdocs build
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
@@ -28,8 +31,8 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     permissions:
-      pages: write      # to deploy to Pages
-      id-token: write   # to verify the deployment originates from an appropriate source
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

diff --git a/.tool-versions b/.tool-versions
@@ -0,0 +1 @@
+python 3.10
diff --git a/.../52437fff-3c14-4c18-aa22-a656f64f00f0.png → .../52437fff-3c14-4c18-aa22-a656f64f00f0.png b/.../52437fff-3c14-4c18-aa22-a656f64f00f0.png → .../52437fff-3c14-4c18-aa22-a656f64f00f0.png
diff --git a/.../b456ffb9-f5bf-4387-b8ec-fd9796ad957b.png → .../b456ffb9-f5bf-4387-b8ec-fd9796ad957b.png b/.../b456ffb9-f5bf-4387-b8ec-fd9796ad957b.png → .../b456ffb9-f5bf-4387-b8ec-fd9796ad957b.png
diff --git a/.../df9d2843-4b89-4341-98a9-61f1c9b1f780.png → .../df9d2843-4b89-4341-98a9-61f1c9b1f780.png b/.../df9d2843-4b89-4341-98a9-61f1c9b1f780.png → .../df9d2843-4b89-4341-98a9-61f1c9b1f780.png
diff --git a/docs/technical-reference/eeprom.md → docs/hexpansions/eeprom.md b/docs/technical-reference/eeprom.md → docs/hexpansions/eeprom.md
@@ -1,5 +1,4 @@
-Eeprom format
-===
+# Eeprom format
 
 This document is a work in progress. More details will be added as they become available.
 
@@ -13,34 +12,36 @@ We will look for eeproms on the following i2c addresses:
 The header is 32 bytes long and contains the following values:
 
 - Magic (offset 0, length 4):
-    - ASCII `THEX`
-        - This must match exactly
-- Manifest version (offset 4, length 4): 
-    - ASCII `2024`
-        - This must match exactly
+  - ASCII `THEX`
+    - This must match exactly
+- Manifest version (offset 4, length 4):
+  - ASCII `2024`
+    - This must match exactly
 - Filesystem info (offset 8, length 8):
-    - 2 bytes offset (bytes from beginning of eeprom)
-        - This is the number of bytes from the start of the eeprom to the start of the littlefs filesystem. It must be a multiple of the eeprom page size, and greater or equal to 32.
-    - 2 bytes page size (eeprom page size in bytes)
-        - As specified in the eeprom datasheet
-    - 4 bytes total size (total filesystem size in bytes)
+  - 2 bytes offset (bytes from beginning of eeprom)
+    - This is the number of bytes from the start of the eeprom to the start of the littlefs filesystem. It must be a multiple of the eeprom page size, and greater or equal to 32.
+  - 2 bytes page size (eeprom page size in bytes)
+    - As specified in the eeprom datasheet
+  - 4 bytes total size (total filesystem size in bytes)
 - VID/PID (offset 16, length 4)
-    - 2 bytes VID
-        - This is a Vendor ID. Vendor IDs are assigned by the Unnecessary Hexpansion Bureaucracy Implementers Forum ([UHB-IF](https://badge.emfcamp.org/wiki/UHB-IF)) To obtain a Vendor ID, contact the UHB-IF at (location to be disclosed). If you don't want to do that, use a vendor ID from [here](https://badge.emfcamp.org/wiki/UHB-IF/Uncontrolled_IDs).
-    - 2 bytes PID
-        - This is a Product ID. If you have a Vendor ID, you can choose your own Product ID. If you are using the free-for-all Vendor ID, you will have to coordinate number assignments with other users on a wiki page (to be disclosed). Each hexpansion design with an eeprom needs a unique VID/PID combination.
+  - 2 bytes VID
+    - This is a Vendor ID. Vendor IDs are assigned by the Unnecessary Hexpansion Bureaucracy Implementers Forum ([UHB-IF](https://badge.emfcamp.org/wiki/UHB-IF)) To obtain a Vendor ID, contact the UHB-IF at (location to be disclosed). If you don't want to do that, use a vendor ID from [here](https://badge.emfcamp.org/wiki/UHB-IF/Uncontrolled_IDs).
+  - 2 bytes PID
+    - This is a Product ID. If you have a Vendor ID, you can choose your own Product ID. If you are using the free-for-all Vendor ID, you will have to coordinate number assignments with other users on a wiki page (to be disclosed). Each hexpansion design with an eeprom needs a unique VID/PID combination.
 - Unique ID (offset 20, length 2)
-    - 0x0000 if unused, otherwise unique ID
-        - This may be used to identify individual hexpansion instances of the same kind. Leave at zero if not using, otherwise ensure each hexpansion instance has a unique value.
+  - 0x0000 if unused, otherwise unique ID
+    - This may be used to identify individual hexpansion instances of the same kind. Leave at zero if not using, otherwise ensure each hexpansion instance has a unique value.
 - Friendly name (offset 22, length 9, padded with 0x00)
-    - This is an ASCII string containing a name to be displayed in menus and prompts so that users can identify the hexpansion. It can contain up to nine characters, and unused characters should be set to 0x00.
+  - This is an ASCII string containing a name to be displayed in menus and prompts so that users can identify the hexpansion. It can contain up to nine characters, and unused characters should be set to 0x00.
 - Checksum (offset 31, length 1)
-    - This is a checksum calculated by the following algorithm:
-    1. Start with a variable S with the value 0x55
-    2. for each byte B of the header **except the first byte**, S = B xor S. The first byte (index 0) is ignored. Only bytes with index 1-30 are used.
-    3. when all 30 bytes have been processed, store the result in the checksum position
 
-    An example implementation of the checksum algorithm in Python:
+  - This is a checksum calculated by the following algorithm:
+
+  1. Start with a variable S with the value 0x55
+  2. for each byte B of the header **except the first byte**, S = B xor S. The first byte (index 0) is ignored. Only bytes with index 1-30 are used.
+  3. when all 30 bytes have been processed, store the result in the checksum position
+
+  An example implementation of the checksum algorithm in Python:
 
 ```python
 
@@ -49,17 +50,17 @@ def calc_checksum(header): #header assumed to be of type bytes
     for b in header[1:]:
         value= value ^ b
     return value
-        
+
 header_w_checksum = header+bytes([calc_checksum(header)]) #to generate a checksum
-    
+
 calc_checksum(header_w_checksum) # should return 0 if checksum is correct
-    
+
 ```
 
 The header format uses little-endian byte ordering for the individual values, e.g. 0x0123 = 0x01 as least significant byte and 0x23 as most significant byte, resulting in a value of 8961
 
 The Littlefs filesystem should start on a page boundary of the eeprom. If your eeprom has a page size larger than 32 bytes, this means there will be gap between the header and the filesystem. If your eeprom has a page size smaller than 32 bytes, this means the header will use more than one page.
- 
+
 The filesystem should contain a file named `app.py` which contains micropython code conformant to the app framework API (to be disclosed). It may contain other Python files or data.
 
 # Example

diff --git a/docs/technical-reference/hexpansions.md → docs/hexpansions/index.md b/docs/technical-reference/hexpansions.md → docs/hexpansions/index.md
@@ -1,7 +1,7 @@
-Hexpansion hardware developer guide
-===
+# Hexpansion hardware developer guide
 
 # tl;dr:
+
 - Hexpansions **MUST BE 1mm thick!** (more on this below)
 - Hexpansions can be a PCB, or can be made of any other **non-conductive material**
 - Hexpansions that are a PCB must have **ENIG finish**.
@@ -12,7 +12,6 @@ Hexpansion hardware developer guide
 - Hexpansions may **not** contain anything that uses the I2C address **0x77**
 - Use the **KiCad template project** provided
 
-
 ## What is a hexpansion?
 
 A Hexpansion is a thing that plugs into one of the hexpansion ports of a tildagon badge (and hopefully into other things in the future).
@@ -22,7 +21,7 @@ specifies a 0.1 mm tolerance for thickness.
 
 You can make a Hexpansion by cutting out a shape out of any sufficiently stiff non-conductive material. The simplest Hexpansion is a piece of 1mm cardstock cut into a particular shape.
 
-If you're laser-cutting a hexpansion out of plastic, note that *cast* acrylic sheet can vary quite a lot in thickness. *Extruded*
+If you're laser-cutting a hexpansion out of plastic, note that _cast_ acrylic sheet can vary quite a lot in thickness. _Extruded_
 acrylic sheet has better dimensional tolerance and is recommended for building hexpansions.
 
 There are some [example 3D printable STL files on Printables](https://www.printables.com/model/826094-emf-tildagon-hexpansion-template), which may be useful as a starting point for prototyping. These have been tested and fit in the slots of a prototype of the 2024 badge.
@@ -31,7 +30,7 @@ There are some [example 3D printable STL files on Printables](https://www.printa
 
 To fit into the slot, the Hexpansion has to have a tab sticking out that is **9.2mm** wide and **6.5mm** long. That tab is 17.75mm away from the board edge.
 
-![](hexpansions/b456ffb9-f5bf-4387-b8ec-fd9796ad957b.png)
+![](./b456ffb9-f5bf-4387-b8ec-fd9796ad957b.png)
 
 The standard hexpansion shape is a hexagon with 32mm between flats. This means the distance between points is approximately 36.65mm. This shape puts the edge of the badge exactly down the middle of the hexagon. You can make the part on the outside any shape you like, but you have to keep it within the continuation of the lines of the hexagon, so it won't interfere with other hexpansions. If you intend for something to plug into your hexpansion, make sure that the plug also does not cross into the adjacent segment.
 
@@ -53,18 +52,18 @@ If your hexpansion is electronic, it will connect to the tildagon with some pads
 
 The connector has the same pinout at the SFP interface used in networking equipment (if you feel like making an extremely cursed transceiver, go ahead!). The pinout is as follows:
 
-| Bot side | Signal  | | Top side | Signal |
-| -------- | --------|-| -------- |--- |
-| 1     | GND        |.| 11     | GND |
-| 2     | Low speed 1|.| 12     | High speed 1 |
-| 3     | Low speed 2|.| 13     | High speed 2 |
-| 4     | I2C SDA    |.| 14     | GND |
-| 5     | I2C SCL    |.| 15     | +3V3 |
-| 6     | Detect     |.| 16     | +3V3 |
-| 7     | Low speed 3|.| 17     | GND |
-| 8     | Low speed 4|.| 18     | High speed 3 |
-| 9     | Low speed 5|.| 19     | High speed 4 |
-| 10    | GND        |.| 20     | GND |
+| Bot side | Signal      |     | Top side | Signal       |
+| -------- | ----------- | --- | -------- | ------------ |
+| 1        | GND         | .   | 11       | GND          |
+| 2        | Low speed 1 | .   | 12       | High speed 1 |
+| 3        | Low speed 2 | .   | 13       | High speed 2 |
+| 4        | I2C SDA     | .   | 14       | GND          |
+| 5        | I2C SCL     | .   | 15       | +3V3         |
+| 6        | Detect      | .   | 16       | +3V3         |
+| 7        | Low speed 3 | .   | 17       | GND          |
+| 8        | Low speed 4 | .   | 18       | High speed 3 |
+| 9        | Low speed 5 | .   | 19       | High speed 4 |
+| 10       | GND         | .   | 20       | GND          |
 
 The Detect pin lets the tildagon know that a hexpansion has been inserted or removed. It also controls power to the hexpansion. The pin has a weak pullup, and you should connect it to GND on your hexpansion. If you want the ability to disconnect power from your hexpansion, you can add a circuit to disconnect Detect from GND.
 
@@ -73,6 +72,7 @@ The +3V3 pins can provide up to 600mA of current at 3.3V. If your hexpansion nee
 Pins 4 and 5 provide an I2C interface. Each hexpansion port has a separate I2C interface. You can put any devices you like on that bus, and they can use any I2C address, **except 0x77**. We need that address to talk to our I2C mux, and if a hexpansion responds to it, we have to disconnect its I2C bus. There are no pullups on the I2C bus - you have to provide those yourself.
 
 If you want code on the tildagon to be able to recognize your hexpansion, you can add an i2c EEPROM. We have currently tested two EEPROM ICs, but many more will work if they have the same address and interface as one of those. The ones we tested are:
+
 - ZD24C64A-XGMT
 - M24C16-RMN6TP
 
@@ -84,12 +84,12 @@ There are five low speed pins (LS1-LS5) that are connected to a GPIO expander IC
 
 There are four high-speed pins (HS1-HS4) that are directly attached to the microcontroller on the Tildagon. Please do not try to source or sink too much current from these pins. You can connect these to any of the peripherals on the ESP32-S3 that are not already in use. Three of the six ports on the tildagon have high-speed pins that are attached to the internal ADC (analogue to digital converter, for measuring analogue signals). They are the connector behind the row of three buttons, and the connectors either side of that (highlighted in the image below).
 
-![](hexpansions/df9d2843-4b89-4341-98a9-61f1c9b1f780.png)
+![](./df9d2843-4b89-4341-98a9-61f1c9b1f780.png)
 
 # Mechanical clearance
 
 Because there is a battery between the top and bottom board of the tildagon, there are restrictions to how tall components on hexpansions can be. Here are the height restrictions and their relevant areas:
 
-![](hexpansions/52437fff-3c14-4c18-aa22-a656f64f00f0.png)
+![](./52437fff-3c14-4c18-aa22-a656f64f00f0.png)
 
 The two upper hexpansion slots are right above the two USB connectors. Because of the cable overmold there may not be anything sticking out below the board in those slots. Hexpansions that go into other slots have 1mm of clearance below the PCB surface up to the tildagon board edge, and unlimited clearance beyond the edge. If you have through-hole components on your hexpansion PCB, they cannot be used in the slots over the USB connectors as the solder tails below the board will interfere with the USB cable overmolding.
diff --git a/docs/index.md b/docs/index.md
@@ -2,37 +2,53 @@
 
 As in previous years, we're making a badge. Unlike previous years, we're trying to make a longer-lasting platform. We're publishing more information ahead of the event so that people can build things for the badge early on. You can reasonably expect things you build for this year's badge to work in future years too.
 
+<div class="grid cards" markdown>
+
+- [I'm a badge holder and I want to know how to use the badge](using-the-badge)
+- [I'm a software hacker and I want to make a badge app](tildagonos-apps)
+- [I'm a hardware hacker and I want to make a hexpansion](hexpansions)
+- [I'm a volunteer (or I want to be) and I want to hack on badge firmware](tildagonos-firmware)
+
+</div>
+
+!!! info
+
+    Need help?
+
+    - irc: __irc.libera.chat #emfcamp-badge__
+    - matrix: __[#badge:emfcamp.org][matrix]__
+
 ![A hexagonal camp badge, with three smaller hexagonal PCBs containing breakout pins peaking out from the edges, and a screen showing @emfcamp](images/badge-photos/badge-with-screen.jpg "Tildagon with attached Hexpansions and screen")
 
 This year's badge is the Tildagon badge. It's a hexagon with a slot on each side that you can plug hexpansions into. A hexpansion is a 1 mm thick object with a particular shape on one edge. It can be made of cardstock, so you can quickly add some cat ears to your badge, or it can be a printed circuit board.
 
 ![A hexagonal camp badge, made up of two PCBs with a gap between them, lit by RGB LEDs on top, with more LEDs shining inside. It has illustrations of cats on the silkscreen.](images/badge-photos/badge-in-the-dark.jpg "Tildagon in the dark")
 
-* Hardware - [emfcamp/badge-2024-hardware](https://github.com/emfcamp/badge-2024-hardware)
-* Software - [emfcamp/badge-2024-software](https://github.com/emfcamp/badge-2024-software)
+- Hardware - [emfcamp/badge-2024-hardware](https://github.com/emfcamp/badge-2024-hardware)
+- Software - [emfcamp/badge-2024-software](https://github.com/emfcamp/badge-2024-software)
 
 ## Badge specs
 
 The processor in the badge will be the same as in 2022, and it will run [MicroPython](https://micropython.org/).
 
-* ESP32-S3 microcontroller with 2MB of PSRAM and 8MB of flash
-* USB-C connector
-* WiFi
-* Six hexpansion connectors
-* Round screen, six buttons, lots of colourful LEDs
-* Power management, motion sensing
+- ESP32-S3 microcontroller with 2MB of PSRAM and 8MB of flash
+- USB-C connector
+- WiFi
+- Six hexpansion connectors
+- Round screen, six buttons, lots of colourful LEDs
+- Power management, motion sensing
 
 ## Hexpansions
 
 ![A small spirit level, attached to a 3D printed hexagonal mount with notches to attach it to the badge. The mounting hexagon is slightly larger than the thumb holding it.](images/badge-photos/hexpansion.png "A Hexpansion")
 
 Hexpansions are things that plug into the badge's expansion connectors. Almost anything can be a hexpansion: the simplest hexpansion is just a piece of 1 mm card cut into the right shape. Hexpansion connectors provide:
 
-* Up to 600mA of 3.3V power (current-limited)
-* An I2C bus (separate for each hexpansion)
-* 4 high-speed GPIO pins connected directly to the ESP32-S3
-* 5 lower-speed GPIO pins connected to a GPIO expander/LED driver
-* 1 hexpansion detection pin (also used to switch power to the hexpansion on/off if needed)
+- Up to 600mA of 3.3V power (current-limited)
+- An I2C bus (separate for each hexpansion)
+- 4 high-speed GPIO pins connected directly to the ESP32-S3
+- 5 lower-speed GPIO pins connected to a GPIO expander/LED driver
+- 1 hexpansion detection pin (also used to switch power to the hexpansion on/off if needed)
 
 A hexpansion can optionally provide an I2C EEPROM from the list of approved devices. If an EEPROM is present, the badge will be able to read a hexpansion identifier and name. You can also store code on the EEPROM, which will be copied to the badge and run from there.
 
@@ -50,28 +66,30 @@ In future events, we will reuse the base part and maintain compatibility in soft
 
 ## A list of variously realistic hexpansion ideas
 
-* GPS / compass / IMU (for joust)
-* Buzzer (for notifing the wearer and joust)
-* Speaker (for notifying everyone near the wearer and joust)
-* Heart rate monitor
-* Modular synthesizer
-* Pretty / blinding LEDs
-* ePaper
-* Actual paper
-* Sandpaper
-* Cat ears
-* Drone arms
-* Hexapod legs
-* Fuzzy tail
-* Googly eyes
-* Memory card reader
-* RFID reader
-* TV-b-gone
-* Infrared communication port
-* Ultrasonic emitter
-* Big red button
-* Weather station
-* Bicycle mount
-* Polearm attachment
-* Gnat attractor
-* Keyboard
+- GPS / compass / IMU (for joust)
+- Buzzer (for notifing the wearer and joust)
+- Speaker (for notifying everyone near the wearer and joust)
+- Heart rate monitor
+- Modular synthesizer
+- Pretty / blinding LEDs
+- ePaper
+- Actual paper
+- Sandpaper
+- Cat ears
+- Drone arms
+- Hexapod legs
+- Fuzzy tail
+- Googly eyes
+- Memory card reader
+- RFID reader
+- TV-b-gone
+- Infrared communication port
+- Ultrasonic emitter
+- Big red button
+- Weather station
+- Bicycle mount
+- Polearm attachment
+- Gnat attractor
+- Keyboard
+
+[matrix]: https://matrix.to/#/#badge:emfcamp.org
diff --git a/docs/tildagonos-apps/guides/ui-widget-overview.md b/docs/tildagonos-apps/guides/ui-widget-overview.md
@@ -0,0 +1,3 @@
+# UI Widget Overview
+
+WIP
diff --git a/docs/tildagonos-apps/guides/using-badge-hardware.md b/docs/tildagonos-apps/guides/using-badge-hardware.md
@@ -0,0 +1,3 @@
+# Using Badge Hardware
+
+WIP
diff --git a/docs/tildagonos-apps/how-to-write-a-tildagon-os-app.md b/docs/tildagonos-apps/how-to-write-a-tildagon-os-app.md
@@ -0,0 +1,19 @@
+# How To Write A Tildagon OS App
+
+This guide will help you write an "Hello, World" app for the Tildagon badge.
+
+!!! danger
+
+      This guide is not yet available
+
+## What next?
+
+<div class="grid cards" markdown>
+
+- [Tildagon OS Programming Interface Reference](./reference)
+- [Interfacing with badge hardware](./guides/using-badge-hardware)
+- [Using the badge simulator][simulator]
+
+</div>
+
+[simulator]: https://github.com/emfcamp/badge-2024-software/tree/main/sim
diff --git a/docs/tildagonos-apps/index.md b/docs/tildagonos-apps/index.md
@@ -0,0 +1,30 @@
+# Tildagon OS Apps
+
+Tildagon OS is the name for the firmware that runs on the badge. It is based on
+MicroPython, and provides some software interfaces for apps to use to interact
+with the badge hardware, and to provide a user interface.
+
+## App Development
+
+!!! warning
+
+    This is a work in progress. The badge firmware is not yet ready for general
+    use.
+
+You can write apps for the badge in micropython. In development you can use your
+hardware badge for testing your code, or you can use the [simulator].
+
+You can use most micropython libraries, and for some functionality we provide
+abstractions - for example, a semantic interface to the buttons, so that your
+app uses a consistent button interface to other apps.
+
+For more info check out our [Getting Started guide](./how-to-write-a-tildagon-os-app).
+
+## Publishing your app
+
+Apps can be published to the app store to be made available to other EMF2024
+attendees. To publish your app to the app store, put your app in a GitHub
+repository and make sure it's accompanied with an app manifest. Tag your repo with
+the `tildagon-app` tag, and the app store will pick it up within about 10 minutes.
+
+[simulator]: https://github.com/emfcamp/badge-2024-software/tree/main/sim