Hardware manual · rev. 2026-11

TRKeys 4-Key Macropad

A DIY four-button keypad built on an ESP32-C3. A single hardware switch picks one of three completely different personalities at power-on — a Bluetooth keyboard, a Wi-Fi button that fires MQTT messages, or a daily habit tracker.

Mode 1

BLE Keyboard

Each key sends a Bluetooth HID keystroke to a paired computer or phone.

switch detent 3 · A=LOW B=HIGH
Mode 2

Wi-Fi / MQTT

Each key publishes a message to an MQTT broker over Wi-Fi, with LED feedback.

switch detent 2 · A=HIGH B=LOW
Mode 3

Habit Tracker

Four lit LEDs; press a key to mark a habit done for the day. Auto-resets nightly.

switch detent 4 · A=LOW B=LOW
⚙ Configure it in your browser. Everything below — key mappings, Wi-Fi, and MQTT broker details — is editable at runtime with no reflashing, using the TRKeys Configurator. Plug the board in over USB, open the page in Chrome or Edge, and hit Connect. (Web Serial; desktop Chrome/Edge only.)

Overview

TRKeys is firmware for a four-button macropad running on an ESP32-C3 (RISC-V, Wi-Fi + Bluetooth LE). All three modes are compiled into a single firmware image; the active mode is chosen by a physical mode-select switch, which is read at boot and then polled every 50 ms. Slide to another position and the pad follows: moving to or from Off is instant, and moving between two live modes restarts the board by itself — no power-cycling and no reflashing required.

PropertyValue
MicrocontrollerESP32-C3 (QFN32, rev v0.4), 4 MB flash, 40 MHz crystal
FrameworkESP-IDF v5.3.2
Bluetooth stackNimBLE (HID-over-GATT)
Keys / LEDs4 push-buttons, 4 indicator LEDs
Console / flashingNative USB (USB-Serial-JTAG)
BLE device nameTRKeys

Quick start

  1. Pick a mode on the mode-select switch (see the switch map below).
  2. Power the board over USB. On boot the four LEDs blink together to confirm the mode: 1 blink = BLE, 2 blinks = Wi-Fi/MQTT, 3 blinks = Habit tracker. In the two network modes a single light first sweeps back and forth across the keys — 1, 2, 3, 4, 3, 2… — while Wi-Fi associates; the mode blink follows once it is connected, so the blink means ready rather than merely powered.
  3. Use it:
    • BLE — pair with "TRKeys" from your computer/phone Bluetooth menu, then press keys.
    • Wi-Fi/MQTT — the board joins Wi-Fi and connects to the broker; press keys to publish.
    • Habit tracker — all four LEDs light; press a key to switch its LED off for the day.

Board & pinout

Buttons are wired active-low (common leg to GND, sense pin pulled up internally) — pressed reads 0. LEDs are wired active-high — GPIO → LED → GND, with no series resistor — so a GPIO driven high turns the LED on. The LEDs are self-flashing RGB parts, so the firmware controls on and off, not colour.

The pin map is grouped by header for tidy wiring on an ESP32-C3 SuperMini: all four buttons on the left header (beside the 3V3 pin they common to), and the four LEDs plus the mode switch on the right header.

FunctionKey 1Key 2Key 3Key 4Header
Button GPIOGPIO0GPIO1GPIO3GPIO4left
LED GPIOGPIO10GPIO7GPIO6GPIO5right
SignalGPIONotes
Mode-select AGPIO20Input, internal pull-down (right header; the U0RXD pin)
Mode-select BGPIO21Input, internal pull-down (right header; the U0TXD pin)
Console / USBnative USBUSB-Serial-JTAG — flashing, monitor, and the config console all share this port
Button debounce is 20 ms. Buttons trigger on a GPIO interrupt (any edge) and are confirmed after the debounce delay.

Why these pins

On the SuperMini the pin choice is essentially forced. Of the 13 GPIOs on the two headers, three are already spoken for — GPIO8 (onboard LED), GPIO9 (BOOT button / strapping), and GPIO2 (strapping) — leaving exactly ten usable pins for the ten signals (4 buttons + 4 LEDs + 2 mode). The roles are electrically interchangeable, so they're grouped for the cleanest harness: the four buttons on the left header (beside the 3V3 pin they common to), and the four LEDs plus the mode switch on the right header (LEDs on 5/6/7/10, mode on 20/21). The LED cathode rail commons back to the GND pin on the left header, beside 3V3.

The mode switch lands on the UART0 pins (GPIO20/GPIO21). It's read at firmware startup and polled from then on, after those pins are reconfigured as inputs, so the mode read is reliable. The only caveat: a HIGH mode throw momentarily shares GPIO21 (U0TXD) with the ROM's boot-log driver at power-on — harmless in practice, and the reason some layouts prefer to keep the mode switch on quieter pins.

Power & battery

The macropad runs from a single lithium cell charged by a TP4056 module. The cell reaches the SuperMini's 5V pin through pole A of the mode switch, and the board's own LDO produces the 3.3 V rail everything else runs on.

USB-C ──▶ TP4056 ──▶ B+ ─────┬──── Li-ion cell (1S, 3.0–4.2 V)
          (charger)   B- ────┴──── cell −
                             │
                      OUT+ ──┴──▶ [switch pole A] ──▶ SuperMini 5V pin
                      OUT- ──────────────────────▶ SuperMini GND
                                                            │
                                                     onboard LDO
                                                            │
                                                       3V3 rail ──┬── ESP32-C3
                                                                  └── mode-switch common
GND ────────────────────────────────────────────┬── LED cathode rail
                                                └── button common
The cell feeds 5V, never 3V3. A fully charged cell is 4.2 V; the ESP32-C3's absolute maximum supply is 3.6 V. Wiring the battery to the 3V3 pin bypasses the onboard regulator and destroys the chip.

Dropout sets the real cutoff

Producing 3.3 V needs the input above 3.3 V plus the regulator's dropout, and dropout rises with current:

Cell voltageIdle / BLEWi-Fi TX burst (~350 mA)
4.2 V (full)finefine
3.7 V (nominal)finemarginal on a high-dropout part
3.5 Vfinelikely browns out
3.3 V and belowregulator has dropped out — dead

So the practical cutoff is around 3.5 V, not the cell's 3.0 V floor — roughly the bottom fifth of the discharge curve is unusable. That is inherent to an LDO on a 1S cell, not a fault. A 100–470 µF bulk capacitor across 3V3/GND matters more on battery than it did on USB: it is what rides out the Wi-Fi transmit transient as the cell sags.

There is no battery monitoring. All ten usable GPIOs are already allocated, so no ADC pin is free for a divider — the firmware cannot report charge state or warn on low battery. The TP4056's own LEDs (red = charging, blue/green = complete) are the only indication.

Charging

Use the protected TP4056 module — the 6-pin variant with IN+ IN- B+ B- OUT+ OUT-, carrying a DW01A + FS8205 pair. The bare 4-pin version has no over-discharge cutoff and will let the cell drain below 2.5 V and be damaged. Take the load from OUT+/OUT-, never B+/B-, or that protection is bypassed.

Charge current is set by the module's Rprog resistor:

RprogCharge current
1.2 kΩ (common default)1000 mA
2 kΩ580 mA
3 kΩ400 mA
4 kΩ300 mA
10 kΩ130 mA

Match this to the cell — 0.5C–1C is the usual safe range. The common 1.2 kΩ default is 1 A, which is 3.7C into this unit's 270 mAh cell and will shorten its life. Swap Rprog to 2 kΩ or higher for small cells.

Charge at position 1 (OFF). The TP4056 has no load-sharing circuitry, so current drawn from OUT+ during a charge disrupts its charge-termination detection. Pole A isolates the board, so charging in the OFF position avoids this entirely.

Two USB ports

PortUse for
TP4056 USBCharging only
SuperMini USBFlashing, serial console, Configurator
Never power from both at once. With the switch on and the SuperMini's USB plugged in, 5 V from USB and ~4 V from the cell meet on the same 5V node and back-feed each other. Flash and configure at position 1 — the board runs happily from its own USB while pole A keeps the cell isolated. A Schottky in series with pole A's output enforces this in hardware rather than by procedure.

Current budget

LoadDraw
ESP32-C3, BLE mode~30–130 mA depending on connection interval
ESP32-C3, Wi-Fi TX peak~350 mA burst
4 LEDs, all lit~80 mA if the self-flashing RGB parts run at ~20 mA each
Worst case (Wi-Fi TX + all LEDs)~430 mA

Runtime on the fitted 270 mAh cell, derated to ~216 mAh usable for the ~3.5 V cutoff above: roughly 2–3 h in Wi-Fi/MQTT, 4–5 h in BLE, 8–9 h in habit tracker. Order-of-magnitude only — actual draw depends on connection intervals and how often the LEDs light. Note the ~430 mA worst case above is 1.6C out of this cell: small pouch cells sag hard at that rate, and the sag lands straight on the LDO dropout, so a Wi-Fi burst on a half-empty cell is the likeliest cause of an unexplained brownout.

Battery level reporting

The pad reports a battery percentage to whatever it is paired with, but nothing on the board measures the cell. All five ADC-capable pins are taken by the keys, and no fuel gauge is fitted. What you see is an estimate built from spend accounting.

It works because the mode switch physically opens the battery rail at position 1: the firmware only runs while the cell is actually being drained, so powered-on time is a direct proxy for consumption. Elapsed time is multiplied by an assumed per-mode current, the running total lives in NVS across power cycles, and the result goes out over BLE rounded down to 10 %.

Three things feed the sum: a per-mode base current for the MCU and radio, the LEDs actually lit at that moment (metered, not assumed — at ~20 mA each, four lit LEDs draw more than everything else combined), and one-off costs for key reports, MQTT publishes and Wi-Fi associations. That last group is minor for BLE and significant on a flaky network, where repeated reconnection is genuinely expensive.

Habit-tracker runtime depends on your habits. An outstanding habit holds its LED on, so a pad with all four still to do draws roughly 125 mA against 45 mA with them all marked done — around 1.7 h of runtime versus 4.8 h. The estimate tracks this correctly because it counts lit LEDs rather than assuming a duty cycle.

Tell it your cell's rated capacity over the serial console — the default is 270 mAh, the cell this unit ships with, so you only need this if yours differs:

CFG:SET BATT_CAP=270

Enter the rated figure, not the usable one. The firmware already derates by 20 % for the LDO dropout described above.

Resetting to full after a charge

The estimate has no way to notice charging on its own: the TP4056 charges from its own USB-C and the ESP32 is not on that path. It has to be told. There are three ways, and which one applies depends on the order you do things:

What you doResult
Charge at position 1, switch on while still plugged in, then unplugAutomatic — the firmware reads the charger at boot
Leave the pad on while it chargesAutomatic, but see the back-feed warning above
Charge, unplug, then switch onNothing is detected — use the chord

The habit worth forming: when the TP4056's blue LED comes on, flick the switch to any live position for a couple of seconds before unplugging the charger. The pad boots, reads the charger, and re-arms itself.

Otherwise, hold keys 3 and 4 together for one second. Two LED blinks confirm it. The chord works in every position including Off, and CFG:BATTRESET over the console does the same thing.

Automatic detection needs one wire. Run a thin wire from the cathode of the TP4056's blue LED — which is STDBY, pin 6 of the charger IC — to GPIO8. No resistor; the ESP32's internal pull-up does the work, and ground is already shared through OUT-. Without that wire the keys 3+4 chord is the only way to reset the estimate. Check it with CFG?: BATT_CHARGED=1 when the blue LED is lit, 0 otherwise.

Two periods are excluded from the accounting, because the cell is not supplying the board during them: while the charger reports the cell full, and while a USB host is attached to the SuperMini. The second check detects an enumerated host rather than bare 5 V, so a plain wall charger on that port still counts against the estimate.

Treat the number as a guess. The per-mode currents are estimates, not measurements, and nothing ever corrects them against reality. The reading is useful for “roughly how much is left” and worthless as a precise figure. The TP4056's own LEDs — red charging, blue complete — remain the authoritative word on charge state.
Lithium safety. Never reverse B+/B- on the TP4056 — it destroys the module and can vent the cell. Verify polarity before the cell goes on. Do not charge unattended, and retire any cell that is swollen, punctured, or has been deeply discharged.

Mode + power switch

One switch does two jobs: row A gates battery power, row B carries the 2-bit mode code. Twelve pins in two rows of six, four detents.

This part has no common pin. Most 2P4T packages give you a common plus four throws. This one does not — each detent shorts a pair of pins two apart, and the pair steps one pin per click. Wiring it as common-and-throws gives a board that powers up in only one position and a mode code that never changes. Meter it before you solder.

Harness

Five conductors leave the switch. Four go to the SuperMini on a 5-way connector; the red one goes to the TP4056 instead.

172839410511612SuperMini 5VTP4056 OUT+GPIO21 (B)3V3GPIO20 (A)ROW A · powerROW B · moden/cn/cn/c
WirePinsGoes toNote
Red2 + 3 bridgedTP4056 OUT+cell positive, upstream of the switch
Black1 + 4 + 5 bridgedSuperMini 5VLDO input — never 3V3
White8GPIO21 (B)asserted at detent 3 — BLE
Yellow9 + 10 bridged3V3the rail both sense pins are switched onto
Green11GPIO20 (A)asserted at detent 2 — Wi-Fi / MQTT
Pins 6, 7 and 12 are left unconnected. TP4056 OUT− goes straight to SuperMini GND and does not pass through the switch.
Bridge on the pin shanks, not in the through-holes — each hole takes one wire. Keep every bridge clear of its neighbours. In row B the hazards are 8/9 and 10/11: adjacent pins on different nets, so a bridge that grazes the wrong shank ties 3V3 onto a sense pin permanently and the pad reports the same mode in every position.

What shorts at each detent

Solid arcs conduct and do something; dashed arcs land on an unconnected pin and do nothing. Row A opening at detent 1 is what makes detent 1 a real power cut.

ROW A · POWERROW B · MODE123456789101112Detent 1Detent 2Detent 3Detent 4
DetentRow ARow BABMode
1open — power cutyellow → n/cLOWLOWOff
2closed3V3 → greenHIGHLOW2 · Wi-Fi / MQTT (2 blinks)
3closed3V3 → whiteLOWHIGH1 · BLE Keyboard (1 blink)
4closedyellow → n/cLOWLOW3 · Habit Tracker (3 blinks)

Why detents 1 and 4 read the same

One pair closes per detent, so a single wiper can tie at most one sense pin to 3V3. Four detents, three codes — detents 1 and 4 both read 0,0. On battery that costs nothing, because detent 1 opens row A and the board is simply unpowered there.

On USB the board stays alive through the cut, so the firmware tells them apart by which code it saw on the way in. Detent 1 is only reachable through detent 2 (1,0) and detent 4 only through detent 3 (0,1), so the previous code names the position. Spinning the switch end to end faster than the 50 ms poll can skip the middle detent and land on the wrong one; click back a position and forward again to resync.

A cold boot already sitting on 0,0 has no entry direction to go on and assumes Habit Tracker. That is always right on battery. On USB, to reach Off from cold, click to detent 2 and back. The key lock — all four keys held for two seconds — is the dependable software off on USB.

A=1, B=1 means a wiring fault. No detent can tie both sense pins to 3V3 at once, so if the console reports Off with the switch plainly on a live position, two row-B pins are shorted together. The firmware decodes 1,1 as Off deliberately, so a short fails safe instead of firing keystrokes.

Identify the pins before soldering

Number 1–6 along one row and 7–12 along the other, then meter on continuity:

  1. Step through all four detents watching one pin. A connected pin shows continuity to exactly one partner, in exactly one detent — the pin two places along. No pin connects to a different partner each time; if one does, this is a different part and the plan does not apply.
  2. Find the detent where pins 4 and 6 are continuous. That end of the travel is detent 1, the one that must cut power.
  3. If detent 1 lands at the other end, your numbering is mirrored. Either turn the switch around in the enclosure, or read the table mirrored — row A pin n becomes 7−n, row B pin n becomes 19−n. Setting MODE_SWITCH_REVERSED to 1 in main.c compensates in firmware instead.
  4. Confirm the rows are independent — no pin in row A should show continuity to any pin in row B, in any detent.
Crossing the two rows puts cell voltage on GPIO20/GPIO21 — past the 3.6 V absolute maximum, and the one wiring error here that destroys the ESP32-C3. Check row isolation before the battery goes anywhere near the switch.

Wiring notes

Test points & bring-up

TPNodeUnpoweredPowered, idlePowered, active
TP0Cell / B+3.0–4.2 Vsamesags under Wi-Fi TX
TP13V3 rail—3.30 V ±0.15sags <0.1 V on Wi-Fi TX
TP2GND rail0 V reference0 V0 V
TP3LED cathode railcontinuity to GND0 V0 V
TP4Button common railcontinuity to GND0 V0 V
TP5a–dLED GPIO (5/6/7/10)—0 V (off)~3.3 V (lit)
TP6a–dButton GPIO (0/1/3/4)—3.30 V (released)0 V (pressed)
TP7 / TP8GPIO20 / GPIO21—per the switch table above
TP9Pole A output / 5V pin—0 V at detent 1; cell voltage at detents 2–4

Bring-up sequence

Do the battery steps first — a wiring fault with a lithium cell attached is a far worse failure than one on USB.

  1. Cell disconnected, meter on continuity: 3V3 ↔ GND must read open. A few ohms is a short — find it before anything is energised.
  2. Check TP4056 orientation before fitting the cell. Reversed B+/B- destroys the module and can vent the cell. Verify OUT+ is positive against OUT- with the module on USB and no cell attached.
  3. Verify pole A switching. Cell connected, meter on TP9: 0 V at position 1, cell voltage at positions 2–4. If position 1 does not fully isolate, stop — charging and flashing both depend on it.
  4. Unpowered, diode mode: red probe on each LED's GPIO leg, black on the GND leg. Unreliable for the self-flashing RGB parts — a meter sources ~1 mA, not enough to start the internal controller, so a dead reading proves nothing. Orientation is anode-to-GPIO, identified by the longer leg and the flat on the rim.
  5. Confirm the LEDs are the self-flashing RGB type before powering up. No series resistors are fitted, so a plain LED in one of these positions has nothing to limit its current and will overload the GPIO pad.
  6. Power up on USB at position 1, unflashed: all LEDs dark. The USB device may connect and disconnect on repeat — that is the ROM boot-looping on empty flash, not a fault. Hold BOOT while plugging in for a stable port.
  7. Flash, then watch the boot blink: all four LEDs blink together, once for Mode 1, twice for Mode 2, three times for Mode 3. This single test confirms LED polarity, the LED rail, all four LED GPIOs and the mode switch at once.
  8. Per key, Mode 1 (BLE): press each key — its LED lights while held and clears on release.
  9. Battery run test: switch to detent 2 (Wi-Fi/MQTT), unplug USB, confirm the board runs and reconnects. Then charge via the TP4056 at position 1 and confirm its status LED changes from charging to complete.

Bill of materials

QtyPartNotes
1ESP32-C3 SuperMiniUSB-C, native USB-Serial-JTAG
1TP4056 module, protected6-pin IN+ IN- B+ B- OUT+ OUT- with DW01A + FS8205. Not the bare 4-pin version
1Li-ion cell, 1S270 mAh, 3.0–4.2 V. Needs Rprog of 10 kΩ or ~4 kΩ — the 1.2 kΩ default is 3.7C
1Switch, 2P4T12 pins, 2 rows of 6, 4 detents. Pole A = battery power, pole B = mode bits
4Momentary SPST switchKey switches; no external pull resistors needed
4Self-flashing RGB LED, 5 mmInternal controller, free-running colour cycle — firmware controls on/off, not colour
0LED series resistorNone fitted. The self-flashing RGB LEDs are internally current-limited and wire straight from GPIO to GND
1100–470 µF electrolyticAcross 3V3/GND. More important on battery than on USB
1100 nF ceramicHarness tap decoupling
1Schottky diode (optional)In series with pole A output, to enforce USB/battery isolation in hardware

Mode 1 · BLE Keyboard

The board advertises as a standard Bluetooth LE HID keyboard named TRKeys. Pair it from any host's Bluetooth menu; it reconnects automatically and re-advertises if the host disconnects. Each key press sends a modifier + keycode "tap" (press then release) as a standard 8-byte boot-keyboard report.

KeyDefault comboModifier byteKeycode
Key 1Ctrl+10x010x1E
Key 2Ctrl+20x010x1F
Key 3Ctrl+30x010x20
Key 4Ctrl+40x010x21

Key mappings are configurable at runtime over the serial console (see below) — no reflashing needed. In BLE mode each key's LED lights while the button is physically held and turns off on release. The modifier byte follows the USB HID spec: 0x01 = Left Ctrl, 0x02 = Left Shift, 0x08 = Left GUI (⌘ on macOS).

USB HID identity: VID 0x16C0, PID 0x05DF, appearance = Keyboard.

Mode 2 · Wi-Fi / MQTT

The board joins a Wi-Fi network and opens a TLS WebSocket connection to an MQTT broker. Each key press publishes a configurable JSON message to the broker; the board also subscribes to a response topic. Power-save is disabled to keep the long-lived TLS/WebSocket connection stable.

SettingValue
Brokerwss://mqtt.uranus.im/mqtt (WebSocket Secure / TLS)
Client IDdevice1 (broker ACL requires this exact ID)
Publish topicagents/default/device1/messages
Subscribe topicagents/default/device1/responses
Default payloads{"message":"button 1"} … button 4
TLS verificationBuilt-in Mozilla CA certificate bundle

LED feedback: after a press the four LEDs run a chase animation while awaiting the broker's response; when a response arrives on the subscribe topic, all four LEDs flash together once.

Wi-Fi credentials, broker details, topics, and per-key payloads are all runtime-editable from the Configurator (stored in NVS) — no reflashing. The compiled-in USER CONFIG values are just the first-boot defaults.

Mode 3 · Habit Tracker

A daily habit tracker. Each of the four LEDs represents a habit and starts lit ("not done yet today"). Pressing a key marks that habit done: its LED turns off, the state is saved to flash, and — because the board also connects to Wi-Fi/MQTT in this mode — a message is published to the broker. A habit can only be marked once per day.

Set your timezone. With the default UTC0, the nightly reset fires at midnight UTC, which may be the middle of your day.

Firmware defaults (compile-time)

Every setting below is editable at runtime via the Configurator and stored in NVS. The values in the USER CONFIG block at the top of main/main.c are only the first-boot defaults (used until something is saved over serial) — edit and reflash only if you want to change those baked-in defaults.

#define WIFI_SSID        "<your-ssid>"
#define WIFI_PASS        "<your-wifi-password>"

#define MQTT_BROKER_URI   "wss://mqtt.uranus.im/mqtt"
#define MQTT_USERNAME     "default"
#define MQTT_PASSWORD     "<broker-password>"
#define MQTT_CLIENT_ID    "device1"
#define MQTT_TOPIC_PUB    "agents/default/device1/messages"
#define MQTT_TOPIC_SUB    "agents/default/device1/responses"

#define COPYPASTE_MOD    0x01     /* Left Ctrl; use 0x08 for macOS Cmd */
#define HID_KEY_1        0x1E     /* keys 1-4 default to Ctrl+1..Ctrl+4 */

#define SNTP_SERVER      "pool.ntp.org"
#define HABIT_TZ         "UTC0"   /* set to your local POSIX TZ string */
Secrets. The real Wi-Fi and MQTT passwords are stored in this block in the firmware source, not on this public page. Keep them out of any public repository or shared build.

Serial config console

Per-key settings can be changed live over the same USB serial port used for flashing — no rebuild required. Open the port (any serial terminal) and use this simple line protocol. Changed values are written to NVS immediately and persist across reboots.

The Configurator speaks this protocol for you, but it's plain text you can drive from any serial terminal too.

CommandEffect
CFG?Dump all config (device + per-key + active MODE); output ends with a CFG:END line.
CFG:REBOOTRestart the board (needed to apply Wi-Fi / broker changes).
Per-key (KEY1–KEY4)
CFG:SET KEY<n>_BLE_MOD=0x01BLE modifier byte for key n (Ctrl 0x01, Shift 0x02, Alt 0x04, GUI 0x08; OR them).
CFG:SET KEY<n>_BLE_KEY=0x1EBLE HID keycode for key n.
CFG:SET KEY<n>_MQTT=<text>Mode 2 MQTT payload for key n (≤63 chars).
CFG:SET KEY<n>_HABIT=<text>Mode 3 habit-tracker payload for key n (≤63 chars).
CFG:SET KEY<n>_HABIT_CYCLE=<0|1|2>Mode 3 reset cycle for key n: 0 = hourly, 1 = daily, 2 = weekly.
Device-wide (Wi-Fi / broker)
CFG:SET WIFI<n>_SSID= / WIFI<n>_PASS= / WIFI<n>_LABEL=Wi-Fi profile n (0–3): SSID, password, and a location label. The board joins whichever stored network is in range (strongest wins). Use {loc} in a message to insert the connected label.
CFG:SET MQTT_URI=<uri>Broker URI, e.g. wss://host/mqtt or mqtt://host:1883.
CFG:SET MQTT_USER= / MQTT_PASS= / MQTT_CLIENTID=Broker username, password, and client ID.
CFG:SET MQTT_PUB=<topic> / MQTT_SUB=<topic>Publish and subscribe topics.

Each CFG:SET replies CFG:OK on success or CFG:ERR … on a bad key/field. Example session:

> CFG?
CFG:KEY1_BLE_MOD=0x01
CFG:KEY1_BLE_KEY=0x1E
CFG:KEY1_MQTT={"message":"button 1"}
... (keys 2-4) ...
CFG:END

> CFG:SET KEY1_BLE_KEY=0x04      # remap key 1 to the letter "a"
CFG:OK

> CFG:SET KEY2_MQTT={"cmd":"lights_on"}
CFG:OK

Stored state (NVS)

Both the per-key config and the habit-tracker state are kept in the ESP32's non-volatile storage under the cfg namespace.

KeyContents
keycfg6Per-key BLE modifiers, BLE keycodes, Mode 2 MQTT payloads, Mode 3 habit payloads, and per-key habit reset cycle.
devcfg3Device-wide: up to 4 Wi-Fi profiles (SSID/password/label), MQTT URI/user/password/client ID, and publish & subscribe topics.
habitst3Habit tracker runtime state: per-key last-reset period buckets and the "already done this period" bitmask.

Build & flash

Built with ESP-IDF v5.3.2, target esp32c3. From the project directory:

# one-time: select the target
idf.py set-target esp32c3

# build, flash, and open the serial monitor (replace COM4 with your port)
idf.py -p COM4 build flash monitor

To flash an already-built image without rebuilding (esptool directly):

esptool.py --chip esp32c3 -p COM4 -b 460800 \
  --before=default_reset --after=hard_reset write_flash \
  --flash_mode dio --flash_freq 80m --flash_size 2MB \
  0x0     bootloader/bootloader.bin \
  0x10000 keypress.bin \
  0x8000  partition_table/partition-table.bin

Key build options (from sdkconfig.defaults): NimBLE enabled with the HID service, the large single-app partition table, the mbedTLS CA certificate bundle for the wss:// broker, and the console routed to USB-Serial-JTAG.

Troubleshooting

SymptomCause & fix
Could not open COMx, the port is busy or doesn't exist A serial monitor or another program is holding the port — close it before flashing. If the port truly isn't there, replug the USB cable and confirm the COM number.
Wrong mode after power-on In the network modes the sweep comes first — wait for it to stop. Then count the boot blinks (1/2/3). If they don't match the switch, re-check the mode-select wiring on GPIO20/GPIO21. Unwired = falls back to Mode 2.
Wi-Fi connects then stalls Router likely runs WPA2/WPA3 "transition" mode; the firmware advertises PMF-capable to handle this. Confirm SSID/password in USER CONFIG.
MQTT "not connected, dropping" in logs Broker/TLS not connected yet — presses are dropped until the connection is up. Check broker URI, credentials, and that the client ID is device1.
Habit tracker resets at the wrong time Set HABIT_TZ to your local POSIX timezone string and reflash.
BLE keys do nothing Host not paired/connected — presses are dropped when disconnected. Re-pair "TRKeys" from the host Bluetooth menu.