hue-switch-console

Web console (Vercel + Neon Postgres) for Wi-Fi Hue wall switches. It never talks to the Bridge. A XIAO or npm run push-from-bridge uploads topology. Humans sign in with Google, GitHub or an emailed code (a password on self-hosted consoles without email). Devices use an API key.

Two products, one console:

• Simple (hue-simple-switch, ESP32-C6) — GPIO channels (boot and d0–d5), recipes per channel and event.
• Round (hue-round-switch, ESP32-S3 + circle) — pages (room/zone group, tap / double-tap, scene lists, dimmer). Not GPIO.

Everything in the three repos is English: UI, docs, comments.

This repo owns the contract the switches implement:

• Device HTTP contract: docs/device-api.md.
• USB protocol (Setup ↔ firmware): docs/usb-protocol.md.
• Product model: docs/definitions.md.
• Round pages: docs/round-pages.md.
• Cross-repo changes: AGENTS.md ("Multi-repo") and the "Contract change" issue template.

Shipped specs and prototypes are kept as history in docs/archive/.

Production host: https://hue.tineira.com.

Local

cp .env.example .env.local
# DATABASE_URL (your own Postgres; DATABASE_DRIVER=pg unless it is Neon),
# AUTH_SECRET, USER_EMAIL, USER_PASSWORD, EMAIL_DEV_CONSOLE=1
npm install
npm run dev

Use a development database, never production. The console creates its tables and the first user on the first request. The schema lives in db/schema.sql; after editing it, run npm run schema and commit lib/generated/schema.ts too (CI checks they match). Open http://localhost:3000/login and sign in with USER_EMAIL / USER_PASSWORD. Full walkthrough: CONTRIBUTING.md.

Boards are flashed and provisioned from Setup (/setup; /devices and /install redirect there) in Chrome or Edge over USB. That screen writes Wi-Fi (Improv) and a device token (HUESET), and points the XIAO at DEVICE_CONSOLE_URL (else BETTER_AUTH_URL, else the Setup page's own address). The hosted console sets https://hue.tineira.com. A board cannot reach localhost: to test against a local console, set DEVICE_CONSOLE_URL to your machine's LAN address. Nothing is compiled into the firmware: config.h holds only SERIAL_DEBUG, in dev too. Firmware images are uploaded by firmware CI and served from the database (see below).

On a PC that can reach the Bridge:

# PowerShell
$env:HUE_BRIDGE_IP="192.168.100.12"
$env:HUE_APP_KEY="your-hue-key"
$env:CONSOLE_TOKEN="hsw_…"
$env:CONSOLE_URL="http://localhost:3000"
npm run push-from-bridge

Self-hosting

You can run your own console (on Vercel, a home server or a Raspberry Pi) and set up switches that talk to it instead of hue.tineira.com. In short:

• Postgres, AUTH_SECRET, USER_EMAIL and USER_PASSWORD (below), plus DEVICE_CONSOLE_URL: the address switches use to reach your console. Setup writes it to each board and shows it first.
• Switches need either a public name with a real certificate (https://) or plain http:// on your LAN, with Setup opened at http://localhost:3000 on the server. Private CAs do not work.
• Firmware: node scripts/import-firmware.mjs <round|simple> copies the hosted console's current release, or your fork of a firmware repo uploads its own builds once you set the CONSOLE_UPLOAD_URL variable and FIRMWARE_UPLOAD_TOKEN secret.

Step by step: docs/self-hosting.md.

Accounts and sign-in

Sign-in is Better Auth running inside the console on the same Postgres; there is no auth service to sign up for. Design history: docs/archive/specs/multi-user-accounts.md.

Self-hosting needs only DATABASE_URL, AUTH_SECRET, USER_EMAIL and USER_PASSWORD. That gives one account with a password; sign-up stays closed. Neon is the default driver; for any other Postgres set DATABASE_DRIVER=pg.

Hosted (hue.tineira.com) adds, each optional and off until set:

Env var	Turns on
RESEND_API_KEY, EMAIL_FROM	Emailed 6-digit codes, invites and notices. Password sign-in turns off. EMAIL_FROM e.g. Hue Switch <[email protected]> (domain verified in Resend)
SIGNUP_MODE	closed (default), invite, waitlist or open: the starting mode. A mode saved in /admin → Settings wins over it. Without email the console is always closed
USER_CAP	Seats (accounts plus unused invites) the waitlist mode fills automatically, until the admin saves a cap in /admin (default: no cap)
WAITLIST_EMAILS_PER_DAY	Waitlist invites and confirmations a day, within EMAIL_DAILY_CAP (default 40)
RESEND_WEBHOOK_SECRET	Resend webhook at /api/webhooks/resend (email.bounced, email.complained, email.suppressed): undeliverable addresses leave the waitlist
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	Continue with Google. Callback https://<host>/api/auth/callback/google
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET	Continue with GitHub. Callback https://<host>/api/auth/callback/github
TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY	Cloudflare Turnstile on the email and waitlist forms
BETTER_AUTH_URL	Public URL for OAuth callbacks and links in emails (else taken from the request)
ADMIN_EMAILS	Comma-separated admins for /admin (default: USER_EMAIL)
CRON_SECRET	The daily cleanup cron (vercel.json)
EMAIL_DAILY_CAP	Emails a day before email sign-in says it is busy (default 90, under Resend's free 100)
LIMIT_SWITCHES, LIMIT_BRIDGES, LIMIT_KEYS, LIMIT_SNAPSHOT_KB

Local development without sending mail: EMAIL_DEV_CONSOLE=1 prints codes to the server log instead (never in production).

Device API

See docs/device-api.md. Short version:

• POST /api/device/register — Bearer device key; MAC, firmware, product, channels, rich snapshot
• GET /api/device/config?mac= — Simple: { rev, recipes[] } with channelId. Round: { rev, product, pageSwipeAxis, screenTimeoutSec, pages[], recipes[] } with pageId (not recipes-only)
• PUT /api/switches/{mac}/recipes — logged-in user, Simple GPIO
• PUT /api/switches/{mac}/pages — logged-in user, Round pages

POST /api/ingest is gone (410). Postgres replaces the old file / KV store.

Firmware TLS against https://hue.tineira.com must verify the certificate.

Docs-only pushes

Vercel skips the build when everything since the last successful deployment is docs (docs/, *.md), or when the commit message has [skip deploy] (vercel.json ignoreCommand, scripts/vercel-ignore.sh). docs/changelog.md still deploys, since /changelog reads it. The firmware repos do the same for their release workflow; there the manual tag is [skip ci].

Firmware release pipeline

A push to main in a firmware repo uploads a release candidate to the console. It is stored, and it waits in /admin until a signed-in admin presses Make current. Only then does Setup offer it to boards plugged in over USB, Switches offer it over Wi-Fi, and /changelog list it. No commit lands in this repo and nothing redeploys.

push to main (hue-round-switch / hue-simple-switch)
  → .github/workflows/firmware.yml: build (SERIAL_DEBUG 0), read FIRMWARE_VERSION
  → notes = that version's section of the firmware repo's CHANGELOG.md
  → POST https://hue.tineira.com/api/firmware/<product>      [FIRMWARE_UPLOAD_TOKEN]
  → Postgres: firmware_releases + firmware_parts (approved_at null: waiting)
  → /admin → Firmware: the release is marked "waiting"; an admin presses Make current
  → firmware_current = this release, approved_at set
  → /firmware/<product>/manifest.json, OTA offers and /changelog use it on the next request

The upload token can only add releases. Choosing the current release takes an admin session (ADMIN_EMAILS). This holds for a product's first release too: until an admin makes it current, the product has no manifest and Setup has nothing to install for it. The upload answers 201 (200 for a re-upload of the same bins) with "current": false while the release waits. Bins of a waiting release are not served, and its notes stay off /changelog, Setup and Switches. Releases that were current before this rule existed count as released.

FIRMWARE_VERSION in the firmware source is the version the wizard shows. Bumping it is what makes Setup offer Update. A rebuild without a bump is answered 409 version_exists: the bins stay as they were (their URLs are cached forever) and only the notes are updated. Design history: docs/archive/specs/firmware-uploads.md.

The console checks every upload: all four parts, a major.minor.patch version, non-empty notes, and the chip id inside bootloader.bin / firmware.bin (ESP32-S3 for round, ESP32-C6 for simple). It keeps the bins of the last 5 releases per product, plus the current one and any still waiting. Release rows and their notes are kept for the changelog.

When Setup offers Update, it lists the notes of every version after the board's one up to the release it installs. A bullet that starts with Important: is shown first, with an "Important" label, on Setup and on /changelog. Use it for something the person must know or do before or right after updating (a button to press, a setting that resets), not for new features. Design history: docs/archive/specs/setup-update-notes.md.

Each upload also sends credits: the firmware repo's THIRD_PARTY.json, the third-party software linked into the image (core, ESP-IDF, every library pinned in sketch.yaml). Firmware CI fails when that file and sketch.yaml disagree. The console shows the current release's list on the public /credits page; the field is optional, and a re-upload of the same version replaces it. Design history: docs/archive/specs/credits.md.

Flash layout

The console serves the four parts at fixed offsets, never taken from an upload. Same on both boards (Arduino-ESP32 3.3.12):

Part	Offset	Source
bootloader.bin	0x0	boards.txt build.bootloader_addr for XIAO_ESP32S3 and XIAO_ESP32C6
partitions.bin	0x8000	ESP32 image layout
boot_app0.bin	0xe000	otadata in default_8MB.csv (Round) and hue-simple-switch/partitions.csv
firmware.bin	0x10000	app0 in the same tables

The wizard never erases flash. NVS (Hue, recipes, pages, console) must survive a reflash.

Token

One random secret, FIRMWARE_UPLOAD_TOKEN, stored in three places: Vercel (Production) and the Actions secrets of both firmware repos. To set or rotate it, run in PowerShell from this repo, then redeploy the console:

$t = -join ((1..48) | ForEach-Object { '{0:x}' -f (Get-Random -Maximum 16) }); $t | npx vercel env add FIRMWARE_UPLOAD_TOKEN production; $t | gh secret set FIRMWARE_UPLOAD_TOKEN -R tineira/hue-round-switch; $t | gh secret set FIRMWARE_UPLOAD_TOKEN -R tineira/hue-simple-switch; Remove-Variable t

(To rotate, remove the old Vercel value first with npx vercel env rm FIRMWARE_UPLOAD_TOKEN production.)

Rollback and local builds

To roll back (or forward), open /admin → Firmware as an admin and press Make current on any stored release that still has its bins. Every change is in the admin log. POST /api/firmware/<product>/current, which used to do this with the upload token, now answers 410 gone.

Upload a local build (a folder with the four bins) with scripts/upload-firmware.mjs <product> <dir> --version x.y.z --notes <file> [--credits <file>], where --credits is the firmware repo's THIRD_PARTY.json. It waits in /admin like a CI upload.

A self-hosted console copies a released version from another console with scripts/import-firmware.mjs <product> [--from https://hue.tineira.com] [--version x.y.z] (FIRMWARE_UPLOAD_TOKEN and CONSOLE_URL of the console receiving it). It reads the public manifest, the parts (checked against their SHA-256 ETags) and GET /firmware/<product>/<version>/notes, which returns a released version's { product, version, date, notes, credits } (404 for unknown or waiting versions).

When it breaks

Symptom	Cause
Firmware run fails: FIRMWARE_UPLOAD_TOKEN ... missing; cannot upload the release to the console	Secret missing or empty in that firmware repo
Upload answers 401	The firmware repo's secret and Vercel's differ; set both again
Upload answers 503 upload_not_configured	No FIRMWARE_UPLOAD_TOKEN on Vercel, or no redeploy since it was set
Upload answers 400 missing_notes	No ### <version> section in that repo's CHANGELOG.md
Upload answers 400 invalid_image	A part is missing, empty, or built for the other chip
Upload answers 409 version_exists	Same version, new bins: bump FIRMWARE_VERSION
Upload succeeded but Setup still offers the old version	The release is waiting: make it current in /admin → Firmware

Adding a switch

A new firmware repo needs: a firmware.yml upload step like the existing two, a CHANGELOG.md, the FIRMWARE_UPLOAD_TOKEN secret, its product id in lib/firmware.ts (chip id, family) and lib/web-setup/products.ts, the id in the firmware_releases / firmware_current checks in db/schema.sql (then npm run schema), a ## <Product> intro in docs/changelog.md, and a row in AGENTS.md ("Multi-repo").

Safety

The Simple switch has an in-wall build on mains voltage. The designs are uncertified and some are unproven. Read the Safety notice (/safety on any console, or hue.tineira.com/safety) before you build anything. Every account accepts it, and on hue.tineira.com the Terms, before using the console (docs/archive/specs/terms-and-safety.md).

Contributing

See CONTRIBUTING.md. Bugs and ideas go in GitHub issues.

Open work: GitHub issues.

Sponsor

The console and the switch firmwares are free and stay that way. If they are useful to you, you can sponsor the project on GitHub. Sponsorship helps pay for development and does not unlock anything.

License

Copyright (C) 2026 Tomas Neira and contributors.

The console is free software under the GNU Affero General Public License v3.0 (AGPL-3.0-only). If you run a modified copy as a network service, you must offer its users the source of your version; the site footer's "Source" link does that for this deployment. Contributions are accepted under the same license.

The switch firmwares, hue-round-switch and hue-simple-switch, are MIT. The Simple's mains carrier board and enclosure (hue-simple-switch/hardware/) are CERN-OHL-P-2.0.

Not affiliated with or endorsed by Signify. Philips Hue is a trademark of Signify.