Overview

TeerakKeys 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 "TeerakKeys" 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 TeerakKeys. 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.
• Daily reset: the board syncs the clock over SNTP (pool.ntp.org). A background task checks every 15 s; when the local calendar day rolls over, all habits reset (LEDs back on).
• 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 configuration (compile-time)

The tunable settings live in the USER CONFIG block at the top of main/main.c. Edit and reflash to change them.

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

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