Newer
Older
Bluetooth File Transfer
=======================
.. warning::
The file transfer specification is still work in progress
File transfer to the card10 is implemented using the custom Low Effort File
Transfer Protocol.
BLE Service
-----------
The service consists of two GATT characteristics that act as a bidrectional
link, similar to many BLE UART implementations. The two channels are seen from
the Central perspective and hence named Central TX and Central RX.
The current version uses following service specification:
write
- Central RX characteristic:
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
read, notify
Low Effort File Transfer Protocol
---------------------------------
(Version 1)
This protocol was designed to strike a balance between ease of implementation
and reasonable levels of functionality.
Features:
- File push from Central (e.g. Android) to Peripheral (card10)
- Path and file name support
- Chunked data transfer for variable MTUs
- CRC32 error-detection
- Basic error handling
All communication between Central and Peripheral is packet based. The first
byte specifies the packet type using a char followed by an optional CRC and/or
payload, depending on the packet type.
START:
===== ====
0 1-N
----- ----
s path
===== ====
START_ACK:
===== ===
0 1-4
----- ---
S CRC
===== ===
CHUNK:
===== ====== =======
0 1-4 4-N
----- ------ -------
c offset payload
===== ====== =======
CHUNK_ACK:
===== ===
0 1-4
----- ---
C CRC
===== ===
FINISH:
=== ===
0
--- ---
f
=== ===
FINISH_ACK:
=== ===
0
--- ---
F
=== ===
ERROR:
=== ===
0
--- ---
e
=== ===
ERROR_ACK:
=== ===
0
--- ---
E
=== ===
Flow
----
The file transfer process can be described as a series of states from the view
of the Central role:
.. image:: ../static/ble-low-effort-flow.png
``IDLE`` state:
- Send ``START`` to initiate transfer
``START_SENT`` state:
- Wait for ``START_ACK``
``SEND_READY`` state:
- Send first ``CHUNK``
``CHUNK_SENT`` state:
- Wait for ``CHUNK_ACK``
``SEND_READY`` state:
- Repeat previous two steps until all data is sent
- If the last chunk was sent, send ``FINISH``
``FINISH_SENT`` state:
- Wait for ``FINISH_ACK``
After ``FINISH_ACK`` was received, the transfer is complete and the process can
return to ``IDLE``.
Error Handling
--------------
Three types of errors are currently supported:
- CRC errors:
If an ``ACK`` packet contains a CRC that fails the verification, then the
original packet must be retransmitted. If three consecutive attempts to
send a packet fail, then the transfer is aborted.
- ACK timeouts:
If the Central does not receive a required ``ACK`` within 10 seconds, then
the original packet must be retransmitted. If three consecutive attempts to
send a packet fail, then the transfer is aborted.
- Unexpected response:
All steps in the flow described above have exactly one expected response.
If any other packet is received, then the transfer is aborted.
Aborting Transfer
-----------------
To abort the transfer, the Central role sends an ``ERROR`` packet and returns
to ``IDLE`` after receiving the ``ERROR_ACK``.
If the Peripheral role aborts the transfer, i.e. the Central receives an
``ERROR`` at any point, then it responds with ``ERROR_ACK`` and returns to
``IDLE``
.. warning::
As this is a custom file transfer protocol developed under less than ideal
circumstances, it does not provide any guarantees, especially not regarding
reliability or security. The protocol assumes a secure link and a
trustworthy peer, amongst many other things. Use with caution.