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