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
• 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 a broken wire. Not sure whether I just got a bad batch, or whether they are just bad quality in general, but I recommend you keep that in mind when ordering.

License

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

Public Domain Data

I consider the contents of erfamap-output/ and esp32/src/spacemap.h to be in the public domain.

If they are not, I license these under the Creative Commons CC0 1.0 "No Rights Reserved" license.