UNA Watch — BLE File Transfer Service (FTS)

This document is the wire protocol for reading and writing files on a UNA Watch over Bluetooth Low Energy. It is what a companion app or integration implements against; it does not describe the watch’s internal implementation.

The base protocol is the Adafruit CircuitPython BLE File Transfer protocol (service 0xFEBB). UNA implements that command set and adds a small set of backward-compatible fast-transfer extensions (protocol version 5): windowed reads and writes, a file digest query, and safe resume. A client that only knows the classic (version 4) protocol interoperates unchanged.

Conventions

All multi-byte integers are little-endian.
All request/response layouts below are packed (no padding beyond the reserved bytes shown). Byte offsets are given for each field.
Paths are UTF-8, not NUL-terminated on the wire; their length is carried in a pathLength field. Absolute paths, /-separated (e.g. /Apps/Workout/Activity/202607/activity_...fit).
Times are nanoseconds since the Unix epoch (uint64).

Service and characteristics

Item	UUID	Properties
File Transfer Service	`0000FEBB-0000-1000-8000-00805F9B34FB` (`0xFEBB`)	—
Version	`ADAF0001-4669-6C65-5472-616E73666572`	Read
Raw Transfer	`ADAF0002-4669-6C65-5472-616E73666572`	Write Without Response, Notify

Note. The characteristic 16-bit IDs are UNA-specific (ADAF0001 / ADAF0002) and differ from Adafruit’s upstream (ADAF0100 / ADAF0200). Use the UUIDs exactly as listed above — they are what the watch exposes.

All operations are a request written to Raw Transfer and one or more responses delivered as notifications on the same characteristic. Enable notifications (write the CCCD) before issuing commands.

Security. The watch requires a bonded, encrypted connection — pair with the watch before using FTS. Reads and writes on the characteristics are rejected on an unencrypted link.

Capability negotiation

Read the Version characteristic — a single uint32 (little-endian):

4 — classic protocol only (Adafruit-compatible, stop-and-wait).
≥ 5 — UNA fast-transfer extensions are available.

Gating rules for a version-5 client:

Read windowing needs no gate — it degrades automatically against a v4 watch (see Read windowing under the version-5 extensions below).
Write windowing and DIGEST MUST be gated on version ≥ 5.

Command summary

ID	Name	Direction
`0x10`	READ	request
`0x11`	READ_DATA	response
`0x12`	READ_PACING	request (more)
`0x20`	WRITE	request
`0x21`	WRITE_PACING	response
`0x22`	WRITE_DATA	request (data)
`0x30` / `0x31`	DELETE / status	request / response
`0x40` / `0x41`	MKDIR / status	request / response
`0x50` / `0x51`	LISTDIR / entry	request / response
`0x60` / `0x61`	MOVE / status	request / response
`0x70` / `0x71`	DIGEST / status	request / response (UNA extension)

Status codes (the status byte in responses):

Value	Meaning
`0x01`	OK
`0x02`	ERROR (generic)
`0x03`	ERROR_NO_FILE
`0x04`	ERROR_PROTOCOL (malformed/wrong length)
`0x05`	ERROR_READ_ONLY

Notification sizing — read this first

A GATT notification cannot carry more than the negotiated ATT payload = MTU − 3 bytes. Every FTS response has a fixed header, so the usable data per notification is smaller still. For READ_DATA (16-byte header) at MTU 220:

data per notification ≤ (MTU − 3) − 16 = 201 bytes

Do not assume one request maps to one notification of the size you asked for. A version-5 watch delivers a large read as multiple READ_DATA notifications (see below); each READ_DATA is self-describing (chunkOffset, chunkLength), so reassemble by offset and never trust a chunkLength beyond what the notification actually delivered.

Classic operations (protocol version 4)

Read a file

READ 0x10 (request):

Off	Size	Field	Notes
0	1	command = `0x10`
1	1	reserved	0
2	2	pathLength
4	4	chunkOffset	file offset to start at
8	4	chunkSize	bytes requested
12	pathLength	path	UTF-8

READ_DATA 0x11 (response, one or more notifications):

Off	Size	Field	Notes
0	1	command = `0x11`
1	1	status
2	2	reserved
4	4	chunkOffset	offset of this chunk
8	4	totalLength	total file size
12	4	chunkLength	bytes of data that follow
16	chunkLength	data

READ_PACING 0x12 (request more) — after consuming a chunk, ask for the next:

Off	Size	Field	Notes
0	1	command = `0x12`
1	1	status = `0x01`
2	2	reserved
4	4	chunkOffset	next offset = contiguous end (first byte not yet received)
8	4	chunkSize	bytes requested

Classic flow: send READ, receive one READ_DATA, send READ_PACING for the next chunk, repeat until chunkOffset + chunkLength == totalLength.

Write a file

WRITE 0x20 (request):

Off	Size	Field	Notes
0	1	command = `0x20`
1	1	reserved	0
2	2	pathLength
4	4	offset	start offset (0 for a fresh write; see Resume below)
8	8	currentTime	ns since epoch (file mtime)
16	4	totalSize	total bytes to be written
20	pathLength	path

WRITE_PACING 0x21 (response / ACK):

Off	Size	Field	Notes
0	1	command = `0x21`
1	1	status
2	2	reserved
4	4	offset
8	8	truncatedTime	mtime as stored
16	4	freeSpace	bytes still expected (see below)

WRITE_DATA 0x22 (request, carries data):

Off	Size	Field	Notes
0	1	command = `0x22`
1	1	status = `0x01`
2	2	reserved
4	4	offset	offset of this chunk
8	4	dataSize	bytes of data that follow
12	dataSize	data

Classic flow: WRITE, then send WRITE_DATA chunks in ascending order, waiting for a WRITE_PACING ACK after each. freeSpace == 0 is the terminal ACK. bytesAcked = totalSize − freeSpace.

Delete / MkDir / List / Move

DELETE 0x30 → 0x31: request {command, reserved, pathLength} + path; response {command, status}.

MKDIR 0x40 → 0x41: request {command, reserved, pathLength, reserved(4), currentTime(8)} + path; response {command, status, reserved(6), truncatedTime(8)}.

LISTDIR 0x50 → 0x51: request {command, reserved, pathLength} + path (an absolute directory path, starting with /). One 0x51 notification per entry, then a terminating entry with entryNumber == totalEntries and pathLength == 0:

Off	Size	Field	Notes
0	1	command = `0x51`
1	1	status
2	2	pathLength	name length that follows
4	4	entryNumber	0-based
8	4	totalEntries
12	4	flags	bit 0 = directory
16	8	modificationTime	ns since epoch
24	4	fileSize	(ignore for directories)
28	pathLength	name	entry name (not full path)

MOVE 0x60 → 0x61: request {command, reserved, oldPathLength(2), newPathLength(2)} + oldPath + one separator byte + newPath; response {command, status}. Both paths are absolute (start with /).

Fast-transfer extensions (protocol version 5)

All of these run on the same ADAF0002 characteristic — no new services or characteristics.

Read windowing

Instead of one chunk per round-trip, request a large chunkSize (e.g. 4096). The watch answers a single READ_PACING with a burst of READ_DATA notifications totalling up to chunkSize, then waits for the next pacing request.

Each READ_DATA is self-describing — reassemble by chunkOffset, not arrival order.
Pace from the contiguous end: the next READ_PACING.chunkOffset = the first byte you don’t yet have (initialOffset + contiguous bytes received), so a dropped notification is re-requested rather than skipped — not the raw count of bytes received.
Each notification is capped to the payload limit (see Notification sizing above); a large chunkSize simply arrives as several notifications.

Auto-degrade: a v4 watch answers a large chunkSize with a single packet, so a v5 client falls back to classic pacing automatically — no version gate needed.

Recommended window: 4096 bytes. Larger adds little (reads are round-trip bound).

Write windowing (credit-based, with recovery)

Stream WRITE_DATA without waiting per-chunk, bounded by a credit window.

Keep at most WRITE_WINDOW bytes unacked: send back-to-back while bytesSent − bytesAcked < WRITE_WINDOW; otherwise wait for an ACK.
freeSpace is a contiguous high-water-mark (an intentional v5 refinement of the classic ACK — it makes loss detectable). bytesAcked = totalSize − freeSpace is the number of bytes held with no gap from the write’s start; it never advances past a missing chunk. The terminal ACK (freeSpace == 0) is therefore only ever sent for a hole-free file.
Send WRITE_DATA in ascending offset order.
Loss recovery (go-back-N). If bytesAcked stops advancing while bytes are unacked — the window drains to bytesAcked with no terminal ACK — a chunk was lost. Rewind bytesSent = bytesAcked and resume; retransmits overwrite the gap. Arm a short “no ACK progress” timeout to trigger the rewind.
Recommended WRITE_WINDOW: 2048 bytes (~10 chunks at MTU 220). Larger windows can reduce throughput (more drops → more retransmits) and don’t help — writes are round-trip bound. Raise only with digest-verified testing.

Recommended integrity check: after a windowed write, DIGEST the file and compare (below).

DIGEST — integrity without read-back (UNA extension)

Verify a file’s contents without transferring it back over BLE.

DIGEST 0x70 (request): {command, reserved, pathLength} + path.

DIGEST_STATUS 0x71 (response, 12 bytes):

Off	Size	Field	Notes
0	1	command = `0x71`
1	1	status	OK / ERROR_NO_FILE / ERROR
2	2	reserved
4	4	fileSize	total bytes hashed
8	4	crc32	see below

crc32 is standard CRC-32 (IEEE 802.3 / zlib: reflected poly 0xEDB88320, init 0xFFFFFFFF, final XOR 0xFFFFFFFF) over the whole file — identical to Java java.util.zip.CRC32 and Python zlib.crc32. Compute the expected value with a stock library and compare crc32 + fileSize.

Resume

A WRITE with offset > 0 preserves the existing file head [0, offset) and overwrites only from offset onward. So after a disconnect mid-write you may reconnect and continue with WRITE offset = bytesAcked — no need to restart from 0. A fresh WRITE offset = 0 truncates (so a full re-upload also works).

bytesAcked durability. ACKs can lead the watch’s flush to storage. On a clean disconnect the watch flushes before you reconnect, so [0, bytesAcked) is committed and you can resume at raw bytesAcked. If the watch instead reset / lost power mid-write, only data up to its last internal flush is guaranteed — on reconnect, confirm the committed size (LISTDIR or DIGEST’s fileSize) before resuming, and a DIGEST after any resumed transfer is cheap insurance.

Lost terminal ACK. If the final WRITE_PACING is lost, your normal stall→rewind resends the tail and the watch re-acknowledges the completed file (freeSpace == 0) — the same loop concludes “done.” After concluding done, drain any leftover WRITE_PACING notifications before issuing the next command so a stale one isn’t mistaken for the next command’s response.

Compatibility matrix

Client \ Watch	v4 watch	v5 watch
v4 client	classic	classic (v5 features simply unused)
v5 client	classic (windowing auto-degrades; gate writes/DIGEST off)	full fast transfer