Browse Source

some cleaning but now broken bc csdash

Ondřej Hruška 1 year ago
parent
commit
e7c589b835
Signed by: Ondřej Hruška <ondra@ondrovo.com> GPG key ID: 2C5FD5035250423D

+ 16 - 17
ch.fw_structure.tex View File

@@ -4,12 +4,12 @@ The firmware is built around a \textit{core framework} which provides services t
4 4
 
5 5
 \section{Internal Structure Block Diagram}
6 6
 
7
-The data flows and other internal logic of the firmware are depicted in \cref{fig:gex-internal}, with more explanation following in this chapter. The interchangeable role of the three communication interfaces can be clearly seen in the diagram, as well as the central role of the message queue, which decouples interrupts from the processing thread.
7
+The data flows and other internal logic of the firmware are depicted in \cref{fig:gexinternal}, with more explanation following in this chapter. The interchangeable role of the three communication interfaces can be clearly seen in the diagram, as well as the central role of the message queue, which decouples interrupts from the processing thread.
8 8
 
9 9
 \begin{figure}[h]
10 10
 	\centering
11 11
 	\includegraphics[width=\textwidth] {img/gex-internal.pdf}
12
-	\caption{\label{fig:gex-internal}Block diagram showing the internal logic in the GEX firmware}
12
+	\caption{\label{fig:gexinternal}Block diagram showing the internal logic in the GEX firmware}
13 13
 \end{figure}
14 14
 
15 15
 The core framework forms the skeleton of the firmware and usually does not need any changes when new user-facing features are added. When the firmware is ported to a different STM32 microcontroller, the framework is not difficult to adjust and the whole process can be accomplished in a few hours. The porting of units to a different platforms is significantly more challenging.
@@ -25,18 +25,6 @@ The framework provides the following services to units:
25 25
 	\item Interrupt routing (\cref{sec:irq-routing})
26 26
 \end{itemize}
27 27
 
28
-\section{FreeRTOS Synchronization Objects Usage} \label{sec:rtos-in-gex}
29
-
30
-The firmware is built around FreeRTOS (\cref{sec:freertos}) and a number of its synchronization objects and patterns are used to make its operation more robust.
31
-
32
-\subsection{Message and Job Queue}
33
-
34
-The message and job queue, seen in \cref{fig:gex-internal}, is used to decouple asynchronous interrupts from message transmission. All three communication interfaces use interrupts for the asynchronous handling of incoming messages. The same interrupt handler receives an event after a transmission was completed. The queue ensures that messages can be received during the transmission of a large response that demands the use of multiple transmissions.
35
-
36
-The ``transmission complete'' interrupt signals this fact to the message processing task using a binary semaphore. The semaphore is released in the \gls{ISR} and taken when a new block of data is to be transmitted. If more data needs to be transmitted, the queue task waits for the semaphore and enters a Blocked state until the semaphore becomes available again.
37
-
38
-Two mutexes are used in the firmware: one that guards access to TinyFrame until the previous message was fully transmitted, and one to guard a shared memory buffer (reused in several different places to save memory and avoid its re-allocation). The hardware resource registry (explained in \cref{sec:res-allocation}) does not need mutexes for individual resources, as concurrent access to those fields can never happen; resources are always taken or released sequentially by the same task.
39
-
40 28
 \section{Unit Life Cycle and Internal Structure} \label{sec:units-function}
41 29
 
42 30
 GEX's user-facing functions, units, are implemented in \textit{unit drivers}. Those are independent modules in the firmware that the user can enable and configure, in one or more instances. In practice, we are limited by hardware constraints: i.e., there may be only one \gls{ADC} peripheral, or two \gls{SPI} ports. The assignment of those hardware resources to units is handled by the \textit{resource registry} (\cref{sec:res-allocation}).
@@ -72,12 +60,12 @@ To prevent multiple access, the firmware includes a \textit{resource registry} (
72 60
 The resources used by the core framework are taken by a virtual unit \verb|SYSTEM| on start-up to prevent conflicts with the user's units. This is the case of the status \gls{LED}, the Lock button, \gls{USB} pins, the communication \gls{UART}, the pins and an \gls{SPI} peripheral connecting the wireless module, pins used for the crystal oscillator, and the timer/counter which provides the system timebase.
73 61
 
74 62
 
75
-\section{Settings Storage} \label{sec:settings-storage}
63
+\section{Settings Storage} \label{sec:settings_storage}
76 64
 
77 65
 \begin{figure}[h]
78 66
 	\centering
79 67
 	\includegraphics[scale=1.2] {img/settings-storage.pdf}
80
-	\caption{\label{fig:settings-storage}Structure of the settings subsystem}
68
+	\caption{\label{fig:settings_storage}Structure of the settings subsystem}
81 69
 \end{figure}
82 70
 
83 71
 The system and unit settings are written, in a binary form, into designated pages of the microcontroller's Flash memory. The unit settings serialization and parsing is implemented by the respective unit drivers.
@@ -90,7 +78,7 @@ The INI files, which can be edited through the communication \gls{API} or using
90 78
 
91 79
 \section{Message Passing} \label{sec:message_passing}
92 80
 
93
-One of the key functions of the core framework is to deliver messages from the host \gls{PC} to the right units.
81
+One of the key functions of the core framework is to deliver messages from the host \gls{PC} to the right units. The \textit{TinyFrame} protocol is used, described in detail in \cref{sec:tinyframe}; it is represented by the blocks ``TinyFrame Parser'' and ``TinyFrame Builder'' in \cref{fig:gex-internal}.
94 82
 
95 83
 Two groups of messages exist: \textit{system messages} and \textit{unit messages}. System messages can, for instance, access the INI files, or request a list of available units. Unit messages are addressed to a particular unit, and their payload format is defined by the unit's driver. An incoming message is inspected and delivered to the appropriate recipient, or responded to with an error message.
96 84
 
@@ -120,6 +108,17 @@ void DMA1_Channel4_5_6_7_IRQHandler(void)
120 108
 
121 109
 It is evident that multiple units might need to use the same handler, even at the same time, since each \gls{DMA} channel is configured, and works, independently. GEX implements a redirection scheme to accomplish such interrupt sharing: All interrupt handlers are defined in one place, accompanied by a table of function pointers. When a unit driver wants to register an interrupt handler, it stores a pointer to it in this redirection table. Then, once an interrupt is invoked, the common handler checks the corresponding entry in the table and calls the referenced routine, if any. Conversely, when a unit driver de-initializes a unit, it removes all interrupt handlers it used, freeing the redirection table slots for other use.
122 110
 
111
+\section{FreeRTOS Synchronization Objects Usage} \label{sec:rtos-in-gex}
112
+
113
+The firmware is built around FreeRTOS (\cref{sec:freertos}) and a number of its synchronization objects and patterns are used to make its operation more robust.
114
+
115
+\subsection{Message and Job Queue}
116
+
117
+The message and job queue, seen in \cref{fig:gexinternal}, is used to decouple asynchronous interrupts from message transmission. All three communication interfaces use interrupts for the asynchronous handling of incoming messages. The same interrupt handler receives an event after a transmission was completed. The queue ensures that messages can be received during the transmission of a large response that demands the use of multiple transmissions.
118
+
119
+The ``transmission complete'' interrupt signals this fact to the message processing task using a binary semaphore. The semaphore is released in the \gls{ISR} and taken when a new block of data is to be transmitted. If more data needs to be transmitted, the queue task waits for the semaphore and enters a Blocked state until the semaphore becomes available again.
120
+
121
+Two mutexes are used in the firmware: one that guards access to TinyFrame until the previous message was fully transmitted, and one to guard a shared memory buffer (reused in several different places to save memory and avoid its re-allocation). The hardware resource registry (explained in \cref{sec:res-allocation}) does not need mutexes for individual resources, as concurrent access to those fields can never happen; resources are always taken or released sequentially by the same task.
123 122
 
124 123
 
125 124
 \section{Source Code Layout}

+ 2 - 0
ch.gex_units.tex View File

@@ -6,6 +6,8 @@ Each unit's description will be accompanied by a corresponding snippet from the
6 6
 
7 7
 The number in the first column of the command (or event) tables, marked as ``Code'', is the command number (or report type) used in the payload to identify how the message data should be treated. When the request or response payload is empty, it is omitted from the table. The same applies to commands with no response, in which case adding 0x80 to the command number triggers a SUCCESS response after the command is finished.
8 8
 
9
+\section{General Notes}
10
+
9 11
 \subsection{Unit Naming}
10 12
 
11 13
 Unit types are named in uppercase (SPI, 1WIRE, NPX) in the INI file and in the list of units. Unit instances can be named in any way the user desires; using lowercase makes it easier to distinguish them from unit types. It is advisable to use descriptive names, e.g., not ``pin1'', but rather ``button''.

+ 67 - 39
ch.tinyframe.tex View File

@@ -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
 

+ 5 - 5
ch.unit.1wire.tex View File

@@ -22,27 +22,27 @@ parasitic=N
22 22
 	0 & \cname{CHECK\_PRESENCE}
23 23
 	Test if there are any devices attached to the bus.
24 24
 	& \begin{cmdresp}
25
-		\cfield{u8} presence detected (0, 1)
25
+		\cfield{bool} presence detected
26 26
 	 \end{cmdresp} \\
27 27
 
28 28
 	1 & \cname{SEARCH\_ADDR}
29 29
 	Start the search algorithm.
30 30
 	& \begin{cmdresp}
31
-		\cfield{u8} should continue (0, 1)
31
+		\cfield{bool} should continue
32 32
 		\cfield{u64[]} ROM codes
33 33
 	 \end{cmdresp} \\
34 34
 
35 35
 	2 & \cname{SEARCH\_ALARM}
36 36
 	Start the search algorithm, finding only devices in an alarm state.
37 37
 	& \begin{cmdresp}
38
-		\cfield{u8} should continue (0, 1)
38
+		\cfield{bool} should continue
39 39
 		\cfield{u64[]} ROM codes
40 40
 	 \end{cmdresp} \\
41 41
 
42 42
 	3 & \cname{SEARCH\_CONTINUE}
43 43
 	Continue a previously started search
44 44
 	& \begin{cmdresp}
45
-		\cfield{u8} should continue (0, 1)
45
+		\cfield{bool} should continue
46 46
 		\cfield{u64[]} ROM codes
47 47
 	 \end{cmdresp} \\
48 48
 
@@ -65,7 +65,7 @@ parasitic=N
65 65
 	\begin{cmdreq}
66 66
 		\cfield{u64} ROM code
67 67
 		\cfield{u16} read length
68
-		\cfield{u8} verify checksum (0, 1)
68
+		\cfield{bool} verify checksum
69 69
 		\cfield{u8[]} request bytes
70 70
 	\end{cmdreq}
71 71
 	\cjoin

+ 9 - 9
ch.unit.adc.tex View File

@@ -84,7 +84,7 @@ avg_factor=500
84 84
 	Get the averaged values from enabled channels. Not available for high sample rates and when disabled.
85 85
 	&
86 86
 	\begin{cmdresp}
87
-		\cfield{float32[]} smoothed values 0--4095
87
+		\cfield{float[]} smoothed values 0--4095
88 88
 	\end{cmdresp}
89 89
 	\\
90 90
 
@@ -92,13 +92,13 @@ avg_factor=500
92 92
 	Read factory calibration constants from the \gls{MCU}'s \gls{ROM}
93 93
 	&
94 94
 	\begin{cmdresp}
95
-		\cfield{u16} VREFINT\_CAL (raw word)
96
-		\cfield{u16} VREFINT\_CAL\_VADCREF (mV)
97
-		\cfield{u16} TSENSE\_CAL1 (raw word)
98
-		\cfield{u16} TSENSE\_CAL2 (raw word)
99
-		\cfield{u16} TSENSE\_CAL1\_TEMP (°C)
100
-		\cfield{u16} TSENSE\_CAL2\_TEMP (°C)
101
-		\cfield{u16} TSENSE\_CAL\_VADCREF (mV)
95
+		\cfield{u16} V$_\mathrm{REF\_INT}$ voltage (raw ADC word)
96
+		\cfield{u16} ADC reference voltage (mV) during V$_\mathrm{REF\_INT}$ measurement
97
+		\cfield{u16} Temperature sensor voltage in point 1 (raw ADC word)
98
+		\cfield{u16} Temperature sensor voltage in point 2 (raw ADC word)
99
+		\cfield{u16} Temperature in point 1 (°C)
100
+		\cfield{u16} Temperature in point 2 (°C)
101
+		\cfield{u16} ADC reference voltage (mV) during temp. sensor calibration
102 102
 	\end{cmdresp}
103 103
  	\\
104 104
 
@@ -117,7 +117,7 @@ avg_factor=500
117 117
 	&
118 118
 	\begin{cmdresp}
119 119
 		\cfield{u32} requested sample rate
120
-		\cfield{float32} real sample rate
120
+		\cfield{float} achieved sample rate
121 121
 	\end{cmdresp}
122 122
 	\\
123 123
 

+ 1 - 1
ch.unit.dac.tex View File

@@ -80,7 +80,7 @@ Channels are specified in all commands as a bit map:
80 80
 	Set the channel frequency
81 81
 	& \begin{cmdreq}
82 82
 		\cfield{u8} channels
83
-		\cfield{float32} frequency
83
+		\cfield{float} frequency
84 84
 	\end{cmdreq} \\
85 85
 
86 86
 	21 & \cname{SET\_PHASE}

+ 1 - 1
ch.unit.do.tex View File

@@ -44,7 +44,7 @@ open-drain=
44 44
 	Generate a pulse on the selected pins. The microsecond scale may be used only for 0--999\,$\mu$s.
45 45
 	& \begin{cmdreq}
46 46
 		\cfield{u16} pins to pulse
47
-		\cfield{u8} active level (0, 1)
47
+		\cfield{bool} active level
48 48
 		\cfield{u8} scale: 0-ms, 1-$\mu$s
49 49
 		\cfield{u16} duration
50 50
 	\end{cmdreq}

+ 1 - 1
ch.unit.fcap.tex View File

@@ -144,7 +144,7 @@ Some commands include optional parameter setting. Using 0 in the field keeps the
144 144
 	20 & \cname{SET\_POLARITY}
145 145
 	Set pulse polarity (active level)
146 146
 	& \begin{cmdresp}
147
-		\cfield{u8} polarity (0,1)
147
+		\cfield{bool} polarity
148 148
 	\end{cmdresp} \\
149 149
 
150 150
 	21 & \cname{SET\_PRESCALLER}

+ 2 - 2
ch.unit.sipo.tex View File

@@ -46,7 +46,7 @@ The WRITE and CLEAR\_DIRECT commands are the only ones normally used. The others
46 46
 	Load the shift registers and leave the data outputs in the ``trailing data'' state before sending the \textit{Store} pulse.
47 47
 	&
48 48
 	\begin{cmdreq}
49
-		\cfield{u16} trailing data
49
+		\cfield{u16} trailing data (packed pins)
50 50
 		\item For each output (same size)
51 51
 		\begin{pldlist}
52 52
 			\cfield{u8[]} data to load
@@ -58,7 +58,7 @@ The WRITE and CLEAR\_DIRECT commands are the only ones normally used. The others
58 58
 	Directly write to the data pin(s)
59 59
 	&
60 60
     \begin{cmdreq}
61
-		\cfield{u16} values to write
61
+		\cfield{u16} values to write (packed pins)
62 62
 	\end{cmdreq} \\
63 63
 
64 64
 	2 &

+ 5 - 0
document_config.tex View File

@@ -70,6 +70,11 @@
70 70
 	urlcolor={blue!80!black}
71 71
 }
72 72
 
73
+\usepackage{bookmark}
74
+\bookmarksetup{
75
+	numbered,
76
+}
77
+
73 78
 \usepackage[nameinlink,capitalize,noabbrev]{cleveref}
74 79
 
75 80
 %% ACRONYM CONFIG

BIN
img/tf-conceptual.pdf View File


+ 8 - 0
pre.gex_command_tables.tex View File

@@ -126,3 +126,11 @@
126 126
 	\end{lrbox}\fbox{\usebox{\mybox}}
127 127
 	\endgroup
128 128
 }
129
+
130
+
131
+
132
+
133
+
134
+
135
+
136
+

+ 18 - 0
pre.utils.tex View File

@@ -27,3 +27,21 @@
27 27
 \newcommand{\arm}{Arm\xspace}
28 28
 \newcommand{\armcm}{Arm Cortex-M\xspace}
29 29
 \newcommand{\mbed}{Arm Mbed\xspace}
30
+
31
+\newcommand*\xCmdName[2]{#1~(#2)\xspace}
32
+
33
+\newcommand*\CmdSuccess{\xCmdName{0x00}{Success}}
34
+\newcommand*\CmdPing{\xCmdName{0x01}{Ping}}
35
+\newcommand*\CmdError{\xCmdName{0x02}{Error}}
36
+\newcommand*\CmdBulkReadOffer{\xCmdName{0x03}{Bulk~Read~Offer}}
37
+\newcommand*\CmdBulkReadPoll{\xCmdName{0x04}{Bulk~Read~Poll}}
38
+\newcommand*\CmdBulkWriteOffer{\xCmdName{0x05}{Bulk~Write~Offer}}
39
+\newcommand*\CmdBulkData{\xCmdName{0x06}{Bulk~Data}}
40
+\newcommand*\CmdBulkEnd{\xCmdName{0x07}{Bulk~End}}
41
+\newcommand*\CmdBulkAbort{\xCmdName{0x08}{Bulk~Abort}}
42
+\newcommand*\CmdUnitRequest{\xCmdName{0x10}{Unit~Request}}
43
+\newcommand*\CmdUnitReport{\xCmdName{0x11}{Unit~Report}}
44
+\newcommand*\CmdListUnits{\xCmdName{0x20}{List~Units}}
45
+\newcommand*\CmdINIRead{\xCmdName{0x21}{INI~Read}}
46
+\newcommand*\CmdINIWrite{\xCmdName{0x22}{INI~Write}}
47
+\newcommand*\CmdPersistConfig{\xCmdName{0x23}{Persist~Config}}

BIN
references/10.1109@ieeestd.2008.4610935.pdf View File


+ 10 - 0
thesis.bib View File

@@ -515,3 +515,13 @@
515 515
 	url = {https://www.febo.com/pipermail/time-nuts/attachments/20071201/e7833af5/attachment.pdf},
516 516
 	urldate = {2018-05-13}
517 517
 }
518
+
519
+@ARTICLE{floatpaper,
520
+	journal={IEEE Std 754-2008}, 
521
+	title={IEEE Standard for Floating-Point Arithmetic}, 
522
+	year={2008},
523
+	pages={1-70}, 
524
+	keywords={IEEE standards;floating point arithmetic;programming;IEEE standard;arithmetic formats;computer programming;decimal floating-point arithmetic;754-2008;NaN;arithmetic;binary;computer;decimal;exponent;floating-point;format;interchange;number;rounding;significand;subnormal}, 
525
+	doi={10.1109/IEEESTD.2008.4610935}, 
526
+	month={Aug},
527
+}

BIN
thesis.pdf View File