serial-shell

Serial Shell Interaction

Use Cases

The user needs to log in to the serial Shell of an embedded Linux / RTOS device for command-line interaction.
The user needs to send a single command to the device over the serial port and capture the response, for use by scripts or automation flows.
The user has a set of commands that need to be executed on the device in order and wants to import them in batch from a file.
The device runs on an RS-485 half-duplex bus and requires RTS to control transmit/receive switching.
The device Shell uses a non-UTF-8 encoding, or requires CR+LF line endings to parse commands correctly.
Flashing or reset has been completed, and the next step is to manually verify or configure in the Shell on the device side.

A serial device path (on Windows it is COMn, on Linux it is /dev/ttyUSBn or /dev/ttyACMn）。
Baud rate (common: 115200, 9600).
For single-command mode, the command string to execute must be provided.
For batch mode, the path to the command script file must be provided.
Optional parameters: encoding, newline style, RS-485 mode, timeout, Shell prompt regex, log file path.

Serial port priority is: explicit user input,Project Profile in serial_port, script auto-detection result; otherwise block and require the user to specify.
Baud rate priority is: explicit user input,Project Profile in baud_rate, workspace documentation or code constants, and finally fall back to 115200。
Encoding defaults to utf-8; if garbled characters appear in the device echo, first try gbk, then latin-1。
Newline defaults to LF; if the device does not respond after a command is sent, try --crlf。
Mode defaults to interactive terminal; switch to non-interactive mode only when the user explicitly provides --cmd or --script .
If there are multiple equally reasonable serial port candidates, list the candidates and block; do not silently guess.

Confirm that pyserial is installed (pip install pyserial); if missing, return environment-missing and guide installation.
Run the built-in script shell_proxy.py, choosing the mode according to user intent:
- Interactive mode (default)：python shell_proxy.py -p <端口> -b <波特率>, enter the interactive terminal, exit with Ctrl+] .
- Single-command mode：python shell_proxy.py -p <端口> -b <波特率> --cmd "<命令>", wait for the response and exit automatically.
- Batch script mode：python shell_proxy.py -p <端口> -b <波特率> --script <脚本文件>, execute one by one and print the response for each.
If the device Shell requires logging in first or entering a specific directory, use --init "<命令>"(can be repeated multiple times), sent automatically in order after connection.
If the device echo is garbled, first try --encoding gbk ; if it still cannot be recognized, use --hex to view raw bytes to assist diagnosis.
If the device uses RS-485 half-duplex, enable --rs485; if per-character echo needs to be captured, further enable --rs485-byte。
If output needs to be saved to a file, use --log <文件路径>。
When reading script output, focus on command execution results, error messages, and Shell prompt return status, rather than merely relaying the raw text.
Write the confirmed valid serial port, baud rate, and encoding back to Project Profile。

When pyserial is missing, return environment-missing。
When the specified serial port cannot be opened (port does not exist, is occupied by another program, or the device is offline), return connection-failure。
When the host machine does not have permission to access the serial device, return permission-problem。
When there is no response after the command is sent and a timeout occurs, and recovery is still not achieved after trying both encoding and line endings, return target-response-abnormal。
When there are multiple reasonable serial port candidates, or conflicting baud rates are implied in the workspace, return ambiguous-context。
When the script file does not exist or cannot be parsed, return project-config-error。

Serial port naming rules reuse shared/platform-compatibility.md。
The built-in script uses pyserial, across the three host platforms Linux, macOS, and Windows.
On Windows, port names use the COMn format, and the full port name is preserved in the output.
On Linux, common permission issues manifest as PermissionError, and user group membership or udev rules need to be checked.
On macOS, prioritize /dev/cu.* ports, with/dev/tty.* as secondary candidates.

Output the selected serial port, baud rate, encoding, execution mode, and the command execution results or key observations from the interactive session.
Use serial_port、baud_rate to update Project Profile。
If --logwas used, record the log file path.
If --initwas used, record the initialization command and its execution result.
When the command output indicates that the target firmware has crashed, asserted, or abnormally reset, recommend debug-gdb-openocd or debug-jlink。

When the interactive session is complete and the device runtime logs need to be continuously monitored, hand the result to serial-monitor。
When the Shell output indicates a firmware crash and breakpoint or backtrace analysis is needed, hand the result to debug-gdb-openocd or debug-jlink。
When the serial Shell lacks the required tools and the firmware needs to be rebuilt and flashed, hand the result to the corresponding build-* and flash-* skills.