@ -11,7 +11,7 @@ This Discovery board is fitted with four \glspl{LED} on \gls{GPIO} pins PC6 thro
We advise the reader, as a potential user of this discovery board, to review its schematic diagram and ensure the solder-jumpers are configured correctly:
\begin{itemize}
\item Jumpers SB20 and SB23 must be closed to enable the User \gls{USB} connector
\item Jumpers SB20 and SB23 must be closed to enable the User \gls{USB} connector.
\item Jumper SB17 must be open and SB19 closed to use the 8\,MHz clock signal provided by the on-board ST-Link programmer; the internal USB-synchronized 48\,MHz oscillator will be used if the clock signal is not provided (SB19 open).
@ -50,7 +50,7 @@ The updated revision removes the two problematic footprints altogether; a reorga
\section{GEX Zero}
Our desire to re-use the form factor of the Raspberry Pi Zero to exploit the existing market with add-on boards and cases for it has been revealed already in \cref{sec:formfactors}. This was brought to fruition with GEX Zero, the second realized prototype board (counting the two revisions of GEX Hub as one).
Our desire to re-use the form factor of the Raspberry Pi Zero to exploit the existing market with add-on boards and cases for it has been mentioned already in \cref{sec:formfactors}. It was brought to fruition with GEX Zero, the second realized prototype board (counting the two revisions of GEX Hub as one).
GEX Zero exactly copies the dimensions of the Pi Zero, which introduces several challenges:
With the communication protocol clearly defined in \cref{sec:tinyframe,sec:units_overview}, respective\cref{sec:wireless} for the wireless gateway, the implementation of a client software is relatively straightforward. Two client libraries have been developed, in languages C and Python.
With the communication protocol clearly defined in \cref{sec:tinyframe,sec:units_overview}, and\cref{sec:wireless} for the wireless gateway, the implementation of client libraries is relatively straightforward. Two have been developed as a proof-of-concept, in languages C and Python.
\section{General Library Structure}
@ -26,7 +26,7 @@ The structure of a GEX client library is in all cases similar:
\section{Python Library}
The Python GEX library implements both a serial port access and a raw access to \gls{USB} endpoints. Its development has been prioritized over the C library because of its potential to integrate with MATLAB, and because it promises to be the most convenient method to interact with GEX thanks to the ease-of-use that comes with the Python syntax. This library provides a high level \gls{API} above the individual unit types, removing the burden of building and parsing of the binary command payloads from the user.
The Python GEX library implements both a serial port access and raw access to \gls{USB} endpoints. Its development has been prioritized over the C library because of its potential to integrate with MATLAB, and because it promises to be the most convenient method to interact with GEX thanks to the ease-of-use that comes with the Python syntax. This library provides a high level \gls{API} above the individual unit types, removing the burden of building and parsing of the binary command payloads from the user.
The library is composed of a \textit{transport} class, the core class \mono{gex.Client}, and unit classes (e.g., \mono{gex.I2C} or \mono{gex.SPI}).
@ -38,7 +38,7 @@ Three transport implementations have been developed:
\item\mono{gex.TrxSerialThread} -- virtual serial port access with a polling thread and semaphore-based notifications
\item\mono{gex.TrxRawUSB} -- similar to \mono{gex.TrxSerialThread}, but using a raw USB endpoint access
\item\mono{gex.TrxRawUSB} -- similar to \mono{gex.TrxSerialThread}, but using raw USB endpoint access
\end{itemize}
The wireless gateway is accessed by wrapping either of the transports in an instance of \mono{gex.DongleAdapter} before passing it to \mono{gex.Client}.
@ -80,11 +80,11 @@ An example Python program displaying a test pattern on a \gls{LED} matrix using
\caption[GEX Zero with the Micro Dot pHAT add-on board]{\label{fig:pydemo}GEX Zero with the Micro Dot pHAT add-on board, showing a test pattern defined in a Python script}
\end{figure}
First, a client instance is created, receiving the transport as an argument. We use a With block in the example to ensure the transport is safely closed before the program ends, even if that happens due to an exception; this is similar to the Try-Finally pattern in Java. The client (and subsequently the transport) can be closed manually by calling its \mono{.close()} method. Inside the With block, the script proceeds to create unit handles and use them to perform the desired task, in our case a communication with the \gls{LED} matrix driver over the \gls{I2C} bus.
First, a client instance is created, receiving the transport as an argument. We use a \mono{with} block in the example to ensure the transport is safely closed before the program ends, even if that happens due to an exception; this is similar to the \mono{try-finally} pattern, but the de-initialization is done automatically. The client (and subsequently the transport) can be closed manually by calling its \mono{.close()} method. Inside the \mono{with} block, the script proceeds to create unit handles and use them to perform the desired task, in our case a communication with the \gls{LED} matrix driver over the \gls{I2C} bus.
\section{MATLAB integration}
The Python library can be accessed from MATLAB scripts thanks to the MATLAB's two-way Python integration~\cite{matlabpy}. Controlling GEX from MATLAB may be useful when additional processing is required, e.g., with data from the \gls{ADC}; however, in many cases, an open source alternative native to Python exists that could be used for the same purpose, such as the NumPy and SciPy libraries~\cite{numpyscipy}.
The Python library can be accessed from MATLAB scripts thanks to MATLAB's two-way Python integration~\cite{matlabpy}. Controlling GEX from MATLAB may be useful when additional processing is required, e.g., with data from the \gls{ADC}; however, in many cases, an open source alternative native to Python exists that could be used for the same purpose, such as the NumPy and SciPy libraries~\cite{numpyscipy}.
The example in \cref{lst:matlab_api} demonstrates the use of MATLAB to calculate the frequency spectrum of an analog signal captured with GEX. The syntax needed to use the serial port transport (instead of a raw access to USB endpoints) is shown in a comment.
@ -119,9 +119,9 @@ The example in \cref{lst:matlab_api} demonstrates the use of MATLAB to calculate
\section{C Library}
The C library is more simplistic than the Python one; it supports only the serial port transport (\gls{UART} or \gls{CDCACM}) and does not implement asynchronous polling or the unit support drivers. What \textit{is} implement---the transport, a basic protocol handler, and payload building and parsing utilities---is sufficient for most applications, though less convenient than the Python library.
The C library is more simplistic than the Python one; it supports only the serial port transport (\gls{UART} or \gls{CDCACM}) and does not implement asynchronous polling or the unit support drivers. The implemented features---the transport, a basic protocol handler, and payload building and parsing utilities---are sufficient for most applications, though less convenient than the Python library.
This low-level library is intended for applications where the performance of the Python implementation is insufficient, or where an integration with existing C code is required. The full \gls{API} can be found in the library header files. A C version of the example Python script shown above, controlling a \gls{LED} matrix driver, is presented in \cref{lst:c_api_full}. Readers might point out that this example is unnecessarily obtuse, and that the payloads could be constructed in a more readable way. Indeed, two better methods of payload construction are available: one using C structs, and the other taking advantage of the Payload Builder utility bundled with TinyFrame, which is included in the library package.
This low-level library is intended for applications where the performance of the Python implementation is insufficient, or where an integration with existing C code is required. The full \gls{API} can be found in the library header files. A C version of the example Python script shown above, controlling an\gls{LED} matrix driver, is presented in \cref{lst:c_api_full}. Readers might point out that this example is unnecessarily obtuse, and that the payloads could be constructed in a more readable way. Indeed, two better methods of payload construction are available: one using C structs, and the other taking advantage of the Payload Builder utility bundled with TinyFrame, which is included in the library package.
\begin{listing}
\begin{ccode}
@ -211,7 +211,7 @@ The structure-based method utilizes C structs to access individual fields in the
The Payload Builder utility offers a flexible solution to the construction of arbitrary binary payloads. It is used in the GEX firmware to construct messages and events, along with the binary settings storage content.
An example of Payload Builder's usage is shown in \cref{lst:c_api_pb}. We give it a byte buffer and it then fills it with the payload values, taking care of buffer overflow and to advance the write pointer by the right number of bytes. The third parameter of \mono{pb\_init()} is optional, a pointer to a function called when the buffer overflows; this callback can flush the buffer and rewind it, or report an error.
An example of Payload Builder's usage is shown in \cref{lst:c_api_pb}. We give it a byte buffer and it then fills it with the payload values, taking care of buffer overflow, and advancing the write pointer by the right number of bytes. The third parameter of \mono{pb\_init()} is optional, a pointer to a function called when the buffer overflows; this callback can flush the buffer and rewind it, or report an error.
Payload Builder is accompanied by Payload Parser, a tool doing the exact opposite. While it is not needed in our example, we will find this utility useful when processing command responses or events payloads. The full API of those utilities can be found in their header files.
The digital input unit is the input counterpart of the digital output unit. In addition to reading the immediate digital levels of the selected pins, this unit can report asynchronous events on a pin change.
All pins of the unit may be configured either for a rising, falling, or any change detection; due to a hardware limitation, the same pin number may not be used for event detection on different ports (e.g., A1 and B1) at the same time. In order to receive a pin change event, we must arm the pin first, using a command; it can be armed for a single event, or it may be re-armed automatically with a hold-off time. It is, further, possible to automatically arm selected pins on start-up, removing the need to arm them, e.g., after the module restarts or is re-connected.
All pins of the unit may be configured either for a rising, falling, or for any change detection; due to a hardware limitation, the same pin number may not be used for event detection on different ports (e.g., A1 and B1) at the same time. In order to receive a pin change event, we must first arm the pin using a command; it can be armed for a single event, or it may be re-armed automatically with a hold-off time. It is further possible to automatically arm selected pins on start-up, removing the need to arm them, e.g., after the module restarts or is re-connected.
The NeoPixel unit implements the protocol needed to control a digital \gls{LED} strip with WS2812, WS2811, or compatible \gls{LED} driver chips. The NeoPixel protocol (explained in \cref{sec:theory_neo}) is implemented in software, therefore it is available on any \gls{GPIO} pin of the module.
The color data can be loaded in five different format: as packed bytes (3$\times$8 bits color), or as the little- or big-endian encoding of colors in a 32-bit format: 0x00RRGGBB or 0x00BBGGRR. The 32-bit format is convenient when the colors are already represented as an array of 32-bit integers, e.g., extracted from a screen capture or an image.
The color data can be loaded in five different formats: as packed bytes (3$\times$8 bits color), or as the little- or big-endian encoding of colors in a 32-bit format: 0x00RRGGBB or 0x00BBGGRR. The 32-bit format is convenient when the colors are already represented as an array of 32-bit integers, e.g., extracted from a screen capture or an image.
The shift registers driver unit is designed for the loading of data into serial-in/parallel-out (SIPO) shift registers, such as 74xx4094 or 74xx595. Those are commonly used to control segmented LED displays, LED user interfaces, etc.
The shift registers driver unit is designed for the loading of data into serial-in/parallel-out (SIPO) shift registers, such as 74xx4094 or 74xx595. These are commonly used to control segmented \gls{LED} displays, \gls{LED} user interfaces, etc.
Those devices may be daisy-chained: the output of one is connected to the input of another, sharing the same clock and other signals, and they work together as one longer shift register.
\noindent
A SIPO shift register has the following digital pins:
A SIPO shift register has the following pins (possibly named differently with chips from different vendors):
\begin{itemize}
\begin{itemize}[itemsep=0pt]
\item\textit{Shift} -- \gls{SCK}; shifts the data in the register by one bit
\item\textit{Data In} -- \gls{MOSI}; serial data to load into the register
\item\textit{Data Out} -- output for daisy-chaining with other shift registers
\item\textit{Store} -- latches the current register data and shows it on the output
\item\textit{Store} -- latches the current register data and shows it at the outputs
\item\textit{Clear} -- erases the latched data and clears the display
\end{itemize}
@ -43,7 +42,7 @@ The WRITE and CLEAR\_DIRECT commands are the only ones normally used. The others
\begin{cmdlist}
0 &\cname{WRITE}
Load the shift registers and leave the data outputs in the ``trailing data'' state before sending the\textit{Store} pulse.
Load the shift registers and leave the \textit{Data} outputs in the ``trailing data'' state before sending a\textit{Store} pulse.
&
\begin{cmdreq}
\cfield{u16} trailing data (packed pins)
@ -55,7 +54,7 @@ The WRITE and CLEAR\_DIRECT commands are the only ones normally used. The others
