spaceapi-led-map/README.md

# 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.

![The finished map shown from the front](images/spaceapimap_front.jpg)
![The finished map shown from the back, showing the wiring](images/spaceapimap_back.jpg)


## 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 SpaceAPI
directory 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 is available on the [`spaceapimap` branch of the erfamap repository](https://git.kabelsalat.ch/s3lph/erfamap/src/branch/spaceapimap).  Unfortunately, I did not preserve the command used to generate this exact map, but here's an example to get you started:

    ./generate_map.py --erfa-source spaceapi --long-edge 700 --bbox 3.5 45 15 55 --dotsize-erfa 4.75 --dotsize-chaostreff 4.75 --stylesheet laser.css

### 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.

> :warning: **There is a small issue with V1.0 of the PCB!** (Please check the version number on the silk screen!):
>
> Pins 1 and 4 of the OUT pin header are swapped - this can be easily worked around by swapping wires number 1 and 4 in the JST connector plugged into this header.

### esp32/

The PlatformIO Arduino project for the ESP32.  It perfoms the following tasks:

- If no WiFi AP has been configured yet, it starts an AP on its own
    - Connect to the AP (SSID: `spaceapimap`, PSK: `12345678`)
	- Configure the WiFi network the ESP32 should connect to
- Connect to the WiFi network defined previously
- Obtain the current time through NTP
- Fetch the aggregated SpaceAPI responses from `api.spaceapi.io` and parse the JSON response
- Update the WS2812 LEDs

The list of SpaceAPI endpoints to display is defined in `esp32/src/spacemap.h`.
The position of an endpoint in the `spaces` array corresponds to the index of the WS2812 LED it controls.

To compile and upload the code to the ESP32, use [PlatformIO][pio].

Using the PlatformIO Core CLI, upload should be as easy as this single command:

```shell-session
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.

    ![The 3D printed tool with the LED and connector holes.](images/led_tool_1.jpg)
2. Put a LED bulb-first into the tool hole.  Especially on first use, make sure that it's all the way in.

    ![Insert the LED.](images/led_tool_2.jpg)
  - 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.

    ![Cut the LED legs close to the tool's surface.](images/led_tool_3.jpg)
4. Take a cable fitted with JST ZH-4 connectors and push one connector firmly onto the LED legs inside the tool.

    ![Push the JST ZH-4 connector onto the LED's legs.](images/led_tool_4.jpg)
  - 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.

    ![Pull the assembled piece out of the tool.](images/led_tool_5.jpg)
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
  > :warning: **The vendor appears to sell LEDs with different pinouts as the same product!**
  >
  > I recommend you order the LEDs before you order the PCBs so that you can make changes to the PCB if you receive a different pinout.
  > The PCB design in this repo assumes the following LED pin order (starting from the flat side): `Dout`, `GND`, `5V`, `Din`.
- 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)
  - I recommend you order a mix of 100mm, 200mm and 300mm cables, as you'll be facing a variety of distances, and having shorter cables available makes for much easier troubleshooting.
  - In my order, roughly 10% of the cables had at least one broken wire.  So I recommend you order a bit more than what you actually need.
  - Don't rely on the order of colors in the product description.  I've ordered different batches, and got differently color orders each time.


## Additional Features

### Enter Config Mode on Reset

- Solder a button or pin header between pins D5 and D6 on the ESP32-C3 Super Mini.
  - These are the two pins closest to the USB port on the "unused" side of the ESP board.
- Press and hold the button or short the pin header with a jumper while you press the reset button.
- The ESP32 will now boot into WiFi config AP mode, where you can change the WiFi credentials and some additional parameters.
  - If the configured WiFi can't be found, the ESP32 will automatically boot into config AP mode.
- This feature is configurable, see `platformio.ini` on how to disable it or change the pins to use.

### Automatic Brightness Adaption

- You can plug a voltage divider with a LDR (photoresistor) into the `IN` pin header on the PCB with the ESP32 on it, with the voltage divider's center tap connected to the `Din` pin.
- You can use this to both adapt the LED brightness to the ambient light, and to turn off the LEDs below a certain ambient light level.
- The thresholds can be configured via the web interface in config AP mode (see above).
  - Note that the brightness sensor readings are reversed: High values correspond to darker ambient light levels.
- This feature is configurable, see `platformio.ini` on how to disable it or change the pin to use.
  - It is enabled by default.  If you aren't using an LDR, disabled the feature flag, as otherwise your LEDs may flicker or not turn on at all, because the LDR pin is floating by default.

![Schematic of the voltage divider setup](images/brightness_sensor_schematic.png)
![Photo of a rather messy actual implementation](images/brightness_sensor.jpg)


## Meaning of the LED Colors

- <span style="color: #00ff00;">⬤</span> **Green**:  The hackerspace is open.
- <span style="color: #ff0000;">⬤</span> **Red**:  The hackerspace is closed.
- <span style="color: #ff7f00;">⬤</span> **Orange**:  The SpaceAPI aggregator service reported the endpoint to be invalid.  This can either mean that the endpoint is unreachable, or that it did not validate against any of the SpaceAPI schema versions that it claims to be compliant with.
- <span style="color: #0000ff;">⬤</span> **Blue**:  The SpaceAPI aggregator service reported the endpoint was last reachable more than 24h ago.
- <span style="color: #000000;">⬤</span> **Blank**:  The URL of this hackerspace was not contained in the aggregator's response.  Likely the URL has changed.  Please check the contents of https://api.spaceapi.io, or the recently closed PRs on https://github.com/SpaceApi/directory/ for the correct endpoint and update the ESP's program accordingly.

Apart from these per-space states, error states of the SpaceAPI map itself are reported as follows:

- <span style="color: #000000;">⬤</span> **LED 0 flashes every 10s**:  The last update of the map has failed, most likely due to network issues.  If this issue persists, please connect to the ESP's serial console and check the output.
- <span style="color: #ff00ff;">⬤</span> **Purple LED 0**:  The ESP has just started, and has not yet contacted the SpaceAPI aggregator service.  If this is shown for more than a few seconds, the ESP most likely failed to connect to the configured WiFi network.  If this issue persists, check whether there is a `spaceapimap` WiFi AP in your vicinity, and connect to it to verify the WiFi configuration, or connect to the ESP's serial console and check the output.


## License

Unless noted otherwise, the contents of this repository are licensed under the MIT License (See [LICENSE](LICENSE)).

### Public Domain Data

To the best of my knowledge, the contents of `erfamap-output/` and `esp32/src/spacemap.h` are not covered by Swiss copyright law and are therefore in the public domain.

In case I do have copyright claims on them, I license these under the Creative Commons [CC0 1.0][cc0] "No Rights Reserved" license.




[spaceapi]: https://spaceapi.io
[erfamap]: https://git.kabelsalat.ch/s3lph/erfamap
[api.spaceapi.io]: https://api.spaceapi.io/
[pio]: https://platformio.org/
[cc0]: https://creativecommons.org/publicdomain/zero/1.0/