feat: JSON API on the USB serial port for led-tool

One request per line on USB-Serial-JTAG (@api {"id","method","path","body"}),
one @api envelope back; @reboot restarts. Requests run on the httpd task
through the same dispatcher as the WebSocket, so the checks match the web UI
and never race an HTTP handler. Replies go out in chunks under a lock that log
output shares, so a reply over the TX buffer size isn't dropped and log lines
can't land inside one. The primary console moves to USB-Serial-JTAG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
jimmyandClaude Opus 5.5 committed 2026-11-11 22:34:36 +13:00
1 parent 4cd3bc7973
commit 762ec338bc
8 files changed
+266 -4

No files matched your search

+20
View File
@@ -75,6 +75,26 @@ JSON API (port 80):
| POST | `/api/wifi` | `{"ssid","password"}`: save and connect | | POST | `/api/wifi` | `{"ssid","password"}`: save and connect |
| GET | `/api/wifi/scan` | Visible networks | | GET | `/api/wifi/scan` | Visible networks |
### USB configuration (led-tool)
The JSON API above is also served on the USB serial port (`/dev/ttyACM0`, `main/usb_cfg.cpp`), so a driver can be set up without Wi-Fi. One line per request and per reply; every other line is log output:
```
@api {"id":1,"method":"GET","path":"/api/status"}
@api {"id":1,"status":200,"body":"{...}"}
@api {"id":2,"method":"POST","path":"/api/hardware","body":{"num_leds":60}}
@reboot
```
Requests run on the web server's task, with the same checks as the web UI. `led-tool` uses this automatically:
```bash
python cli.py -s
python cli.py -l 60 -o rgb --pin 10 -b 128 -n bar1
```
Open the port with DTR high and RTS low (RTS high with DTR low resets the chip).
Build and flash for the ESP32-C3: Build and flash for the ESP32-C3:
```bash ```bash
+2 -2
View File
@@ -1,6 +1,6 @@
idf_component_register(SRCS "main.cpp" "ws2812.cpp" "net.cpp" "settings.cpp" "web.cpp" "patterns.cpp" "presets.cpp" idf_component_register(SRCS "main.cpp" "ws2812.cpp" "net.cpp" "settings.cpp" "web.cpp" "patterns.cpp" "presets.cpp"
"effects_util.cpp" "ws_client.cpp" "effects_a.cpp" "effects_b.cpp" "effects_rig.cpp" "ota.c" "ddp.cpp" "effects_util.cpp" "ws_client.cpp" "effects_a.cpp" "effects_b.cpp" "effects_rig.cpp" "ota.c" "ddp.cpp" "usb_cfg.cpp"
PRIV_REQUIRES esp_driver_rmt esp_driver_gpio esp_wifi esp_netif esp_event PRIV_REQUIRES esp_driver_rmt esp_driver_gpio esp_wifi esp_netif esp_event
esp_timer nvs_flash esp_http_server esp_http_client cjson mdns esp_hw_support app_update esp_app_format lwip esp_timer nvs_flash esp_http_server esp_http_client cjson mdns esp_hw_support app_update esp_app_format lwip esp_driver_usb_serial_jtag
INCLUDE_DIRS "." INCLUDE_DIRS "."
EMBED_TXTFILES "../web/index.html" "../web/app.js" "../web/style.css") EMBED_TXTFILES "../web/index.html" "../web/app.js" "../web/style.css")
+2
View File
@@ -9,6 +9,7 @@
#include "ota.h" #include "ota.h"
#include "patterns.h" #include "patterns.h"
#include "presets.h" #include "presets.h"
#include "usb_cfg.h"
#include "web.h" #include "web.h"
static const char *TAG = "example"; static const char *TAG = "example";
@@ -30,6 +31,7 @@ extern "C" void app_main(void)
presets_apply_startup(); presets_apply_startup();
ESP_ERROR_CHECK(net_start()); ESP_ERROR_CHECK(net_start());
ESP_ERROR_CHECK(web_start()); ESP_ERROR_CHECK(web_start());
usb_cfg_start(); // led-tool over USB; the LEDs and Wi-Fi work without it
ESP_ERROR_CHECK(ddp_start()); ESP_ERROR_CHECK(ddp_start());
ota_confirm_later(); ota_confirm_later();
+171
View File
@@ -0,0 +1,171 @@
/*
* SPDX-License-Identifier: Apache-2.0
*/
#include <cstdarg>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include "cJSON.h"
#include "driver/usb_serial_jtag.h"
#include "driver/usb_serial_jtag_vfs.h"
#include "esp_log.h"
#include "esp_system.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/task.h"
#include "usb_cfg.h"
#include "web.h"
static const char *TAG = "usb_cfg";
static const char API_PREFIX[] = "@api ";
static const char REBOOT[] = "@reboot";
// The driver's TX buffer takes a write whole or not at all, so a long reply goes out in chunks.
// Log output takes the same lock (log_vprintf), so no log line can land inside a reply.
static SemaphoreHandle_t s_tx_lock;
static vprintf_like_t s_log_vprintf;
static int log_vprintf(const char *fmt, va_list args)
{
// A log from inside a reply write (none today) would deadlock, so only wait if we don't hold it
const bool locked = s_tx_lock && xSemaphoreGetMutexHolder(s_tx_lock) != xTaskGetCurrentTaskHandle()
&& xSemaphoreTake(s_tx_lock, portMAX_DELAY) == pdTRUE;
int r = s_log_vprintf(fmt, args);
if (locked) {
fflush(stdout);
xSemaphoreGive(s_tx_lock);
}
return r;
}
static void write_line(const char *s)
{
static const size_t CHUNK = 256;
xSemaphoreTake(s_tx_lock, portMAX_DELAY);
fflush(stdout); // finish any log text already in stdio's buffer first
for (size_t n = strlen(s); n > 0;) {
size_t k = n < CHUNK ? n : CHUNK;
if (usb_serial_jtag_write_bytes(s, k, pdMS_TO_TICKS(500)) != (int)k) {
break; // no host reading: drop the rest rather than hold up the logs
}
s += k;
n -= k;
}
xSemaphoreGive(s_tx_lock);
}
// An "@api" line: run it and send back the envelope, with the request's id added
static void handle_api(const char *json, char *reply, size_t cap)
{
web_api_call(json, reply, cap);
cJSON *req = cJSON_Parse(json);
const cJSON *id = req ? cJSON_GetObjectItem(req, "id") : NULL;
cJSON *env = cJSON_Parse(reply);
if (!env) {
env = cJSON_CreateObject();
cJSON_AddNumberToObject(env, "status", 500);
cJSON_AddStringToObject(env, "body", "{\"error\":\"reply too large\"}");
}
if (cJSON_IsNumber(id)) {
cJSON_AddNumberToObject(env, "id", id->valuedouble);
}
char *s = cJSON_PrintUnformatted(env);
cJSON_Delete(env);
cJSON_Delete(req);
if (!s) {
return;
}
size_t n = strlen(s);
// A leading newline ends any log line that was half written, so the reply starts its own line
const size_t pre = sizeof(API_PREFIX) - 1;
char *line = (char *)malloc(1 + pre + n + 2);
if (line) {
line[0] = '\n';
memcpy(line + 1, API_PREFIX, pre);
memcpy(line + 1 + pre, s, n);
line[1 + pre + n] = '\n';
line[2 + pre + n] = '\0';
write_line(line);
free(line);
}
cJSON_free(s);
}
static void handle_line(char *line, char *reply, size_t cap)
{
size_t n = strlen(line);
while (n && (line[n - 1] == '\r' || line[n - 1] == ' ')) {
line[--n] = '\0';
}
if (strncmp(line, API_PREFIX, sizeof(API_PREFIX) - 1) == 0) {
handle_api(line + sizeof(API_PREFIX) - 1, reply, cap);
} else if (strcmp(line, REBOOT) == 0) {
write_line("\n@ok\n");
usb_serial_jtag_wait_tx_done(pdMS_TO_TICKS(200));
vTaskDelay(pdMS_TO_TICKS(100));
esp_restart();
}
// Anything else (a stray keypress in a monitor) is ignored
}
static void usb_cfg_task(void *)
{
char *line = (char *)malloc(WEB_API_MSG_MAX + 1);
char *reply = (char *)malloc(WEB_API_REPLY_MAX);
if (!line || !reply) {
ESP_LOGE(TAG, "out of memory");
vTaskDelete(NULL);
return;
}
size_t len = 0;
bool overflow = false; // the current line is too long: drop it up to its newline
uint8_t buf[64];
for (;;) {
int got = usb_serial_jtag_read_bytes(buf, sizeof(buf), portMAX_DELAY);
for (int i = 0; i < got; i++) {
char c = (char)buf[i];
if (c == '\n') {
if (!overflow) {
line[len] = '\0';
handle_line(line, reply, WEB_API_REPLY_MAX);
}
len = 0;
overflow = false;
} else if (!overflow) {
if (len < WEB_API_MSG_MAX) {
line[len++] = c;
} else {
overflow = true;
}
}
}
}
}
esp_err_t usb_cfg_start(void)
{
usb_serial_jtag_driver_config_t cfg = USB_SERIAL_JTAG_DRIVER_CONFIG_DEFAULT();
cfg.rx_buffer_size = 1024;
cfg.tx_buffer_size = 2048;
esp_err_t err = usb_serial_jtag_driver_install(&cfg);
if (err != ESP_OK) {
ESP_LOGE(TAG, "USB serial driver install failed: %s", esp_err_to_name(err));
return err;
}
// Logs go through the driver too, so they and the replies share one queue
usb_serial_jtag_vfs_use_driver();
s_tx_lock = xSemaphoreCreateMutex();
if (!s_tx_lock) {
return ESP_ERR_NO_MEM;
}
s_log_vprintf = esp_log_set_vprintf(log_vprintf);
if (xTaskCreate(usb_cfg_task, "usb_cfg", 6144, NULL, 4, NULL) != pdPASS) {
return ESP_ERR_NO_MEM;
}
ESP_LOGI(TAG, "Config API on the USB serial port");
return ESP_OK;
}
+24
View File
@@ -0,0 +1,24 @@
/*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
#include "esp_err.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Serve the JSON API on the USB serial port (USB-Serial-JTAG), for led-tool.
*
* One request per line, one reply per line; every other line on the port is log output:
* @api {"id": n, "method": "GET" or "POST", "path": "/api/...", "body": ..., "host": optional}
* -> @api {"id": n, "status": 200, "body": "<JSON text>"}
* @reboot -> @ok, then the device restarts
*/
esp_err_t usb_cfg_start(void);
#ifdef __cplusplus
}
#endif
+35 -2
View File
@@ -12,6 +12,8 @@
#include "esp_log.h" #include "esp_log.h"
#include "esp_netif.h" #include "esp_netif.h"
#include "esp_timer.h" #include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include <netinet/tcp.h> #include <netinet/tcp.h>
#include <sys/socket.h> #include <sys/socket.h>
#include "esp_wifi.h" #include "esp_wifi.h"
@@ -1160,8 +1162,8 @@ static esp_err_t api_http_entry(httpd_req_t *req)
return reinterpret_cast<api_fn_t>(req->user_ctx)(&a); return reinterpret_cast<api_fn_t>(req->user_ctx)(&a);
} }
#define WS_MSG_MAX 2048 // a request message #define WS_MSG_MAX WEB_API_MSG_MAX
#define WS_REPLY_MAX 8192 // a reply envelope #define WS_REPLY_MAX WEB_API_REPLY_MAX
// Run an API route on this driver: target is the path, optionally with a query string. // Run an API route on this driver: target is the path, optionally with a query string.
static void ws_local(const char *method, const char *target, const char *body, char *out, size_t cap) static void ws_local(const char *method, const char *target, const char *body, char *out, size_t cap)
@@ -1234,6 +1236,37 @@ static void ws_dispatch(const char *msg, char *out, size_t cap)
cJSON_Delete(top); cJSON_Delete(top);
} }
// A call from outside the HTTP server (the USB config port). It runs on the server's own task, so it
// never races an HTTP or WebSocket handler (the preset list has no lock of its own).
struct api_call_t {
const char *msg;
char *out;
size_t cap;
SemaphoreHandle_t done;
};
static void api_call_work(void *arg)
{
api_call_t *c = static_cast<api_call_t *>(arg);
ws_dispatch(c->msg, c->out, c->cap);
xSemaphoreGive(c->done);
}
void web_api_call(const char *msg, char *out, size_t cap)
{
api_call_t c = { msg, out, cap, xSemaphoreCreateBinary() };
if (!s_server || !c.done) {
envelope(out, cap, 503, "{\"error\":\"web server not running\"}");
} else if (httpd_queue_work(s_server, api_call_work, &c) != ESP_OK) {
envelope(out, cap, 503, "{\"error\":\"server busy\"}");
} else {
xSemaphoreTake(c.done, portMAX_DELAY);
}
if (c.done) {
vSemaphoreDelete(c.done);
}
}
// WebSocket handler: one text frame in, one text frame out // WebSocket handler: one text frame in, one text frame out
// Another site's page must not drive this driver. A browser sends its Origin with the WebSocket // Another site's page must not drive this driver. A browser sends its Origin with the WebSocket
// handshake, and only a page from the LAN (or this device) may open the socket. ESP-IDF has no hook // handshake, and only a page from the LAN (or this device) may open the socket. ESP-IDF has no hook
+10
View File
@@ -10,6 +10,9 @@
extern "C" { extern "C" {
#endif #endif
#define WEB_API_MSG_MAX 2048 // a request message: {"method","path","body","host"}
#define WEB_API_REPLY_MAX 8192 // a reply envelope: {"status","body"}
/** @brief Start the HTTP server on port 80 (UI and JSON API). */ /** @brief Start the HTTP server on port 80 (UI and JSON API). */
esp_err_t web_start(void); esp_err_t web_start(void);
@@ -19,6 +22,13 @@ esp_err_t web_start(void);
*/ */
void web_allow_lan_origin(httpd_req_t *req); void web_allow_lan_origin(httpd_req_t *req);
/**
* @brief Run one API request without HTTP, as the WebSocket does: msg is
* {"method": "GET" or "POST", "path": "/api/...", "body": ..., "host": optional relay target}.
* out gets the envelope {"status": n, "body": "<JSON text>"}. Used by the USB config port.
*/
void web_api_call(const char *msg, char *out, size_t cap);
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
+2
View File
@@ -9,3 +9,5 @@ CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv"
# mDNS opens sockets on both the AP and client interfaces, plus HTTP and DDP. The default 10 runs out and httpd stops accepting. # mDNS opens sockets on both the AP and client interfaces, plus HTTP and DDP. The default 10 runs out and httpd stops accepting.
CONFIG_LWIP_MAX_SOCKETS=16 CONFIG_LWIP_MAX_SOCKETS=16
# Primary console on the C3's built-in USB (/dev/ttyACM0): logs and the led-tool config API (usb_cfg.cpp) share it
CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=y