FAQ & troubleshooting
Common questions.
Common fixes.
Accounts, encryption, multi-device setup, and a troubleshooting guide for the seven situations that account for ~95% of support tickets.
General
General
Do I need an Anthropic, OpenAI or Google account? +
Yes — for the CLI side. Not for the device. Each CLI (Claude Code, Codex, Gemini) authenticates against its own provider as it normally does. The wall monitor itself never talks to any of them.
The device only talks to the broker on your laptop, and the broker reads from the CLIs' local on-disk logs. If you don't already have a CLI installed for a given provider, that provider's card will simply not show on the device.
Does it work offline? +
LAN traffic: yes. The device + broker poll each other over your local network with no internet involved.
Internet is needed for two specific things: SNTP (clock sync, once at boot and hourly thereafter) and Open-Meteo (weather + sunrise/sunset for your city, once an hour). If both are unreachable the dashboard still works — the ambient strip just freezes at its last values and the clock drifts.
How fast does the dashboard update? +
The device polls every 2.4 seconds by default. The broker reads CLI logs on every poll (cheap — it's tailing files) and recomputes percentages on the fly. End-to-end latency from "Claude completes a turn" to "the bar moves" is typically < 3 seconds.
Can I run it without a battery? +
Yes. The battery is optional and only there to ride out brief power cuts (~3 hours). Without it the device behaves identically when powered — it just power-cycles if the wall power drops.
Security & privacy
Security & privacy
Where is my passphrase stored? +
Two places, both encrypted at rest, never sent in clear:
- The device: in ESP32
NVS(non-volatile storage), encrypted with the chip's per-unit flash key. - Your laptop: in
~/.cwm/devices.json, mode 0600, encrypted with your OS keychain.
The passphrase never travels over the LAN. Only the derived PSK is sent, once, at pairing time.
What's actually encrypted on the wire? +
Every request from device → broker carries an X-CWM-HMAC header — HMAC-SHA256 over the URL path + body + timestamp, signed with the PSK. The broker rejects anything with a stale timestamp (> 30 s skew) to prevent replay.
The body itself is AES-CTR encrypted with the same PSK. A passive sniffer on your LAN sees only ciphertext.
Does any usage data leave my machine? +
No. The broker reads CLI logs locally and serves them only to devices on your LAN that present a valid HMAC. There is no telemetry endpoint, no crash reporter, no usage analytics. The firmware's only outbound calls are SNTP and Open-Meteo, both of which receive zero AI-related data.
Network & multi-device
Network & multi-device
Multiple devices in the same house? +
Yes. Each device has its own device_id (last 4 hex of MAC) and announces itself on mDNS as cwm-<device_id>.local. The configure skill picks them up individually.
The broker can serve any number of devices on the same LAN. Each gets its own PSK; per-device keys are independent.
5 GHz Wi-Fi? +
No — the ESP32-S3 radio is 2.4 GHz only. If your router has band-steering enabled, make sure the 2.4 GHz SSID is visible and your home network isn't 5-only.
Does it work over VLANs or guest networks? +
Yes, as long as the device and your laptop can reach each other on layer 3. mDNS discovery requires layer-2 reachability (same VLAN or mDNS-reflector configured on your router). If mDNS is blocked, you can still configure the device manually with its IP.
Firmware
Firmware
Can I modify the firmware? +
The firmware is proprietary. Only the documentation, broker (cwm-mcp) and the MCP plugin are public and MIT-licensed. You can absolutely build your own client against the broker's HTTP API — that's the integration point we support — but the device's flash is signed.
How are firmware updates delivered? +
OTA, over the LAN, via the broker. When a new release lands, your CLI surfaces a notice; /cwallmonitor:update downloads + flashes after you confirm. Updates are signed (Ed25519) and verified by the bootloader before any flash erase.
Troubleshooting
Troubleshooting
Seven situations that cover ~95% of "it's not working" cases. Symptom on the top, fix on the bottom.
Screen doesn't turn on at all.
USB-C plugged in, no LED, no backlight, no display.
FixThe supply may be under-rated. ESP32-S3 boot transients spike to ~700 mA; a 500 mA charger will brown out. Try a 5 V / 1 A or higher USB-C source — ideally a dedicated wall adapter, not a hub port.
If a known-good supply still gives nothing, hold the BOOT button while plugging in. If the screen comes up white with boot:0x1 (DOWNLOAD) visible, see the next entry.
Stuck on boot:0x1 (DOWNLOAD).
Device shows a text dump that includes the line above and never advances past it.
FixThe bootloader strapping pin is being held low, usually because the case was assembled with the BOOT button stuck. Power-cycle while pressing nothing — if it persists, open the back and check the BOOT button isn't pinned by the bezel.
If you actually wanted DOWNLOAD mode (developer flashing), this is expected — connect over USB serial and proceed.
Captive portal doesn't appear.
You joined ClaudeWallMonitor-XXXX, but no portal opens in the browser.
Some OSes only auto-open the portal once per network. On macOS, click the Wi-Fi icon and pick "Use without internet"; on iOS / Android, open the network's "log in" prompt manually.
If still nothing, browse directly to http://192.168.4.1/ — the captive page always lives there, even when auto-detect fails.
Data is stale — bars haven't moved in minutes.
Dashboard still shows yesterday's percentages. Status word at the bottom is dimmed.
FixThe broker isn't being reached. Check, in order:
- Is
cwm-mcpactually running on your laptop?curl localhost:9787/health - Is your laptop on the same Wi-Fi as the device? (different SSIDs / VLANs / guest networks fail silently)
- Ask your CLI "tail the last 20 lines of the broker log" — it'll call
wall_monitor_recent_logsand you'll see the rejected polls, if any.
Audio is silent — no chimes on alerts.
FixSettings → Alert volume; default is 30%. If it's already > 0, check the speaker port on the back of the case isn't pressed against the desk or its stand — that flattens the audio. Lift the unit 1 cm or reseat it on its base.
Weather is wrong / shows another city.
FixThe captive portal city selector occasionally matches the wrong municipality when there are name collisions (there are 7 "Madrid"s worldwide). Settings → City lets you re-enter; the editor accepts City, ISO-country like Madrid, ES for an exact match.
Auto theme stuck on Night during the day.
FixAuto follows your configured city's sunrise/sunset, not the laptop's clock. If the city is set to a place in a different timezone, Auto will look wrong. Update Settings → City, or force the theme: /cwallmonitor:theme day.