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.

  1. 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 HELLO with the matching request ID and state: "READY" when your storage is ready. An optional name appears in the app’s device list. Implement SESSION_BEGIN and SESSION_END and keep file operations within an active session.

  2. Let the app discover and browse storage

    Handle LIST at / first. Advertise a volume path such as /sd with its used and total bytes. A volume entry looks like the example below. Handle LIST for that volume and its directories, using next and more when 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}
  3. Implement file transfers

    Implement the GET_* and PUT_* calls for JSON transfers, along with TRANSFER_STATUS, TRANSFER_HOLD, and TRANSFER_RELEASE for 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.

  4. 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_OK once those features are implemented. Keep the connection at startup baud if you omit optional baud negotiation. Reply with a matching _ERR and a helpful message for unsupported commands.

  5. 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.

JSON control commands and their success responses
CommandRequest fieldsSuccess 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_BAUDbaudReturns baud, switchDelayMs, and fallbackDelayMs. Send at the current serial rate.
BAUD_CONFIRMbaudSend 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_RELEASEdiscard (optional boolean)Releases the hold. Default false preserves unfinished uploads and can reject release. True removes staged upload recovery data.
LISTpath, 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.
MKDIRpathCreates a directory and missing parents as needed.
DELETEpathDeletes a file or recursively deletes a directory. Volume roots are protected.
RENAMEpath, destinationRenames an item in the same directory. The destination must be unused.
MOVEpath, destinationMoves an item to an unused path. Across volumes, the board copies the tree before removing the source. Check both paths after a failure.
COPYpath, destinationCopies a file or directory tree to an unused destination.
UNARCHIVEpath, destinationExtracts a compatible ZIP into an existing destination directory on the same volume. Existing output paths can cause extraction to fail.
DOWNLOAD_BATCHpath, destination, itemsCreates 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_BEGINpathReturns size in bytes and the whole-file crc32.
GET_CHUNKpath, offset, lengthReads 1–480 bytes at a byte offset. Returns offset, Base64 data, and chunk crc32.
PUT_BEGINpath, size, crc32Stages 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_CHUNKpath, offset, data, crc32Writes 1–480 decoded bytes at the next expected offset. Send Base64 data and the CRC of the decoded bytes.
PUT_COMMITpathVerifies whole-file size and CRC before replacing the destination with the staged upload.
PUT_ABORTpathDiscards the staged upload. Release the transfer hold separately if one is active.
PUT_STATUSpath, size, crc32Checks staged upload metadata and returns matches, received (byte count), and prefixCrc.
PUT_RESUMEpath, size, crc32, offset, prefixCrcReturns the accepted offset. A mismatch can reset staging to offset zero. Compare the local prefix CRC before calling.
FAST_PUT_SWITCHpath, offset, requestedPayload (optional), requestedWindow (optional)Switches a staged upload to binary. Returns transferId, offset, chunkSize, and window.
FAST_GET_SWITCHpath, 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

  1. Download. Call GET_BEGIN, then GET_CHUNK with 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.
  2. Upload. Call PUT_BEGIN. Wait for each PUT_CHUNK_OK before advancing the offset. After the last chunk, send PUT_COMMIT and check its reply. Use PUT_ABORT to discard staging intentionally.
  3. Recover. Use PUT_STATUS to inspect staging, and compare prefixCrc with the CRC of the same number of local bytes. Continue at the offset returned by PUT_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.

Decoded header fields in wire order
Byte offsetWidth in bytesField
01Version (2)
11Frame type
21Flags (0)
31Header length (22)
44Transfer ID
84Sequence number
128File byte offset
202Payload 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.