Skip to content

Commit 8ab959b

Browse files
JF002JF002
authored
Merge pull request #839 from Arsen6331/BLE-FS-Docs
Add documentation for BLE FS
2 parents 6a5946c + 47f7326 commit 8ab959b

2 files changed

Lines changed: 176 additions & 1 deletion

File tree

‎doc/BLEFS.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# BLE FS
2+
---
3+
4+
The BLE FS protocol in InfiniTime is mostly Adafruit's BLE file transfer protocol, as described in [adafruit/Adafruit_CircuitPython_BLE_File_Transfer](https://github.com/adafruit/Adafruit_CircuitPython_BLE_File_Transfer). There are some deviations, such as the status codes. These will be described later in the document.
5+
6+
---
7+
8+
## UUIDs
9+
10+
There are two relevant UUIDs in this protocol: the version characteristic, and the raw transfer characteristic.
11+
12+
### Version
13+
14+
UUID: `adaf0100-4669-6c65-5472-616e73666572`
15+
16+
The version characteristic returns the version of the protocol to which the sender adheres. It returns a single unsigned 32-bit integer. The latest version at the time of writing this is 4.
17+
18+
### Transfer
19+
20+
UUID: `adaf0200-4669-6c65-5472-616e73666572`
21+
22+
The transfer characteristic is responsible for all the data transfer between the client and the watch. It supports write and notify. Writing a packet on the characteristic results in a response via notify.
23+
24+
---
25+
26+
## Usage
27+
28+
The separator for paths is `/`, and absolute paths must start with `/`.
29+
30+
All of the following commands and responses are transferred via the transfer characteristic
31+
32+
### Read file
33+
34+
To begin reading a file, a header must first be sent. The header packet should be formatted like so:
35+
36+
- Command (single byte): `0x10`
37+
- 1 byte of padding
38+
- Unsigned 16-bit integer encoding the length of the file path.
39+
- Unsigned 32-bit integer encoding the location at which to start reading the first chunk.
40+
- Unsigned 32-bit integer encoding the amount of bytes to be read.
41+
- File path: UTF-8 encoded string that is _not_ null terminated.
42+
43+
To continue reading the file after this initial packet, the following packet should be sent until all the data has been received. No close command is required after the data has been received.
44+
45+
- Command (single byte): `0x12`
46+
- Status: `0x01`
47+
- 2 bytes of padding
48+
- Unsigned 32-bit integer encoding the location at which to start reading the next chunk.
49+
- Unsigned 32-bit integer encoding the amount of bytes to be read. This may be different from the size in the header.
50+
51+
Both of these commands receive the following response:
52+
53+
- Command (single byte): `0x11`
54+
- Status (signed 8-bit integer)
55+
- 2 bytes of padding
56+
- Unsigned 32-bit integer encoding the offset of this chunk
57+
- Unsigned 32-bit integer encoding the total size of the file
58+
- Unsigned 32-bit integer encoding the amount of data in the current chunk
59+
- Contents of the current chunk
60+
61+
### Write file
62+
63+
To begin writing to a file, a header must first be sent. The header packet should be formatted like so:
64+
65+
- Command (single byte): `0x20`
66+
- 1 byte of padding
67+
- Unsigned 16-bit integer encoding the length of the file path.
68+
- Unsigned 32-bit integer encoding the location at which to start writing to the file.
69+
- Unsigned 64-bit integer encoding the unix timestamp with nanosecond resolution. This will be used as the modification time. At the time of writing, this is not implemented in InfiniTime, but may be in the future.
70+
- Unsigned 32-bit integer encoding the size of the file that will be sent
71+
- File path: UTF-8 encoded string that is _not_ null terminated.
72+
73+
To continue reading the file after this initial packet, the following packet should be sent until all the data has been sent and a response had been received with 0 free space. No close command is required after the data has been received.
74+
75+
- Command (single byte): `0x22`
76+
- Status: `0x01`
77+
- 2 bytes of padding.
78+
- Unsigned 32-bit integer encoding the location at which to write the next chunk.
79+
- Unsigned 32-bit integer encoding the amount of bytes to be written.
80+
- Data
81+
82+
Both of these commands receive the following response:
83+
84+
- Command (single byte): `0x21`
85+
- Status (signed 8-bit integer)
86+
- 2 bytes of padding
87+
- Unsigned 32-bit integer encoding the current offset in the file
88+
- Unsigned 64-bit integer encoding the unix timestamp with nanosecond resolution. This will be used as the modification time. At the time of writing, this is not implemented in InfiniTime, but may be in the future.
89+
- Unsigned 32-bit integer encoding the amount of data the client can send until the file is full.
90+
91+
### Delete file
92+
93+
- Command (single byte): `0x30`
94+
- 1 byte of padding
95+
- Unsigned 16-bit integer encoding the length of the file path.
96+
- File path: UTF-8 encoded string that is _not_ null terminated.
97+
98+
The response to this packet will be as follows:
99+
100+
- Command (single byte): `0x31`
101+
- Status (signed 8-bit integer)
102+
103+
### Make directory
104+
105+
- Command (single byte): `0x40`
106+
- 1 byte of padding
107+
- Unsigned 16-bit integer encoding the length of the file path.
108+
- 4 bytes of padding
109+
- Unsigned 64-bit integer encoding the unix timestamp with nanosecond resolution.
110+
- File path: UTF-8 encoded string that is _not_ null terminated.
111+
112+
The response to this packet will be as follows:
113+
114+
- Command (single byte): `0x41`
115+
- Status (signed 8-bit integer)
116+
- 6 bytes of padding
117+
- Unsigned 64-bit integer encoding the unix timestamp with nanosecond resolution.
118+
119+
### List directory
120+
121+
Paths returned by this command are relative to the path given in the request
122+
123+
- Command (single byte): `0x50`
124+
- 1 byte of padding
125+
- Unsigned 16-bit integer encoding the length of the file path.
126+
- File path: UTF-8 encoded string that is _not_ null terminated.
127+
128+
The response to this packet will be as follows. Responses will be sent until the final entry, which will have entry number == total entries
129+
130+
- Command (single byte): `0x51`
131+
- Status (signed 8-bit integer)
132+
- Unsigned 16-bit integer encoding the length of the file path.
133+
- Unsigned 32-bit integer encoding the entry number
134+
- Unsigned 32-bit integer encoding the total amount of entries
135+
- Flags: unsigned 32-bit integer
136+
+ Bit 0: Set when entry is a directory
137+
+ Bits 1-7: Reserved
138+
- Unsigned 64-bit integer encoding the unix timestamp of the modification time with nanosecond resolution
139+
- Unsigned 32-bit integer encoding the size of the file
140+
- Path: UTF-8 encoded string that is _not_ null terminated.
141+
142+
### Move file or directory
143+
144+
- Command (single byte): `0x60`
145+
- 1 byte of padding
146+
- Unsigned 16-bit integer encoding the length of the old path
147+
- Unsigned 16-bit integer encoding the length of the new path
148+
- Old path: UTF-8 encoded string that is _not_ null terminated.
149+
- 1 byte of padding
150+
- Newpath: UTF-8 encoded string that is _not_ null terminated.
151+
152+
The response to this packet will be as follows:
153+
154+
- Command (single byte): `0x61`
155+
- Status (signed 8-bit integer)
156+
157+
---
158+
159+
## Deviations
160+
161+
This section describes the differences between Adafruit's spec and InfiniTime's implementation.
162+
163+
### Status codes
164+
165+
The status codes returned by InfiniTime are a signed 8-bit integer, rather than an unsigned one as described in the spec.
166+
167+
InfiniTime uses LittleFS error codes rather than the ones described in the spec. Those codes can be found in [lfs.h](https://github.com/littlefs-project/littlefs/blob/master/lfs.h#L70).

‎doc/ble.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ This page describes the BLE implementation and API built in this firmware.
99
### Table of Contents
1010

1111
- [BLE Connection](#ble-connection)
12+
- [BLE FS](#ble-fs)
1213
- [BLE UUIDs](#ble-uuids)
1314
- [BLE Services](#ble-services)
1415
- [CTS](#cts)
@@ -51,6 +52,13 @@ If **CTS** is detected, it'll request the current time to the companion applicat
5152

5253
---
5354

55+
## BLE FS
56+
57+
The documentation for BLE FS can be found here:
58+
[BLEFS.md](./BLEFS.md)
59+
60+
---
61+
5462
## BLE UUIDs
5563
When possible, InfiniTime tries to implement BLE services defined by the BLE specification.
5664

@@ -289,4 +297,4 @@ This characteristic expects a particular format:
289297
- Microsecond divided by `1e6*256` (`uint8`)
290298
- Binary 0001 (`uint8`)
291299

292-
Write all of these together, encoded as little-endian, to the current time characteristic.
300+
Write all of these together, encoded as little-endian, to the current time characteristic.

0 commit comments

Comments
 (0)