Pixels String

Features & Capabilities

Everything the controller does out of the box.

# Effects & Variations

All 24 effects and what each variation does. Set any effect with /api/effect?name=... or by index.

# Hardware Requirements

You need an ESP32, an LED strip, and a power supply. Everything else is optional.

• ESP32 development board
• NeoPixel-compatible LED strip (WS2812B, SK6812, etc.)
• 3.3V-5V level shifter (recommended for longer strips)
• Physical button (optional, GPIO 9 with internal pull-up)
• 5V power supply (sized for your LED count)

Pin Connections

# Getting Started

From a fresh clone to a glowing strip in five steps.

1. Clone and configure

git clone https://github.com/shajanjp/pixels-string.git
cd pixels-string

2. WiFi and network config

Copy the example config and fill in your network details:

cp config.example.h config.h

Then edit config.h:

#define WIFI_SSID       "your-ssid"
#define WIFI_PASSWORD   "your-password"

#define STATIC_IP       IPAddress(192, 168, 1, 55)
#define GATEWAY         IPAddress(192, 168, 1, 1)
#define SUBNET          IPAddress(255, 255, 255, 0)

#define MDNS_HOSTNAME   "pixels-string"

3. (Optional) Modify the dashboard

The dashboard is embedded in the firmware. Edit dashboard.html, then regenerate the embedded header:

npm install
node html-to-header.js

This minifies the HTML, CSS, and JS and produces dashboard_html.h, which is compiled into the firmware.

4. Upload to your ESP32

Open pixels-string.ino in the Arduino IDE or VS Code with PlatformIO, select your ESP32 board, and upload. Required libraries:

• Adafruit_NeoPixel - LED strip driver
• HomeSpan - Apple HomeKit support (Lightbulb + effect switches)
• WiFi, ESPmDNS, Preferences - included with the ESP32 core

5. Find your device

• Check your router's DHCP client list for the static IP you configured
• Or use mDNS: http://pixels-string.local

# Configuration

What lives in config.h and what can be changed at runtime.

Network settings (config.h)

Runtime settings (persisted in NVS)

These are configured via the API and survive reboots:

# Using the Device

Control the strip two ways: the web dashboard or the physical button.

Web dashboard

Open the device's root URL (http://pixels-string.local or your static IP) in any browser. The ESP32 serves a full-featured dashboard where every effect is a card with an animated icon:

• Click a card to activate that effect
• Click the same card again to cycle through its 5 variations - a toast notification shows the variation number
• The active effect is highlighted with a glowing border

The dashboard also exposes power and brightness controls plus a Custom Pixels editor with solid, striped, gradient, and custom range patterns, all with live API feedback.

Saved Presets

A Saved Presets panel lets you keep and reuse your custom looks. From the Custom Pixels modal, give your current configuration a name and save it - the preset appears as a button on the dashboard's home page, painted with a 7-dot preview that mirrors your pattern:

• Save - name and save the current pattern, colors, percentage, and custom ranges from the Custom Pixels modal
• Reapply with one click - clicking a preset button sends the same /api/pixels/set request as the modal's Apply button
• Overwrite - saving a name that already exists replaces that preset
• Delete - a small × control appears on each preset button on hover
• Per-browser - presets are stored in the browser's localStorage, so no state is saved on the device

Physical button controls

# REST API

All endpoints are served on port 80 and accept plain GET requests with query parameters. JSON endpoints return readable, unescaped JSON for easy parsing.

GET /api/effect?name=AURORA
GET /api/effect?index=2    # index 2 = Aurora

GET /api/variation?index=2

GET /api/power?state=off

GET /api/brightness?value=128

{
  "effect": "AURORA",
  "effectIndex": 2,
  "variation": 2,
  "variationMax": 4,
  "power": "on",
  "numEffects": 24,
  "ledCount": 50,
  "brightness": 255,
  "colorOrder": "GRB"
}

GET /config                              # read current config
GET /config?colorOrder=BGR               # set color order
GET /config?ledCount=100                 # set LED count
GET /config?colorOrder=GRB&ledCount=120  # both at once

{
  "colorOrder": "GRB",
  "colorOrderValue": 2,
  "ledCount": 120,
  "brightness": 255,
  "effect": "AURORA",
  "power": "on"
}

GET /api/pixels/set?pattern=solid&color=FF0000

GET /api/pixels/set?pattern=striped&color=FF0000&color=00FF00&color=0000FF

GET /api/pixels/set?pattern=gradient&color=FF0000&color=0000FF&brightness=128

GET /api/pixels/set?pattern=gradient&color=FF0000&color=0000FF&percentage=50

GET /api/pixels/set?pattern=custom&range=1-10:FF0000&range=11-20:0000FF&range=21-25:00FF00

# MCP (Model Context Protocol)

The device speaks the Model Context Protocol over HTTP, so AI assistants can control the LEDs directly.

The ESP32 hosts a minimal MCP server at POST /mcp (JSON-RPC 2.0). Register it as a remote MCP server in any MCP client - Claude Desktop, MCP Inspector, and others - using the device URL:

{
  "mcpServers": {
    "pixels-string": {
      "url": "http://192.168.1.55/mcp"
    }
  }
}

Exposed tools

Two tools are exposed, both backed by the existing effect, pattern, and brightness code:

apply_animation

set_color

# Apple Home (HomeKit)

Thanks to the HomeSpan library, the ESP32 also exposes the LED strip to Apple Home as a Lightbulb accessory. Once paired, you can control it from the Home app, Control Center, and with Siri.

What HomeKit controls

The device exposes two accessories.

Because HomeKit has no native “effect/mode” menu, each of the 24 animations is exposed as its own switch. You can trim this list in homekit.h if you only want a few favorites (delete the corresponding new EffectSwitch(...) lines).

Wiring & networking

HomeSpan takes over WiFi connection and mDNS (it must own the connection to start its HomeKit server). It keeps your static IP from config.h, and its HAP server runs on port 8080 so it does not clash with the REST API on port 80.

Required partition scheme (IMPORTANT - do this first)

HomeSpan makes the firmware ~1.58 MB, which is too large for the default partition scheme (1.3 MB app slot). If you upload without changing it you will get Sketch too big / text section exceeds available space in board. To fix it, give the app a 2 MB slot:

• In the Arduino IDE: Tools > Partition Scheme > No OTA (2MB APP/2MB SPIFFS)
• With arduino-cli: arduino-cli compile --fqbn "esp32:esp32:esp32:PartitionScheme=no_ota" .

Pairing with Apple Home

1. Flash the sketch and power the ESP32.
2. Open the Serial Monitor (115200 baud) and watch HomeSpan start up. It prints the device’s pairing QR and setup code.
3. On your iPhone/iPad, open the Home app > + > Add Accessory, and scan the QR (or tap More options and enter the setup code).
4. The device appears as LED Strip.