\chapter{Units Overview, Commands and Events Description} \label{sec:units_overview}

This chapter describes all functional blocks (units) implemented in GEX, version 1.0. The term ``unit'' will be used here to refer to both unit types (drivers) or their instances where the distinction is not important.

Each unit's description will be accompanied by a corresponding snippet from the configuration file, and a list of supported commands and events. The commands and events described here form the payload of TinyFrame messages \CmdUnitRequest and \CmdUnitReport, as described in \cref{sec:unit_requests_reports}.

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 type \CmdSuccess response after the command is finished.

\section{General Notes}

\subsection{Unit Naming}

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''.

\subsection{Packed Pin Access} \label{sec:packedpins}

Several units facilitate an access to a group of GPIO pins, such as the digital input and output units, or the SPI unit's slave select pins. The STM32 microcontroller's ports have 16 pins each, most of which can be configured to one of several alternative functions (e.g., SPI, PWM outputs, ADC input). As a consequence, it is common to be left with a discontiguous group of pins after assigning all the alternative functions needed by an application.

\begin{figure}[h]
	\centering
	\includegraphics[scale=1] {img/pin-packing.pdf}
	\caption{\label{fig:pin_packing}Pin packing}
\end{figure}

For instance, we could only have the pins 0, 1, 12--15 available on a \gls{GPIO} port. GEX provides a helpful abstraction to bridge the gaps in the port: The selected pins are packed together and represented, in commands and events, as a block of six pins (0x3F) instead of their original positions in the register (0xF003). This scheme is shown in \cref{fig:pin_packing}. The translation is done in the unit driver and works transparently, as if the block of pins had no gaps---all the referenced pins are updated simultaneously without glitches. Where pin numbers are used, the order in the packed word should be provided---in our example, that would be 0--5, counting from the least significant bit.

% here are the unit sections, all following a common pattern
\input{ch.unit.do}
\input{ch.unit.di}
\input{ch.unit.sipo}
\input{ch.unit.npx}
\input{ch.unit.spi}
\input{ch.unit.i2c}
\input{ch.unit.usart}
\input{ch.unit.1wire}
\input{ch.unit.fcap}
\input{ch.unit.adc}
\input{ch.unit.dac}
\input{ch.unit.pwmdim}
\input{ch.unit.touch}





