|
|
@@ -1,17 +1,41 @@
|
|
1
|
1
|
\chapter{Communication Protocol} \label{sec:tinyframe}
|
|
2
|
2
|
|
|
3
|
|
-GEX can be controlled through a hardware \gls{UART}, the \gls{USB} or over a wireless link. To minimize the firmware complexity, all the three connection methods are handled by the same protocol stack and are functionally interchangeable.
|
|
|
3
|
+GEX can be controlled through a hardware \gls{UART}, the \gls{USB}, or over a wireless link. To minimize the firmware complexity, all the three connection methods use the same binary messaging protocol and are functionally interchangeable.
|
|
4
|
4
|
|
|
5
|
|
-The communication is organized in transactions. A transaction consists of one or more messages going in either direction. Messages can be stand-alone, or chained with a response or a follow-up message using the transaction ID. Both peers, GEX and the client application running on the host PC, are equal in the communication: either side can independently initiate a transaction at any time.
|
|
|
5
|
+\begin{wrapfigure}[9]{r}{0.38\textwidth}
|
|
|
6
|
+ \vspace{-1em}
|
|
|
7
|
+ \centering
|
|
|
8
|
+ \includegraphics[scale=1]{img/tf-conceptual.pdf}
|
|
|
9
|
+ \caption{\label{fig:tf-conceptual}TinyFrame API}
|
|
|
10
|
+\end{wrapfigure}
|
|
|
11
|
+
|
|
|
12
|
+GEX uses the \textit{TinyFrame}~\cite{tinyframerepo} framing library, developed, likewise, by the author, but kept as a separate project for easier re-use in different applications. The library implements frame building and parsing, including checksum calculation, and provides high-level \gls{API}.
|
|
|
13
|
+
|
|
|
14
|
+Both peers, GEX and the client library running on the host \gls{PC}, are at an equal level: either side can independently send a message at any time. The communication is organized in transactions; a transaction consists of one or more messages going in either direction. A message can be stand-alone, or chained to another, typically a request, using the frame ID field; this is the major advantage over text-based protocols, like AT commands, where all messages are independent and their relation to each other is not always clear.
|
|
|
15
|
+
|
|
|
16
|
+\section{Binary Payload Structure Notation}
|
|
|
17
|
+
|
|
|
18
|
+Binary payloads are described in several places of this text. We use a shortened notation derived from the C language to represent field data types:
|
|
|
19
|
+
|
|
|
20
|
+\begin{pldlist}
|
|
|
21
|
+ \cfield{bool} -- 8-bit field allowing values 0 (false) and 1 (true)
|
|
|
22
|
+ \cfield{u8}, \cfieldx{u16}, \cfieldx{u32} -- unsigned 8-, 16-, or 32-bit integer
|
|
|
23
|
+ \cfield{i8}, \cfieldx{i16}, \cfieldx{i32} -- signed (two's complement) 8-, 16-, or 32-bit integer
|
|
|
24
|
+ \cfield{char} -- an 8-bit ASCII character
|
|
|
25
|
+ \cfield{float} -- single-precision (32-bit) IEEE~754~\cite{floatpaper} floating point number
|
|
|
26
|
+ \cfield{double} -- double-precision (64-bit) IEEE~754~\cite{floatpaper} floating point number
|
|
|
27
|
+ \cfield{u8[]} -- array of variable length
|
|
|
28
|
+ \cfield{u8[n]} -- array of length n
|
|
|
29
|
+ \cfield{cstring} -- zero-terminated character string (like \cfieldx{char[]}, ending with a 0x00 byte)
|
|
|
30
|
+\end{pldlist}
|
|
6
|
31
|
|
|
7
|
|
-GEX uses a framing library \textit{TinyFrame}~\cite{tinyframerepo}, developed likewise by the author, but kept as a separate project for easier re-use in different applications. The library implements frame building and parsing, checksum calculation and a system of message listeners.
|
|
8
|
32
|
|
|
9
|
33
|
\section{Frame Structure}
|
|
10
|
34
|
|
|
11
|
35
|
Message frames have the following structure (all little-endian):
|
|
12
|
36
|
|
|
13
|
37
|
\begin{boxedpayload}[``TinyFrame'' frame structure, as used in GEX]
|
|
14
|
|
- \cfield{u8} start-of-frame marker (0x01)
|
|
|
38
|
+ \cfield{0x01} start-of-frame marker
|
|
15
|
39
|
\cfield{u16} frame ID
|
|
16
|
40
|
\cfield{u16} payload length
|
|
17
|
41
|
\cfield{u8} frame type
|
|
|
@@ -57,19 +81,19 @@ Message frames have the following structure (all little-endian):
|
|
57
|
81
|
|
|
58
|
82
|
\textit{Frame ID}, which could be better described as \textit{Transaction ID}, uniquely identifies each transaction. The most significant bit is set to a different value in each peer to avoid ID conflicts, and the rest of the ID field is incremented with each initiated transaction.
|
|
59
|
83
|
|
|
60
|
|
-\section{Message Listeners}
|
|
|
84
|
+\section{Message Listeners} \label{sec:tf-listeners}
|
|
61
|
85
|
|
|
62
|
86
|
After sending a message that should receive a response, the peer registers an \textit{ID listener} with the ID of the sent message. A response reuses the original frame ID and when it is received, this listener is called to process it. ID listeners can also be used to receive multi-part messages re-using the original ID.
|
|
63
|
87
|
|
|
64
|
|
-\textit{Frame type} describes the payload and does not have any prescribed format; the values are defined by application (here, GEX). A \textit{type listener} may be registered to handle all incoming messages with a given frame type. It works in a similar way to an ID listener and has a lower priority.
|
|
|
88
|
+\textit{Frame type} describes the payload and does not have any prescribed format in TinyFrame; its values are defined by the application. A \textit{type listener} may be registered to handle all incoming messages with a given frame type. It works in a similar way to an ID listener, but has a lower priority.
|
|
65
|
89
|
|
|
66
|
|
-Each message can be handled by only one listener, unless it explicitly requests the message to be passed on to a lower priority one. Messages unhandled by any listener are given to a default listener, which can, e.g., write an error to a debug log.
|
|
|
90
|
+Each message can be handled by only one listener, unless the listener explicitly requests it to be passed on. Messages not handled by any listener are given to a default listener, which can, e.g., write an error to a debug log.
|
|
67
|
91
|
|
|
68
|
92
|
\section{Designated Frame Types}
|
|
69
|
93
|
|
|
70
|
|
-The following table lists all frame types used by GEX. It is divided into four logical sections: General, Bulk Read/Write, Unit Access, and Settings.
|
|
|
94
|
+\Cref{fig:tf-types} lists the frame types defined by GEX. It is divided into four logical sections: General, Bulk Read/Write, Unit Access, and Settings. The payloads belonging to those frame types will be outlined in the following sections.
|
|
71
|
95
|
|
|
72
|
|
-\begin{table*}[h]
|
|
|
96
|
+\begin{table}[h]
|
|
73
|
97
|
\centering
|
|
74
|
98
|
\begin{tabular}{clll}
|
|
75
|
99
|
\toprule
|
|
|
@@ -92,10 +116,11 @@ The following table lists all frame types used by GEX. It is divided into four l
|
|
92
|
116
|
0x20 & List Units & \textit{Read a list of all instantiated units} \\
|
|
93
|
117
|
0x21 & INI Read & \textit{Request a bulk read transaction of an INI file} \\
|
|
94
|
118
|
0x22 & INI Write & \textit{Request a bulk write transaction of an INI file} \\
|
|
95
|
|
- 0x23 & Persist Config & \textit{Write updated configuration to Flash} \\
|
|
|
119
|
+ 0x23 & Persist Config & \textit{Write updated configuration to flash} \\
|
|
96
|
120
|
\bottomrule
|
|
97
|
121
|
\end{tabular}
|
|
98
|
|
-\end{table*}
|
|
|
122
|
+\caption{\label{fig:tf-types}Frame types used by GEX}
|
|
|
123
|
+\end{table}
|
|
99
|
124
|
|
|
100
|
125
|
|
|
101
|
126
|
\section{Bulk Read and Write Transactions} \label{sec:tf-bulk-rw}
|
|
|
@@ -104,7 +129,7 @@ The bulk read and write transactions are generic, multi-message exchanges which
|
|
104
|
129
|
|
|
105
|
130
|
The reason for splitting a long file into multiple messages, rather than sending it all in one, lies in the hardware limitations of the platform, specifically its small amount of \gls{RAM} (the STM32F072 has only 16\,kB). A message cannot be processed until its payload checksum is received and verified; however, the configuration file can have several kilobytes, owning to the numerous explanatory comments, which would require a prohibitively large data buffer. The chunked transaction could, additionally, be extended to support message re-transmission on timeout without sending the entire file again.
|
|
106
|
131
|
|
|
107
|
|
-A read or write transaction can be aborted by a frame 0x08 (Bulk Abort) at any time, though aborting a write transaction may leave the configuration in a corrupted state. As hinted in the introduction of this chapter, a transaction is defined by sharing a common frame ID. Thus, all frames in a bulk transaction must have the same ID, otherwise the ID listeners would not be called for the subsequent messages.
|
|
|
132
|
+A read or write transaction can be aborted by a frame \CmdBulkAbort at any time, though aborting a write transaction may leave the configuration in a corrupted state. As hinted in the introduction of this chapter, a transaction is defined by sharing a common frame ID. Thus, all frames in a bulk transaction must have the same ID, otherwise the ID listeners would not be called for the subsequent messages.
|
|
108
|
133
|
|
|
109
|
134
|
\Cref{fig:bulk-rw} shows a diagram of the bulk read and write data flow.
|
|
110
|
135
|
|
|
|
@@ -116,9 +141,9 @@ A read or write transaction can be aborted by a frame 0x08 (Bulk Abort) at any t
|
|
116
|
141
|
|
|
117
|
142
|
\subsection{Bulk Read}
|
|
118
|
143
|
|
|
119
|
|
-To read an INI file, we first send a frame 0x21 (INI Read), specifying the target file in the payload:
|
|
|
144
|
+To read an INI file, we first send a frame \CmdINIRead, specifying the target file in the payload:
|
|
120
|
145
|
|
|
121
|
|
-\begin{boxedpayload}[INI Read frame structure]
|
|
|
146
|
+\begin{boxedpayload}[Frame \CmdINIRead payload structure]
|
|
122
|
147
|
\cfield{u8} which file to write
|
|
123
|
148
|
\begin{pldlist}
|
|
124
|
149
|
\item 0 \dots UNITS.INI
|
|
|
@@ -127,45 +152,48 @@ To read an INI file, we first send a frame 0x21 (INI Read), specifying the targe
|
|
127
|
152
|
\end{boxedpayload}
|
|
128
|
153
|
|
|
129
|
154
|
What follows is a standard bulk read transaction with the requested file.
|
|
130
|
|
-GEX offers the file for reading with a frame 0x03 (Bulk Read Offer):
|
|
|
155
|
+GEX offers the file for reading with a frame \CmdBulkReadOffer:
|
|
131
|
156
|
|
|
132
|
|
-\begin{boxedpayload}[Bulk Read frame structure]
|
|
|
157
|
+\begin{boxedpayload}[Frame \CmdBulkReadOffer payload structure]
|
|
133
|
158
|
\cfield{u32} full size of the file in bytes
|
|
134
|
159
|
\cfield{u32} largest chunk that can be read at once
|
|
135
|
160
|
\end{boxedpayload}
|
|
136
|
161
|
|
|
137
|
|
-Now we can proceed to read the file using 0x04 (Bulk Read Poll), which is always responded to with 0x06 (Bulk Data), or 0x07 (Bulk End) if this was the last frame. Data frames have only the useful data as their payload.
|
|
138
|
|
-
|
|
139
|
|
-The 0x04 (Bulk Read Poll) payload specifies how many bytes we want to read:
|
|
|
162
|
+Now we can proceed to read the file using \CmdBulkReadPoll, which is always responded to with \CmdBulkData, or \CmdBulkEnd if this was the last frame. Data frames have only the useful data as their payload. The \CmdBulkReadPoll payload specifies how many bytes we want to read:
|
|
140
|
163
|
|
|
141
|
|
-\begin{boxedpayload}[Bulk Read Poll frame structure]
|
|
|
164
|
+\begin{boxedpayload}[Frame \CmdBulkReadPoll payload structure]
|
|
142
|
165
|
\cfield{u32} how many bytes to read (at most)
|
|
143
|
166
|
\end{boxedpayload}
|
|
144
|
167
|
|
|
|
168
|
+\begin{boxedpayload}[Frame \CmdBulkData or \CmdBulkEnd payload in a ``read'' transaction]
|
|
|
169
|
+\cfield{char[]} a chunk of the read file
|
|
|
170
|
+\end{boxedpayload}
|
|
|
171
|
+
|
|
145
|
172
|
\subsection{Bulk Write}
|
|
146
|
173
|
|
|
147
|
|
-To overwrite an INI file, we first send a frame 0x22 (INI Write) with the file size as its payload. The name of the file is irrelevant, as it is detected automatically by inspecting the content.
|
|
|
174
|
+To overwrite an INI file, we first send a frame \CmdINIWrite with the file size as its payload. The name of the file is irrelevant, as it is detected automatically by inspecting the content.
|
|
148
|
175
|
|
|
149
|
|
-\begin{boxedpayload}[INI Write frame structure]
|
|
|
176
|
+\begin{boxedpayload}[Frame \CmdINIWrite payload structure]
|
|
150
|
177
|
\cfield{u32} size of the written file, in bytes
|
|
151
|
178
|
\end{boxedpayload}
|
|
152
|
179
|
|
|
153
|
|
-The write request is confirmed by a frame 0x05 (Bulk Write Offer) sent back:
|
|
|
180
|
+\noindent
|
|
|
181
|
+The write request is confirmed by a frame \CmdBulkWriteOffer sent back:
|
|
154
|
182
|
|
|
155
|
|
-\begin{boxedpayload}[Bulk Write Offer frame structure]
|
|
|
183
|
+\begin{boxedpayload}[Frame \CmdBulkWriteOffer payload structure]
|
|
156
|
184
|
\cfield{u32} total bytes to write (here copied from the request frame)
|
|
157
|
185
|
\cfield{u32} how many bytes may be written per message
|
|
158
|
186
|
\end{boxedpayload}
|
|
159
|
187
|
|
|
160
|
|
-We can now send the file as a series of frames 0x06 (Bulk Data), or 0x07 (Bulk End) in the last frame, with chunks of the data as their payload. Each frame is confirmed by 0x00 (Success).
|
|
|
188
|
+We can now send the file as a series of frames of type \CmdBulkData, or \CmdBulkEnd in the last frame, with chunks of the data as their payloads. Each frame is confirmed by \CmdSuccess.
|
|
161
|
189
|
|
|
162
|
|
-\begin{boxedpayload}[Bulk Data or Bulk End frame structure]
|
|
163
|
|
- \cfield{u8[]} a chunk of the written file
|
|
|
190
|
+\begin{boxedpayload}[Frame \CmdBulkData or \CmdBulkEnd payload in a ``write'' transaction]
|
|
|
191
|
+ \cfield{char[]} a chunk of the written file
|
|
164
|
192
|
\end{boxedpayload}
|
|
165
|
193
|
|
|
166
|
194
|
\subsection{Persisting the Changed Configuration to Flash}
|
|
167
|
195
|
|
|
168
|
|
-The written INI file is immediately parsed and the settings are applied. However, those changes are not persistent: they exist only in RAM and will be lost when the module restarts. To save the current state to Flash, issue a frame 0x23 (Persist Config). This has the same effect as pressing the LOCK button (or replacing the LOCK jumper) when the INI files are edited using the virtual mass storage.
|
|
|
196
|
+The written INI file is immediately parsed and the settings are applied. However, those changes are not persistent: they exist only in RAM and will be lost when the module restarts. To save the current state to Flash, issue a frame \CmdPersistConfig. This has the same effect as pressing the LOCK button (or replacing the LOCK jumper) when the INI files are edited using the virtual mass storage.
|
|
169
|
197
|
|
|
170
|
198
|
It should be noted that after flashing a firmware, the Flash control registers may remain in an unexpected state and the module must first be manually restarted before attempting to persist settings. Otherwise an assertion will fail and the module is restarted by a watchdog, losing the temporary changes.
|
|
171
|
199
|
|
|
|
@@ -174,44 +202,44 @@ It should be noted that after flashing a firmware, the Flash control registers m
|
|
174
|
202
|
|
|
175
|
203
|
\section{Reading a List of Units}
|
|
176
|
204
|
|
|
177
|
|
-The frame 0x20 (List Units) requests a list of all available units in the GEX module. The list includes all units' callsigns, names and types. The response payload has the following format (in pseudocode):
|
|
|
205
|
+The frame \CmdListUnits requests a list of all available units in the GEX module. The list includes all units' callsigns, names and types. The response payload has the following format:
|
|
178
|
206
|
|
|
179
|
|
-\begin{boxedpayload}[List Units response structure (frame type Success)]
|
|
|
207
|
+\begin{boxedpayload}[Frame \CmdListUnits response structure]
|
|
180
|
208
|
\cfield{u8} the number of available units
|
|
181
|
209
|
\item For each unit:
|
|
182
|
210
|
\begin{pldlist}
|
|
183
|
211
|
\cfield{u8} unit callsign
|
|
184
|
|
- \cfield{char[]} unit name (zero-terminated string)
|
|
185
|
|
- \cfield{char[]} unit type (zero-terminated string)
|
|
|
212
|
+ \cfield{cstring} unit name
|
|
|
213
|
+ \cfield{cstring} unit type
|
|
186
|
214
|
\end{pldlist}
|
|
187
|
215
|
\end{boxedpayload}
|
|
188
|
216
|
|
|
189
|
217
|
|
|
190
|
218
|
\section{Unit Requests and Reports} \label{sec:unit_requests_reports}
|
|
191
|
219
|
|
|
192
|
|
-Frame types 0x10 (Unit Request) and 0x11 (Unit Report) are dedicated to messages sent to and by unit instances. Each has a fixed header (\textit{inside the payload}) followed by unit-specific data.
|
|
|
220
|
+Frame types \CmdUnitRequest and \CmdUnitReport are dedicated to messages sent to and by unit instances. Each has a fixed header (\textit{inside the payload}) followed by unit-specific data.
|
|
193
|
221
|
|
|
194
|
222
|
\subsection{Unit Requests}\label{sec:unit_requests_format}
|
|
195
|
223
|
|
|
196
|
|
-Unit requests deliver a message from the host to a unit instance. Unit drivers implements different commands, each with its own payload structure. The frame 0x10 (Unit Request) has the following structure:
|
|
|
224
|
+Unit requests deliver a message from the host to a unit instance. Unit drivers implements different commands, each with its own payload structure. The frame \CmdUnitRequest has the following structure:
|
|
197
|
225
|
|
|
198
|
|
-\begin{boxedpayload}[Unit Request frame structure]
|
|
|
226
|
+\begin{boxedpayload}[Frame \CmdUnitRequest payload structure]
|
|
199
|
227
|
\cfield{u8} unit callsign
|
|
200
|
228
|
\cfield{u8} command number, handled by the unit driver
|
|
201
|
|
- \cfield{u8[]} command payload, handled by the unit driver; its size and content depend on the unit driver and the particular command number, as listed in \cref{sec:units-overview}
|
|
|
229
|
+ \cfield{u8[]} command payload, handled by the unit driver; its size and content depend on the unit driver and the particular command number, as defined in \cref{sec:units-overview}
|
|
202
|
230
|
\end{boxedpayload}
|
|
203
|
231
|
|
|
204
|
232
|
The most significant bit of the command byte (0x80) has a special meaning: when set, the message delivering routine responds with 0x00 (Success) after the command completes, unless an error occurred. That is used to get a confirmation that the message was delivered and the module operates correctly (as opposed to, e.g., a lock-up resulting in a watchdog reset). Requests which normally generate a response (e.g., reading a value from the unit) should not be sent with this flag, as that would produce two responses at once.
|
|
205
|
233
|
|
|
206
|
234
|
\subsection{Unit Reports}\label{sec:unit_reports_format}
|
|
207
|
235
|
|
|
208
|
|
-Several unit types can produce asynchronous events, such as reporting a pin change or a triggering condition. The event is timestamped and sent with a frame type 0x11 (Unit Report):
|
|
|
236
|
+Several unit types can produce asynchronous events, such as reporting a pin change, or a triggering condition. The event is timestamped and sent with a frame type \CmdUnitReport:
|
|
209
|
237
|
|
|
210
|
|
-\begin{boxedpayload}[Unit Report (event) frame structure]
|
|
|
238
|
+\begin{boxedpayload}[Frame \CmdUnitReport payload structure]
|
|
211
|
239
|
\cfield{u8} unit callsign
|
|
212
|
240
|
\cfield{u8} report type, defined by the unit driver
|
|
213
|
241
|
\cfield{u64} event time (microseconds since power-on)
|
|
214
|
|
- \cfield{u8[]} report payload; similar to requests, the payload structure depends on the unit driver and the particular report type
|
|
|
242
|
+ \cfield{u8[]} report payload; similar to requests, the payload structure depends on the unit driver and the particular report type, as defined in \cref{sec:units-overview}
|
|
215
|
243
|
\end{boxedpayload}
|
|
216
|
244
|
|
|
217
|
245
|
|
