# SpaceAPI LED Map

A map of hackerspaces lasercut from plywood, with their [SpaceAPI][spaceapi] opening states shown in red and green LEDs.

The LEDs are WS2812-compatible bulb-shaped LEDs, and they are controlled by an ESP32-C3 board.

This is a work in progress (2nd half 2024) project; documentation will be updated as the project progresses.

## Contents of This Repository

### erfamap-output/

The data for lasercutting the map was generated using a modified
version of my [Erfamap][erfamap] project, which uses the
[api.spaceapi.io][api.spaceapi.io] SpaceAPI aggregator instead of the
CCC internal Wiki to determine which dots to place where.  A lot of
this data was edited by hand in order to improve it for laser cutting.

- `spaceapi-info.json` is the cache file used by the modified script.
  It has been edited manually to remove some entries which had broken
  or unsuitable API endpoints.
- `map.svg` is the output file generated by the modified script.
- `map-prepared.svg` is the file that has been prepared for laser cutting and engraving:
  - Labels have been move manually so that they are easier to assign to the correct LED, and so they don't overlap with any of the country borders.
  - Text has been converted to paths.
  - All paths have been assigned to layers corresponding to how they should be processed.

The modified Erfamap script will be released at a later point after some further cleanup.

### pcb/

The KiCad project for the PCBs that connect everything together.

Each PCB connects to 10 LEDs, and the PCB can be chained together to
form a single WS2812 chain.  There are 83 LEDs in the current version, so a total of 9 of these PCBs is required.
The ESP32-C3 needs to be soldered to the first PCB.

### esp32/

The PlatformIO Arduino project for the ESP32.  It perfoms the following tasks:
- Connect to the WiFi network defined at compile time
- Obtain the current time through NTP
- Fetch the aggregated SpaceAPI responses from api.spaceapi.io and parse the JSON response
- Update the WS2812 LEDs

Compile and upload to the ESP32 using PlatformIO:

```bash
export ESP32_WPA2_SSID=the-wifi-ssid
export ESP32_WPA2_PSK=the-wifi-psk
pio run -t upload
```

### led_plugging_tool/

A 3D-printable tool that helps with cutting the LED legs to size and attach them to JST ZH-4 connectors the correct way.

Usage:

1. Print the tool on a 3D printer.
2. Put a LED bulb-first into the tool hole.  Especially on first use, make sure that it's all the way in.
    - The LED should only fit in one orientation.
3. Use a pair of wire cutters to cut the LED legs as close to the tool's surface as possible.
4. Take a cable fitted with JST ZH-4 connectors and push one connector firmly onto the LED legs inside the tool.
    - The connector, too, should only (fully) fit in one orientation.
	- You may need to bend the LED legs a little to get them to a pitch close enough to 1.5mm that the connector will slide on.
5. Pull the cable to remove the connector and LED from the tool.
6. Repeat steps 2-5 for every LED you need to prepare.

## Components

- WS2812-compatible 5mm bulb LEDs: https://de.aliexpress.com/item/1005005003701575.html
- Black 5mm LED sockets: https://de.aliexpress.com/item/1005005062684329.html
- ESP32-C3 Super Mini: https://de.aliexpress.com/item/1005006252882434.html
- JST-ZH cables: https://de.aliexpress.com/item/1005007298855435.html (4P, Reversed)


[spaceapi]: https://spaceapi.io
[erfamap]: https://git.kabelsalat.ch/s3lph/erfamap
[api.spaceapi.io]: https://api.spaceapi.io/