ESP32-C3 JSON-RPC Firmware

Firmware for the ESP32-C3 that exposes a JSON-RPC 2.0 API over three transports simultaneously: HTTP, BLE (NUS-compatible GATT), and MQTT.

Features

Feature	Details
JSON-RPC 2.0	HTTP POST `/rpc`, BLE GATT NUS service, MQTT
RGB LED	WS2812 NeoPixel on GPIO 8
GPIO LED	GPIO 0
DHT11 sensor	Temperature & humidity on GPIO 2
MAX7219 display	8×8 LED matrix via SPI (CS=19, CLK=1, DIN=18)
Buzzer	Active buzzer on GPIO 10
IR transceiver	M5Stack Unit IR, NEC protocol (TX GPIO 4, RX GPIO 5)
Cron engine	SNTP-synced cron scheduler, up to 16 NVS-persisted jobs
WiFi	STA + AP modes, NVS-persisted config
OTA	HTTP/HTTPS firmware update via `Sys.Ota`
Config	NVS persistence, SPIFFS fallback (`spiffs/wifi_config.txt`)

Hardware Pinout

Signal	GPIO
RGB LED (WS2812)	8
DHT11 data	2
Buzzer	10
LED 0	0
IR TX	4
IR RX	5
MAX7219 CS	19
MAX7219 CLK	1
MAX7219 DIN	18

Getting Started

Prerequisites

ESP-IDF v5.x
Target: esp32c3

Build & Flash

idf.py set-target esp32c3
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

Initial WiFi Configuration

On first boot, place credentials in spiffs/wifi_config.txt (one line: SSID, next line: password):

MySSID
MyPassword

The config is written to NVS and can be updated at runtime via Wifi.Sta.Set.

JSON-RPC 2.0 API

All requests use the standard JSON-RPC 2.0 envelope:

{"jsonrpc":"2.0","method":"METHOD","params":{...},"id":1}

Transports

Transport	Details
HTTP	`POST http://<device-ip>/rpc` with `Content-Type: application/json`
BLE	Write request to RX characteristic `6E400002-…`, read response via notifications on TX `6E400003-…` (NUS service `6E400001-…`)
MQTT	Configured via `Config.Set`; device publishes heartbeats and responds to RPC topics

Methods

`Sys.Info`

Returns chip information.

// request
{"jsonrpc":"2.0","method":"Sys.Info","id":1}

// response
{
  "model": "esp32c3",
  "cores": 1,
  "revision": 3,
  "free_heap": 204800,
  "idf_version": "v5.2.0",
  "device_name": "esp32c3_AABBCC"
}

`Sys.Reboot`

Schedules a reboot 500 ms after the response is sent.

`Sys.Factory`

Erases NVS and reboots to factory defaults.

`Sys.Methods`

Returns a list of all registered RPC method names.

`Sys.Ota`

Triggers an OTA firmware update. The device reboots on success.

{
  "jsonrpc": "2.0",
  "method": "Sys.Ota",
  "params": { "url": "http://192.168.1.10/firmware.bin" },
  "id": 1
}

`Wifi.Info`

Returns current WiFi status (STA IP, AP status, RSSI, etc.).

`Wifi.Sta.Set`

Configure station (client) mode.

{
  "jsonrpc": "2.0",
  "method": "Wifi.Sta.Set",
  "params": { "enable": true, "ssid": "MyNet", "password": "s3cr3t" },
  "id": 1
}

`Wifi.Ap.Set`

Configure access point mode.

{
  "jsonrpc": "2.0",
  "method": "Wifi.Ap.Set",
  "params": { "enable": true, "ssid": "esp32-ap", "password": "12345678" },
  "id": 1
}

`Ble.Info`

Returns BLE device name and connection state.

`Ht.Info`

Returns the latest DHT11 temperature and humidity reading.

// response
{ "temperature": 24.5, "humidity": 55.0 }

`Display.Effect`

Runs a numbered animation on the MAX7219 8×8 display (1–16).

{
  "jsonrpc": "2.0",
  "method": "Display.Effect",
  "params": { "effect": 3 },
  "id": 1
}

`Light.Led.Set`

Set a GPIO LED on or off.

{
  "jsonrpc": "2.0",
  "method": "Light.Led.Set",
  "params": { "gpio": 4, "state": 1 },
  "id": 1
}

`Light.Rgb.Set`

Set the WS2812 RGB LED color.

{
  "jsonrpc": "2.0",
  "method": "Light.Rgb.Set",
  "params": { "on": 1, "r": 255, "g": 128, "b": 0 },
  "id": 1
}

`Ir.Send`

Transmit a NEC IR frame.

{
  "jsonrpc": "2.0",
  "method": "Ir.Send",
  "params": { "addr": 0x00, "cmd": 0x12 },
  "id": 1
}

`Mqtt.Set`

Configure the MQTT broker connection. Changes are persisted to NVS and the client reconnects automatically.

{
  "jsonrpc": "2.0",
  "method": "Mqtt.Set",
  "params": {
    "host": "192.168.1.5",
    "port": 1883,
    "username": "user",
    "password": "pass"
  },
  "id": 1
}

`Mqtt.Info`

Returns the current MQTT connection status and configuration (password redacted).

`Config.Get`

Returns the full device configuration as JSON (passwords redacted).

`Config.Set`

Updates device configuration. Persisted to NVS immediately. Accepted fields: device_name, wifi_ap_ssid, wifi_ap_password, wifi_ap_enabled.

{
  "jsonrpc": "2.0",
  "method": "Config.Set",
  "params": {
    "device_name": "my-device"
  },
  "id": 1
}

`Cron.List`

Returns all scheduled cron jobs.

`Cron.Get`

Returns a single cron job by id.

{ "jsonrpc": "2.0", "method": "Cron.Get", "params": { "id": 1 }, "id": 1 }

`Cron.Create`

Creates a new cron job. Jobs are persisted to NVS and survive reboots (max 16 jobs).

{
  "jsonrpc": "2.0",
  "method": "Cron.Create",
  "params": {
    "expression": "0 * * * *",
    "method": "Light.Rgb.Set",
    "params": { "on": 0 },
    "enabled": true
  },
  "id": 1
}

`Cron.Update`

Updates an existing cron job. All fields except id are optional.

{
  "jsonrpc": "2.0",
  "method": "Cron.Update",
  "params": { "id": 1, "enabled": false },
  "id": 1
}

`Cron.Delete`

Deletes a cron job by id.

{ "jsonrpc": "2.0", "method": "Cron.Delete", "params": { "id": 1 }, "id": 1 }

Project Structure

main/
  main.c              – Entry point, peripheral initialization
  config.[ch]         – NVS-backed AppConfig (WiFi, device name)
  wifi_manager.[ch]   – WiFi STA/AP management
  http_server.[ch]    – HTTP server with /rpc endpoint
  ble_gatt_server.[ch]– BLE NUS-compatible GATT server
  mqtt_manager.[ch]   – MQTT client and heartbeat
  ota_manager.[ch]    – OTA firmware update task
  cron_engine.[ch]    – SNTP-synced cron scheduler (NVS-persisted jobs)
  rpc_m.[ch]          – RPC dispatcher (method registry)
  rpc_json.[ch]       – JSON-RPC 2.0 envelope parsing & response helpers
  rpc_m_sys.[ch]      – Sys.* handlers
  rpc_m_wifi.[ch]     – Wifi.* handlers
  rpc_m_ble.[ch]      – Ble.* handlers
  rpc_m_ht.[ch]       – Ht.* handlers (DHT11)
  rpc_m_display.[ch]  – Display.* handlers (MAX7219)
  rpc_m_light.[ch]    – Light.* handlers (LED, RGB)
  rpc_m_ir.[ch]       – Ir.* handlers (M5Stack Unit IR)
  rpc_m_config.[ch]   – Config.* handlers
  rpc_m_mqtt.[ch]     – Mqtt.* handlers
  rpc_m_cron.[ch]     – Cron.* handlers
  dht11.[ch]          – DHT11 driver with periodic background task
  max7219.[ch]        – MAX7219 SPI driver + effect engine
  gpio_led.[ch]       – GPIO LED driver
  gpio_rgb.[ch]       – WS2812 RGB LED driver (via led_strip component)
  buzzer.[ch]         – Buzzer driver
  m5stack_unit_ir.[ch]– M5Stack Unit IR driver (RMT-based NEC TX/RX)
  app_event.[ch]      – Application-level event bus
spiffs/
  wifi_config.txt     – Default WiFi credentials (SSID / password)
partitions.csv        – Custom partition table
sdkconfig.defaults    – Default Kconfig overrides

Configuration

Runtime configuration is stored in NVS under the config namespace and can be managed via Config.Get / Config.Set. MQTT broker settings have their own dedicated Mqtt.Set / Mqtt.Info methods. Cron jobs are also persisted to NVS automatically.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
main		main
web		web
.clang-format		.clang-format
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
README.md		README.md
partitions.csv		partitions.csv
sdkconfig.defaults		sdkconfig.defaults
wifi_config.txt.example		wifi_config.txt.example

Folders and files

Latest commit

History

Repository files navigation

ESP32-C3 JSON-RPC Firmware

Features

Hardware Pinout

Getting Started

Prerequisites

Build & Flash

Initial WiFi Configuration

JSON-RPC 2.0 API

Transports

Methods

Sys.Info

Sys.Reboot

Sys.Factory

Sys.Methods

Sys.Ota

Wifi.Info

Wifi.Sta.Set

Wifi.Ap.Set

Ble.Info

Ht.Info

Display.Effect

Light.Led.Set

Light.Rgb.Set

Ir.Send

Mqtt.Set

Mqtt.Info

Config.Get

Config.Set

Cron.List

Cron.Get

Cron.Create

Cron.Update

Cron.Delete

Project Structure

Configuration

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`Sys.Info`

`Sys.Reboot`

`Sys.Factory`

`Sys.Methods`

`Sys.Ota`

`Wifi.Info`

`Wifi.Sta.Set`

`Wifi.Ap.Set`

`Ble.Info`

`Ht.Info`

`Display.Effect`

`Light.Led.Set`

`Light.Rgb.Set`

`Ir.Send`

`Mqtt.Set`

`Mqtt.Info`

`Config.Get`

`Config.Set`

`Cron.List`

`Cron.Get`

`Cron.Create`

`Cron.Update`

`Cron.Delete`

Packages