SpaceAPI LED Map

A map of hackerspaces lasercut from plywood, with their 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 project, which uses the 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.

⚠️ 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.

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

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

  ⚠️ 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.

Meaning of the LED Colors

• ⬤ Green: The hackerspace is open.
• ⬤ Red: The hackerspace is closed.
• ⬤ 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.
• ⬤ Blue: The SpaceAPI aggregator service reported the endpoint was last reachable more than 24h ago.
• ⬤ 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:

• ⬤ 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.
• ⬤ 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 otherwise noted, the contents of this repository are licensed under the MIT License (See LICENSE).

Public Domain Data

To the best of my knowledge, the contents of erfamap-output/ and esp32/src/spacemap.h are not protectable by copyright 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 "No Rights Reserved" license.