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.
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.
@ -116,6 +116,6 @@ The message and job queue, seen in \cref{fig:gex_internal}, is used to decouple
\subsection{Lock Objects}
\subsection{Lock Objects}
The ``transmission complete'' interrupt signals the readiness to transmit more data to the message-sending task using a binary semaphore. This semaphore is taken by the task before sending a block of data, and released by the \gls{ISR}, ensuring that the task waits for the transmission to complete before attempting to send more data.
The ``transmission complete'' interrupt signals the readiness to transmit more data to the message-sending task using a binary semaphore. This semaphore is taken by the task before sending a block of data, and released by the \gls{ISR}, ensuring that the task waits for the transmission to complete before attempting to send more data.
Two mutexes are used in the firmware: one that guards access to the TinyFrame Builder until the previous message was fully transmitted, and one to guard a shared memory buffer (reused in several 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 thanks to the way the system is organized; resources are always taken or released sequentially by the same task.
Two mutexes are used in the firmware: one that guards access to the TinyFrame Builder until the previous message was fully transmitted, and one to guard a shared memory buffer (reused in several 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 thanks to the way the system is organized; resources are always taken or released sequentially by the same task.
@ -48,12 +48,10 @@ All GEX hardware platforms have some common characteristics (\cref{fig:users_vie
\item\textbf{Wireless connection}
\item\textbf{Wireless connection}
A wireless connection is implemented using a radio module on the GEX board. To use it we need a counterpart, the \textit{wireless gateway}, which connects to the \gls{PC}using \gls{USB} with\gls{CDCACM}.
A wireless connection is implemented using a radio module on the GEX board. To use it we need a counterpart, the \textit{wireless gateway}, which connects to the \gls{PC}via \gls{USB} and acts as a\gls{CDCACM} device.
\end{itemize}
\end{itemize}
All three interfaces share the same binary communication protocol (see below). The wireless connection is an exception, as the gateway itself needs to be managed by the host application, and it can connect to more than one GEX board, necessitating an addressing scheme. Its modified protocol will be explained in \cref{sec:wireless}.
The \gls{USB} connection is always enabled first on start-up. GEX waits its for enumeration by the host \gls{PC}. When not enumerated in a few seconds, it concludes that the interface is not active and tries other enabled options. The wireless module, connected through \gls{SPI}, can be detected by reading one of its registers that should have a known value. A \gls{UART} interface cannot be tested so reliably, thus it is always considered active\footnote{A detection of the UART connection would be possible by measuring the Rx pin voltage, which should idle at a high level (here 3.3\,V). This was not implemented in the initial firmware version.}.
The \gls{USB} connection is always enabled first on start-up. GEX waits its for enumeration by the host \gls{PC}. When not enumerated in a few seconds, it concludes that the interface is not active and tries other enabled options. The wireless module, connected through \gls{SPI}, can be detected by reading one of its registers that should have a known value. A \gls{UART} interface cannot be tested so reliably, thus it is always considered active\footnote{A detection of the UART connection would be possible by measuring the Rx pin voltage, which should idle at a high level (here 3.3\,V). This was not implemented in the initial firmware version.}.
It has been proposed earlier in the text that STM32 Nucleo and Discovery development boards might be used as the hardware platform for this project. Indeed, a Discovery board with STM32F072~\cite{disco-f072} was used as a development platform for the majority of the GEX firmware. This inexpensive board may be used to try the GEX firmware without having access to the custom hardware.
It has been proposed earlier in the text that STM32 Nucleo and Discovery development boards might be used as the hardware platform for this project. Indeed, a Discovery board with STM32F072~\cite{disco-f072} was used as a development platform for the majority of the GEX firmware. This inexpensive board may be used to try the GEX firmware without having access to the custom hardware.
\subsection{Discovery F072 Configuration and Pin Mapping}
\subsection{Discovery STM32F072 Configuration and Pin Mapping}
This Discovery board is fitted with four \glspl{LED} on \gls{GPIO} pins PC6 through PC9, in a compass arrangement. The ``north'' \gls{LED}, PC6, is used as the GEX status indicator. The ``User'' button, connected to PA0, is mapped as the GEX Lock button, controlling the settings storage.
This Discovery board is fitted with four \glspl{LED} on \gls{GPIO} pins PC6 through PC9, in a compass arrangement. The ``north'' \gls{LED}, PC6, is used as the GEX status indicator. The ``User'' button, connected to PA0, is mapped as the GEX Lock button, controlling the settings storage.
@ -85,7 +85,7 @@ Like our STM32 microcontroller, the Broadcom processor on the Raspberry Pi multi
@ -79,10 +79,9 @@ The rest of the porting process, after generating the base project, can be summa
\item Update other platform-dependent code (such as the debug \gls{UART} configuration). The compiler should warn about those occurrences when trying to build the project.
\item Update other platform-dependent code (such as the debug \gls{UART} configuration). The compiler should warn about those occurrences when trying to build the project.
\item Try to build the project by running ``\verb|make|'' in the terminal. After all errors are corrected, the firmware may be flashed using ST-Link by running ``\verb|make flash|'', or through the \gls{DFU} interface with ``\verb|make dfu|''.
\item Try to build the project by running ``\verb|make|'' in the terminal.
\end{itemize}
\end{itemize}
After succeeding with the compilation, we can test the firmware image. It is highly probable that there will be errors that need correcting.
After the firmware successfully compiles, we can flash it to the \gls{MCU} using ST-Link by running ``\verb|make flash|'', or through the \gls{DFU} interface with ``\verb|make dfu|''.
A good first step is to ensure the debug \gls{UART}'s configuration is correct so that we can see the log output. It should be available on the pin PA9 at 115200\,baud. Thanks to the generous usage of assertions, most errors should produce helpful log messages, leading us to their probable cause. We proceed to experiment with the device, trying the features described in \cref{sec:conceptual}, while observing the debug log for any anomalies.
The first thing to verify after flashing the firmware is that the debug \gls{UART}'s configuration is correct and we can see the log output, which should be available on pin PA9 at 115200\,baud. Thanks to a generous usage of assertions, most errors should produce helpful log messages in the log. We can then proceed to experiment with the device, testing the features described in \cref{sec:conceptual} while observing the debug log for any anomalies.
@ -193,14 +193,15 @@ We can now send the file as a series of frames of type \CmdBulkData, or \CmdBulk
\subsection{Persisting the Changed Configuration to Flash}
\subsection{Persisting the Changed Configuration to Flash}
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.
The written INI file is immediately parsed and the settings are applied. However, these changes are not persistent: they exist only in \gls{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 closing the virtual mass storage by pushing the Lock button.
\iffalse
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.
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.
% TODO there must be a workaround, and then this paragraph can be removed.
% TODO there must be a workaround, and then this paragraph can be removed.
\fi
\section{Reading a List of Units}
\section{Reading the List of Units}
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:
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:
@ -229,7 +230,7 @@ Unit requests deliver a message from the host to a unit instance. Unit drivers i
\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}
\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}
\end{boxedpayload}
\end{boxedpayload}
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.
The most significant bit of the command byte (0x80) has a special meaning: when set, the message delivering routine responds with \CmdSuccess 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.
Four methods of a wireless connection have been considered: Bluetooth (perhaps with CC2541), WiFi with ESP8266, a 868\,MHz long range link with SX1276, and a 2.4\,GHz link with nRF24L01+. Bluetooth was dismissed early for its complexity, and ESP8266 for its high consumption in continuous reception mode, although both solutions might be viable for certain applications and with more development time.
Four methods of a wireless connection have been considered: Bluetooth (perhaps with the Texas Instruments CC2541), WiFi with the Espressif ESP8266, a 868\,MHz long range radio link with the Semtech SX1276, and a 2.4\,GHz radio link with the nRF24L01+. Bluetooth was dismissed early for its complexity, and the ESP8266 for its high power consumption, although both solutions might be viable for certain applications and with more development time.
The Semtech SX1276~\cite{semtech-manual} and Nordic Semiconductor nRF24L01+ ~\cite{nrf-manual} transceivers have both been tested using the first GEX prototype, proving its usefulness as a hardware development tool, and it has been confirmed they could fulfill the requirements of our application.
\begin{figure}[h]
\begin{figure}[h]
\centering
\centering
@ -36,11 +34,13 @@ In \gls{OOK}, the carrier generator is switched on and off to transmit ones and
\subsection{LoRa Modulation}
\subsection{LoRa Modulation}
LoRa is a patented proprietary modulation developed by Semtech. It uses a direct sequence frequency hopping spread spectrum modulation and can achieve very long range transmission (over 10\,km is not uncommon). LoRa is available only with transceiver \glspl{IC} produced by Semtech and for this reason it is rather expensive.
LoRa uses a direct sequence frequency hopping spread spectrum modulation scheme and can achieve very long range transmission. A higher-level specification defines how the devices using LoRa should behave in a large area network, though the modulation may be used for point-to-point connections as well.
LoRa is a proprietary technology developed by Semtech; it is free to use, but is available only with transceiver \glspl{IC} produced by the company.
\section{Comparing SX1276 and nRF24L01+}
\section{Comparing SX1276 and nRF24L01+}
The two transceivers are compared in \cref{fig:nrf_sx_comparison}. It is apparent that each of them has its strengths and weaknesses, which will be discussed below.
The SX1276and nRF24L01+ transceivers have both been tested using the first GEX prototype, proving its usefulness as a hardware development tool, they proved capable of fulfilling the requirements of the GEX radio link use-case. We compared them in \cref{fig:nrf_sx_comparison} using data from their datasheets~\cite{semtech-manual,nrf-manual}. It is apparent, after inspecting the table, that each has its strengths and weaknesses and the choice depends on the particular application's needs.
\begin{table}[h]
\begin{table}[h]
\centering
\centering
@ -58,7 +58,7 @@ The two transceivers are compared in \cref{fig:nrf_sx_comparison}. It is apparen
@ -66,36 +66,40 @@ The two transceivers are compared in \cref{fig:nrf_sx_comparison}. It is apparen
\caption[Comparison of the SX1276 and nRF24L01+ wireless transceivers]{\label{fig:nrf_sx_comparison}Comparison of the SX1276 and nRF24L01+ wireless transceivers, using data from their datasheets (price in USD from DigiKey in a 10\,pcs. quantity, recorded on May 6th 2018)}
\caption[Comparison of the SX1276 and nRF24L01+ wireless transceivers]{\label{fig:nrf_sx_comparison}Comparison of the SX1276 and nRF24L01+ wireless transceivers, using data from their datasheets (price in USD from DigiKey in a 10\,pcs. quantity, recorded on May 6th 2018)}
\end{table}
\end{table}
SX1276 supports additional modulation modes, including a proprietary LoRa scheme with a frequency-hopping spread spectrum modulation that can be received at a distance up to 20\,km in ideal conditions. The long-range capability is reflected in a higher consumption during transmission. However, its consumption in receiver mode is slightly lower than that of the nRF24L01+.
The SX1276 supports additional modulation modes, including the proprietary LoRa scheme that can be received at long distances. The power consumption required to achieve this long-range communication makes it impractical for continuous operation on battery or solar power.
nRF24L01+ provides higher data rates at short distances. Its power consumption is comparable or lower than that of the SX1276. It lacks a dedicated reset pin, but that can be easily worked around using an external transistor to momentarily disconnect its Vdd pin.
Both devices implement some form of a packet engine with error checking; that of the nRF24L01+, called ShockBurst, is more advanced as it implements acknowledgment responses and automatic re-transmission, leading to a potentially more robust communication without an additional overhead on the side of the microcontroller.
The nRF24L01+ provides higher data rates at short distances. Its power consumption is comparable or lower than that of the SX1276. It lacks a dedicated reset pin, but that can be worked around using an external transistor to momentarily disconnect it from the power supply.
Both devices implement some form of a packet engine with error checking; that of the nRF24L01+, called ShockBurst, is more advanced, as it implements acknowledgment responses and automatic re-transmission, leading to potentially more robust communication without additional overhead in the control software.
\section{Integration of the nRF24L01+ into GEX}
The nRF24L01+ was selected to be integrated into GEX thanks to its inclusion of the ShockBurst engine, higher possible data rates and significantly lower price. The SX1276, nonetheless, remains an interesting option that could be used as an alternative in the future, should the need for a long range communication arise.
\section{Wireless Link with the nRF24L01+}
A separate device, the \textit{GEX wireless gateway}, was developed to provide the PC connection to a nRF24L01+ module. It is based on the STM32F103 microcontroller in its smallest package (LQFP48), selected for its low cost and good availability.
The nRF24L01+ was selected to be integrated into GEX thanks to its inclusion of the ShockBurst engine, higher possible data rates and significantly lower price. The SX1276, nonetheless, remains an interesting option, should the need for a long range communication arise.
\todo[inline]{TODO the above --remove/update/link to the hw chapter}
A pair of these radio modules can form a bidirectional data connection, functionally replacing \gls{USB} or \gls{UART} as a communication interface. However, we need to connect the second module to the \gls{PC} to control GEX through the radio link. A separate \gls{USB} device, a \textit{wireless gateway}, was developed for this purpose; its hardware will be presented in \cref{sec:rfgateway}.
\caption{A block diagram of the wireless connection}
\caption{A block diagram of the wireless connection}
\end{wrapfigure}
\end{wrapfigure}
The gateway presents itself to the host as a \gls{CDCACM} device, much like the GEX modules themselves (here called \textit{nodes}) when connected over \gls{USB}. It implements a simple protocol which encapsulates the binary data sent to or from a connected node. The wrapped GEX protocol, which is described in \cref{sec:tinyframe}, remains unchanged.
The gateway presents itself to the host as a \gls{CDCACM} device, much like the GEX modules themselves (here called \textit{nodes}) when connected over \gls{USB}. However, the standard GEX communication protocol cannot be used directly, as the gateway itself needs to be managed through the interface, and it can connect to more than one GEX module at once, necessitating an addressing scheme. This problem could be solved by adding a side channel, additional \gls{USB} endpoints, to interact with the gateway itself; that option was not explored further, but it is clear that it would compromise our ability to use the simple virtual COM port \gls{USB} driver.
The gateway has a 4-byte \textit{network ID}, a number derived from the \gls{MCU}'s unique ID number. The network ID must be entered into the system settings file of all nodes that wish to communicate with the gateway. Additionally, each module is assigned a 1-byte number serving as its address in the network. These addresses are loaded into the gateway by the user application, and are used to configure the nRF24L01+ to listen to messages from the corresponding nodes. The nRF24L01+ uses 5-byte addressing; the full node addresses are composed of the network ID and the one additional address byte.
The gateway has a 4-byte network ID, a number derived from the \gls{MCU}'s unique ID by calculating its 32-bit \gls{CRC}. The network ID must be entered into all nodes that wish to communicate with the gateway. Additionally, each module is assigned a 1-byte number which serves as its address in the network. The gateway can receive messages from up to 6 nodes.
The gateway protocol, when used to communicate with a node, encapsulates the raw binary data sent to or from connected nodes; the wrapped TinyFrame protocol remains unchanged.
All messages sent to or from the gateway are a multiple of 64 bytes long, padded with zeros if shorter. The message starts with a control byte determining its type, as summarized in the following table:
All messages sent to or from the gateway are a multiple of 64 bytes long, padded with zeros if shorter. A message starts with a control byte determining its type, as summarized in the following table listing the structure of all supported messages.
\newpage
{
{
\tabulinesep=5pt
\tabulinesep=5pt
\begin{longtabu} to \textwidth{P{5em} X[5] X[4,l]}
\begin{longtabu} to \textwidth{P{5em} X[5] X[4,l]}
@ -159,10 +163,10 @@ All messages sent to or from the gateway are a multiple of 64 bytes long, padded
A host program connecting to a node or nodes through the gateway should follow the following procedure to initialize and configure the gateway:
A host program connecting to a node or nodes through the gateway should follow the following procedure to initialize and configure the gateway:
\begin{enumerate}
\begin{enumerate}
\item Send the `GET\_NET\_ID' command to test if the gateway is connected (and obtain its network ID as a side effect)
\item Send the ``GET\_NET\_ID'' command to test if the gateway is connected (and obtain its network ID as a side effect)
\item Restart the gateway using the `RESTART' command to clean any possible previous configuration.
\item Restart the gateway using the ``RESTART'' command to clean any possible previous configuration; this is not needed when the gateway was restarted or freshly connected to the \gls{USB} port.
\item Add the node address(es) using `ADD\_NODES'
\item Add the node address(es) using the ``ADD\_NODES'' command.
\item Ping the connected node(s) via TinyFrame (passed through `SEND\_MSG' and `INCOMING\_MSG') to test if the connection works.
\item Ping the connected node(s) through the GEX communication protocol to test the connection. Note that GEX will not use the radio module if \gls{USB} is connected and enumerated, as it has lower priority.
