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 that is read once at boot. Changing modes means flipping the switch and power-cycling (or resetting) the board — no reflashing required.

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.
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-high (common leg to 3V3, sense pin pulled down internally). LEDs are wired active-low — 3V3 → 220 Ω resistor → LED → GPIO — so a GPIO driven low turns the LED on.

Mode-select switch

The mode is encoded on just two GPIOs using a 4-position switch (OFF plus three "on" throws). Each throw ties the board's 3V3 to a specific 2-bit combination of GPIO3 (A) and GPIO10 (B). The pins are read once at boot, 5 ms after the pull-downs are enabled.

Wiring notes

• Buttons: one leg to 3V3, the other to the button GPIO. Internal pull-downs are enabled in firmware, so no external resistor is needed.
• LEDs: 3V3 → 220 Ω → LED anode…cathode → GPIO. Each LED has its own resistor. Driving the GPIO low sinks current and lights the LED.
• UART0 is unused — its TX pin overlaps a key GPIO, so the console deliberately runs on native USB instead.

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 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).

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.

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.

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.
• Reset cycle: the board syncs the clock over SNTP (pool.ntp.org). A background task checks every 15 s; when the current period rolls over, all habits reset (LEDs back on). The cycle is configurable — hourly, daily, or weekly — from the Configurator.
• Timezone: the day boundary uses a POSIX TZ string, default UTC0. Set this to your local zone (e.g. PST8PDT,M3.2.0,M11.1.0) or the reset happens at UTC midnight.

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.

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.

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