serial_download
Download binary files from a device over a serial session using ZMODEM. Runs sz on the device, handles the transfer handshake, and saves the file locally.
Instructions
Download a binary file from the device over ZMODEM via an existing serial session. The device must have lrzsz installed (sz command). IMPORTANT: this tool triggers the device-side sz by itself (via send_cmd); do NOT manually run sz (or serial_exec/write sz) on the session beforehand — a pre-started sz enters its own sending state that breaks the tool's ZMODEM handshake. Just call this tool and pass send_cmd when a directory change is needed (e.g. "cd /home && sz {remote}"). remote_path resolves on the device relative to the shell's current working directory — prefer an absolute path, or combine send_cmd with a cd to pin the directory. If the remote file does not exist or is unreadable, sz errors out and the transfer fails (a partial local file, if any, is removed on failure). 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. | |
| send_cmd | No | Device send command template (default: 'sz {remote}'). {remote} is replaced by remote_path. The tool runs this command itself on the device — do NOT start sz manually beforehand. Use it for directory changes, e.g. "cd /home && sz {remote}" | |
| local_path | Yes | Local destination file path | |
| session_id | Yes | The session ID returned by serial_open | |
| remote_path | Yes | Remote source file path on the device. Resolved relative to the shell's current working directory — prefer an absolute path, or pin the directory via send_cmd (e.g. "cd /home && sz {remote}"). The file must exist and be readable; otherwise sz errors out and the transfer fails. | |
| 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). |