Merge pull request #8 from npentrel/front-page

Update front page

Pipfile

@@ -6,6 +6,7 @@ name = "pypi"
 [packages]
 mkdocs = "*"
 mkdocs-material = "*"
+mkdocs-glightbox = "*"
 
 [dev-packages]
 

README.md

@@ -0,0 +1,50 @@
+# Tildagon Badge Documentation
+
+This is the source for the [Tildagon Badge Documentation](https://tildagon.badge.emfcamp.org/).
+Contributions are welcome!
+
+## Testing the documentation on your computer
+
+### Project Setup
+
+Run these commands to set up a Python virtual environment and install the required packages for the project in the project folder:
+
+```sh
+pip install pipenv
+pipenv install
+```
+
+You only need to run this command once.
+To activate the virtual environment, run:
+
+```sh
+pipenv shell
+```
+
+If you open a new terminal window, navigate back to the project folder and activate the virtual environment again.
+
+### Serve the docs locally
+
+To serve the docs locally on your machine, run the following command:
+
+```sh
+mkdocs serve
+```
+
+### Generate HTML docs
+
+To generate the full HTML version of the docs run:
+
+```sh
+make build-prod
+```
+
+You can serve the resulting docs with:
+
+```sh
+python3 -m http.server 9000 --directory public
+```
+
+## Contribute to the documentation
+
+Want to improve our documentation? Please do! You can [open a PR](https://docs.github.com/en/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop) and we'll take a look.

docs/hexpansions/index.md

@@ -26,6 +26,18 @@ acrylic sheet has better dimensional tolerance and is recommended for building h
 
 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.
 
+## Connectors
+
+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)
+
+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.
+
 ## Shape and size
 
 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.

docs/index.md

@@ -1,99 +1,116 @@
 # Tildagon
 
-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.
+![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"){: style="width:300px; height: auto" , align=right }
 
-<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)
+This year's badge is the Tildagon badge. It's a hexagon with a slot on each side that you can plug _[hexpansions](#hexpansions)_ into. A hexpansion is a 1 mm thick object with a hexagon shape on one edge (a six-sided polygon like this: ⬡). It can be made of cardstock, so you can quickly add some cat ears to your badge, or it can be a printed circuit.
 
-</div>
+Unlike in previous years, [Emfcamp](https://www.emfcamp.org/) is trying to make a [longer-lasting platform](#a-reusable-platform-with-an-interchangeable-part) so any apps developed for it will work for multiple years.
 
-!!! info
+<br>
 
-    Need help?
+## What would you like to do with your badge?
 
-    - irc: __irc.libera.chat #emfcamp-badge__
-    - matrix: __[#badge:emfcamp.org][matrix]__
+<div class="grid cards" markdown>
 
-![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")
+- [I want to know how to use the badge](using-the-badge)
+- [I want to make a badge app](tildagonos-apps)
+- [I want to make a hexpansion](hexpansions)
+- [I want to hack on badge firmware](tildagonos-firmware)
 
-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.
+</div>
 
-![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")
+!!! info "Need help? Ask here:
 
-- Hardware - [emfcamp/badge-2024-hardware](https://github.com/emfcamp/badge-2024-hardware)
-- Software - [emfcamp/badge-2024-software](https://github.com/emfcamp/badge-2024-software)
+    - irc: __irc.libera.chat #emfcamp-badge__
+    - matrix: __[#badge:emfcamp.org][matrix]__
 
 ## Badge specs
 
-The processor in the badge will be the same as in 2022, and it will run [MicroPython](https://micropython.org/).
+![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"){: style="width:300px;height: auto;margin:auto;display:block;" }
 
 - ESP32-S3 microcontroller with 2MB of PSRAM and 8MB of flash
 - USB-C connector
 - WiFi
-- Six hexpansion connectors
+- Six [hexpansion](#hexpansions) connectors
 - Round screen, six buttons, lots of colourful LEDs
 - Power management, motion sensing
 
+!!! info "The processor in the badge is the same as in 2022, and it will run [MicroPython](https://micropython.org/)."
+
 ## 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)
-
-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.
-
-The hexpansion technical documentation, pinout, and paper and PCB templates for them, are in [this repository](https://github.com/emfcamp/badge-2024-hardware).
-
-## Why are we doing this?
-
-We're tired of building the same thing over and over just to make it new and special. We're tired of putting ever-increasing stacks of e-waste into the drawers of the hacking world. We're especially tired of people not being able to meaningfully build things for the badge before the event, and none of those things working by the next event.
-
-Instead of redesigning badges from scratch every two years, we're building a reusable platform with an interchangeable part that is specific to the event, and a base part which will remain compatible over multiple years. This will not only let us waste less effort and fewer materials, but also provide all attendees with a stable base to build on. We're putting more effort and better parts than usual into the base board, providing infrastructure so we don't have to remake things that tend to stay the same, or rewrite software and drivers for every event. We've put all the power management, communications, USB, expansion connectors, storage, motion sensing, and battery charging into this board.
-
-We want to let you make physical things that interact with the badge more easily, in the knowledge that those things are going to continue working with future event badges. In previous years, expandability has always been an afterthought - people still managed to do amazing things with their badges, but it was a lot of effort.
-
-In future events, we will reuse the base part and maintain compatibility in software and hardware for the existing hexpansions. We put all the expensive and hard-to-get-right functionality on the base part, so that we don't waste those parts and it doesn't end up in a drawer forever. The most energy-intensive part of each badge is the battery, so we've made it compatible with the batteries from the 2016 and 2018 badges. Instead of having a lanyard, we are making the USB cable itself be the lanyard for this badge - cables in different lengths are available for people of different sizes, and it can also be used for badge-to-badge and badge-to-computer communication.
-
-## 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
-
-[matrix]: https://matrix.to/#/#badge:emfcamp.org
-[using-the-badge]: "./using-the-badge"
-[tildagonos-apps]: "./tildagonos-apps"
-[hexpansions]: "./hexpansions"
-[tildagonos-firmware]: "./tildagonos-firmware"
+![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"){: style="width:300px;height: auto;margin:auto;display:block;" }
+
+Hexpansions are accessories 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 hexagonal shape.
+
+??? note "Expand to show 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
+
+
+For more information, see:
+
+- [Hexpansion hardware developer guide](/hexpansions/).
+- [Technical documentation, pinout, and paper and PCB templates][badge-2024-hardware].
+
+## A reusable platform with an interchangeable part
+
+Instead of redesigning badges from scratch every two years, we're building:
+
+- a reusable platform
+- a base part which will remain compatible over multiple years.
+  The base contains power management, communications, USB, expansion connectors, storage, motion sensing, and battery charging into this board
+- an interchangeable part that is specific to the event
+
+### Why are we doing this?
+
+We want to let you make physical things that interact with the badge more easily, in the knowledge that those things are going to continue working with future event badges.
+In previous years, expandability has always been an afterthought - people still managed to do amazing things with their badges, but it was a lot of effort.
+
+Additionally, we're tired of building the same thing over and over just to make it new and special.
+We're tired of putting ever-increasing stacks of e-waste into the drawers of the hacking world.
+We're especially tired of people not being able to meaningfully build things for the badge before the event, and none of those things working by the next event.
+
+The Tildagon will not only let us waste fewer materials, but it also provides us and attendees with a stable base to build on and invest in.
+
+For us, the stable infrastructure means we do not need to rewrite software and drivers for every event.
+Instead we can focus our efforts on the smaller event-specific part.
+
+Investing in the Tildagon for multiple years also means we've put more effort and better parts than usual into the base board.
+We put all the expensive and hard-to-get-right functionality on the base part.
+In future events, we will reuse this base part and maintain compatibility in software and hardware for existing hexpansions.
+
+The most energy-intensive part of each badge is the battery, so we've made it compatible with the batteries from the 2016 and 2018 badges.
+
+Instead of having a lanyard, we are making the USB cable itself be the lanyard for this badge - cables in different lengths are available for people of different sizes, and it can also be used for badge-to-badge and badge-to-computer communication.
+
+[badge-2024-hardware]: https://github.com/emfcamp/badge-2024-hardware
+[badge-2024-software]: https://www.github.com/emfcamp/badge-2024-software
+[badge-2024-documentation]: https://www.github.com/emfcamp/badge-2024-documentation
+[badge-2024-app-store]: https://www.github.com/emfcamp/badge-2024-app-store
+[badge-tent-volunteering]: ./badge-tent-volunteering.md

mkdocs.yml

@@ -35,4 +35,6 @@ markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
+plugins:
+   - glightbox