From eb34d121ac88db271a496e9e0594592af69669dd Mon Sep 17 00:00:00 2001 From: Jeanie Date: Mon, 27 Oct 2025 22:51:57 +0900 Subject: [PATCH] docs tidying and proper readme --- tools-bao/README.md | 109 +++++++++++++++++++++++++++++++++- tools-bao/bao.py | 11 +--- tools-bao/commands/build.py | 4 -- tools-bao/commands/monitor.py | 5 -- 4 files changed, 107 insertions(+), 22 deletions(-) diff --git a/tools-bao/README.md b/tools-bao/README.md index dde1a3443..d605abba9 100644 --- a/tools-bao/README.md +++ b/tools-bao/README.md @@ -1,7 +1,110 @@ -# Bao CLI (temporary home) +# Baochip Tools CLI -This is the Baochip CLI used by the VS Code extension. It will be moved under `tools/` after repo cleanup. +**Baochip Tools CLI** is a unified command-line tool for managing, building, flashing, and debugging Baochip-based embedded systems. It provides a suite of utilities to streamline development, deployment, and diagnostics for both firmware and hardware. -## Install +This tool is designed to be use by used by the VS Code extension at https://github.com/baochip/bao-vscode-ext but can also be used alone. + + +## Features + +- **Serial Port Management**: List and monitor available serial ports. +- **Flashing**: Copy UF2 firmware images to a mounted boot drive. +- **Version Checking**: Compare local and device firmware versions to determine if updates are needed. +- **Artifact Listing**: List available UF2 images for flashing. +- **Environment Diagnostics**: Check Python and serial environment health. + +## Installation + +This CLI is designed to be run from the `tools-bao` directory: + +```sh +python tools-bao/bao.py [options] +``` + +## Requirements + +Python 3.7+ + +Before using, please install the requirements: ```bash python -m pip install --force-reinstall -r tools-bao/requirements.txt +```` + +## Commands Overview + +### `ports` +List all available serial ports on your system. + +**Usage:** +```sh +python tools-bao/bao.py ports +``` + +### `monitor` +Open a serial monitor to interact with a device. + +**Options:** +- `-p, --port` (required): Serial port (e.g., `COM5`, `/dev/ttyUSB0`) +- `-b, --baud`: Baud rate (default: 115200) +- `--ts`: Show timestamps on received lines +- `--save`: Append output to a file +- `--reset`: Toggle DTR/RTS on open +- `--crlf`: Use CRLF as TX line ending (default LF) +- `--raw`: Send keystrokes immediately (raw mode) +- `--no-echo`: Do not locally echo typed input +- `--rtscts`, `--xonxoff`, `--dsrdtr`: Enable hardware/software flow control + +**Usage:** +```sh +python tools-bao/bao.py monitor -p COM3 --ts +``` + +### `flash` +Copy one or more UF2 files to a mounted boot drive. + +**Options:** +- `--dest` (required): Mount path of the UF2 boot drive (e.g., `D:\`) +- `files`: One or more UF2 files to copy + +**Usage:** +```sh +python tools-bao/bao.py flash --dest D:\ loader.uf2 xous.uf2 +``` + +### `artifacts` +List available UF2 images for flashing. Can output as JSON for scripting. + +**Options:** +- `--json`: Output in JSON format + +**Usage:** +```sh +python tools-bao/bao.py artifacts --json +``` + +### `update-all` +Check if the board’s firmware version differs from the local version. + +**Options:** +- `-p, --port` (required): Serial port to query +- `-b, --baud`: Baud rate (default: 115200) +- `--timeout`: Seconds to wait for version response (default: 3.0) +- `--json`: Output in JSON format + +**Usage:** +```sh +python tools-bao/bao.py update-all -p COM3 --json +``` + +### `doctor` +Check your Python environment and serial port setup for common issues. + +**Usage:** +```sh +python tools-bao/bao.py doctor +``` + +## Global Options + +- `--version`: Show CLI version and exit. +- `-v, --verbose`: Enable verbose output (debug logging and tracebacks). diff --git a/tools-bao/bao.py b/tools-bao/bao.py index 165714721..88bd5b263 100644 --- a/tools-bao/bao.py +++ b/tools-bao/bao.py @@ -1,12 +1,3 @@ -""" -Baochip CLI — entry point for host-side utilities. - -Usage examples: - python tools-bao/bao.py ports - python tools-bao/bao.py monitor -p COM3 -b 115200 --ts - python tools-bao/bao.py build --target dabao -""" - import argparse import sys import logging @@ -21,7 +12,7 @@ from commands.build import cmd_build from commands.artifacts import cmd_artifacts from commands.update_all import cmd_update_all -VERSION = "0.1.0" # Update as needed +VERSION = "0.1.0" def main(): ap = argparse.ArgumentParser( diff --git a/tools-bao/commands/build.py b/tools-bao/commands/build.py index 3e30e4e9e..7f03aff92 100644 --- a/tools-bao/commands/build.py +++ b/tools-bao/commands/build.py @@ -4,10 +4,6 @@ import logging from utils.common import project_root def cmd_build(args) -> None: - """ - Run cargo xtask to build a Xous image for Baochip. - Exits with the cargo process exit code on failure. - """ target = args.target cargo_cmd = ["cargo", "xtask", target] if args.release: diff --git a/tools-bao/commands/monitor.py b/tools-bao/commands/monitor.py index 5c4201a44..f04017977 100644 --- a/tools-bao/commands/monitor.py +++ b/tools-bao/commands/monitor.py @@ -6,11 +6,6 @@ from serial.serialutil import SerialException from utils.serial_utils import open_serial, safe_close def _stdin_to_serial(ser, args, stop_event: threading.Event): - """ - Writer thread: read from stdin and write to serial. - - Line mode (default): blocks waiting for a line, appends LF or CRLF. - - Raw mode (--raw): sends characters immediately without waiting for newline. - """ try: if getattr(args, "raw", False): # Raw mode: read larger chunks for smooth pastes when available