Harden USB logging and persist watchdog events in management reports
This commit is contained in:
1 parent
bd55369aa9
commit
3add4695cc
98 files changed
+7207
-372
No files matched your search
@@ -7,9 +7,13 @@
|
||||
// which Web Crypto exposes directly. AES-CBC with a zero IV supplies the
|
||||
// required AES block primitive; only its first ciphertext block is used.
|
||||
const HEADER = 83;
|
||||
const MGR2_HEADER = 98;
|
||||
const CURRENT_HEADER = 111;
|
||||
const TAG = 16;
|
||||
const ENTRY = 13;
|
||||
const PER_PAGE = 6;
|
||||
const MGR2_PER_PAGE = 5;
|
||||
const CURRENT_PER_PAGE = 4;
|
||||
const MAX_KEYS = 36;
|
||||
const ZERO_BLOCK = new Uint8Array(16);
|
||||
const UTF8 = new TextEncoder();
|
||||
@@ -214,22 +218,35 @@
|
||||
return (await hmacSha256(key, concatBytes(radio, normalized))).slice(0, 12);
|
||||
}
|
||||
|
||||
function layout(payload) {
|
||||
const magic = bytesToAscii(payload, 0, 4);
|
||||
if (magic === "MGR1") return { header: HEADER, perPage: PER_PAGE };
|
||||
if (magic === "MGR2") return { header: MGR2_HEADER, perPage: MGR2_PER_PAGE };
|
||||
if (magic === "MGR3") return { header: CURRENT_HEADER, perPage: CURRENT_PER_PAGE };
|
||||
return null;
|
||||
}
|
||||
|
||||
function canonicalLength(payload) {
|
||||
if (payload.length < HEADER + TAG || bytesToAscii(payload, 0, 4) !== "MGR1") {
|
||||
managementError("This data does not begin with an MGR1 management page.");
|
||||
const format = layout(payload);
|
||||
if (!format || payload.length < format.header + TAG) {
|
||||
managementError("This data does not begin with a complete MGR1/MGR2/MGR3 management page.");
|
||||
}
|
||||
if (format.header >= MGR2_HEADER && ((uint16LE(payload, 83) & 0xf800) || (payload[85] & 0xc0))) {
|
||||
managementError("Reserved USB status bits must be zero.");
|
||||
}
|
||||
if (format.header === CURRENT_HEADER) usbWatchdogEvent(payload);
|
||||
const page = payload[78];
|
||||
const pages = payload[79];
|
||||
const total = payload[80];
|
||||
const first = payload[81];
|
||||
const count = payload[82];
|
||||
const expectedPages = total ? Math.ceil(total / PER_PAGE) : 1;
|
||||
const expectedPages = total ? Math.ceil(total / format.perPage) : 1;
|
||||
if (total > MAX_KEYS || pages !== expectedPages || page >= pages ||
|
||||
first !== page * PER_PAGE || first > total ||
|
||||
count !== Math.min(PER_PAGE, total - first)) {
|
||||
managementError("The MGR1 page index or ACL bounds are invalid.");
|
||||
first !== page * format.perPage || first > total ||
|
||||
count !== Math.min(format.perPage, total - first)) {
|
||||
managementError("The management page index or ACL bounds are invalid.");
|
||||
}
|
||||
return HEADER + count * ENTRY + TAG;
|
||||
return format.header + count * ENTRY + TAG;
|
||||
}
|
||||
|
||||
function paddedFloodLength(canonical) {
|
||||
@@ -256,13 +273,13 @@
|
||||
const hops = pathInfo & 0x3f;
|
||||
if (width > 3 || hops * width > 64) return null;
|
||||
const payloadOffset = pathOffset + 1 + width * hops;
|
||||
if (payloadOffset >= bytes.length || bytesToAscii(bytes, payloadOffset, 4) !== "MGR1") return null;
|
||||
if (payloadOffset >= bytes.length || !layout(bytes.slice(payloadOffset))) return null;
|
||||
const payload = bytes.slice(payloadOffset);
|
||||
const canonical = canonicalLength(payload);
|
||||
const padded = paddedFloodLength(canonical);
|
||||
if (payload.length !== canonical &&
|
||||
(payload.length !== padded || !payload.slice(canonical).every((value) => value === 0))) {
|
||||
managementError("MGR1 packet padding or length is invalid.");
|
||||
managementError("Management packet padding or length is invalid.");
|
||||
}
|
||||
return {
|
||||
payload: payload.slice(0, canonical),
|
||||
@@ -277,26 +294,35 @@
|
||||
}
|
||||
|
||||
function parseCanonical(bytes) {
|
||||
if (bytesToAscii(bytes, 0, 4) !== "MGR1") return null;
|
||||
if (!layout(bytes)) return null;
|
||||
const canonical = canonicalLength(bytes);
|
||||
const padded = paddedFloodLength(canonical);
|
||||
if (bytes.length !== canonical &&
|
||||
(bytes.length !== padded || !bytes.slice(canonical).every((value) => value === 0))) {
|
||||
managementError("MGR1 payload padding or length is invalid.");
|
||||
managementError("Management payload padding or length is invalid.");
|
||||
}
|
||||
return { payload: bytes.slice(0, canonical), envelope: null };
|
||||
}
|
||||
|
||||
function inputByteStreams(input) {
|
||||
if (typeof input !== "string" || input.trim() === "") {
|
||||
managementError("Paste one or more MGR1 payloads or GroupData packet hex values first.");
|
||||
managementError("Paste one or more MGR1/MGR2/MGR3 payloads or GroupData packet hex values first.");
|
||||
}
|
||||
if (input.length > 32768) managementError("The pasted value is too large to be management-report data.");
|
||||
const candidates = [input, ...input.split(/\r?\n/)];
|
||||
// A wrapped single page is one candidate, not an invalid first-line
|
||||
// fragment. Conversely, joining complete page lines creates a bogus
|
||||
// oversized canonical page: let each line retain its own bounds.
|
||||
try {
|
||||
const whole = hexToBytes(input);
|
||||
if (parseCanonical(whole) || parsePacket(whole)) return [whole];
|
||||
} catch (_error) {
|
||||
// JSON/log wrappers and multiple complete page lines are handled below.
|
||||
}
|
||||
const candidates = input.split(/\r?\n/);
|
||||
const quotedRaw = /["'](?:raw|data)["']\s*:\s*["']([^"']+)["']/gi;
|
||||
let match;
|
||||
while ((match = quotedRaw.exec(input)) !== null) candidates.push(match[1]);
|
||||
const streams = input.match(/(?:0x)?[0-9a-f]{2}(?:(?:[\s:,_-]*)(?:0x)?[0-9a-f]{2}){15,}/gi);
|
||||
const streams = input.match(/(?:0x)?[0-9a-f]{2}(?:(?:[ \t:,_-]*)(?:0x)?[0-9a-f]{2}){15,}/gi);
|
||||
if (streams) candidates.push(...streams);
|
||||
|
||||
const unique = new Map();
|
||||
@@ -319,7 +345,7 @@
|
||||
try {
|
||||
parsed = parseCanonical(bytes) || parsePacket(bytes);
|
||||
} catch (error) {
|
||||
if (error instanceof ManagementDecodeError && bytesToAscii(bytes, 0, 4) !== "MGR1") {
|
||||
if (error instanceof ManagementDecodeError && !layout(bytes)) {
|
||||
// It may be an unrelated hex stream alongside a valid packet.
|
||||
continue;
|
||||
}
|
||||
@@ -333,7 +359,7 @@
|
||||
}
|
||||
}
|
||||
if (!found.length) {
|
||||
managementError("No complete MGR1 management page was found. Paste canonical MGR1 payload hex or an entire GroupData packet.");
|
||||
managementError("No complete management page was found. Paste canonical MGR1/MGR2/MGR3 payload hex or an entire GroupData packet.");
|
||||
}
|
||||
return found;
|
||||
}
|
||||
@@ -366,6 +392,45 @@
|
||||
return ({ 1: "repeater", 2: "room server", 3: "sensor" })[value] || `unknown (${value})`;
|
||||
}
|
||||
|
||||
function usbStatus(payload) {
|
||||
if (!["MGR2", "MGR3"].includes(bytesToAscii(payload, 0, 4))) return null;
|
||||
const flags = uint16LE(payload, 83);
|
||||
const names = ["supported", "loggingEnabled", "watchdogEnabled", "hostConnected",
|
||||
"readerConnected", "stalled", "recovering", "recoveryDeferred", "persistenceReady", "watchdogAuto", "loggerActive"];
|
||||
const result = {};
|
||||
names.forEach((name, bit) => { result[name] = Boolean(flags & (1 << bit)); });
|
||||
result.stage = payload[85] & 3;
|
||||
result.backoffStep = (payload[85] >> 2) & 15;
|
||||
result.retrySeconds = uint32LE(payload, 86);
|
||||
result.inactiveSeconds = uint32LE(payload, 90);
|
||||
result.autoConnectedSeconds = uint32LE(payload, 94);
|
||||
return result;
|
||||
}
|
||||
|
||||
function usbWatchdogEvent(payload) {
|
||||
if (bytesToAscii(payload, 0, 4) !== "MGR3") return null;
|
||||
const code = payload[98];
|
||||
const sequence = uint32LE(payload, 107);
|
||||
if (!sequence) {
|
||||
if (!payload.slice(98, 111).every((value) => value === 0)) {
|
||||
managementError("Invalid empty USB watchdog event.");
|
||||
}
|
||||
return null;
|
||||
}
|
||||
const reasons = code & 15;
|
||||
const actionCode = (code >> 4) & 7;
|
||||
if (!reasons || actionCode < 1 || actionCode > 4) {
|
||||
managementError("Invalid USB watchdog event reason/action.");
|
||||
}
|
||||
const names = ["host-absent", "reader-absent", "tx-stalled", "client-inactive"];
|
||||
return {
|
||||
reasons, reasonNames: names.filter((_name, bit) => reasons & (1 << bit)),
|
||||
actionCode, action: [null, "soft-recovery", "reenumerate", "reboot-requested", "reboot-cancelled"][actionCode],
|
||||
persisted: Boolean(code & 128), epoch: uint32LE(payload, 99),
|
||||
uptimeSeconds: uint32LE(payload, 103), sequence,
|
||||
};
|
||||
}
|
||||
|
||||
function publicFields(payload, envelope) {
|
||||
const valid = uint16LE(payload, 76);
|
||||
const capabilities = payload[73];
|
||||
@@ -374,6 +439,7 @@
|
||||
const knownActive = featureNames(active & known);
|
||||
const unknownActive = featureNames(capabilities & ~known);
|
||||
return {
|
||||
protocol: bytesToAscii(payload, 0, 4),
|
||||
radioId: bytesToHex(payload.slice(4, 20)),
|
||||
sequence: uint32LE(payload, 20),
|
||||
timestamp: uint32LE(payload, 24),
|
||||
@@ -396,6 +462,8 @@
|
||||
acl: `${payload[80]} total; ${payload[82]} on this page`,
|
||||
partialSince: Boolean(valid & 32),
|
||||
mcuTemperature: Boolean(valid & 64),
|
||||
usbLogging: usbStatus(payload),
|
||||
usbWatchdogLast: usbWatchdogEvent(payload),
|
||||
envelope,
|
||||
};
|
||||
}
|
||||
@@ -417,9 +485,11 @@
|
||||
});
|
||||
const sorted = [...byPage.values()].sort((left, right) => left.payload[78] - right.payload[78]);
|
||||
const reference = sorted[0].payload;
|
||||
const header = layout(reference).header;
|
||||
if (sorted.some((page) => !equalBytes(page.payload.slice(0, 78), reference.slice(0, 78)) ||
|
||||
!equalBytes(page.payload.slice(HEADER, header), reference.slice(HEADER, header)) ||
|
||||
page.payload[79] !== reference[79] || page.payload[80] !== reference[80])) {
|
||||
managementError("MGR1 pages do not belong to the same snapshot.");
|
||||
managementError("Management pages do not belong to the same snapshot.");
|
||||
}
|
||||
return sorted;
|
||||
}
|
||||
@@ -427,9 +497,10 @@
|
||||
async function decryptPage(payload, password, candidate) {
|
||||
const root = await passwordKey(password);
|
||||
const key = await deriveKey(root, "MeshCore-MGR1-SIV", payload.slice(4, 20));
|
||||
const header = layout(payload).header;
|
||||
const privateLength = payload[82] * ENTRY;
|
||||
const plaintext = await openSiv(key, payload.slice(0, HEADER),
|
||||
payload.slice(HEADER, HEADER + privateLength), payload.slice(HEADER + privateLength));
|
||||
const plaintext = await openSiv(key, payload.slice(0, header),
|
||||
payload.slice(header, header + privateLength), payload.slice(header + privateLength));
|
||||
try {
|
||||
let wanted = null;
|
||||
if (candidate) wanted = await aclFingerprint(password, payload.slice(4, 20), candidate);
|
||||
@@ -517,6 +588,7 @@
|
||||
|
||||
function render(model) {
|
||||
const values = [
|
||||
["Protocol", model.public.protocol],
|
||||
["Reporter", model.public.radioId], ["Sequence", model.public.sequence],
|
||||
["Report time", timestampText(model.public.timestamp)], ["Role", model.public.role],
|
||||
["Firmware", model.public.firmware], ["Bootloader", model.public.bootloader],
|
||||
@@ -528,6 +600,35 @@
|
||||
["Compiled capabilities", model.public.compiled], ["Known active capabilities", model.public.active],
|
||||
["Page", model.public.page], ["ACL", model.public.acl],
|
||||
];
|
||||
const usb = model.public.usbLogging;
|
||||
if (usb) {
|
||||
const stage = ["idle", "soft recovery wait", "re-enumeration wait", "reboot pending"][usb.stage];
|
||||
values.push(["USB logging", usb.supported ? (usb.loggingEnabled ? "enabled" : "disabled") : "unsupported"],
|
||||
["USB watchdog", usb.watchdogAuto ? "Auto (qualifying)" : usb.watchdogEnabled ? "On" : "Off"],
|
||||
["USB Auto qualification", `${usb.autoConnectedSeconds}s of 1209600s`],
|
||||
["USB host / reader", `${usb.hostConnected ? "host connected" : "no host"}; ${usb.readerConnected ? "reader connected" : "no reader"}`],
|
||||
["USB logging client", usb.loggerActive ? "recent USB stats polling (15-minute lease)" : "inactive (stats lease or healthy USB link missing)"],
|
||||
["USB recovery", `${usb.stalled ? "stalled; " : ""}${usb.recovering ? "recovering; " : ""}${usb.recoveryDeferred ? "deferred; " : ""}${stage}; backoff=${usb.backoffStep}`],
|
||||
["USB retry interval / inactive", `${usb.retrySeconds}s / ${usb.inactiveSeconds}s`],
|
||||
["USB persistence", usb.persistenceReady ? "ready" : "not ready"]);
|
||||
} else {
|
||||
values.push(["USB logging status", "unavailable in MGR1"]);
|
||||
}
|
||||
const event = model.public.usbWatchdogLast;
|
||||
if (event) {
|
||||
values.push(["Last USB watchdog event", `#${event.sequence}: ${event.action}`],
|
||||
["USB watchdog event reasons", event.reasonNames.join(", ")],
|
||||
["USB watchdog event time", `${timestampText(event.epoch)} (advisory RTC; raw epoch=${event.epoch})`],
|
||||
["USB watchdog event uptime", `${event.uptimeSeconds}s at the recorded boot`],
|
||||
["USB watchdog event persistence", event.persisted ? "saved" : "RAM-only"],
|
||||
["USB watchdog action meaning", event.actionCode === 3
|
||||
? "Reboot was requested; this does not prove a physical reset occurred."
|
||||
: event.actionCode === 4 ? "Reboot request was cancelled; no physical reset is claimed."
|
||||
: "Recovery attempt was recorded; this does not prove successful recovery."]);
|
||||
} else {
|
||||
values.push(["Last USB watchdog event", model.public.protocol === "MGR3"
|
||||
? "none recorded" : "unavailable in MGR1/MGR2"]);
|
||||
}
|
||||
summary.replaceChildren();
|
||||
values.forEach(([term, description]) => {
|
||||
const item = document.createElement("div");
|
||||
@@ -540,7 +641,7 @@
|
||||
});
|
||||
status.textContent = model.authenticated
|
||||
? `Password-authenticated ${model.suppliedPages}/${model.pageCount} page${model.pageCount === 1 ? "" : "s"}.`
|
||||
: "Public-only decode — no authenticity claim without the management password.";
|
||||
: "Public-only decode - no authenticity claim without the management password.";
|
||||
status.classList.toggle("management-status-authenticated", model.authenticated);
|
||||
|
||||
warningList.replaceChildren();
|
||||
|
||||
@@ -104,15 +104,15 @@ getters; relaying a command over LoRa keeps its remote restrictions.
|
||||
|
||||
| Build/profile | Command availability |
|
||||
|---|---|
|
||||
| Standard non-MQTT repeater or room server | Keeps the normal role CLI and, where USB is a safe plaintext console, embeds debug/packet logging behind persistent `get/set usb.logging`. The explicitly selected portable policy can omit WebConfig and browser WiFi OTA, so those commands are unavailable and the omission is recorded in the capability manifest. |
|
||||
| Standard non-MQTT repeater or room server | Keeps the normal role CLI and, where USB is a safe plaintext console, embeds packet logging behind persistent `get/set usb.logging` and separately saved `get/set usb.debug` verbosity. USB debug defaults off and requires compiled diagnostic support. The explicitly selected portable policy can omit WebConfig and browser WiFi OTA, so those commands are unavailable and the omission is recorded in the capability manifest. |
|
||||
| Legacy standard logging | No longer emitted separately. Its behavior is compiled into the ordinary artifact. Size-constrained STM32 targets embed packet logging without verbose `MESH_DEBUG`. |
|
||||
| LoRa-OTA (`-ota-`) | LoRa OTA adds the `ota ...` commands; it does not otherwise reduce the role CLI. ESP32 `no_external_sensors` artifacts retain the compact browser WiFi uploader, the complete CLI, and up to 254 neighbors, subject to recorded internal-DRAM reductions. |
|
||||
| nRF52 repeater/room-server/sensor release pair | `full-ota` retains the complete supported sensor recipe; `reduced-ota` omits declared optional sensor drivers. Both include verified LoRa OTA, use the same logical target identity and exact storage/layout contract within the pair, and retain the role's normal commands. Repeaters/room servers also verify `retry.preset`. RAK3401 and RAK4631 reduced builds retain GPS where compatible and INA219/INA226/INA260/INA3221 I2C voltage/current monitors. External QSPI/SD targets also publish both choices. Companion/Terminal Chat and KISS roles do not enter this policy. |
|
||||
| ESP32 MQTT observer or ESP-NOW bridge | Always uses the expanded FULL partition profile. The build never substitutes a reduced CLI to fit the legacy application slot. |
|
||||
| FULL ESP32 USB + WiFi | Uses the matching MQTT target with packet logging on, verbose debug off, and the complete command surface supported by that role and hardware. `get/set logging.output off\|usb\|wifi\|both` selects and persists the active output paths. |
|
||||
| FULL ESP32 logging fallback | Uses the matching non-MQTT target only when no WiFi MQTT sibling exists, with debug and packet logging enabled and the complete command surface supported by that role and hardware. Its persistent USB gate also covers output-off operation, avoiding a second FULL ESP-NOW image. |
|
||||
| nRF52 dual-CDC Full Companion | Fresh installs expose only interface `00`; it starts as an ASCII terminal and automatically hands a complete `<` frame to framed Companion. The same interface also carries exclusive serial mOTA traffic. Enabling logging and rebooting adds interface `02` for plaintext logs. BLE and source-only LoRa OTA remain available. `get/set usb.logging` persistently controls whether the logging interface is present. |
|
||||
| ESP32 single-TTY Full Companion | Every ESP32 Full image starts with the ASCII terminal on its one USB TTY and automatically hands a complete `<` frame to framed Companion. On 1.17.1.5, run `set powersaving off` first. `set usb.logging on` switches that TTY to an input-capable plaintext logging terminal and makes framed Companion unavailable on USB; `set usb.logging off` stops logging but leaves the TTY in normal ASCII mode. The terminal stop token or a valid incoming framed probe then performs the ordinary switch to Binary Companion. A saved logging-on setting starts directly in that logging terminal and disables automatic frame detection. BLE, WiFi, and source-only LoRa OTA remain available. ESP32 Full uses Arduino-ESP32 2.x where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but still expose only one TTY. |
|
||||
| FULL ESP32 USB + WiFi | Uses the matching MQTT target with packet logging, USB debug defaulting off, and the complete command surface supported by that role and hardware. Debug verbosity can be enabled only for diagnostics compiled into that image. `get/set logging.output off\|usb\|wifi\|both` selects and persists the active output paths; `get/set usb.debug` separately saves USB verbosity. |
|
||||
| FULL ESP32 logging fallback | Uses the matching non-MQTT target only when no WiFi MQTT sibling exists, with debug and packet support compiled and the complete command surface supported by that role and hardware. USB debug defaults off; `get/set usb.debug` selects verbose output independently of packet capture. Its persistent USB master also covers output-off operation, avoiding a second FULL ESP-NOW image. |
|
||||
| nRF52 dual-CDC Full Companion | Fresh installs expose only interface `00`; it starts as an ASCII terminal and automatically hands a complete `<` frame to framed Companion. The same interface also carries exclusive serial mOTA traffic. Enabling logging and rebooting adds output-only interface `02` for ASCII RAW/RX/TX records and optional debug. BLE and source-only LoRa OTA remain available. `get/set usb.logging` persistently controls whether the logging interface is present; `get/set usb.debug` changes verbosity without a reboot. Send CLI/control queries to interface `00`, not the log endpoint. |
|
||||
| ESP32 single-TTY Full Companion | Every ESP32 Full image starts with the ASCII terminal on its one USB TTY and automatically hands a complete `<` frame to framed Companion. On 1.17.1.5, run `set powersaving off` first. `set usb.logging on` switches that TTY to an input-capable plaintext RAW/RX/TX logging terminal and makes framed Companion unavailable on USB; `set usb.logging off` stops logging but leaves the TTY in normal ASCII mode. `get/set usb.debug` separately controls saved verbose diagnostics, defaulting off. The terminal stop token or a valid incoming framed probe then performs the ordinary switch to Binary Companion. A saved logging-on setting starts directly in that logging terminal and disables automatic frame detection. BLE, WiFi, and source-only LoRa OTA remain available. ESP32 Full uses Arduino-ESP32 2.x where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but still expose only one TTY. |
|
||||
| `no_external_sensors` | Trims selected optional environmental/ranging drivers and their settings; it does not remove generic I2C, core repeater discovery, routing, or runtime RS-232 commands. RAK3401 and RAK4631 profiles retain the four common INA I2C voltage/current monitors. GPS-preserving RAK nRF52 OTA profiles retain their GPS commands and provider; RAK4631 defaults the bridge to UART 2 because RAK12501/L76K GPS uses UART 1. Legacy target suffixes remain stable for OTA identity compatibility. |
|
||||
|
||||
The four retained INA drivers are entries in the optional environmental-sensor
|
||||
@@ -129,6 +129,10 @@ both devices on one bus, leave RAK12500 at `0x42`, strap INA3221 A0 to SCL for
|
||||
`logging`, `OTA`, and `FULL` describe independent build features in historical
|
||||
filenames. Current standard artifacts use no `-logging-` infix because their
|
||||
USB logging is runtime controlled.
|
||||
USB packet capture and debug verbosity share the canonical artifact, not a new
|
||||
build/profile name. `usb.logging` remains the master; verbose diagnostics need
|
||||
both that switch and saved `usb.debug` on. Fresh and legacy preferences default
|
||||
debug to off. Setting debug on cannot restore code compiled out of an image.
|
||||
|
||||
## Canonical bulk-build policy
|
||||
|
||||
|
||||
@@ -38,6 +38,14 @@ Build columns mean:
|
||||
where there is no MQTT sibling. It has the complete parser and a saved
|
||||
USB-logging on/off gate. ESP-NOW bridges use this profile.
|
||||
|
||||
USB packet output and verbose diagnostics are separate saved controls in
|
||||
current source. Where `usb.logging` is available, `get/set usb.debug on|off`
|
||||
selects debug intent without changing packet capture or adding a build variant.
|
||||
Debug defaults off for fresh and older preference images; effective output
|
||||
requires `usb.logging` and `usb.debug` on plus compiled diagnostic support.
|
||||
See [live USB logging](cli_commands.md#control-live-usb-logging) for transport
|
||||
restrictions and Full Companion RAW output.
|
||||
|
||||
The firmware-configured INA3221 and RAK12500 addresses are both `0x42`; they
|
||||
cannot coexist on one bus at those addresses. Leave RAK12500 at `0x42`, strap
|
||||
INA3221 A0 to SCL for `0x43`, and use a build with
|
||||
@@ -71,6 +79,7 @@ over the normal binary USB, BLE, or TCP connection:
|
||||
| `stats-core`, `stats-radio`, `stats-radio-diag`, `stats-packets` | Local terminal and binary command `0x42` |
|
||||
| `erase` | Local terminal and binary command `0x42`; reboot after erasing stored settings |
|
||||
| `set freq <MHz>` | Local terminal, binary command `0x42`, and authorized LoRa CLI; reboot to apply |
|
||||
| [`get public.key`](cli_commands.md#view-this-nodes-public-key) | Companion text terminal and binary command `0x42`; read-only, no private-key export feature required |
|
||||
| `get prv.key` | Local terminal and binary command `0x42`; requires private key export enabled |
|
||||
| `get password` | Reports that Companion has no admin password; infrastructure returns its password locally |
|
||||
| `get wifi.pwd`, `get mqttN.password`, `get mqttN.token` | Local terminal and binary command `0x42`; corresponding WiFi/MQTT feature required |
|
||||
@@ -124,6 +133,9 @@ should use command `0x42`. See [Companion radio binary protocol](companion_proto
|
||||
| Logging | [`log start`; `log stop`; `log erase`](cli_commands.md#logging) | Storage-backed roles retain data; other roles can return empty data | Yes | Yes | Yes |
|
||||
| Logging | [`log`](cli_commands.md#print-the-captured-log-to-the-serial-terminal) | Local connection | Local | Local | Local |
|
||||
| Logging | [`get/set usb.logging`; unified FULL `get/set logging.output`](cli_commands.md#control-live-usb-logging) | Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; nRF52 Full Companion can add a reboot-controlled second CDC | Yes | Yes | No |
|
||||
| Logging | [`get/set usb.debug`](cli_commands.md#control-live-usb-logging) | Same USB-control availability; saved intent defaults off; actual diagnostics need compiled support and USB master on | Yes | Yes | No |
|
||||
| Logging | [`get/set usb.watchdog off\|on\|auto`](usb_logging_watchdog.md) | Current source; recovery requires native USB, live logging, and durable storage; Auto qualifies from USB stats polling | Yes | Yes | Feature |
|
||||
| Logging | [`get usb.watchdog.last`](usb_logging_watchdog.md#last-event-review) | Current source; latest USB watchdog event with advisory timestamp, uptime, action, reasons, and durability; native USB required | Yes | Yes | Feature |
|
||||
| Radio | [`get radio`; `set radio ...`](cli_commands.md#view-or-change-this-nodes-radio-parameters) | All text CLI roles | Yes | Yes | Yes |
|
||||
| Radio | [`get tx`; `set tx <dbm>`](cli_commands.md#view-or-change-this-nodes-transmit-power) | Board TX-power limits apply | Yes | Yes | Yes |
|
||||
| Radio | [`tempradio ...`; `normalradio`](cli_commands.md#change-the-radio-parameters-for-a-set-duration) | Full parser | Yes | Yes | Yes |
|
||||
@@ -293,6 +305,9 @@ should use command `0x42`. See [Companion radio binary protocol](companion_proto
|
||||
| Logging | [`log start`; `log stop`; `log erase`](cli_commands.md#logging) | Storage-backed roles retain data | Yes | Yes | Yes | Yes | Yes |
|
||||
| Logging | [`log`](cli_commands.md#print-the-captured-log-to-the-serial-terminal) | Local connection | Local | Local | Local | Local | Local |
|
||||
| Logging | [`get/set usb.logging`; unified FULL `get/set logging.output`](cli_commands.md#control-live-usb-logging) | Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; every ESP32 Full Companion uses an input-capable single-TTY logging terminal with framed USB Companion disabled while logging | Yes | Yes | No | No | Yes |
|
||||
| Logging | [`get/set usb.debug`](cli_commands.md#control-live-usb-logging) | Same USB-control availability; saved intent defaults off; actual diagnostics need compiled support and USB master on | Yes | Yes | No | No | Yes |
|
||||
| Logging | [`get/set usb.watchdog off\|on\|auto`](usb_logging_watchdog.md) | Current source; recovery requires native USB, live logging, and durable storage; Auto qualifies from USB stats polling | Yes | Yes | Feature | Yes | Yes |
|
||||
| Logging | [`get usb.watchdog.last`](usb_logging_watchdog.md#last-event-review) | Current source; latest USB watchdog event with advisory timestamp, uptime, action, reasons, and durability; native USB required | Yes | Yes | Feature | Yes | Yes |
|
||||
| Radio | [`get radio`; `set radio ...`](cli_commands.md#view-or-change-this-nodes-radio-parameters) | All text CLI roles | Yes | Yes | Yes | Yes | Yes |
|
||||
| Radio | [`get tx`; `set tx <dbm>`](cli_commands.md#view-or-change-this-nodes-transmit-power) | Board TX-power limits apply | Yes | Yes | Yes | Yes | Yes |
|
||||
| Radio | [`tempradio ...`; `normalradio`](cli_commands.md#change-the-radio-parameters-for-a-set-duration) | Full parser | Yes | Yes | Yes | Yes | Yes |
|
||||
|
||||
+101
-19
@@ -462,7 +462,7 @@ command `0x42` where the role supports the command; unavailable over LoRa.
|
||||
### Remove a neighbor
|
||||
**Usage:**
|
||||
- `neighbor.remove <pubkey_prefix>`
|
||||
- `neighbor.remove` — remove all neighbors
|
||||
- `neighbor.remove` - remove all neighbors
|
||||
|
||||
**Parameters:**
|
||||
- `pubkey_prefix`: An even-length hexadecimal prefix (up to the full 64-character
|
||||
@@ -1040,17 +1040,27 @@ flip state on display-enabled observer builds.
|
||||
|
||||
## Logging
|
||||
|
||||
Builds compiled with `MESH_PACKET_LOGGING` emit one `RAW:` line for every
|
||||
received radio frame. Serial output uses backpressure: if a connected host
|
||||
temporarily stops reading, packet processing waits for USB transmit space
|
||||
instead of silently omitting the record. A disconnected host cannot retain an
|
||||
unbounded capture, so logging deployments should keep the reader attached and
|
||||
draining the serial port.
|
||||
Non-compact builds compiled with `MESH_PACKET_LOGGING` emit a `RAW:` line
|
||||
for received radio frames that reach the raw capture hook while `usb.logging`
|
||||
is on, including Full Companion. Frames rejected by the early route policy
|
||||
are not exposed to raw capture.
|
||||
`RAW:` contains the complete received frame as uppercase hexadecimal, not only
|
||||
its decoded payload. Packet records do not require verbose USB debug output.
|
||||
Keep the host reader attached and draining the serial port: capture is best
|
||||
effort, not durable storage. Native-USB transports use bounded queues and drop
|
||||
records rather than block radio processing when the host stops reading;
|
||||
`DROP:<count>` markers report capture loss when output capacity returns.
|
||||
|
||||
Every valid received frame also emits the decoded RX summary, including signal,
|
||||
Successfully parsed received frames also emit the decoded RX summary, including signal,
|
||||
timing, hash, type, route, and payload information. Frames that cannot be
|
||||
decoded still emit their `RAW:` line. Transmitted packets emit the decoded TX
|
||||
summary.
|
||||
decoded, or cannot obtain a packet-pool slot, can still emit their `RAW:` line.
|
||||
Transmitted packets emit the decoded TX
|
||||
summary. RAW and RX summary are separate records, not an atomic pair; a queue
|
||||
drop or disconnect can leave a summary without its RAW bytes. USB log consumers
|
||||
must not associate a stale RAW record with the next unrelated summary.
|
||||
Size-constrained `MESH_PACKET_LOGGING_COMPACT` images instead use `R<hex>` and
|
||||
`T<hex>` records; that compact stream is not the full ASCII RAW/summary format
|
||||
expected by ordinary USB-to-MQTT parsers.
|
||||
|
||||
Ordinary non-OTA artifacts compile packet logging into the canonical image and
|
||||
control its live USB output at runtime; no separate `-logging-` artifact is
|
||||
@@ -1072,8 +1082,27 @@ set usb.logging on
|
||||
set usb.logging off
|
||||
set usb.logging on reboot
|
||||
set usb.logging off reboot
|
||||
get usb.debug
|
||||
set usb.debug on
|
||||
set usb.debug off
|
||||
```
|
||||
|
||||
Current source also provides `get usb.watchdog` and saved
|
||||
`set usb.watchdog off|on|auto`. Missing watchdog state defaults to Auto, which
|
||||
requires 14 continuous healthy logging-client days before saving On. Existing
|
||||
five-minute USB stats polls confirm recent logging-client activity; a plugged
|
||||
cable/open TTY alone does not. See the [USB logging watchdog](usb_logging_watchdog.md) for staged
|
||||
five-minute USB recovery, physical-fault-only MCU resets, persisted backoff,
|
||||
status fields, and safe shutdown deferrals. Older release binaries need an
|
||||
upgrade before these commands exist.
|
||||
|
||||
`get usb.watchdog.last` shows the latest USB watchdog event: recovery action,
|
||||
fault-reason bitmask, advisory node-clock epoch, uptime at the event, sequence,
|
||||
and whether the record passed durable readback. It survives reboot on durable
|
||||
storage. `reboot-requested` records intent, not proof that a physical reset
|
||||
occurred; a later safety veto records `reboot-cancelled`. See the watchdog
|
||||
documentation for storage and timestamp limitations.
|
||||
|
||||
**ESP32 1.17.1.5 USB logging procedure:** disable device sleep before enabling
|
||||
the log stream, using separate text commands:
|
||||
|
||||
@@ -1088,16 +1117,44 @@ saving. This works around the [released USB sleep bug](old-releases/1.17.1.5.md#
|
||||
nRF52 does not need this ESP32 workaround.
|
||||
|
||||
These commands are compiled into ordinary USB-loggable artifacts and every
|
||||
Full Companion. They control live USB debug and packet output. CommonCLI roles
|
||||
save the setting in `/com_prefs`, so it survives reboot; their first boot
|
||||
defaults to on. Full Companion and ordinary USB Companion start off on a fresh
|
||||
installation so diagnostics cannot corrupt framed traffic.
|
||||
Full Companion. `usb.logging` is the saved USB output master and packet-log
|
||||
gate. `usb.debug` is a separate saved preference for verbose diagnostics;
|
||||
effective USB debug output requires both switches to be on. Packet RAW and
|
||||
RX/TX summaries require only the master switch. `get usb.debug` reports saved
|
||||
intent even when the master is off. Turning `usb.logging` off does not erase
|
||||
that intent; turning it back on restores debug output if `usb.debug` is on.
|
||||
|
||||
CommonCLI roles save these settings in `/com_prefs`; their fresh USB logging
|
||||
default is on. Full Companion and ordinary USB Companion start with the
|
||||
master off on a fresh installation so diagnostics cannot corrupt framed
|
||||
traffic. Verbose USB debug defaults to off for every role, including when
|
||||
loading older preferences without a debug field. Updates retain an existing
|
||||
saved `usb.logging` choice. Older binaries without the new `usb.debug`
|
||||
command retain their previous behavior until upgraded.
|
||||
|
||||
For packet-only capture, use these separate text commands:
|
||||
|
||||
```text
|
||||
set usb.debug off
|
||||
set usb.logging on
|
||||
```
|
||||
|
||||
Use `set usb.debug on` temporarily when troubleshooting, then turn it off
|
||||
again to reduce USB traffic. This setting applies immediately and needs no
|
||||
USB-interface reboot. It does not select a firmware variant or enable code
|
||||
omitted from the image: verbose output still requires compiled `MESH_DEBUG`
|
||||
or other relevant diagnostic support. A packet-only build can retain the
|
||||
preference without gaining missing debug messages.
|
||||
|
||||
Debug off suppresses verbose diagnostic chatter, not functional CLI replies,
|
||||
USB port identity/drop markers, or retained operational warnings. Readers
|
||||
must still filter non-packet lines instead of treating every line as a packet.
|
||||
|
||||
On Full Companion these lines belong to its text terminal, not `meshcli`'s
|
||||
Binary `get/set` parameter namespace. Open interface `00`, send
|
||||
`+++MESHCORE-TERM-START`, and then issue the command. Running
|
||||
`meshcli ... get usb.logging` directly can instead return
|
||||
`Unknown var usb.logging` because that is a different protocol operation.
|
||||
`meshcli ... get usb.logging` or `get usb.debug` directly can instead return
|
||||
`Unknown var ...` because that is a different protocol operation.
|
||||
|
||||
nRF52 Full Companion defaults logging to off and enumerates only USB interface
|
||||
`00`, which carries Companion, terminal, and serial mOTA traffic. Enabling
|
||||
@@ -1107,6 +1164,8 @@ the optional `reboot` argument saves the choice and reports that a reboot is
|
||||
required when the USB interface count must change. The exact
|
||||
`set usb.logging on reboot` and `set usb.logging off reboot` forms save the
|
||||
choice, send their reply, and reboot one second later only when needed.
|
||||
Interface `02` is logging-only, not an input-capable CLI. Send logging/debug
|
||||
commands to interface `00`; USB debug uses the same log endpoint as packets.
|
||||
|
||||
On every ESP32 Full Companion, enter the USB text terminal and use
|
||||
`set usb.logging on` (preceded by `set powersaving off` on 1.17.1.5) to turn that TTY into a logging-repeater-style plaintext
|
||||
@@ -1123,6 +1182,20 @@ frames active on interface `00`; ESP32 resumes the ordinary ASCII/Binary
|
||||
switcher after the logging terminal turns logging off. This setting does not
|
||||
change the node-storage capture controlled by `log start` and `log stop`.
|
||||
|
||||
For a USB-to-MQTT bridge, enable packet logging but leave `usb.debug` off.
|
||||
Full Companion now supplies the ASCII RAW/RX/TX packet stream needed by such
|
||||
consumers; it does not provide durable or lossless capture. A compatible host
|
||||
must also support the role's identity/control commands and replies: packet
|
||||
records alone do not make an existing bridge compatible. Companion now answers
|
||||
`get public.key` with its node public key. ESP32 Full's logging TTY remains
|
||||
input-capable and accepts that query. nRF52 Full's dedicated logging CDC is
|
||||
not a command/reply console (its bounded stats-poll input only renews the
|
||||
watchdog client lease):
|
||||
a host integration must use interface `00` for commands and identity and
|
||||
interface `02` for logs.
|
||||
Existing single-port bridges that require CLI replies cannot simply point at
|
||||
the dedicated log endpoint. This change does not add a two-port bridge driver.
|
||||
|
||||
Companion, Repeater, Room Server, and Sensor builds with both MQTT and USB
|
||||
logging provide the same saved selector for both output paths:
|
||||
|
||||
@@ -1143,6 +1216,8 @@ in `both` mode; Full Companion starts with USB logging off. To change only
|
||||
MQTT, use `set mqtt.enabled on|off`; `get mqtt.enabled` checks the saved
|
||||
switch and `get mqtt.running` checks whether the MQTT service is running.
|
||||
Turning MQTT off preserves all broker slots and credentials.
|
||||
The output selector changes the USB master, not saved `usb.debug` intent;
|
||||
WiFi MQTT logging is independent of the USB debug preference.
|
||||
|
||||
On **1.17.1.5 ESP32**, run `set powersaving off` before selecting
|
||||
`set logging.output usb` or `set logging.output both`, since those modes
|
||||
@@ -1895,7 +1970,7 @@ through binary command `0x42`; this command does not report the Bluetooth PIN.
|
||||
**Note:** On nRF52 boards with power management and a boot-voltage setting,
|
||||
this is a saved *relative* calibration: `1.000` keeps the board conversion,
|
||||
`1.050` raises all reported battery millivolts by 5%, and `0` resets to
|
||||
`1.000`. The allowed range is `0.500`–`1.500`. This affects boot protection,
|
||||
`1.000`. The allowed range is `0.500`-`1.500`. This affects boot protection,
|
||||
running cutoff, telemetry, battery alerts, and percentage. Calibrate against a
|
||||
voltmeter before enabling a low cutoff. Other boards retain their existing
|
||||
board-specific multiplier behavior, or return unsupported.
|
||||
@@ -2167,6 +2242,13 @@ get clock.sync.status
|
||||
#### View this node's public key
|
||||
**Usage:** `get public.key`
|
||||
|
||||
Returns this node's identity public key without changing it or exposing its
|
||||
private key. Companion supports the query through its text terminal and
|
||||
framed CLI command `0x42` (`CMD_RUN_CLI_COMMAND`); its reply is `> ` followed
|
||||
by exactly 64 uppercase hexadecimal characters. Private-key export support
|
||||
is not required. On nRF52 Full Companion, send the query to control interface
|
||||
`00`, not the output-only logging interface `02`.
|
||||
|
||||
---
|
||||
|
||||
#### View this node's firmware version
|
||||
@@ -4909,12 +4991,12 @@ get adc.multiplier
|
||||
set adc.multiplier 1.050
|
||||
```
|
||||
|
||||
The custom empty/full endpoints may be 2000–4200 mV and must be at least 100 mV
|
||||
The custom empty/full endpoints may be 2000-4200 mV and must be at least 100 mV
|
||||
apart. Setting either endpoint automatically selects `custom`; boot lock and
|
||||
cutoff remain separately adjustable. `get pwrmgt.bootlock` and
|
||||
`get pwrmgt.cutoff` show the values in force after selecting a profile.
|
||||
|
||||
For a RAK3401/RAK13302 LiFePO₄ cell:
|
||||
For a RAK3401/RAK13302 LiFePO4 cell:
|
||||
|
||||
```text
|
||||
set battery.profile lifepo4
|
||||
|
||||
@@ -173,6 +173,36 @@ base where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x
|
||||
platform but follow the same one-TTY policy. No ESP32 Full build enumerates a
|
||||
second CDC interface.
|
||||
|
||||
`usb.logging` is the saved master for USB packet output. `usb.debug` separately
|
||||
saves verbose diagnostic intent and defaults off, including when older
|
||||
preferences do not contain the new field. RAW/RX/TX packet records need only
|
||||
the master; diagnostics need both switches and compiled debug support. Turning
|
||||
the master off preserves debug intent. `get usb.debug` reports that saved
|
||||
choice, not whether USB currently owns a plaintext logging stream.
|
||||
|
||||
Full Companion now emits complete received frames as uppercase ASCII `RAW:`
|
||||
hex, separately from decoded RX summaries and TX summaries. Leave debug off
|
||||
for USB-to-MQTT capture. These are bounded best-effort records; drops and host
|
||||
disconnects can separate a RAW/summary pair. The dedicated nRF52 log CDC cannot
|
||||
answer CLI/identity queries: programs expecting one bidirectional CLI/log port
|
||||
need separate control-port support, not just a change to the serial pathname.
|
||||
Companion supports `get public.key` in the primary terminal or framed CLI;
|
||||
the reply is `> ` followed by 64 uppercase hex characters. This query does not
|
||||
make the dedicated log CDC input-capable or establish full bridge compatibility.
|
||||
Send `get/set usb.debug` to the primary ASCII terminal; changing verbosity
|
||||
needs no USB-interface reboot and does not relax Binary/mOTA ownership rules.
|
||||
|
||||
Current source adds `get usb.watchdog` and saved `set usb.watchdog off|on|auto`, defaulting to
|
||||
Auto until 14 continuous healthy logging-client days qualify it for On.
|
||||
Existing USB stats polls renew a 15-minute client lease; a cable or DTR alone
|
||||
does not count. A lost confirmed client can trigger USB-only recovery after
|
||||
lease expiry plus five minutes. MCU resets additionally require On and a
|
||||
full physical-fault interval, a verified tier save, and clear protocol/update
|
||||
ownership. Active Binary USB and mOTA sessions veto recovery. On dual CDC,
|
||||
only logging CDC1 accepts the bounded stats markers; primary CDC0 stats do not
|
||||
renew that lease. CDC1 still provides no CLI/statistics replies.
|
||||
See [USB logging watchdog](usb_logging_watchdog.md) for status and limitations.
|
||||
|
||||
With logging enabled on a shared port, the stop token is rejected with
|
||||
`ERROR: set usb.logging off before Binary mode`. Turn logging off first; a
|
||||
successful binary-mode acknowledgement must not immediately revert to logging.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Management report decoder
|
||||
|
||||
Paste MGR1 management-report payloads or complete GroupData packets from a
|
||||
Paste MGR1, MGR2, or MGR3 management-report payloads or complete GroupData packets from a
|
||||
packet analyzer to read a radio's public management information. Everything,
|
||||
including password authentication and ACL decryption, happens locally in this
|
||||
browser. The report, password, and candidate public key are never uploaded.
|
||||
@@ -13,13 +13,13 @@ by someone who does not know that password.
|
||||
## Decode a management report
|
||||
|
||||
<div class="management-tool" data-management-decoder>
|
||||
<label for="management-packet-input">MGR1 payload or complete GroupData packet hex</label>
|
||||
<label for="management-packet-input">MGR1/MGR2/MGR3 payload or complete GroupData packet hex</label>
|
||||
<textarea
|
||||
id="management-packet-input"
|
||||
data-role="input"
|
||||
spellcheck="false"
|
||||
autocomplete="off"
|
||||
placeholder="Paste analyzer Raw Data, canonical MGR1 payload hex, or one MQTT raw value per line"
|
||||
placeholder="Paste analyzer Raw Data, canonical MGR1/MGR2/MGR3 payload hex, or one MQTT raw value per line"
|
||||
aria-describedby="management-packet-help"
|
||||
></textarea>
|
||||
<p class="management-help" id="management-packet-help">
|
||||
@@ -31,7 +31,7 @@ by someone who does not know that password.
|
||||
<label for="management-password-input">Management password <span>(optional for public fields; required for ACLs)</span></label>
|
||||
<input id="management-password-input" data-role="password" type="password" autocomplete="new-password">
|
||||
<p class="management-help">
|
||||
The password remains in this page only. The decoder derives the MGR1 AES-SIV key in
|
||||
The password remains in this page only. The decoder derives the management AES-SIV key in
|
||||
your browser and does not send it anywhere.
|
||||
</p>
|
||||
|
||||
@@ -67,9 +67,10 @@ by someone who does not know that password.
|
||||
## What the decoder accepts
|
||||
|
||||
- Complete `PAYLOAD_TYPE_GRP_DATA` (`0x06`) analyzer/MQTT packet hex. It checks
|
||||
the MeshCore route header, encoded path length, MGR1 page bounds, and required
|
||||
the MeshCore route header, encoded path length, version-specific page bounds, and required
|
||||
zero padding.
|
||||
- A canonical MGR1 payload beginning with `4D475231` (`MGR1`).
|
||||
- A canonical payload beginning with `4D475231` (`MGR1`), `4D475232` (`MGR2`),
|
||||
or `4D475233` (`MGR3`).
|
||||
- One raw packet or canonical payload per line; duplicate observations of an
|
||||
identical page are deduplicated.
|
||||
|
||||
@@ -78,5 +79,32 @@ the report-specific fingerprints and the administrator and/or OTA-signer flags.
|
||||
It cannot turn a fingerprint back into a full key. Use the optional candidate
|
||||
field to test a specific full public key.
|
||||
|
||||
MGR2 and MGR3 also show USB logging, host/reader connection, logger-client activity, stalled/recovering/deferred
|
||||
state, recovery stage, saved backoff, retry interval/inactive seconds, Auto qualification
|
||||
seconds, and persistence
|
||||
readiness. Unsupported observation is shown explicitly; legacy MGR1 has no
|
||||
USB block and shows it as unavailable. These values are the report-start
|
||||
snapshot, not proof that a Pi or host application is healthy. Older decoder
|
||||
copies require an update for MGR3.
|
||||
|
||||
MGR3 additionally shows the latest USB watchdog action, reason mask and names,
|
||||
advisory node-clock timestamp, recorded-boot uptime seconds, event sequence,
|
||||
and whether the record was durably saved. Software recovery and re-enumeration
|
||||
mean attempted actions, not successful repairs. A reboot request is not proof
|
||||
that a reboot completed; a later cancellation can replace it. The node clock
|
||||
can be wrong, even when it resembles a valid date. Event uptime and sequence
|
||||
remain useful for ordering. MGR1/MGR2 do not carry this event field and show it
|
||||
as unavailable. All 36 ACL entries still fit, using up to nine MGR3 pages.
|
||||
|
||||
Reports contain a frozen latest-event snapshot, not immediate watchdog alerts
|
||||
or a complete event history. See [USB logging watchdog](usb_logging_watchdog.md)
|
||||
for local review and persistence limitations.
|
||||
|
||||
Host/reader connection only describes the USB link or open reader. Logger-client
|
||||
activity means recent USB stats polling within a 15-minute lease, renewed by
|
||||
the existing five-minute polls without a new registration or heartbeat command.
|
||||
The flag also requires logging enabled and a connected, unstalled USB link.
|
||||
It does not identify the client or prove MQTT delivery, disk writes, or Pi health.
|
||||
|
||||
For the report schedule, public-field layout, cryptographic design, and the
|
||||
offline Python capture tool, see [Management reports](management_reports.md).
|
||||
+100
-18
@@ -1,4 +1,4 @@
|
||||
# Management reports (MGR1)
|
||||
# Management reports (MGR1/MGR2/MGR3)
|
||||
|
||||
Available on repeater (including observer), room-server and sensor firmware.
|
||||
Companions/terminal-chat nodes and KISS modems do not originate these reports.
|
||||
@@ -6,6 +6,11 @@ Off by default. A management password and explicit enable are both required.
|
||||
No radio settings, existing preferences layout, or OTA authorization policy is
|
||||
changed by enabling reporting. This protocol does **not** authorize updates.
|
||||
|
||||
Current firmware emits `MGR3`, including a public USB logging/recovery snapshot
|
||||
and its latest watchdog event. Updated decoders still accept legacy `MGR1` and
|
||||
`MGR2`; older decoder copies need an update to read MGR3. Reporting USB status
|
||||
does not enable logging or change retry policy.
|
||||
|
||||
## CLI
|
||||
|
||||
Run through the existing local CLI or an authenticated administrator session:
|
||||
@@ -48,14 +53,16 @@ identifies the reporter.
|
||||
|
||||
Direct and flood schedules are independently configurable and may each be
|
||||
turned off. Fresh settings are `direct=5d` and `flood=21d`; global reporting is
|
||||
still off until `mgmt.enabled on`. Direct accepts 5–90 days and requires the
|
||||
shared path. Flood accepts 21–90 days and requires a resolvable shared region.
|
||||
still off until `mgmt.enabled on`. Direct accepts 5-90 days and requires the
|
||||
shared path. Flood accepts 21-90 days and requires a resolvable shared region.
|
||||
At least one route must remain active while reporting is enabled. The legacy
|
||||
`set mgmt.interval N` shorthand enables both, setting direct to `N` and flood to
|
||||
`max(21,N)`. No transmission is sent merely by configuring a password. Initial
|
||||
reporting waits for the configured schedules. Reports have deterministic
|
||||
per-radio/per-sequence jitter of up to an hour; pages are spaced at least a
|
||||
minute apart.
|
||||
minute apart. Watchdog events appear in the next scheduled snapshot, not as
|
||||
immediate radio alerts. Multiple events between snapshots can replace the
|
||||
latest-event record; this is not a complete off-node event history.
|
||||
|
||||
The radio cannot know that an observer uploaded a packet to MQTT, so the flood
|
||||
schedule is deliberately independent of direct transmission. A region-scoped
|
||||
@@ -90,8 +97,8 @@ is bounded to 1.5 KiB, plus a small configuration object and temporary stack use
|
||||
## Routing and MQTT
|
||||
|
||||
Both direct/path and flood reports use **`PAYLOAD_TYPE_GRP_DATA` (`0x06`)**.
|
||||
The route bits independently select direct or flood. `MGR1` is an application
|
||||
extension with **literally plaintext public fields**, not a call to the ordinary
|
||||
The route bits independently select direct or flood. `MGR1`/`MGR2`/`MGR3` are application
|
||||
extensions with **literally plaintext public fields**, not a call to the ordinary
|
||||
encrypted `createGroupDatagram()` builder. A fixed public marker is not an owner
|
||||
or password-derived channel ID. There is no outer channel encryption.
|
||||
|
||||
@@ -108,7 +115,7 @@ not flood-route it.
|
||||
|
||||
The observer's existing MQTT `PACKET` JSON supplies the complete frame in `raw`.
|
||||
No broker configuration or password changes are necessary to capture a report.
|
||||
The decoder understands all four route forms, 1–3-byte hashes, scope transport
|
||||
The decoder understands all four route forms, 1-3-byte hashes, scope transport
|
||||
codes, and duplicate copies heard by several uplinks:
|
||||
|
||||
```
|
||||
@@ -126,11 +133,11 @@ For a browser-local decoder that also decrypts and authenticates ACL entries,
|
||||
use the [Management report decoder](management_decoder.md). It does not upload
|
||||
the captured packet or password.
|
||||
|
||||
## Canonical payload (little endian)
|
||||
## Canonical MGR3 payload (little endian)
|
||||
|
||||
| Offset | Bytes | Field |
|
||||
|---:|---:|---|
|
||||
| 0 | 4 | `MGR1` |
|
||||
| 0 | 4 | `MGR3` |
|
||||
| 4 | 16 | First 16 bytes of reporter public key |
|
||||
| 20 | 4 | Persisted report sequence (never wraps; exhaustion stops TX) |
|
||||
| 24 | 4 | RTC Unix timestamp; advisory, may be wrong |
|
||||
@@ -142,7 +149,7 @@ the captured packet or password.
|
||||
| 52 | 4 | Staging capacity; planning still checks actual package geometry |
|
||||
| 56 | 4 | OTA capability bits |
|
||||
| 60 | 2 | Uptime hours, saturated at 65535 |
|
||||
| 62 | 4 | Weekly minimum mV, minimum °C, maximum °C |
|
||||
| 62 | 4 | Weekly minimum mV, minimum C, maximum C |
|
||||
| 66 | 4 | Since-report extrema in the same format |
|
||||
| 70 | 1 | History coverage hours, capped at 168 |
|
||||
| 71 | 1 | Interval days for this report's direct or flood schedule |
|
||||
@@ -152,13 +159,86 @@ the captured packet or password.
|
||||
| 75 | 1 | Mask of status bits whose state is known |
|
||||
| 76 | 2 | Validity/partial-history flags |
|
||||
| 78 | 1 | Zero-based page index |
|
||||
| 79 | 1 | Total pages (1–6) |
|
||||
| 80 | 1 | Unique ACL count (0–36) |
|
||||
| 79 | 1 | Total pages (1-9) |
|
||||
| 80 | 1 | Unique ACL count (0-36) |
|
||||
| 81 | 1 | First ACL index in this page |
|
||||
| 82 | 1 | ACL entries on this page (0–6) |
|
||||
| 83 | 13 × count | AES-SIV encrypted ACL entries |
|
||||
| 82 | 1 | ACL entries on this page (0-4) |
|
||||
| 83 | 2 | USB status flags |
|
||||
| 85 | 1 | Packed USB recovery stage and retry backoff step |
|
||||
| 86 | 4 | USB full-reboot retry interval seconds |
|
||||
| 90 | 4 | USB inactive seconds |
|
||||
| 94 | 4 | USB continuous Auto qualification seconds |
|
||||
| 98 | 1 | Latest watchdog reason/action/durability code |
|
||||
| 99 | 4 | Latest watchdog event RTC Unix epoch; advisory, zero if unavailable |
|
||||
| 103 | 4 | Uptime seconds at that event's boot |
|
||||
| 107 | 4 | Latest watchdog event sequence, saturated at 4294967295 |
|
||||
| 111 | 13 * count | AES-SIV encrypted ACL entries |
|
||||
| after ACL | 16 | Full AES-SIV authentication tag |
|
||||
| after tag | 0–15 | Zero padding to group-compatible length; not part of canonical payload |
|
||||
| after tag | 0-15 | Zero padding to group-compatible length; not part of canonical payload |
|
||||
|
||||
MGR3 retains all 36 ACL entries, using four per page and up to nine pages. The
|
||||
largest canonical page is 179 bytes and already group-compatible;
|
||||
the radio payload budget is unchanged. The USB snapshot is frozen with the
|
||||
other public fields at report start and repeated on each page. It is not a
|
||||
live host-health monitor.
|
||||
|
||||
USB flag bits 0-10 are, in order: supported, logging enabled, watchdog enabled,
|
||||
host connected, reader connected, stalled, recovering, recovery deferred,
|
||||
persistence ready, watchdog Auto, and logger active. Bits 11-15 must be zero.
|
||||
Byte 85 bits 0-1 hold stage: 0 idle, 1 soft-recovery wait, 2 re-enumeration
|
||||
wait, and 3 reboot pending. Bits 2-5 hold the saved backoff step; bits 6-7
|
||||
must be zero. Backoff is not a count of successful recoveries. The three
|
||||
timers are unsigned seconds; local recovery/reboot counters are not sent.
|
||||
The retry field is the saved backoff interval, not a countdown to an action;
|
||||
inactive age is reported separately. USB-only cleanup can precede that interval.
|
||||
Unsupported USB observation/recovery is explicitly represented by a false
|
||||
supported bit, not omitted or mistaken for a connected healthy reader.
|
||||
USB status describes the radio's observed transport and policy, not proof
|
||||
that the host process, MQTT uplink, SSH service, or Pi is healthy.
|
||||
Host/reader connection alone does not mean a logging client is running.
|
||||
The logger-active bit means recent USB stats polling within a 15-minute lease
|
||||
while logging is enabled and the observed USB host/reader link is not stalled,
|
||||
separate from USB attachment or an open reader. The existing five-minute stats
|
||||
polls renew this lease; no new client-registration or heartbeat command is
|
||||
required. This does not identify the client, prove logs reached MQTT or disk,
|
||||
or show that the Pi remains otherwise healthy.
|
||||
|
||||
Missing watchdog state on new or upgraded installations defaults to Auto.
|
||||
Auto promotes to saved On after 14 continuous healthy logging-USB days with
|
||||
renewed stats polling; its qualification age resets on reboot, detach, stall,
|
||||
stats-lease expiry, or USB logging off.
|
||||
Explicit On and Off remain available. Nonlogging/no-reader nodes remain
|
||||
Auto without watchdog board reboots. The Auto flag and age report this
|
||||
qualification separately from an enabled On policy.
|
||||
Use the node's `get usb.watchdog` and `set usb.watchdog off|on|auto` CLI to
|
||||
inspect or change policy; receiving a management snapshot changes nothing.
|
||||
|
||||
The 13-byte latest-event block is all zero when no event is available. Otherwise
|
||||
byte 98 bits 0-3 are the reason mask: host absent, reader absent, TX stalled,
|
||||
and confirmed stats client inactive. Bits 4-6 hold the action: 1 software
|
||||
recovery attempted, 2 re-enumeration attempted, 3 reboot requested, or 4 reboot
|
||||
cancelled after a final health/ownership check. Bit 7 means the event was saved
|
||||
and verified on durable storage. Sequence is nonzero for a present event.
|
||||
Physical faults may combine reason bits; stats-only expiry cannot authorize a
|
||||
board reboot. Epoch zero is allowed when the clock source is unavailable.
|
||||
|
||||
Event time is the node's advisory clock, not verified UTC. Default clocks can
|
||||
start at a plausible fixed date. Clock corrections do not rewrite old events;
|
||||
recorded uptime and sequence help review them independently. A saved reboot
|
||||
request is intent, not proof of a completed reset. The latest event survives
|
||||
normal reboot and mode changes, but is not a log of hardware hangs or sudden
|
||||
power failures. See [USB logging watchdog](usb_logging_watchdog.md) for storage
|
||||
failure, cancellation, and review limitations.
|
||||
|
||||
Legacy MGR2 retains the same offsets through byte 97, followed by encrypted ACL
|
||||
entries at byte 98 and the authentication tag. It carries five entries per page
|
||||
and up to eight pages. Its USB status is available, but watchdog event history
|
||||
is unavailable rather than an empty modern record.
|
||||
|
||||
Legacy MGR1 retains the same offsets through byte 82, followed immediately
|
||||
by encrypted ACL entries at byte 83 and the authentication tag. It carries
|
||||
six entries per page and up to six pages, with no USB block. Its absent USB
|
||||
status is decoded as unavailable, not as all switches off.
|
||||
|
||||
Each private entry is a per-radio 12-byte keyed fingerprint followed by flags:
|
||||
bit 0 administrator, bit 1 trusted OTA signer. Duplicate entries combine flags.
|
||||
@@ -175,9 +255,9 @@ means compiled support; active means an established usable apply/store path.
|
||||
Validity bits: 0 firmware version, 1 bootloader version, 2 EndF/base identity,
|
||||
3 staging capacity, 4 partial week, 5 partial since-report period, 6 MCU temperature.
|
||||
Voltage is unsigned millivolts, zero missing. Temperatures: zero missing,
|
||||
1–251 represent −50…200 °C, 252 below range, 253 above range, 254–255 reserved.
|
||||
1-251 represent -50..200 C, 252 below range, 253 above range, 254-255 reserved.
|
||||
OTA bits: 0 protocol compiled, 1 transfer DEFLATE, 2 2-KiB app transfer blocks;
|
||||
bits 8–23 are apply codec bits (full/sequential/in-place). Transfer DEFLATE is
|
||||
bits 8-23 are apply codec bits (full/sequential/in-place). Transfer DEFLATE is
|
||||
not compressed bootloader apply. There is **no manifest ID**. Exact old binaries
|
||||
are still needed on the computer to generate a differential update; a hash alone
|
||||
cannot reconstruct them. Unknown metadata must not be treated as OTA readiness.
|
||||
@@ -193,7 +273,9 @@ needs a candidate administrator's full key to identify a fingerprint.
|
||||
|
||||
Encryption is [RFC 5297 AES-SIV-CMAC-256](https://www.rfc-editor.org/rfc/rfc5297),
|
||||
using the existing rweather AES primitive. The single associated-data string is
|
||||
the complete 83-byte clear header. Ciphertext is exactly the ACL byte length.
|
||||
the complete clear header: 111 bytes for MGR3, including USB status and its event,
|
||||
98 bytes for MGR2, or 83 bytes for MGR1. All retain the existing derivation domains; the authenticated
|
||||
magic and layout distinguish their wire versions. Ciphertext is exactly the ACL byte length.
|
||||
Full 16-byte tag, no truncation. This deterministic misuse-resistant mode avoids
|
||||
reliance on the firmware's noncryptographic general-purpose RNG or RTC nonces.
|
||||
An identical restored snapshot may repeat ciphertext, but does not expose XORs
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Feature switches by role — 1.17.1.5 USA Cascade
|
||||
# Feature switches by role - 1.17.1.5 USA Cascade
|
||||
|
||||
Use these settings with the exact board's canonical release image. Former
|
||||
logging, power-saving, FEM-gain, and rotated-display variants are now runtime
|
||||
@@ -71,6 +71,16 @@ change them. A command requires its feature to be compiled into the build.
|
||||
`set usb.logging on|off` changes only USB logging. On MQTT-capable builds,
|
||||
`set mqtt.enabled on|off` changes only MQTT and keeps broker settings;
|
||||
`set logging.output off|usb|wifi|both` selects both outputs together.
|
||||
`set usb.debug on|off` separately saves verbose USB diagnostics. Debug output
|
||||
requires both USB switches on; RAW/RX/TX packet records need only
|
||||
`usb.logging`. Leave `usb.debug off` for USB-to-MQTT packet capture.
|
||||
|
||||
Current source also includes a saved [USB logging watchdog](usb_logging_watchdog.md):
|
||||
`get usb.watchdog` and `set usb.watchdog off|on|auto`. Missing state defaults to
|
||||
Auto, qualifying from 14 continuous healthy USB stats-polling days, not a cable
|
||||
or open TTY alone. Confirmed client loss can trigger USB-only repair; MCU resets
|
||||
require On and an entire physical-fault tier, growing from one hour to one week.
|
||||
This repairs the node's USB connection, not the host Pi or MQTT service.
|
||||
|
||||
## Full Companion commands
|
||||
|
||||
@@ -83,6 +93,8 @@ change them. A command requires its feature to be compiled into the build.
|
||||
| External FEM TX gain | `set radio.fem.txgain on` | `set radio.fem.txgain off` | `get radio.fem.txgain` |
|
||||
| ESP32 USB logging | `set powersaving off`, then `set usb.logging on` | `set usb.logging off` | `get powersaving`, `get usb.logging` |
|
||||
| nRF52 second USB logging port | `set usb.logging on reboot` | `set usb.logging off reboot` | `get usb.logging` |
|
||||
| Verbose USB diagnostics | `set usb.debug on` while USB logging is on | `set usb.debug off` | `get usb.debug` reports saved intent |
|
||||
| USB logging watchdog (current source) | `set usb.watchdog auto` or `on` | `set usb.watchdog off` | `get usb.watchdog`; native USB and durable storage required |
|
||||
| MQTT master | `set mqtt.enabled on` | `set mqtt.enabled off` | `get mqtt.enabled`, `get mqtt.running`, `get mqtt.status` |
|
||||
| ESP32 persistent WebConfig | `set webui on` | `set webui off` | `get webui` |
|
||||
| ESP32 WebConfig browser console | `set wifi.cli on` | `set wifi.cli off` | `get wifi.cli` |
|
||||
@@ -94,11 +106,19 @@ Saved settings apply immediately unless noted. Rotation and gain controls
|
||||
report unsupported hardware instead of creating that feature. Fresh Full
|
||||
Companion preferences enable device power saving and leave USB logging off;
|
||||
existing saved preferences win after an update.
|
||||
USB debug defaults off, including on upgrade from preferences without that
|
||||
field. Its saved intent survives switching the USB master off. Verbose messages
|
||||
still require compiled debug support; changing this preference adds no missing
|
||||
code and does not require a reboot.
|
||||
|
||||
**ESP32:** logging and binary Companion traffic share one USB port. Turn logging
|
||||
off before handing USB to an app/MOTA host. **nRF52:** the optional second CDC
|
||||
port is for logs; use the primary port for Companion/MOTA. Adding/removing the
|
||||
second port requires a reboot; the optional suffix shown above requests it.
|
||||
Full Companion includes complete ASCII RAW packet records and decoded RX/TX
|
||||
summaries, independent of verbose debug. The nRF52 log port is output-only;
|
||||
CLI/identity queries belong to interface `00`. A USB-to-MQTT program that expects
|
||||
both logs and CLI replies on one port cannot use interface `02` alone.
|
||||
|
||||
### MQTT controls shared by Companion and infrastructure
|
||||
|
||||
@@ -167,6 +187,7 @@ from some portable builds. The USB browser console still works without it.
|
||||
| Setting | Enable | Disable | Read back |
|
||||
| --- | --- | --- | --- |
|
||||
| Live USB logging | ESP32 1.17.1.5: `set powersaving off`, then `set usb.logging on`; other platforms: `set usb.logging on` | `set usb.logging off` | `get powersaving`, `get usb.logging` |
|
||||
| Verbose USB diagnostics | `set usb.debug on` while USB logging is on | `set usb.debug off` | `get usb.debug` reports saved intent |
|
||||
| Capture RX log to node storage | `log start` | `log stop` | `log` prints the capture locally |
|
||||
| RS232 / ESP-NOW bridge master | `set bridge.enabled on` | `set bridge.enabled off` | `get bridge.enabled`, `get bridge.running`, `get bridge.type` |
|
||||
| MQTT periodic status publication | `set mqtt.status on` | `set mqtt.status off` | `get mqtt.status` shows connection status |
|
||||
@@ -189,6 +210,13 @@ nRF52 Full Companion. `log start/stop` records to storage independently of live
|
||||
USB logging. Use
|
||||
`log erase` to delete that capture.
|
||||
|
||||
For quiet packet capture in current firmware, use `set usb.debug off` and
|
||||
`set usb.logging on`. Verbose diagnostics default off for fresh and upgraded
|
||||
preferences without the new field. The debug choice is saved separately;
|
||||
turning logging off, or selecting `logging.output wifi`, does not erase it.
|
||||
Debug output is effective only when USB logging is on and the image includes
|
||||
the relevant debug code. RAW/RX/TX records remain enabled without debug.
|
||||
|
||||
For **ESP32 1.17.1.5 USB logging**, run these as separate commands in the
|
||||
role's text terminal (or remote admin CLI on infrastructure):
|
||||
|
||||
@@ -232,6 +260,8 @@ settings override these defaults. To toggle only MQTT while keeping
|
||||
USB logging unchanged, use `set mqtt.enabled off` / `on`. Neither setting
|
||||
turns LoRa repeating off. Repeater forwarding uses `set repeat off` / `on`
|
||||
and `get repeat` separately.
|
||||
The selector changes USB master output, not saved `usb.debug` intent. Direct
|
||||
WiFi MQTT is independent of that USB verbosity preference.
|
||||
|
||||
The `set powersaving off` step above is the **1.17.1.5 ESP32 USB workaround**.
|
||||
**WiFi/MQTT-only logging does not need it while the Repeater/Room Server MQTT
|
||||
|
||||
@@ -55,6 +55,7 @@ the corresponding feature:
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `stats-core`, `stats-radio`, `stats-radio-diag`, `stats-packets` | Runtime diagnostics |
|
||||
| `get public.key` | Read-only node identity public key; Companion returns `> ` followed by 64 uppercase hex characters |
|
||||
| `get prv.key` | Node identity private key; Companion requires private key export enabled in the build |
|
||||
| `get password` | Infrastructure admin password; Companion reports that it has no admin password |
|
||||
| `erase` | Erase stored identity and settings; reboot for a fresh node |
|
||||
@@ -264,10 +265,28 @@ GPS idle behavior; it does not change LoRa RXPS or WiFi modem sleep.
|
||||
```
|
||||
get usb.logging
|
||||
set usb.logging {on|off} [reboot]
|
||||
get usb.debug
|
||||
set usb.debug {on|off}
|
||||
```
|
||||
Shows or changes persistent live USB debug and packet output in an ordinary
|
||||
USB-loggable Companion or Full Companion. USB Companion and Full start off on
|
||||
a fresh install with logging disabled to protect framed traffic.
|
||||
Shows or changes persistent USB packet output and a separate verbose-debug
|
||||
preference in an ordinary USB-loggable Companion or Full Companion.
|
||||
`usb.logging` is the master; debug output requires the master and `usb.debug`
|
||||
to be on. RAW and RX/TX packet records need only the master. Use
|
||||
`set usb.debug off` with packet logging for USB-to-MQTT capture.
|
||||
`get usb.debug` reports saved intent, even while the master is off. Disabling
|
||||
the master does not clear it. Debug defaults off for fresh installs and older
|
||||
preferences without the new field; it still needs compiled debug support.
|
||||
Changing debug verbosity takes effect without a reboot.
|
||||
|
||||
Current source also accepts `get usb.watchdog` and saved
|
||||
`set usb.watchdog off|on|auto`. Auto is the default and requires 14 continuous
|
||||
healthy logging-client days before saving On. Exact USB stats polls, not merely
|
||||
USB attachment, renew the client lease. See
|
||||
[USB logging watchdog](usb_logging_watchdog.md) for USB-only repair, increasing
|
||||
physical-fault reboot intervals, status fields, and ownership/storage safeguards.
|
||||
|
||||
USB Companion and Full start off on a fresh install with the logging master
|
||||
disabled to protect framed traffic.
|
||||
nRF52 Full changes its interface count after a reboot and keeps Companion on
|
||||
interface `00`. Every ESP32 Full Companion has one TTY and needs no reboot:
|
||||
logging uses the active text terminal, disables framed Binary Companion on
|
||||
@@ -275,6 +294,12 @@ USB, and continues accepting `set usb.logging off`. Turning logging off leaves
|
||||
the port in the normal ASCII terminal, matching fresh firmware. Send
|
||||
`+++MESHCORE-TERM-STOP`, or let a Companion app send a valid framed probe, to
|
||||
switch it to Binary Companion afterward.
|
||||
Full Companion emits complete received frames as uppercase ASCII `RAW:` hex
|
||||
followed by decoded RX summaries where possible; TX summaries are separate.
|
||||
These are best-effort records, not atomic pairs or a durable capture.
|
||||
nRF52 interface `02` is logging-only: send CLI/control commands on interface
|
||||
`00`. A single-port bridge that queries identity on its logging port needs
|
||||
separate control-port support before it can use that dedicated log endpoint.
|
||||
|
||||
```
|
||||
reboot
|
||||
|
||||
@@ -1,7 +1,16 @@
|
||||
# Full USB logging repair — 1.17.1.6
|
||||
# Full USB logging repair - 1.17.1.6
|
||||
|
||||
Audit date: 2026-09-13. Release firmware source: `306feebe6d648a247f925894f876be9d747fc8d2`.
|
||||
|
||||
This is historical qualification of the 1.17.1.6 images, not an all-board
|
||||
runtime test of later firmware. Current source separates the saved USB output
|
||||
master (`usb.logging`) from opt-in diagnostic verbosity (`usb.debug`, default
|
||||
off), and adds full ASCII RAW records to Full Companion. See
|
||||
[current USB logging controls](../cli_commands.md#control-live-usb-logging)
|
||||
for defaults, legacy preference handling, capture-loss behavior and dedicated
|
||||
CDC/control-port restrictions. These source changes do not imply new hardware
|
||||
validation of the published images listed below.
|
||||
|
||||
The original Station G2 Full Repeater and Full Room Server images omitted USB
|
||||
packet logging. Both inherited `-UMESH_PACKET_LOGGING` from their ordinary MQTT
|
||||
observer recipes. Full added `-DMESH_PACKET_LOGGING=1`, but PlatformIO's
|
||||
|
||||
@@ -0,0 +1,198 @@
|
||||
# USB logging watchdog
|
||||
|
||||
Current source includes a saved USB logging watchdog in Companion, Repeater,
|
||||
Room Server, and Sensor. It repairs the radio's USB connection; it cannot
|
||||
restart a Pi, restore SSH, or prove MQTT or disk delivery. Supported backends
|
||||
are ESP32 native TinyUSB/HWCDC and nRF52 TinyUSB. An external USB-to-UART
|
||||
adapter is not an observable native-USB backend.
|
||||
Unsupported targets compile out recovery timers and statefile transactions;
|
||||
their watchdog commands report unsupported rather than saving an unusable mode.
|
||||
Management still reports the logging master with USB support false.
|
||||
|
||||
## Commands and defaults
|
||||
|
||||
```text
|
||||
get usb.watchdog
|
||||
get usb.watchdog.last
|
||||
set usb.watchdog auto
|
||||
set usb.watchdog on
|
||||
set usb.watchdog off
|
||||
```
|
||||
|
||||
Setters accept exactly one lowercase mode, save it before applying, and do not
|
||||
reboot immediately. They do not enable `usb.logging` or `usb.debug`.
|
||||
|
||||
| Mode | Behavior |
|
||||
| --- | --- |
|
||||
| `auto` | Default for missing watchdog state, including upgrades. Requires 14 continuous healthy logging-client days before saving `on`, with the retry tier reset to one hour. A previously confirmed client can receive USB-only recovery before promotion, but Auto never reboots the MCU. |
|
||||
| `on` | Explicitly arms physical USB recovery and eventual MCU reboot. A confirmed stats client also gets USB-only recovery if its stats polls stop; missing polls alone cannot authorize MCU reboot. |
|
||||
| `off` | No watchdog probes, automatic USB recovery, qualification, or MCU reset. Packet logging remains independent. |
|
||||
|
||||
Existing valid saved On/Off choices win. Auto qualification is RAM-only and
|
||||
restarts on reboot, USB disconnect, observed stall, expired client lease,
|
||||
logging master Off, or an explicit mode change. A node that has never confirmed
|
||||
a logging client does not cycle USB in Auto merely because no cable is attached.
|
||||
|
||||
## Confirming a logging client
|
||||
|
||||
The existing `meshcoretomqtt` five-minute `stats-core`, `stats-radio`, and
|
||||
`stats-packets` polls renew a 15-minute lease. Only complete, exact stats
|
||||
commands received on the actual USB logging endpoint count; BLE, network,
|
||||
LoRa, management reports, and ordinary framed Companion traffic do not.
|
||||
No new heartbeat command is required. A cable, open TTY, DTR, or kernel USB
|
||||
ACK alone cannot qualify Auto.
|
||||
|
||||
`logger=1` requires the USB logging master, an observed host and reader, a fresh
|
||||
stats lease, and no physical TX stall. Any program polling those commands can
|
||||
qualify: this is not application identification or proof that packets were
|
||||
parsed, published to MQTT, or written to disk. A one-time manual stats query
|
||||
can also establish the lease; use watchdog Off when later USB-only reconnection
|
||||
would be unwanted.
|
||||
|
||||
On nRF52 Full Companion, only the dedicated logging CDC (`*-if02`) establishes
|
||||
the lease. That endpoint accepts bounded stats-poll markers without replying
|
||||
with statistics or exposing arbitrary CLI/configuration commands. Queries and
|
||||
configuration still use primary CDC (`*-if00`), whose stats queries do not
|
||||
prove a logging reader. Existing single-port bridges needing identity/CLI
|
||||
replies still require separate control-port support.
|
||||
|
||||
## Recovery timing and safety
|
||||
|
||||
For a physical host/reader outage, or pending TX with no real completion,
|
||||
software USB recovery is requested after five minutes. Re-enumeration follows
|
||||
after another 60 seconds if health is not restored. These are one staged
|
||||
attempt per outage, not a repeated five-minute reboot loop. Busy backends retry
|
||||
at most once every five seconds without consuming an attempted stage.
|
||||
|
||||
After a confirmed client's stats lease expires, USB-only repair is due five
|
||||
minutes later: normally 20 minutes after its last stats poll. This applies in
|
||||
Auto and, once a client is confirmed during that boot, On. On with no stats
|
||||
client observed remains compatible with non-stats log readers. A gap in stats
|
||||
polls does not by itself reboot a healthy USB transport.
|
||||
|
||||
MCU reboot requires On, a physical USB fault lasting the entire saved tier,
|
||||
and the USB recovery grace periods. Tiers grow after reset authorization:
|
||||
1, 2, 4, 8, 16, 32, 64, 128, then 168 hours (one week). An older app-only
|
||||
stats outage cannot shorten a later physical fault's interval. Ten minutes
|
||||
of healthy monitored operation resets a raised tier to one hour.
|
||||
|
||||
Native TX-completion events are the progress evidence. Queueing, purging,
|
||||
reinitializing, or accepting the optional bounded minute probe is not proof
|
||||
of recovery. The watchdog never waits for a host. USB connection reports,
|
||||
especially HWCDC's host/reader flags, are SDK approximations and do not reliably
|
||||
identify an open TTY process.
|
||||
|
||||
Recovery waits for active Binary USB clients, mOTA/update owners, unsaved
|
||||
contacts, radio tests/calibration/temporary-radio operations, functional CLI
|
||||
work, and selected/in-flight radio transmissions to clear. Stale ASCII output
|
||||
from a disconnected or stalled host does not indefinitely prevent recovery.
|
||||
Before MCU reset, the next tier must commit and pass readback; the firmware
|
||||
then rechecks transport health and ownership. Re-enumeration preserves the
|
||||
configured USB descriptors, but can disconnect host applications and lose
|
||||
best-effort packet records.
|
||||
|
||||
## Persistence and status
|
||||
|
||||
The independent, versioned, CRC-protected `/usb_wdg` statefile does not
|
||||
change existing role preference offsets. Unreadable/corrupt state or a volatile
|
||||
fallback filesystem disables automatic recovery/promotion. Failed commits
|
||||
remain fail-closed; an explicit setter can retry or repair this statefile on
|
||||
durable storage, applying only after complete verification. It cannot make
|
||||
volatile storage durable. A verified backup repairs a conclusively missing
|
||||
primary after an interrupted rename; unreadable live state is not replaced
|
||||
automatically.
|
||||
|
||||
Current writes use the 33-byte UW2 format, including the latest watchdog event.
|
||||
Valid 20-byte UW1 files still load with their saved mode, tier, and counters;
|
||||
they upgrade on the next legitimate event/configuration save, not merely on
|
||||
boot. Each attempted software recovery or re-enumeration saves its event and
|
||||
counters once. Probes, idle ticks, ownership/backend deferrals, and status
|
||||
reads do not write flash. A failed save leaves the live event marked unsaved
|
||||
and automatic actions fail closed until explicit repair.
|
||||
|
||||
### Last-event review
|
||||
|
||||
```text
|
||||
get usb.watchdog.last
|
||||
```
|
||||
|
||||
This returns the latest event only, not an unbounded history. New events replace
|
||||
older ones; exporting periodic management reports can retain observations
|
||||
off-node. Mode changes preserve the record. Erasing the filesystem or restoring
|
||||
a backup can remove or roll back it.
|
||||
|
||||
The event includes an advisory Unix epoch from the node's RTC, uptime seconds
|
||||
at that recorded boot, a saturating event sequence, action, reason bitmask, and
|
||||
durability status. Uptime extends the millisecond clock across rollover.
|
||||
RTC time is not verified UTC: default clocks can start at a plausible fixed
|
||||
date, and a later time correction does not rewrite old events. Epoch zero
|
||||
is allowed and can mean no usable timestamp source. Use a synchronized node
|
||||
clock for meaningful calendar times; sequence and recorded uptime remain useful when
|
||||
clock time is wrong.
|
||||
|
||||
Reason bits are `1` host absent, `2` reader absent, `4` physical TX stalled,
|
||||
and `8` previously confirmed stats client inactive. Physical failures can set
|
||||
multiple bits; a stats-only expiry uses bit 8 and cannot authorize an MCU reset.
|
||||
Actions are `soft-recovery`, `reenumerate`, `reboot-requested`, and
|
||||
`reboot-cancelled`. Software actions mean the backend reported an attempt, not
|
||||
that USB was successfully repaired. A reboot request is persisted with the
|
||||
next backoff tier before authorization; health/ownership are rechecked after
|
||||
the commit. A subsequent veto records cancellation immediately in RAM. If OTA
|
||||
or another owner makes storage unsafe, its durable save waits for a safe
|
||||
application tick; power loss before that save can leave the earlier reboot
|
||||
intent on disk. Neither the intent record
|
||||
nor the existing reboot counter proves a completed physical reset. Power loss
|
||||
or a hardware main-loop watchdog can occur without any opportunity to save
|
||||
an exact trigger time; this record covers the staged USB logging watchdog.
|
||||
|
||||
`get usb.watchdog` includes these compact fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `usb`, `log`, `host`, `reader`, `logger` | Backend supported; logging master; observed physical USB host/reader; confirmed healthy stats client. |
|
||||
| `stall`, `stage`, `step` | Physical TX stall; stage 0 idle, 1 software wait, 2 re-enumeration wait, 3 reset pending; saved tier index 0-8. |
|
||||
| `retry`, `idle`, `auto` | Saved MCU interval, current monitored fault age, and continuous Auto qualification age, in seconds. Retry is not an action countdown. |
|
||||
| `defer`, `fs` | Ownership/backend deferral and verified durable persistence readiness. |
|
||||
| `rec`, `boot` | Attempted USB recoveries and durable reset authorizations. Attempts save the event and recovery count together; a failed save can leave the live recovery count unsaved. The reset count can include a later safety/health veto; it is not a count of completed physical reboots. |
|
||||
|
||||
The [MGR3 management report](management_reports.md) exports the USB status and
|
||||
the same latest-event record as a frozen, authenticated public snapshot. Updated
|
||||
Python and browser decoders retain MGR1/MGR2 support; older decoder copies must
|
||||
be updated to read MGR3. Events appear on the normal management schedule, not
|
||||
as immediate alerts. Reading status does not renew the logging-client lease.
|
||||
|
||||
## Verification
|
||||
|
||||
Initial watchdog qualification on 2026-10-03, before the latest-event extension,
|
||||
passed 109 USB regression tests, 143 native test cases, 11 management protocol
|
||||
tests, and the browser decoder checks.
|
||||
Tests execute the production policy, runtime, marker parser, role ownership
|
||||
guards, and native USB boundaries with simulated clock, filesystem, and FIFO
|
||||
faults. The 14-day qualification uses an advanced test clock, not a hardware
|
||||
soak. Bounded console output, unread hosts, session races, and exact stats
|
||||
markers are covered.
|
||||
|
||||
Those initial compiled checks passed Station G2 Full Companion, Repeater, and Room Server;
|
||||
XIAO nRF52 Full Companion and Repeater (full and reduced OTA qualifications);
|
||||
and ordinary RAK 3x72 STM32 USB Companion. The STM32 image retains all CLI
|
||||
features and its 32 KiB filesystem, but has only 368 bytes of app flash margin;
|
||||
its unsupported USB watchdog machinery is compiled out.
|
||||
|
||||
Latest-event/MGR3 verification on the same date passed 116 USB regression tests,
|
||||
15 management tests with fatal AddressSanitizer/UndefinedBehaviorSanitizer
|
||||
checks, and the browser decoder tests. Coverage includes timestamp callbacks,
|
||||
clock corrections and rollover, legacy-state migration, commit failures,
|
||||
reboot-intent cancellation, deferred cancellation saves, and authenticated
|
||||
cross-language MGR1/MGR2/MGR3 decoding. The full native suite passed 1,713 cases
|
||||
during implementation; the final packet validator also passed a fresh 116-case
|
||||
routing suite and 5,855,168 previous/current validator comparisons under fatal
|
||||
sanitizers.
|
||||
|
||||
The extension compiled in standard Station G2 Full Companion and Repeater,
|
||||
XIAO nRF52 Repeater, and RAK 3x72 USB Companion. The normal `build.sh` STM32
|
||||
recipe at version `1.17.1.9` retains all CLI features and the 32 KiB filesystem,
|
||||
with 372 bytes of app flash margin; longer version strings or future changes
|
||||
can still exceed that tight budget. No features or filesystem space were cut
|
||||
to fit this extension. This is not an all-board release qualification or a
|
||||
physical USB recovery test. No hardware was flashed, and verification artifacts
|
||||
stayed outside `out`.
|
||||
Reference in new issue
Block a user