Pacman Ghost Light for Uptime Kuma

This is the CircuitPython code used to build a Paladone Pac-Man Ghost Light whose lights adjust based on the status of monitors in Uptime Kuma.

Demo of Pacman Ghost Light cycling through the light states:

U1ZuKpI.mp4

(My iPhone camera does not accurately capture the colors)

Requirements:

• Uptime Kuma.
• CircuitPython 8.x.
• Compatible board with Wi-Fi.
• Adafruit NeoPixel-compatible RGB LEDs (ie: WS2812b).

Optional:

• SSD1306-compatible 128x64 display.

Any supported CircuitPython board that provides Wi-Fi, 5v, and 2 pins of GPIO ought to work (plus 3v3 and i2c if using a typical SSD1306 display). I've personally used this on a Raspberry Pi Pico W and ESP-C3-13-Kit. In my general experience, ESP32 boards have better Wi-Fi reliabilitiy than the Pico W. With CircuitPython on the Pico W the Wi-Fi library as of v8.2.10 does not change wifi.radio.connected to False when a Wi-Fi connection becomes unavailable until the radio or board is reset — on the ESP32-C3 it works as expected.

The specific ESP32-C3 board I've used does not seem to be available to purchase anywhere any more, but the ESP-C3-12F-Kit appears to be equivalent and of breadboard-friendly width.

Installation:

Copy everything from the code/ directory to the CircuitPython root. All necessary CircuitPython libraries are included in the code/lib directory.

Note: The adafruit_displayio_ssd1306 library has been modified at line 57 to increase the scan rate. Should that not work for your display, you can revert the modification or drop in the original from Adafruit's CircuitPython Bundle.

Configuration:

There are settings that MUST be configured for this to work.

• settings.toml:

  • METRICS_URL = Complete URL to the Prometheus metrics endpoint on your Uptime Kuma instance (ie: http://something/metrics). Required.
  • API_TOKEN = Your Uptime Kuma API token. Needed if authentication is enabled. See /settings/api-keys on your Uptime Kuma instance.
  • CIRCUITPY_WIFI_SSID = Wi-Fi SSID. Required.
  • CIRCUITPY_WIFI_PASSWORD = Wi-Fi password. Required.
  • CIRCUITPY_WEB_API_PORT = Set to use the CircuitPython Web Workflow (ie: if your board doesn't support the "CIRCUITPY" drive).
  • CIRCUITPY_WEB_API_PASSWORD = Password for the CircuitPython Web Workflow (optional).

• settings.py:

  • General settings:
    • interval_refresh = How often to check Uptime Kuma (in seconds).
    • interval_timeout = How long to wait for Uptime Kuma response (in seconds).
    • use_ntp = [ True | False ] Set the board clock using NTP.
  • Body LED settings:
    • use_body_pixels = [ True | False ]
    • body_pixels_pin = GPIO to use for body LEDs.
    • body_pixels_count = Number of body LEDs.
    • body_pixels_brightness = Body LED brightness, 1 = 100%.
  • Eye LED settings:
    • use_eye_pixels = [ True | False ]
    • eye_pixels_pin = GPIO to use for eye LEDs.
    • eye_pixels_count = Number of eye LEDs.
    • eye_pixels_brightness = Eye LED brightness, 1 = 100%.
  • LCD settings:
    • use_display = [ True | False ]
    • scl_pin = GPIO to use for i2c SCL
    • sda_pin = GPIO to use for i2c SDA

Some combination of Body LED, Eye LED, and LCD settings must be configured, or else it won't do anything beyond outputting to the serial port.

Modifying:

There are a series of functions prefixed with action_ which control the LED states:

• action_Booting: Startup.
• action_NoWifi: Wi-Fi not yet connected.
• action_HaveWifi: Wi-Fi has connection.
• action_Unreachable: Uptime Kuma unreachable / non-responsive.
• action_Pending: Some Uptime Kuma monitors are in the Pending state.
• action_Outage: Some Uptime Kuma monitors are in the Outage state.
• action_Up: All Uptime Kuma monitors are Up.

For testing purposes, set loop_light_states = True in settings.py to infinitely loop through the color states.

Constructing:

Building and wiring up your Pacman Ghost is an exercise left up to you. Frankly, I barely know what I'm doing.

The Pacman Ghost Light shell easily comes apart with four screws on the back and a bit of prying to release the tabs. Stripping out the guts is a couple more screws. My original proof-of-concept version used a Pico W, 5 RGB LEDs for the body, and recycled the white LEDs for the eyes (always on). My second incarnation runs an ESP-C3-13-Kit, uses 9 RGB LEDs for the body, and adds two more RGB LEDs for the eyes. With the eyes I had to scrape the holes and surface a bit for a good-ish fit and hot glued the RGB LEDs in place.

A wiring diagram representative of my ESP32-C3 build:

A wiring diagram representative of my Pico W build:

My test rig:

With a screen for debugging, two "eye" and three "body" LEDs.

(My iPhone camera does not accurately capture the LED colors)