docs(ble): publish BLE File Transfer Service protocol + services overview - #273
Conversation
…view First public documentation of the watch's BLE interface, for companion-app and third-party integrators: - BLE-File-Transfer-Service.md: the FTS wire protocol -- Adafruit 0xFEBB base (classic v4) plus UNA's backward-compatible v5 fast-transfer extensions (read/write windowing, credit-based writes with go-back-N recovery, the DIGEST integrity query, safe resume). Byte-offset wire table per command. - BLE-Services-Overview.md: the standard GATT service map (Device Information, Current Time, Battery, File Transfer, Nordic UART). Wire contract only, no firmware internals. The "notification sizing" section documents the MTU-3 per-notification ceiling that clients were re-deriving.
|
Warning Review limit reached
Next review available in: 23 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughAdded documentation for UNA Watch BLE services and the BLE File Transfer Service. The documentation covers security, service mappings, version-4 operations, version-5 transfer extensions, CRC-32 digests, resumable writes, and compatibility behavior. ChangesBLE protocol documentation
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@Docs/BLE-File-Transfer-Service.md`:
- Around line 131-132: Update Docs/BLE-File-Transfer-Service.md lines 131-132
and 218-221 so both classic and windowed READ calculations derive nextOffset
from initialOffset plus contiguousBytesReceived; do not use total received bytes
for windowed reads where chunks may arrive out of order.
- Around line 85-87: Add the text language identifier to the fenced code block
containing the notification-size arithmetic, changing its opening fence to use
text while preserving the example content.
- Around line 160-175: Update Docs/BLE-File-Transfer-Service.md at lines 160-175
to define WRITE_PACING.freeSpace as the explicit available client credit limit,
and describe progress using WRITE_PACING.offset and its ACK flow rather than
remaining file bytes or a high-water mark. Also revise lines 238-246 to remove
hole-sensitive high-water-mark semantics unless this section explicitly marks
them as an intentional protocol change; keep the documented behavior consistent
with the Adafruit v4 protocol so progress and resume calculations use credit and
ACK offsets.
- Around line 186-188: The v4 summaries in Docs/BLE-File-Transfer-Service.md
require two wire-format corrections: at lines 186-188, update the LISTDIR
summary to describe the path as a UTF-8 directory path without requiring a
trailing slash; at lines 202-203, include the one-byte separator/padding byte
between oldPath and newPath in the MOVE request format.
- Around line 28-30: Update the Version and Raw Transfer characteristic UUIDs in
the BLE File Transfer Service table from ADAF0001/ADAF0002 to ADAF0100/ADAF0200
respectively, preserving the remaining UUID segments and properties.
In `@Docs/BLE-Services-Overview.md`:
- Around line 11-14: Rename the “Standard services” heading to “Service map” and
reorganize the entries into distinct Bluetooth SIG standard and vendor-specific
service sections. Classify 0xFEBB as an Adafruit vendor service and Nordic NUS
as Nordic-specific, and use the service-specific footer reference for entries
that do not follow published SIG specifications.
- Around line 51-54: Update the Nordic UART section and its related table entry
to use the complete characteristic UUIDs, mapping
6E400002-B5A3-F393-E0A9-E50E24DCCA9E as write/RX and
6E400003-B5A3-F393-E0A9-E50E24DCCA9E as notify/TX.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: cf2417ce-0cae-41ad-9661-f6cdcfe336b6
📒 Files selected for processing (2)
Docs/BLE-File-Transfer-Service.mdDocs/BLE-Services-Overview.md
…ible anchors
Add a '📡 BLE Interface' toctree section to Docs/index.rst listing the two
new pages (unregistered pages build as orphans and never appear in the site
nav). Replace GitHub-style {#anchor} heading IDs and their internal links —
this MyST config enables neither attrs_block nor heading auto-anchors, so
they would render literally / dangle — with plain in-page references.
…pping, code-fence lang - MOVE request: document the 1-byte separator between oldPath and newPath (firmware validates sizeof(req)+oldLen+1+newLen); note both paths absolute. - LISTDIR: path is an absolute directory (starts with /), not 'ending in /'. - Nordic UART: give the actual characteristic directions — 6E400002 = Notify (watch->client), 6E400003 = Write (client->watch); flag that this is swapped vs Nordic's usual convention. - Note the FTS characteristic UUIDs are UNA-specific (ADAF0001/0002) and differ from Adafruit upstream (ADAF0100/0200) so they aren't 'corrected' later. - Mark the high-water-mark freeSpace as an intentional v5 refinement. - Tag the notification-size code fence as text; rename services heading. (Rejected the review's UUID and NUS-direction 'fixes' — both contradicted the deployed firmware; verified against kernel source.)
|
Thanks — triaged all 7 against the firmware source (the docs must match the deployed device, which deviates from the Adafruit/Nordic norms in two places). Applied:
Not applied (verified against firmware — the suggestions contradict the device):
Both rejections are behavioural deviations confirmed in the firmware, not doc errors. |
For windowed reads (reassemble-by-offset), the next READ_PACING.chunkOffset must be the first byte not yet received (initialOffset + contiguous bytes), so a dropped notification is re-requested rather than skipped.
1 participant
What
The first public documentation of the UNA Watch BLE interface — two client-facing references for companion-app and third-party integrators:
Docs/BLE-File-Transfer-Service.md— the FTS wire protocol. Documents the Adafruit0xFEBBbase (classic v4) and UNA's backward-compatible v5 fast-transfer extensions: read/write windowing, credit-based writes with go-back-N recovery, theDIGESTintegrity query, and safe resume. Every command has a byte-offset wire table.Docs/BLE-Services-Overview.md— the standard GATT service map (Device Information, Current Time, Battery, File Transfer, Nordic UART).Why
External clients have been implementing against this interface black-box (e.g. #272), re-deriving details like the per-notification size ceiling. These docs are the wire contracts they need — wire contract only, no firmware internals.
Notes
MTU − 3per-notification ceiling behind FTS whole-file read: real_chunklen can advertise 3 more bytes than the notification delivers, no continuation #272 (fixed in firmware; documented here so clients don't recompute it wrong).Summary by CodeRabbit