Skip to content

TODO / Roadmap

v1.0

  • Implement base string parsing flow
  • Implement user authentication flow
  • Implement history buffer support
  • Implement autocomplete actions triggered by the Tab key
  • Add basic and Blue Pill examples
  • Add support for ESC sequences and other ASCII control commands

v2.0

  • Review approaches for using the shell module with multiple instances, if needed
  • Optimize history handling — fix bugs, improve user experience, replace CRC32 with Jenkins hash, etc.
  • Implement advanced autocomplete with flag suggestions
  • Simplify configuration file structure
  • Add a built-in default command for querying the shell interface
  • Optimize options file structure

v2.1

  • Support input range only from space till ~
  • Change command table attachment from storing commands to storing pointers to commands
  • Add an extra space (' ') on double-Tab during command autocompletion
  • Implement input blocking while waiting for specific keys (Enter, Yes/No, etc.)
  • Save previous symbol and handle different terminals setup (\r, \n or \r\n)
  • Add string print with deAuth reason on deAuth event
  • Automatically generate documentation on GitHub Pages

v2.2

  • Add support for storing passwords in encrypted (hashed) form in memory

v2.3

  • Review default command behavior and provide more detailed output about it
  • Fix fault on history read and write callbacks if history isn't inited
  • Review groups, permissions, and access levels for commands, users, and options; document them
  • Check the same names for commands and options (if short and long options repited in one command or commands are same)

v2.4 (Security, Robustness & Developer Experience)

Security Improvements

  • Implement constant-time comparison for login/password validation to prevent timing attacks
  • Add secure memory zeroing for sensitive data (password hash buffer) using volatile loop
  • Add comprehensive input validation for login and password lengths
  • Improve credential checking with length validation before comparison

Robustness & Bug Fixes

  • Fix potential fault in history read/write callbacks when history is not initialized
  • Fix escape sequence bug in input handling
  • Add duplicate detection for short and long option flags within commands (triggers ASSERT)
  • Fix command line flush bug
  • Fix argument processing flow
  • Multiple small fixes and code quality improvements

Features & Enhancements

  • Add history save support for interactive commands
  • Add default command description to help output
  • Add more detailed build information to shell startup banner (compiler, OS, build date/time)
  • Add FreeRTOS version detection support
  • Add WSH_SHELL_PRINT_LEVEL macro for better print control
  • Add debug build flag support
  • Review and document groups, permissions, and access levels system

Documentation & Tooling

  • Update documentation for permission rules and access control
  • Add ELF size analysis utility script
  • Fix grammar and typos in documentation
  • Update README with clearer examples
  • Fix VSCode task configurations
  • Improve Makefile structure

v2.5 (Security & Stability Fixes)

  • Fix typo in WshShellCmd_FindOpt parameter validation (pcCmd || pcCmd → pcCmd || pcStr)
  • Add VLA stack overflow protection in autocomplete (check against WSH_SHELL_AUTOCOMPLETE_MAX_CANDIDATES)
  • Add bounds checking before buffer copy in autocomplete to prevent buffer overflow
  • Add secure erase of sensitive data (saltPass) in default hash function using volatile loop
  • Add volatile qualifier to constant-time comparison variables to prevent compiler optimization
  • Add validation for unclosed quotes in command parsing (WshShellStr_ParseToArgcArgv)

v2.6 (Build System, UX & Developer Tooling)

  • Restructure build system: remove static library target, add gen-config target, move config generation to example/ directory
  • Add compiler selection support (CC ?= gcc / clang) with passthrough from top-level Makefile
  • Add --ping / -p flag to default wsh command for adapter health check
  • Improve print macros format: add colored [TAG] prefix to INFO/WARN/ERR messages for easier log parsing
  • Fix unknown token handling: print [WARN] for unrecognized options instead of silently falling back to default behavior
  • Fix spurious ERR_EMPTY response when valid options are followed by unknown tokens in the same command call
  • Add entry/exit info messages for interactive mode
  • Fix IntelliSense configuration (c_cpp_properties.json)
  • Update and improve documentation
  • Extend autocomplete to support flag suggestions (not just command names)

v3.0 (Python Adapter, Tests & CI)

  • Add Python wsh_shell_adapter package with serial/UART and local PTY transports
  • Implement shell sync/auth flow with command execution, retry logic, sync probe verification, and structured output parsing
  • Add TOML-based adapter configuration
  • Add serial port auto-discovery by fixed port or vid/pid, including interactive port selection helpers
  • Add adapter unit tests for sync/login flow, JSON parsing, fragmented writes, timeout retry, empty command validation, and config loading
  • Add integration tests for running against example/build/example via PTY and for non-zero exit on failed WSH_SHELL_ASSERT
  • Add adapter and test documentation
  • Automate adapter test runs in GitLab CI

v3.1 (Command Model & UX Extensions)

Subcommand Trees

  • Add WSH_SHELL_SUBCOMMANDS / WSH_SHELL_SUBCOMMANDS_MAX_DEPTH config flags (default-on, overridable)
  • Extend WshShellCmd_t with SubCmds / SubCmdNum (compiled out when feature disabled)
  • Add WshShellCmd_GetSubCmdNum, WshShellCmd_GetSubCmdByIndex, WshShellCmd_SearchSubCmd helpers
  • Descend subcommand tree in WshShell_StringHandler with argv shifting, depth guard, and per-level access check
  • Recursively validate subcommand tables on WshShellCmd_Attach (duplicate names, NULL entries, nested options)
  • Extend WshShellCmd_PrintOptionsOverview to list subcommands; suppress empty "Options overview" section
  • Extend autocomplete to walk the subcommand tree and complete partial subcommand names
  • Add meaningful demo: wsh user list / wsh user whoami driven by the existing user table, with flags at every hierarchy level
  • Keep flat -u / --user when WSH_SHELL_SUBCOMMANDS=0 via slot macro; remove it when subcommands are on
  • Add ParseError field to WshShellOption_Ctx_t; set it in WshShellCmd_ParseOpt on unknown token so handlers can distinguish end-of-options from bad flag without restructuring the loop
  • Update all handlers (including WshShellCmdDef) to check ParseError and return ERR_PARAM on unknown flags
  • Document subcommand feature (usage/subcommands.md, index.md feature list)
  • Add usage/writing-commands.md — standard handler template with X-macro tables, parse loop, and ParseError explanation

Numeric Literal Base Auto-Detect

  • Change WSH_SHELL_STRTOL base from 10 to 0 in WshShellCmd_GetOptValue — 0x prefix → hex, 0 prefix → octal, else decimal; no API change
  • Add missing-argument guard in WshShellCmd_ParseOpt — if flag requires N args but fewer tokens follow, print [WARN] and set ParseError instead of crashing in GetOptValue
  • Replace ASSERT(false) in WshShellCmd_GetOptValue bounds check with graceful ERR_EMPTY

v3.2

Enum Option Type

  • Add WshShellOptionEnum_t struct (Values + Count) and Enum field to WshShellOption_t; always compiled in (no config gate)
  • Add WSH_SHELL_OPT_ENUM macro; all other option macros append WSH_SHELL_OPT_ENUM_TAIL (,NULL) to suppress -Wmissing-field-initializers
  • Validate enum value in WshShellCmd_GetOptValue — unknown value prints [WARN] and returns ERR_PARAM
  • Extend autocomplete: complete partial enum value after a known ENUM flag; list all values when flag is fully typed followed by a space
  • Add WSH_SHELL_ENUM_VALUE_MAX_LEN config knob (default 16)
  • Demo: wsh user list --format [table|short]
  • Document enum options in usage/writing-commands.md

Default Command Tree Restructure

  • Replace ad-hoc wsh options with a clean subcommand tree: wsh user, wsh user list, wsh user whoami, wsh history, wsh history list, wsh history clear
  • Remove contrived interactive demo from wsh root; add wsh tokenize as interactive demo (gated WSH_SHELL_INTERACTIVE_MODE)
  • Keep flat -u / --user, -g / --histprint, -r / --histrst fallback flags when WSH_SHELL_SUBCOMMANDS=0 via slot macros

Ctrl+C Cancel

  • Add WSH_SHELL_SYM_CANCEL (0x03) constant to wsh_shell_io.h; always active, no config gate
  • Handle in WshShell_SymbolHandler: print ^C, exit interactive mode if active (via shared WshShell_ExitInteractive helper), clear input buffer, reprint prompt — never deauths
  • WshShellPromptWait_Handle: flush active wait and return ERR_EMPTY on Ctrl+C so the cancel handler runs normally
  • Document Ctrl+C / Ctrl+D behaviour in usage/writing-commands.md

Hex Dump Utility

  • Add WshShellMisc_HexDump(pBuff, len, offset) to wsh_shell_misc — hexdump -C style output, 16 bytes per row
  • Row width configurable via WSH_HEXDUMP_COLS in wsh_shell_cfg_def.h (default 16)
  • Demo in example/shell.c: dump command dumps live PS1 buffer bytes
  • Document in usage/writing-commands.md under "Shell Utilities"

v3.3 (Fixes & Adapter Extensions)

Python Adapter — IoT Raw Backend

  • Add RawAdapter for non-shell binary protocols alongside the existing shell adapter (wsh_shell_adapter/raw_adapter.py)
  • Extend transport.py to support raw byte streams in addition to line-based shell I/O
  • Document raw-adapter usage in wsh_shell_adapter/README.md and docs/usage/python-adapter.md

Integration Test Infrastructure

  • Add pytest-based integration test suite under tests/integration/ (smoke, history, features) driving example/build/example via PTY
  • Split existing adapter tests into tests/unit/ with shared conftest.py fixtures
  • Add VS Code task entry for running the suite locally

Short Option Length Fix

  • WshShellCmd_FindOpt: match short flags by strLen <= WSH_SHELL_OPTION_SHORT_NAME_LEN instead of strict equality, so short flags shorter than the configured maximum are recognised when WSH_SHELL_OPTION_SHORT_NAME_LEN > 2
  • Add NULL guard for options without ShortName on the short-flag path

IAR Build Compatibility

  • Replace Cyrillic с (U+0441) with Latin c in identifiers (Pe159)
  • Remove VLA in wsh_shell_autocomplete.c — switch candidates[cmdNum + 1][...] to the existing WSH_SHELL_AUTOCOMPLETE_MAX_CANDIDATES cap (Pe028)

Misc

  • Add WshShellMisc_AsciiPrint helper for printable-only output
  • Autocomplete cleanup and subcommand-related corner-case fixes
  • Fix PtyProcessTransport error path on Windows in the Python adapter
  • Trim flash-footprint tables in README.md / docs/index.md to only feature-toggle macros (drop numeric-size knobs that don't fit the on/off cost model)

v3.4 (Persistent Session & Prompt-Wait Polish)

Persistent Login Session

  • Add wsh_shell_session.{c,h} — hashed WshShellSession_t descriptor (reboot budget + user index) with integrator-supplied read/write handlers, mirroring the history I/O pattern
  • Add WSH_SHELL_SESSION config flag (default-on); every public function keeps its signature as a stub when disabled
  • WshShellSession_Init discards an invalid store so uninitialised no-init RAM can never be restored
  • Add WshShell_SessionArm / WshShell_SessionRestore / WshShell_SessionIsKeepActive / WshShell_SessionRebootsLeft to the shell API; restore spends one reboot from the budget
  • Clear the session in WshShell_DeAuth — a logout must not be silently undone by the next reboot
  • Add flat -k / --keep N option to the default command via slot macro; wsh status prints the remaining budget
  • Wire the feature into the PC example: --session <file> stands in for no-init RAM, so restarting the process models a reboot
  • Add integration tests covering arming, restore across reboots, budget exhaustion, --keep 0, logout, and a corrupted store
  • Document in usage/session.md, usage/bare-metal.md, index/README feature lists

Prompt-Wait Hint Budget

  • Add WSH_SHELL_PROMPT_WAIT_HINT_RETRIES (default 3) and RejectedNum counter reset on every WshShellPromptWait_Attach
  • Add WshShellPromptWait_HintIsNeeded() for handlers to check before printing their hint; the bell still answers every refused keystroke
  • Run the handler before the Ctrl+C escape in WshShellPromptWait_Handle so a wait can undo what it guarded; Ctrl+C still always escapes, whatever the handler returns
  • Add integration tests for the hint budget, the per-wait reset, and the silent Ctrl+C escape

Fixes

  • Print [WARN] instead of [ERR ] when a command handler returns WSH_SHELL_RET_STATE_WARNING
  • Fix autocomplete-disabled notice: emit it on its own line instead of padding it onto the current input
  • Python adapter: stop anchoring prompt detection to the end of the buffer and scan for the last prompt match, so async log lines sharing the UART no longer break sync and never leak into command output
  • Add utils/measure-footprint.py + make footprint; refresh the footprint tables in README.md / docs/index.md with reproducible numbers