On this page
File transfer (XMODEM / YMODEM)
XMODEM and YMODEM move a file over a connection that already exists, in either direction. The usual reason is firmware updates: a device drops into its bootloader, starts printing C once a second, and wants an image sent to it.
Five variants are supported, sending and receiving: XMODEM (128 bytes, checksum), XMODEM-CRC, XMODEM-1K, YMODEM and YMODEM-G. Most microcontroller bootloaders — ST's AN3155 and a great many vendor BSPs — speak YMODEM, so that is the one to reach for first.
Transfers work on a serial port, a TCP client, a TCP server and a remote serial port over RFC 2217. UDP is not offered: XMODEM and YMODEM retransmit by block number and cannot resynchronise after a datagram arrives out of order.
ZMODEM is not supported. On a target running Linux, sz -X and rz -X put that machine into XMODEM/YMODEM mode and cover the same job.
While a transfer runs, the protocol bytes stay out of the receive view, the log and the Cloud Console; a progress strip appears above the receive view with the file name, protocol, bytes, rate, time remaining and retry count. It is not a modal dialog, so the bootloader's own output stays visible behind it.
Send a file to a device
- Connect as usual and check the baud rate is the bootloader's, which is often not the application's.
- Put the device into its bootloader. The receive view should show it polling with
C. - Choose Connection → Send File… (
Ctrl+Shift+S). - Pick YMODEM, choose the file, confirm.
There is no moment to catch: starting a transfer takes over the device's polling, so the C characters already on screen are not a problem.
The grey line across the top of the dialog — COM3 · 115200 8N1 · no flow control — is worth a glance every time. A wrong value there is the most common reason a transfer never starts, and reading it beforehand beats any error message afterwards.
If the device's manual asks for XMODEM instead, pick XMODEM-CRC or XMODEM-1K.
Receive a file from a device
Choose Connection → Receive File… (Ctrl+Shift+R), pick the protocol and the folder, then start the sending side on the device.
The file name comes from the device, so it is treated as untrusted input: path separators, control characters and reserved Windows device names are removed, and the result always lands inside the folder you chose. An existing file is never overwritten — a second app.bin is saved as app (1).bin. Whenever the name on disk differs from the one the device asked for, an event line says so, because a file saved under a name you did not choose is a file you will not find.
Data is written to a hidden .part file and renamed into place only when the transfer completes, so a half-received file never looks like a finished one.
Two limits belong to the protocol rather than to this application:
- XMODEM carries no length, so a received file is always padded up to a whole number of blocks with
0x1A. Use YMODEM when the exact size matters, such as when a firmware image is checksummed. - XMODEM never says it has finished, so receiving has a size limit — 100 MB by default, changeable in the receive dialog. Without it a device that never sends
EOTwould fill the disk.
What a transfer takes over
A transfer owns the port for its duration. While one runs, these are refused with a reason rather than silently ignored: the Send button, automatic send, terminal keystrokes, Cloud Console sends, Break, DTR/RTS, changing the serial parameters, pausing the view, and bridging the port.
The last four are worth naming because none of them is "sending data": a Break is a burst of framing errors, dropping DTR resets many devices, changing a parameter reopens the port, and pausing the view diverts the bytes the protocol is waiting for. Any one of them ends an update.
Stopping the connection is always allowed. It sends a cancel first, but waits only briefly for it — Stop must not hang.
Transfer to a device that dialled in (TCP Server)
XMODEM and YMODEM assume there is exactly one other end, and a TCP server has as many as have connected. A transfer therefore pins one client when it starts, and everything after that goes to and comes from that client only.
With one client connected it is chosen automatically. With several, select one in the client list first — this deliberately does not fall back to "the first one" the way the Send button does. Sending a hand-typed frame to the wrong device is obvious immediately; flashing firmware into the wrong device is not.
The other clients keep sending, receiving and displaying normally throughout, and a client that connects mid-transfer does not disturb it. If the pinned client disconnects, the transfer fails at once rather than waiting out a protocol timeout.
This topology — the device dials in, rather than being dialled — is what 4G DTUs and edge gateways do, and terminal programs that can only dial out cannot reach them at all.
YMODEM-G and hardware flow control
YMODEM-G streams: the sender does not wait for an acknowledgement after each block. That makes it faster, and it also means there is no retransmission at all — one error ends the whole transfer.
It therefore needs hardware flow control (RTS/CTS). Without it YMODEM-G is not "slower", it is "fails partway through", so the option is greyed out on a connection that has no flow control, with the reason beside it.
When a transfer fails
| Message | What to check |
|---|---|
| The device did not request the transfer | Whether the device really entered receive mode, and whether the baud rate matches the line at the top of the dialog |
| Data kept failing its checksum | Baud rate mismatch or line noise |
| The device cancelled the transfer | The device refused; read its own output |
| Gave up after 10 retries | As above — usually the physical link |
| The connection was closed / lost | The device may be left with an incomplete image — run the update again |
Three behaviours are worth knowing before they surprise you:
- After cancelling a send, the device still receives up to one more block. Bytes already handed to the operating system cannot be recalled. If that was a firmware update, run the whole update again.
- A dropped connection is never resumed automatically. For a device being written to flash, silently continuing is dangerous: nothing on this side knows what state the device is in. An explicit failure and a fresh update is safer than something that looks like it worked.
- A failed receive keeps what arrived, renamed to
<name>.partial, with the path in an event line — but cancelling deletes it. Cancelling is an instruction; a dropped line is not.
Update a device through a device server (RFC 2217)
Connect with Remote Serial (RFC 2217) and everything above works unchanged, so an engineer in the office can update a device on site. The far end only has to speak RFC 2217 as a server: a Moxa NPort, ser2net, or another machine running this application in server mode.
Plain TCP forwarding also carries the file, but a bootloader usually runs at a different baud rate from the application, and only RFC 2217 can change the remote port's baud rate. Doing both over one connection — set the remote parameters, then send the file — is what makes the remote update work end to end.