Serial protocol
Build a client that can browse and transfer files over the board’s USB serial port.
Connect and start a session
Open the port at the firmware’s startup baud (115200 by default), 8 data bits, no parity, and one stop bit. Close other software using that port.
Send one UTF-8 JSON object per line, terminated by LF. Keep each request within 4095 bytes before the terminator. Include v: 1, a nonzero unsigned 32-bit id unique among outstanding requests, and a command type. Put the command fields at the top level.
Replies repeat the request ID and use COMMAND_OK or COMMAND_ERR. Check the message field on errors. Malformed or oversized requests can produce PROTOCOL_ERR with id: 0. See the error reference.
Send the following requests one at a time, waiting for each matching reply. Begin the session when HELLO_OK reports READY or PC_SESSION. Wait for the SESSION_END reply before closing the port.
{"v":1,"id":1,"type":"HELLO"}
{"v":1,"id":2,"type":"SESSION_BEGIN"}
{"v":1,"id":3,"type":"LIST","path":"/sd","offset":0}
{"v":1,"id":4,"type":"SESSION_END"}
Example listing reply:
{"v":1,"id":3,"type":"LIST_OK","entries":[{"name":"logs","dir":true,"size":0}],"next":1,"more":false}
Use LIST with / to discover available volumes. For files, use absolute UTF-8 paths such as /sd/logs or /littlefs/logs. Use forward slashes and avoid traversal segments, control characters, and reserved staging paths. When more is true, pass next as the next listing’s offset.
SENSOR_DATA_PENDING and SENSOR_DATA_SAVED are unsolicited JSON events with v: 1 and type. At a safe pause, end the session while leaving the port open so the board can write its readings. After reading the reply, use the startup baud if the firmware restored it. Start a fresh session after the saved event.
Write firmware for the existing Windows app
You can write your own Serial File Manager firmware and use the existing Windows program as the client. Your firmware provides the serial endpoint and handles storage on the board. Use the command reference for the wire format and replies.
Make the board connect
Expose a serial port that Windows can open. Use 115200 baud, 8-N-1, and the JSON line format above. Reply to
HELLOwith the matching request ID andstate: "READY"when your storage is ready. An optionalnameappears in the app’s device list. ImplementSESSION_BEGINandSESSION_ENDand keep file operations within an active session.Let the app discover and browse storage
Handle
LISTat/first. Advertise a volume path such as/sdwith its used and total bytes. A volume entry looks like the example below. HandleLISTfor that volume and its directories, usingnextandmorewhen the listing spans multiple replies.{"v":1,"id":3,"type":"LIST_OK","entries":[{"name":"SD card","dir":true,"volume":"/sd","size":0,"totalBytes":1073741824}],"next":1,"more":false}Implement file transfers
Implement the
GET_*andPUT_*calls for JSON transfers, along withTRANSFER_STATUS,TRANSFER_HOLD, andTRANSFER_RELEASEfor the app’s recovery flow. Stage uploads and verify their sizes and CRCs before replacing files. Preserve recoverable data when a cable is unplugged. If the board also writes to storage, coordinate those writes with the PC session.Add more commands as you need them
Use the command reference to add folder creation, rename, move, copy, delete, and ZIP extraction. Advertise binary transfer or batch downloads in
HELLO_OKonce those features are implemented. Keep the connection at startup baud if you omit optional baud negotiation. Reply with a matching_ERRand a helpful message for unsupported commands.Test directly with the Windows app
Select the board’s COM port and connect. Check that a volume and its folders appear. Upload a small file, download it to a different folder, and compare the files. Then test disconnecting during a transfer and reconnecting to check that recovery preserves the original file. Validate these flows on each board you support.
Command reference
Start a PC session before issuing any command from TRANSFER_STATUS onward. Check the capabilities in HELLO_OK and handle rejection of calls on older firmware.
| Command | Request fields | Success and behavior |
|---|---|---|
HELLO | — | Reports device, optional name, build, state, baud, baudPending, baudRates, storage readiness and capacities. Current builds advertise binaryTransfer, binaryMaxPayload, binaryMaxWindow, and downloadBatch. |
SET_BAUD | baud | Returns baud, switchDelayMs, and fallbackDelayMs. Send at the current serial rate. |
BAUD_CONFIRM | baud | Send at the new rate after switchDelayMs. If the board does not receive confirmation, it falls back to its startup rate. |
SESSION_BEGIN | — | Starts or reattaches to a PC storage session. |
SESSION_END | — | Closes the session and normally syncs the queued sensor records. Check queueSynced if present. A retained transfer hold returns transferPending and queuePending instead, leaving the session recoverable. The board normally restores startup baud after replying. |
TRANSFER_STATUS | — | Returns pending, a boolean indicating a persistent transfer hold. |
TRANSFER_HOLD | — | Persists a hold in LittleFS, deferring queue replay during recoverable transfers. |
TRANSFER_RELEASE | discard (optional boolean) | Releases the hold. Default false preserves unfinished uploads and can reject release. True removes staged upload recovery data. |
LIST | path, offset (optional, default 0) | Returns entries, next, and more. Each entry contains name, dir, size, and may include modified (Unix seconds). At /, volume entries also include volume and totalBytes, and size is used bytes. |
MKDIR | path | Creates a directory and missing parents as needed. |
DELETE | path | Deletes a file or recursively deletes a directory. Volume roots are protected. |
RENAME | path, destination | Renames an item in the same directory. The destination must be unused. |
MOVE | path, destination | Moves an item to an unused path. Across volumes, the board copies the tree before removing the source. Check both paths after a failure. |
COPY | path, destination | Copies a file or directory tree to an unused destination. |
UNARCHIVE | path, destination | Extracts a compatible ZIP into an existing destination directory on the same volume. Existing output paths can cause extraction to fail. |
DOWNLOAD_BATCH | path, destination, items | Creates an archive on the same volume at an unused destination. path is the current directory. items is an array of 1–64 absolute paths. A single-item batch must be a directory. Returns size and crc32. Download the archive, then delete it when done. |
GET_BEGIN | path | Returns size in bytes and the whole-file crc32. |
GET_CHUNK | path, offset, length | Reads 1–480 bytes at a byte offset. Returns offset, Base64 data, and chunk crc32. |
PUT_BEGIN | path, size, crc32 | Stages an upload with total size and whole-file CRC. Maximum size is 1 GiB in the command validator. Available storage can impose a lower limit. |
PUT_CHUNK | path, offset, data, crc32 | Writes 1–480 decoded bytes at the next expected offset. Send Base64 data and the CRC of the decoded bytes. |
PUT_COMMIT | path | Verifies whole-file size and CRC before replacing the destination with the staged upload. |
PUT_ABORT | path | Discards the staged upload. Release the transfer hold separately if one is active. |
PUT_STATUS | path, size, crc32 | Checks staged upload metadata and returns matches, received (byte count), and prefixCrc. |
PUT_RESUME | path, size, crc32, offset, prefixCrc | Returns the accepted offset. A mismatch can reset staging to offset zero. Compare the local prefix CRC before calling. |
FAST_PUT_SWITCH | path, offset, requestedPayload (optional), requestedWindow (optional) | Switches a staged upload to binary. Returns transferId, offset, chunkSize, and window. |
FAST_GET_SWITCH | path, crc32, offset (zero), requestedPayload (optional), requestedWindow (optional) | Switches a download to binary from the beginning. Pass the crc32 from GET_BEGIN. Returns transferId, offset, chunkSize, window, size, and crc32. |
Transfer files with JSON
- Download. Call
GET_BEGIN, thenGET_CHUNKwith byte offsets starting at zero. Request fewer bytes for the final chunk if needed. Verify each decoded chunk and check the completed file’s size and CRC before using the local copy. - Upload. Call
PUT_BEGIN. Wait for eachPUT_CHUNK_OKbefore advancing the offset. After the last chunk, sendPUT_COMMITand check its reply. UsePUT_ABORTto discard staging intentionally. - Recover. Use
PUT_STATUSto inspect staging, and compareprefixCrcwith the CRC of the same number of local bytes. Continue at the offset returned byPUT_RESUME. If the commit reply is lost, verify the destination before retrying.
CRC-32 uses reflected IEEE polynomial 0xEDB88320 and initial and final XOR 0xFFFFFFFF. JSON CRC fields contain eight hexadecimal digits. The ASCII bytes for 123456789 produce cbf43926.
Binary transfer frames
Use binary mode when HELLO_OK advertises binaryTransfer: 2. Send PUT_BEGIN or GET_BEGIN, then the matching FAST_*_SWITCH. Switch parsers immediately after the success line. Use the negotiated limits, up to 1024 payload bytes and four frames in current firmware.
COBS-encode each complete frame and append byte 00. The decoded frame contains a 22-byte header, payload, and a four-byte little-endian CRC-32 covering the header and payload.
| Byte offset | Width in bytes | Field |
|---|---|---|
| 0 | 1 | Version (2) |
| 1 | 1 | Frame type |
| 2 | 1 | Flags (0) |
| 3 | 1 | Header length (22) |
| 4 | 4 | Transfer ID |
| 8 | 4 | Sequence number |
| 12 | 8 | File byte offset |
| 20 | 2 | Payload length |
Multi-byte fields are unsigned little-endian. Frame types are DATA=1, ACK=2, NAK=3, FINISH=4, FINISH_ACK=5, ABORT=6, and ERROR=7.
Sequence numbers start at zero. Send up to the negotiated window of DATA frames before waiting for a cumulative ACK. ACK and NAK identify the next expected sequence and file offset. Retransmit from the requested position. Validate transfer IDs, lengths, offsets, and CRCs before accepting data.
FINISH carries a four-byte little-endian whole-file CRC with the offset set to the file size. For uploads, the board verifies and commits the file before replying with FINISH_ACK. For downloads, the client verifies the file before sending FINISH_ACK. The board then returns to JSON. It also leaves binary mode on ABORT or after 30 seconds of inactivity. A reconnecting client can use a new JSON HELLO to resynchronise.