serial_upload
Upload a binary file to a device over serial using ZMODEM, running the receive command automatically. Set idle and total timeouts to handle stalled transfers and avoid hangs.
Instructions
Upload a binary file to the device over ZMODEM via an existing serial session. The device must have lrzsz installed (rz command). IMPORTANT: this tool triggers the device-side rz by itself (via recv_cmd); do NOT manually run rz (or serial_exec/write rz) on the session beforehand — a pre-started rz enters its own waiting state that breaks the tool's ZMODEM handshake. Just call this tool and pass recv_cmd when a working directory change is needed (e.g. "cd /home && rz"). Blocks until transfer completes, fails, or times out; progress is logged to stderr. Two timeouts: idle_timeout aborts on stalled transfer (real failure); timeout caps total duration and reports a suggested value if still progressing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | Overall timeout in seconds as a safety cap against indefinite hangs (default: 300). If reached while the transfer is still progressing (no idle), reports the timeout as too small with a suggested value instead of silently truncating. | |
| recv_cmd | No | Device receive command (default: 'rz'). The tool runs this command itself on the device after disabling flow control — do NOT start rz manually beforehand. Use it for directory changes or options, e.g. "cd /home && rz -e" to receive into /home, or 'rz -e' to escape control chars | |
| local_path | Yes | Local source file path | |
| session_id | Yes | The session ID returned by serial_open | |
| remote_name | No | Remote file name (default: basename of local_path). The device rz will name the file accordingly. | |
| idle_timeout | No | Idle timeout in seconds: if no data flows for this long, the transfer is treated as a real failure (link/device stalled) and aborted. Independent of file size (default: 15, min: 3). |