Current project state

This file is working memory. Update it during active work and before handoff; do not treat it as a permanent design record.

Development state

Based on checked-in source plus README.md and docs/roadmap.md:

Hardware characterization, serial service, session broker, USB CDC, Wi-Fi, HTTPS/WebSocket, SSH serial transport, and local display/control are implemented and documented as target-hardware validated.
Phase 8A role-based user storage/UART0 administration and Phase 8B role-aware HTTPS/SSH authentication and targeted revocation are documented as target-hardware validated.
Phase 8C admin SSH is implemented in source and uses the shared esp_console registry. Target-hardware validation is explicitly pending.
Phase 8D web user administration and Phase 8E browser login/session integration are planned, not implemented.
Security/production hardening, OTA, BLE evaluation, advanced networking, and optional filesystem features remain future roadmap work.
Reserved OTA, coredump, NVS-key, and storage partitions do not imply those runtime features are implemented.

Recent memory audit

Fixed failed-initialization ownership leaks for wolfSSH, partial HTTPS startup, and TinyUSB teardown. Failed teardown now retains ownership and blocks unsafe duplicate initialization.
Serial-service RX/TX stream payloads (16 KiB and 8 KiB effective capacity) now prefer PSRAM with internal fallback; FreeRTOS controls and UART driver buffers remain internal.
The 5,360-byte transactional user-database candidate now prefers PSRAM with internal fallback while the live database remains internal. Candidate contents are wiped after each transaction and wiped/freed on initialization or recovery failure.
UART and admin-SSH completion formatter buffers were reduced from 2 KiB to 1 KiB each; current worst-case output is 890 bytes and overflow remains fail-closed.
Linked RAM fell from 99,508 to 92,188 bytes (7,320 bytes). PSRAM placement of serial payloads additionally removes about 24 KiB of normal internal-heap pressure on the target.
pio run passes. A preliminary target run reports significantly more free memory and stable, improved operation after these changes. This is useful evidence but not completion of Phase 8C validation.
Remaining targeted checks include stored/migrated/recovered user-database mutations, USB enumeration, HTTPS start/stop failure recovery where injectable, SSH initialization/login, completion display, and sustained multi-transport serial traffic while checking memory telemetry.

Clearly incomplete or transitional areas

Phase 8C hardware-validation matrix remains pending. It includes route separation, shared command serialization, history/completion, prompts, output backpressure, revocation during queued work, deferred SSH lifecycle/reboot actions, and full concurrent transport operation.
Current HTTPS has no web-based user administration and gives both roles the same status/terminal routes.
Browser authentication still uses HTTP Basic; integrated login/logout sessions are planned.
NVS encryption, secure boot/flash encryption review, authentication rate limiting, production certificate/provisioning policy, and OTA are not implemented.

Known inconsistencies

These observations should be checked when touching the relevant area; they are not automatically bugs requiring unrelated cleanup.

Some source comments still call shared commands UART0-only or call the current local status/control task read-only.
USER_DATABASE_LOAD_EMPTY is only an initialization/failure sentinel at the checked-in revision: every successful user_database_init() path returns STORED or MIGRATED_LEGACY, so main.c's successful "new empty" log branch is unreachable.
SSH startup is currently gated on successful web_security initialization even though SSH uses separate host-key material. Needs verification: whether this coupling is intentional recovery policy or an accidental startup dependency.

Items to verify in future work

Complete the documented Phase 8C target-hardware validation before marking it complete.
Confirm task-local Newlib standard-stream behavior if ESP-IDF/Newlib configuration changes; admin SSH command output relies on dispatcher-task stream redirection.
If HTTPD concurrency configuration changes, add locking around the boot-local Basic-authentication cache.

Active Task

Objective: Keep UART1 configuration independent of USB CDC host line coding and move the Phase 0 RS-232 signal status command under debug.
Relevant files: src/usb_cdc_transport.{c,h}, src/usb_console.c, src/rs232_hw_test.c, src/console_completion.c, related documentation.
Findings: The USB transport converted cached CDC line coding into serial_config_t and called serial_service_apply_config() after writer acquisition. Separately, root status was a Phase 0 diagnostic that needed to claim the RS-232 port and therefore failed while the production serial service owned it.
Decision: Treat CDC line coding as diagnostic metadata only. UART1 configuration remains exclusively controlled by explicit serial commands and their NVS persistence. Keep all Phase 0 RS-232 diagnostics, including signal status, under debug.
Changes completed: Removed the pending line-coding apply path and its counters; retained the latest host setting for usb status. Replaced root status with debug status, updated completion and documentation.
Remaining work: Target-hardware verification: acquire/release USB writer ownership after changing a host terminal's line coding and confirm UART1 remains at the configured framing. Verify debug status works after serial stop and root status is unknown.
Risks / things to remember: Host terminal line-coding selectors no longer configure the physical RS-232 port; use serial set/serial save instead. debug status remains ownership-protected and requires UART1 to be stopped. pio run passed after both changes.

Handoff template

Objective:
Relevant files:
Findings:
Decisions made:
Changes completed:
Remaining work:
Risks / things to remember:

6.1 KiB Raw Blame History