From 762ec338bc1b0edd88c8ecb5b0dafc6507d5585d Mon Sep 17 00:00:00 2001 From: jimmy Date: Wed, 11 Nov 2026 22:34:36 +1300 Subject: [PATCH] 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 --- README.md | 20 ++++++ main/CMakeLists.txt | 4 +- main/main.cpp | 2 + main/usb_cfg.cpp | 171 ++++++++++++++++++++++++++++++++++++++++++++ main/usb_cfg.h | 24 +++++++ main/web.cpp | 37 +++++++++- main/web.h | 10 +++ sdkconfig.defaults | 2 + 8 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 main/usb_cfg.cpp create mode 100644 main/usb_cfg.h diff --git a/README.md b/README.md index 86867f6..6f16859 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,26 @@ JSON API (port 80): | POST | `/api/wifi` | `{"ssid","password"}`: save and connect | | 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: ```bash diff --git a/main/CMakeLists.txt b/main/CMakeLists.txt index 212e069..d0b693e 100644 --- a/main/CMakeLists.txt +++ b/main/CMakeLists.txt @@ -1,6 +1,6 @@ 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 - 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 "." EMBED_TXTFILES "../web/index.html" "../web/app.js" "../web/style.css") diff --git a/main/main.cpp b/main/main.cpp index 8502267..e0f4ba5 100644 --- a/main/main.cpp +++ b/main/main.cpp @@ -9,6 +9,7 @@ #include "ota.h" #include "patterns.h" #include "presets.h" +#include "usb_cfg.h" #include "web.h" static const char *TAG = "example"; @@ -30,6 +31,7 @@ extern "C" void app_main(void) presets_apply_startup(); ESP_ERROR_CHECK(net_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()); ota_confirm_later(); diff --git a/main/usb_cfg.cpp b/main/usb_cfg.cpp new file mode 100644 index 0000000..6964b3a --- /dev/null +++ b/main/usb_cfg.cpp @@ -0,0 +1,171 @@ +/* + * SPDX-License-Identifier: Apache-2.0 + */ +#include +#include +#include +#include + +#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; +} diff --git a/main/usb_cfg.h b/main/usb_cfg.h new file mode 100644 index 0000000..909a8c5 --- /dev/null +++ b/main/usb_cfg.h @@ -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": ""} + * @reboot -> @ok, then the device restarts + */ +esp_err_t usb_cfg_start(void); + +#ifdef __cplusplus +} +#endif diff --git a/main/web.cpp b/main/web.cpp index d75995c..d0526d5 100644 --- a/main/web.cpp +++ b/main/web.cpp @@ -12,6 +12,8 @@ #include "esp_log.h" #include "esp_netif.h" #include "esp_timer.h" +#include "freertos/FreeRTOS.h" +#include "freertos/semphr.h" #include #include #include "esp_wifi.h" @@ -1160,8 +1162,8 @@ static esp_err_t api_http_entry(httpd_req_t *req) return reinterpret_cast(req->user_ctx)(&a); } -#define WS_MSG_MAX 2048 // a request message -#define WS_REPLY_MAX 8192 // a reply envelope +#define WS_MSG_MAX WEB_API_MSG_MAX +#define WS_REPLY_MAX WEB_API_REPLY_MAX // 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) @@ -1234,6 +1236,37 @@ static void ws_dispatch(const char *msg, char *out, size_t cap) 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(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 // 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 diff --git a/main/web.h b/main/web.h index 8ca586c..36fd345 100644 --- a/main/web.h +++ b/main/web.h @@ -10,6 +10,9 @@ extern "C" { #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). */ 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); +/** + * @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": ""}. Used by the USB config port. + */ +void web_api_call(const char *msg, char *out, size_t cap); + #ifdef __cplusplus } #endif diff --git a/sdkconfig.defaults b/sdkconfig.defaults index d0994b1..72e234b 100644 --- a/sdkconfig.defaults +++ b/sdkconfig.defaults @@ -9,3 +9,5 @@ CONFIG_PARTITION_TABLE_CUSTOM=y 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. 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