# System Component [](https://components.espressif.com/components/espp/system) The `system` component answers "what is this device, how is it doing, and can I restart it?" for any espp application: - `espp::SystemInfo` — static getters (and a one-call `collect()` / `to_string()` snapshot) for the chip model / revision / cores / features, the ESP-IDF version, the application description (project name, version, build date and time, ELF SHA-256), the running and boot partitions with the OTA image state, the reset reason, uptime, base MAC, flash and PSRAM sizes, CPU frequency and the free / minimum-free heap. - `espp::SystemControl` — `reboot()` and `reboot_to_bootloader()`: the latter sets the chip's *force download boot* flag and restarts, so the device comes back in the ROM bootloader's download mode ready for `esptool` / `idf.py flash` (what holding the BOOT strap does, without a button). Supported on the ESP32-S2 / -S3 (the ROM enumerates its USB CDC / DFU device afresh after the reset), -C2 / -C3 / -C5 / -C6 / -C61 / -H2 / -H21 and -P4 (USB-Serial-JTAG); the classic ESP32 has no software path and reports `operation_not_supported`. On the S2 / S3 the ROM can also keep the USB peripheral's state across the reset (`BootloaderOptions::usb_persist`, `SystemService::Config::usb_persist`) so the host sees no re-plug — **opt-in, off by default**: the ROM only expects that from an application whose USB device is ROM-CDC/DFU-compatible (ESP-IDF's ROM USB console); a TinyUSB vendor + CDC composite like the espp examples has different descriptors, and persisting it can leave the host with a stale enumeration the bootloader cannot serve. - `espp::SystemService` — both of the above as a transport-agnostic [dispatcher](../dispatcher) module (`espp.system` v1, module 7 by default): `GET_INFO` answers with a tagged-record snapshot hosts can extend-proof decode, `REBOOT` / `REBOOT_TO_BOOTLOADER` reply OK and restart after a delay. Both restarts are guarded by `Config::allow_reboot` / `allow_bootloader` and an optional `on_reboot_request` veto callback, so an application can refuse a restart while, say, a motor is running. The hosted [system console](https://esp-cpp.github.io/espp/apps/system_console.html) web app (`web/system_console.html`) talks to the service over WebUSB or Web Serial, and to the [monitor](../monitor) component's `MonitorService` (heap regions + task table, live) when the device advertises it. The console connected to the example over WebUSB: device info, the two restart buttons and the heap gauges <img width="954" alt="espp System Console: device info, reboot / bootloader controls and heap gauges" src="https://github.com/user-attachments/assets/bc5fa520-f3a0-40de-9b53-889a887c0322" /> and its live task table, streamed by `MonitorService` <img width="946" alt="espp System Console streaming the task table (name, CPU %, stack high-water mark, priority, core)" src="https://github.com/user-attachments/assets/c2c962bf-debb-44c7-96a7-95527218d953" /> Auto-connect / auto-reconnect: opened with `?autoconnect=1&transport=usb|serial&vid=0x1209&pid=0x0d3a[&serial=...]` (what the Device Hub's links carry) the console connects on load, without the browser chooser, to a device the page was already granted. The **auto-reconnect** checkbox (default on, remembered per origin) reconnects after an unexpected link loss, e.g. the **Reboot** button: the device re-enumerates with the same ids and the console picks it up again. **Reboot into bootloader** disables that for the next loss (the ROM enumerates as a different USB device). Both paths only see devices the browser already granted to this page, i.e. a page served over HTTPS, or HTTP on localhost; a `file://` copy loses the grant on reload. <!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --> **Table of Contents** - [System Component](#system-component) - [Protocol (module 7, `espp.system` v1)](#protocol-module-7-esppsystem-v1) - [Host side: release the device before it resets](#host-side-release-the-device-before-it-resets) - [Example](#example) <!-- markdown-toc end --> ## Protocol (module 7, `espp.system` v1) Framed with `stream_frame` and routed by `espp::Dispatcher`; requests carry the reply flag clear, replies set it (type high bit). All multi-byte fields are little-endian. See `include/detail/system_protocol.hpp` (host-buildable, with `test/system_host_test.cpp`). | Type | Dir | Meaning | |------|-----|---------| | `0x01` GET_INFO | H→D | request an INFO reply | | `0x02` REBOOT | H→D | `[delay_ms u16]` — reply OK, restart after the delay | | `0x03` REBOOT_TO_BOOTLOADER | H→D | `[delay_ms u16]` — reply OK, restart into download mode | | `0x81` INFO | D→H | tagged records `[tag u8][len u8][value]` (unknown tags are skipped) | | `0x83` OK | D→H | `[request_type u8]` | | `0x84` ERROR | D→H | `[request_type u8][code u32][utf8 message]` — code is the POSIX errno of the chosen `std::errc` (the message is authoritative) | Every reply echoes the request frame's optional `stream_frame` correlation id, so a host that stamps its requests can pair replies with them and drop a late reply to a request it already timed out (the console does). INFO tags: 1 chip model (str), 2 chip revision (u16), 3 cores (u8), 4 chip features (u32), 5 IDF version, 6 project name, 7 app version, 8 build date, 9 build time, 10 ELF SHA-256 (32 bytes), 11 running partition, 12 boot partition, 13 OTA state (u8), 14 reset reason (u8), 15 uptime ms (u64), 16 MAC (6 bytes), 17 flash size, 18 PSRAM size, 19 CPU MHz, 20 free heap, 21 min free heap (all u32), 22 capabilities (u32: bit0 reboot allowed, bit1 bootloader reboot allowed and supported). The delay is clamped to at least `Config::min_restart_delay` so the OK reply leaves the transport before the restart. ## Host side: release the device before it resets A host that sends **REBOOT_TO_BOOTLOADER** over USB must have let go of the device before the reset fires. A device that is still open and claimed at that moment (a WebUSB interface with an IN transfer pending, a pyusb handle, an open serial port) can leave the host holding a stale record of it; macOS in particular. Then the ROM's USB device, which has other ids, does not enumerate until the board is unplugged and plugged back in. To the user it looks as if the device hung on its way into the bootloader. So, in a host (a web page, a script, a tool): 1. Ask for a delay long enough to close the connection first: at least **1000 ms**. The System Console sends `max(1000, the delay box)` for a bootloader reboot. 2. As soon as the OK reply arrives, stop anything that keeps transfers in flight (e.g. a monitor stream), release the interface and close the device (WebUSB: `releaseInterface()` then `close()`; Web Serial: cancel the reader and `close()` the port). If the link drops before the OK, the device is already on its way; close your side the same way. 3. Only then wait for the ROM's device: it enumerates with different ids (USB-Serial-JTAG `303a:1001` or the ROM's USB CDC `303a:0009` on the ESP32-S3), so look for it rather than reconnecting to the old one. A plain **REBOOT** comes back with the same ids and is reconnected the usual way, but the same order (close, then let it reset) never hurts. ## Example The [example](./example) exposes `SystemService` and `MonitorService` on the native USB port (vendor / WebUSB + CDC / Web Serial) of an ESP32-S3 for the system console web app.
da452d00f3a74499f899a69160fa8ea140d14bc9
idf.py add-dependency "espp/system^1.4.6"