12 Commits

Author SHA1 Message Date
38a33e38b1 Fix DE-9 logo accuracy and reframe docs for MCP client perspective
Logo/favicon: Replace crude rectangle with proper DE-9 connector geometry
derived from EIA/TIA-574 specs (D-shaped shell, 5-over-4 pin layout,
hex standoff mounting posts).

Documentation: Rewrite all code examples from the MCP client perspective.
Remove Python syntax highlighting, use JSON boolean conventions
(true/false instead of True/False), and add framing notes explaining
tool-call notation. Tutorials now guide users through natural language
interaction with the assistant rather than direct function calls.
2026-02-02 22:42:48 -07:00
dc8caddb8f Add Starlight documentation site with full content
Astro 5 + Starlight docs site with 17 pages covering all 30 mcserial
tools. Structured using Diataxis framework: tutorials, guides, reference,
and concepts. Includes Docker + caddy-docker-proxy deployment for
mcserial.l.zmesh.systems with HMR support behind reverse proxy.

Content pages:
- Landing page with feature overview and quick start
- Tutorials: getting started, loopback testing (loop://)
- Guides: RS-232 basics, RS-485/Modbus, file transfers, network ports
- Reference: common tools, RS-232 tools, RS-485 tools, file transfer
  tools, URL schemes, MCP resources, environment variables
- Concepts: RS-232 vs RS-485, flow control
2026-02-02 22:01:48 -07:00
5c655fe743 Add URL handlers, pyserial feature parity, and cp2110 extra
- open_serial_port now accepts URL schemes (socket://, rfc2217://,
  loop://, spy://, cp2110://) via serial_for_url()
- cp2110 HID-to-UART support gated behind optional [cp2110] extra
- Add grep parameter to list_serial_ports for regex filtering
- Add read_serial_lines for batch multi-line reads
- Add cancel_read/cancel_write for pending I/O interruption
- Add set_flow_control for manual XON/XOFF gating
- Add break_condition to get_modem_lines response
2026-02-01 22:39:09 -07:00
b5bd2bb470 Update README with RS-485, file transfer, and auto-baud docs
Reorganized tool tables by mode (RS-232, RS-485, file transfer) and
added usage examples for Modbus bus scanning and ZMODEM transfers.
2026-01-28 22:49:06 -07:00
e8a6197b8c Address code review findings for file transfer protocols
Critical fixes:
- Add max_transfer_size (100MB default) to XMODEM receive
- Validate ZMODEM position values with optional max_valid bound

High priority:
- Extract shared utils to _utils.py (sanitize_filename, open_file_atomic)
- Document XMODEM padding behavior (protocol limitation)
- Add filesize bounds checking in YMODEM (clamp to 10GB)
- Increase ZMODEM subpacket limit from 8KB to 32KB

Medium priority:
- Add timeout parameter to YMODEM/ZMODEM send/receive methods
- Narrow exception handling (SerialException, OSError, ValueError)
- Make ZMODEM cancel more robust (3 retries with delays)
- Add length validation in _verify_block to prevent IndexError
2026-01-28 19:59:22 -07:00
fb671a7c34 Add X/Y/ZMODEM file transfer protocols with security hardening
File transfer protocols:
- XMODEM: 128/1024-byte blocks with checksum or CRC-16
- YMODEM: Batch transfers with file metadata in block 0
- ZMODEM: Streaming protocol with auto-resume capability

Security and robustness fixes:
- Atomic file creation (O_CREAT|O_EXCL) prevents TOCTOU races
- Transfer size limits (100MB default) prevent memory exhaustion
- Byte range validation (0-255) with clear error messages
- 4GB overflow handling for ZMODEM position encoding
- CRC-32 table initialized at module load for thread safety
- Timeout enforcement prevents indefinite hangs

Server enhancements:
- file_transfer_send/receive/send_batch tools
- atexit cleanup for open connections
- Thread-safety documentation for _connections registry
2026-01-28 12:27:48 -07:00
974f2ee6dc Add RS-485 specific tools
New tools for RS-485 half-duplex communication:

- check_rs485_support: Detect hardware RS-485 capability via udev/ioctl
  Reports driver type (FTDI/CP210x/CH340), kernel support, and recommendations

- rs485_transact: Send request and receive response with automatic
  TX/RX turnaround timing. Handles manual RTS control when needed.

- rs485_scan_addresses: Scan bus for responding devices (1-247)
  Useful for Modbus device discovery
2026-01-27 22:42:40 -07:00
948775968d Default to auto-baud detection when opening ports
open_serial_port() now auto-detects baud rate when baudrate=None (default).
Returns detection confidence and top candidates in response.

Falls back to DEFAULT_BAUDRATE (9600) if no data received or low confidence.

Optional autobaud_probe parameter for sync-based detection on echo devices.
2026-01-27 22:29:19 -07:00
8014b2833b Add smart baud rate auto-detection
Uses multiple heuristics for reliable detection:
- 0x55 sync pattern analysis (self-synchronizing byte)
- Bit transition counting (0x55 has 7 transitions vs ~3.5 avg)
- Byte distribution entropy (text clusters vs random)
- ASCII readability scoring with UTF-8 validation
- Line ending and null byte detection

Supports optional probe string (use "UUUUU" for sync-based detection
on echo-enabled devices). Returns top 5 candidates with confidence scores.
2026-01-27 22:26:26 -07:00
f9f5f3527f Add advanced pyserial features
Flow control:
- xonxoff, rtscts, dsrdtr in open_serial_port and configure_serial

Timeouts:
- write_timeout and inter_byte_timeout support

New tools:
- read_until: read until custom terminator (not just newline)
- set_rs485_mode: half-duplex RS-485 for industrial/Modbus
- set_low_latency_mode: reduce kernel buffering latency (Linux)
- set_break_condition: hold/release break state

Also:
- exclusive port locking option in open_serial_port
- updated get_connection_status with all new fields
2026-01-27 22:19:29 -07:00
96d6e3e86b Add RS-232 modem control line tools
New tools for hardware control:
- get_modem_lines: read all input (CTS/DSR/RI/CD) and output (RTS/DTR) lines
- set_modem_lines: set RTS/DTR states
- pulse_line: pulse RTS or DTR for reset sequences (ESP32, Arduino, etc.)
- send_break: send serial break signal

Also added RI and CD to get_connection_status and port status resource.
2026-01-27 22:15:03 -07:00
1a26109fc1 Initial MCP serial server implementation
FastMCP server for serial port access via Model Context Protocol:
- 10 tools: list, open, close, read, write, configure, flush, status
- 4 dynamic resources: ports list, data, status, raw hex
- USB device filtering (hides phantom ttyS ports by default)
- Full pyserial support with configurable baudrate/parity/etc
2026-01-27 22:05:59 -07:00