espp/system

1.4.6

Latest
uploaded 1 hour ago
System identity / status (chip, app, partitions, reset reason, uptime, heap) and restart control (reboot, reboot into the ROM bootloader), plus a framed stream service and a browser console (WebUSB / Web Serial)

Readme

# System Component

[![Badge](https://components.espressif.com/components/espp/system/badge.svg)](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.

Links

Supports all targets

Maintainer

  • William Emfinger <waemfinger@gmail.com>
To add this component to your project, run:

idf.py add-dependency "espp/system^1.4.6"

download archive

Stats

  • Archive size
    Archive size ~ 58.33 KB
  • Downloaded in total
    Downloaded in total 488 times
  • Weekly Downloads Weekly Downloads (All Versions)
  • Downloaded this version
    This version: 0 times

Badge

espp/system version: 1.4.6
|