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.
BLE Keyboard
Each key sends a Bluetooth HID keystroke to a paired computer or phone.
Wi-Fi / MQTT
Each key publishes a message to an MQTT broker over Wi-Fi, with LED feedback.
Habit Tracker
Four lit LEDs; press a key to mark a habit done for the day. Auto-resets nightly.
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.
| Property | Value |
|---|---|
| Microcontroller | ESP32-C3 (QFN32, rev v0.4), 4 MB flash, 40 MHz crystal |
| Framework | ESP-IDF v5.3.2 |
| Bluetooth stack | NimBLE (HID-over-GATT) |
| Keys / LEDs | 4 push-buttons, 4 indicator LEDs |
| Console / flashing | Native USB (USB-Serial-JTAG) |
| BLE device name | TRKeys |
Quick start
- Pick a mode on the mode-select switch (see the switch map below).
- 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.
- 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.
| Function | Key 1 | Key 2 | Key 3 | Key 4 | Header |
|---|---|---|---|---|---|
| Button GPIO | GPIO0 | GPIO1 | GPIO3 | GPIO4 | left |
| LED GPIO | GPIO10 | GPIO7 | GPIO6 | GPIO5 | right |
| Signal | GPIO | Notes |
|---|---|---|
| Mode-select A | GPIO20 | Input, internal pull-down (right header; the U0RXD pin) |
| Mode-select B | GPIO21 | Input, internal pull-down (right header; the U0TXD pin) |
| Console / USB | native USB | USB-Serial-JTAG — flashing, monitor, and the config console all share this port |
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.
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
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 voltage | Idle / BLE | Wi-Fi TX burst (~350 mA) |
|---|---|---|
| 4.2 V (full) | fine | fine |
| 3.7 V (nominal) | fine | marginal on a high-dropout part |
| 3.5 V | fine | likely browns out |
| 3.3 V and below | regulator 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.
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:
| Rprog | Charge 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.
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
| Port | Use for |
|---|---|
| TP4056 USB | Charging only |
| SuperMini USB | Flashing, serial console, Configurator |
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
| Load | Draw |
|---|---|
| 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.
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 do | Result |
|---|---|
| Charge at position 1, switch on while still plugged in, then unplug | Automatic — the firmware reads the charger at boot |
| Leave the pad on while it charges | Automatic, but see the back-feed warning above |
| Charge, unplug, then switch on | Nothing 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.
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.
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.
Harness
Five conductors leave the switch. Four go to the SuperMini on a 5-way connector; the red one goes to the TP4056 instead.
| Wire | Pins | Goes to | Note |
|---|---|---|---|
| Red | 2 + 3 bridged | TP4056 OUT+ | cell positive, upstream of the switch |
| Black | 1 + 4 + 5 bridged | SuperMini 5V | LDO input — never 3V3 |
| White | 8 | GPIO21 (B) | asserted at detent 3 — BLE |
| Yellow | 9 + 10 bridged | 3V3 | the rail both sense pins are switched onto |
| Green | 11 | GPIO20 (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. | |||
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.
| Detent | Row A | Row B | A | B | Mode |
|---|---|---|---|---|---|
| 1 | open — power cut | yellow → n/c | LOW | LOW | Off |
| 2 | closed | 3V3 → green | HIGH | LOW | 2 · Wi-Fi / MQTT (2 blinks) |
| 3 | closed | 3V3 → white | LOW | HIGH | 1 · BLE Keyboard (1 blink) |
| 4 | closed | yellow → n/c | LOW | LOW | 3 · 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:
- 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.
- Find the detent where pins 4 and 6 are continuous. That end of the travel is detent 1, the one that must cut power.
- 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 becomes19−n. SettingMODE_SWITCH_REVERSEDto1inmain.ccompensates in firmware instead. - Confirm the rows are independent — no pin in row A should show continuity to any pin in row B, in any detent.
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
- Buttons: one leg to
GND— the same rail the LED cathodes land on — the other to the button GPIO. Internal pull-ups are enabled in firmware, so no external resistor is needed. Pressed reads 0, released reads 1.
Revised from active-high. The firmware previously enabled pull-downs and expected the common leg on3V3; wired toGNDthat can never produce an edge, so a press fires no interrupt and logs nothing. The mode switch is the opposite — pole B's common stays on3V3, becauseGPIO20/GPIO21still use pull-downs. - LEDs:
GPIO → LED anode…cathode → GND. No series resistors are fitted: the self-flashing RGB parts limit their own current through the controller inside each LED. Driving the GPIO high sources current and lights the LED. The cathodes common onto one rail landing onGND— note this is ground, not 3V3: a cathode tied to 3V3 can never conduct, since the anode would have to exceed 3.3 V + Vf. - UART0 is unused — its pins (
GPIO20/21) are reused for the mode switch, so the console deliberately runs on native USB instead.
Test points & bring-up
| TP | Node | Unpowered | Powered, idle | Powered, active |
|---|---|---|---|---|
| TP0 | Cell / B+ | 3.0–4.2 V | same | sags under Wi-Fi TX |
| TP1 | 3V3 rail | — | 3.30 V ±0.15 | sags <0.1 V on Wi-Fi TX |
| TP2 | GND rail | 0 V reference | 0 V | 0 V |
| TP3 | LED cathode rail | continuity to GND | 0 V | 0 V |
| TP4 | Button common rail | continuity to GND | 0 V | 0 V |
| TP5a–d | LED GPIO (5/6/7/10) | — | 0 V (off) | ~3.3 V (lit) |
| TP6a–d | Button GPIO (0/1/3/4) | — | 3.30 V (released) | 0 V (pressed) |
| TP7 / TP8 | GPIO20 / GPIO21 | — | per the switch table above | |
| TP9 | Pole 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.
- Cell disconnected, meter on continuity:
3V3↔GNDmust read open. A few ohms is a short — find it before anything is energised. - Check TP4056 orientation before fitting the cell. Reversed
B+/B-destroys the module and can vent the cell. VerifyOUT+is positive againstOUT-with the module on USB and no cell attached. - 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.
- 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.
- 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.
- 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.
- 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.
- Per key, Mode 1 (BLE): press each key — its LED lights while held and clears on release.
- 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
| Qty | Part | Notes |
|---|---|---|
| 1 | ESP32-C3 SuperMini | USB-C, native USB-Serial-JTAG |
| 1 | TP4056 module, protected | 6-pin IN+ IN- B+ B- OUT+ OUT- with DW01A + FS8205. Not the bare 4-pin version |
| 1 | Li-ion cell, 1S | 270 mAh, 3.0–4.2 V. Needs Rprog of 10 kΩ or ~4 kΩ — the 1.2 kΩ default is 3.7C |
| 1 | Switch, 2P4T | 12 pins, 2 rows of 6, 4 detents. Pole A = battery power, pole B = mode bits |
| 4 | Momentary SPST switch | Key switches; no external pull resistors needed |
| 4 | Self-flashing RGB LED, 5 mm | Internal controller, free-running colour cycle — firmware controls on/off, not colour |
| 0 | LED series resistor | None fitted. The self-flashing RGB LEDs are internally current-limited and wire straight from GPIO to GND |
| 1 | 100–470 µF electrolytic | Across 3V3/GND. More important on battery than on USB |
| 1 | 100 nF ceramic | Harness tap decoupling |
| 1 | Schottky 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.
| Key | Default combo | Modifier byte | Keycode |
|---|---|---|---|
| Key 1 | Ctrl+1 | 0x01 | 0x1E |
| Key 2 | Ctrl+2 | 0x01 | 0x1F |
| Key 3 | Ctrl+3 | 0x01 | 0x20 |
| Key 4 | Ctrl+4 | 0x01 | 0x21 |
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).
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.
| Setting | Value |
|---|---|
| Broker | wss://mqtt.uranus.im/mqtt (WebSocket Secure / TLS) |
| Client ID | device1 (broker ACL requires this exact ID) |
| Publish topic | agents/default/device1/messages |
| Subscribe topic | agents/default/device1/responses |
| Default payloads | {"message":"button 1"} … button 4 |
| TLS verification | Built-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.
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.
- Persistence: the "muted" state and the current day are stored in NVS, so the LED pattern survives a power cycle and is restored immediately at boot — before Wi-Fi or time sync completes.
- Per-key reset cycle: the board syncs the clock over SNTP
(
pool.ntp.org). A background task checks every 15 s; each habit has its own cycle — hourly, daily, or weekly (set per key in the Configurator). When a given key's period rolls over, that habit re-arms (its LED comes back on) independently of the others. - Timezone: the day boundary uses a POSIX
TZstring, defaultUTC0. Set this to your local zone (e.g.PST8PDT,M3.2.0,M11.1.0) or the reset happens at UTC midnight.
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 */
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.
| Command | Effect |
|---|---|
CFG? | Dump all config (device + per-key + active MODE); output ends with a CFG:END line. |
CFG:REBOOT | Restart the board (needed to apply Wi-Fi / broker changes). |
| Per-key (KEY1–KEY4) | |
CFG:SET KEY<n>_BLE_MOD=0x01 | BLE modifier byte for key n (Ctrl 0x01, Shift 0x02, Alt 0x04, GUI 0x08; OR them). |
CFG:SET KEY<n>_BLE_KEY=0x1E | BLE 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.
| Key | Contents |
|---|---|
keycfg6 | Per-key BLE modifiers, BLE keycodes, Mode 2 MQTT payloads, Mode 3 habit payloads, and per-key habit reset cycle. |
devcfg3 | Device-wide: up to 4 Wi-Fi profiles (SSID/password/label), MQTT URI/user/password/client ID, and publish & subscribe topics. |
habitst3 | Habit 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
| Symptom | Cause & 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. |