more units described ...............

ch.gex_units.tex

@@ -2,7 +2,8 @@
 
 This chapter describes all functional blocks (units) implemented in GEX at the time of publication of this work. Each unit supports a different set of binary commands and events. The term "unit" will be used 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.
+Each unit's description will be accompanied by a corresponding snippet from the configuration file, and a list of supported commands and events. When the command's request payload is empty, it's 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 if the command succeeds.
+
 
 \section{Naming Conventions and Common Principles}
 
@@ -23,6 +24,7 @@ Several units facilitate an access to a group of GPIO pins, such as the digital
 For instance, we could only have the pins 0, 1, 12--15 available on a 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 figure \ref{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}

ch.unit.di.tex

@@ -1,7 +1,78 @@
-\section{Digital Input Unit}
+\section{DI: Digital Input}
 
 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 generate asynchronous events on a pin change. The state of the entire input port, together with a microsecond timestamp (as is the case for all asynchronous events), is reported to the host either on a rising, falling, or any pin change. 
 
 The pin change event can be configured independently for each pin. In order to receive a pin change event, it must be armed first; The pin can be armed for a single event, or it may be re-armed automatically with a hold-off time. It's further possible to automatically arm selected pin triggers on start-up.
+
+
+\subsection{DI Configuration}
+
+\begin{inicode}
+	[DI:in@2]	
+	# Port name
+	port=A
+	# Pins (comma separated, supports ranges)
+	pins=0
+	# Pins with pull-up
+	pull-up=
+	# Pins with pull-down
+	pull-down=
+	
+	# Trigger pins activated by rising/falling edge
+	trig-rise=
+	trig-fall=
+	# Trigger pins auto-armed by default
+	auto-trigger=
+	# Triggers hold-off time (ms)
+	hold-off=100
+\end{inicode}
+
+\subsection{DI Events}
+
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
+	\toprule
+	\textbf{Code} & \textbf{Name} & \textbf{Meaning} & \textbf{Payload}  \\	
+	\midrule	
+	
+	0x00 & PIN\_CHANGE & A pin change event. The payload includes a snapshot of all configured pins captured immediately after the change was registered.
+	& \makecell[tl]{
+		\fld{u16} changed pins \\
+		\fld{u16} port snapshot
+	} \\	
+	\bottomrule
+\end{tabularx}
+
+\subsection{DI Commands}
+
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
+	\toprule
+	\textbf{Code} & \textbf{Name} & \textbf{Function} & \textbf{Payload}  \\	
+	\midrule	
+	
+	0x00 & READ & Read the pins
+	& \makecell[tl]{
+		\fldresp
+		\fld{u16} pin states
+	} \\
+
+	0x01 & ARM\_SINGLE & Arm for a single event
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} pins to arm
+	} \\
+
+	0x02 & ARM\_AUTO & Arm with automatic re-arming after each event
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} pins to arm
+	} \\
+
+	0x03 & DISARM & Dis-arm selected pins
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} pins to dis-arm
+	} \\
+	\bottomrule
+\end{tabularx}

ch.unit.do.tex

@@ -16,36 +16,44 @@ initial=
 open-drain=
 \end{inicode}
 
+\subsection{DO Events}
+
+This unit generates no events.
 
 \subsection{DO Commands}
 
-\begin{tabularx}{\textwidth}{p{2.2em} l X p{.38\textwidth}}
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
 	\toprule
 	\textbf{Code} & \textbf{Name} & \textbf{Function} & \textbf{Payload}  \\	
 	\midrule	
 	
 	0x00 & WRITE & Write to all pins 
 	& \makecell[tl]{
+		\fldreq
 		\fld{u16} new value
 	} \\
 	
 	0x01 & SET & Set selected pins to 1 
 	& \makecell[tl]{
+		\fldreq
 		\fld{u16} pins to set
 	} \\
 	
 	0x02 & CLEAR & Set selected pins to 0 
 	& \makecell[tl]{
+		\fldreq
 		\fld{u16} pins to clear
 	} \\
 
 	0x03 & TOGGLE & Toggle selected pins 
 	& \makecell[tl]{
+		\fldreq
 		\fld{u16} pins to toggle
 	} \\
 
 	0x04 & PULSE & Generate a pulse on the selected pins. The $\mu$s scale may be used only for 0--999\,$\mu$s.
 	& \makecell[tl]{
+		\fldreq
 		\fld{u16} pins to pulse \\
 		\fld{u8} active level (0, 1) \\
 		\fld{u8} scale: 0-ms, 1-$\mu$s \\

ch.unit.i2c.tex

@@ -1,5 +1,78 @@
+\section{I2C Unit}
+
+The I2C unit provides access to one of the microcontroller's I2C peripherals. It can be configured to use either of the three speeds (Standard, Fast and Fast+) and supports both 10-bit and 7-bit addressing. 10-bit addresses can be used in commands by setting their highest bit (0x8000), as a flag to the unit. 
+
+\subsection{I2C Configuration}
+
+\begin{inicode}
+[I2C:d@4]
+# Peripheral number (I2Cx)
+device=1
+# Pin mappings (SCL,SDA)
+#  I2C1: (0) B6,B7    (1) B8,B9
+#  I2C2: (0) B10,B11  (1) B13,B14
+remap=0
+
+# Speed: 1-Standard, 2-Fast, 3-Fast+
+speed=1
+# Analog noise filter enable (Y,N)
+analog-filter=Y
+# Digital noise filter bandwidth (0-15)
+digital-filter=0
+\end{inicode}
+
+\subsection{I2C Events}
+
+This unit generates no events.
+
+\subsection{I2C Commands}
+
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
+	\toprule
+	\textbf{Code} & \textbf{Name} & \textbf{Function} & \textbf{Payload}  \\	
+	\midrule	
+	
+	0x00 & WRITE & Raw write transaction
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} slave address \\
+		\fld{u8[]} bytes to write \\	
+	} \\
+
+	0x01 & READ & Raw read transaction
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} slave address \\
+		\fld{u16} number of read bytes \\
+		\fldresp
+		\fld{u8[]} received bytes \\	
+	} \\
+	
+	0x02 & WRITE\_REG & Write to a slave register. Sends the register number and the data in the same I2C transaction. Multiple registers can be written to slaves supporting auto-increment.
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} slave address \\
+		\fld{u8} register number \\
+		\fld{u8[]} bytes to write \\	
+	} \\
+	
+	0x03 & READ\_REG & Read from a slave register. Writes the register number and issues a read transaction of the given length. Multiple registers can be read from slaves supporting auto-increment.
+	& \makecell[tl]{
+		\fld{u16} slave address \\
+		\fld{u8} register number \\
+		\fld{u16} number of read bytes \\
+		\fldresp
+		\fld{u8[]} received bytes \\	
+	} \\
+
+	\bottomrule
+\end{tabularx}
+
+
+
+
+
+
 
 
-\section{I2C Unit}
 
-The I2C unit provides access to one of the microcontroller's I2C peripherals. It can be configured to use either of the three speeds (Standard, Fast and Fast+) and supports both 10-bit and 8-bit addressing.

ch.unit.npx.tex

@@ -1,6 +1,71 @@
+\section{NPX: NeoPixel}
 
+The NeoPixel unit implements the protocol needed to control a digital LED strip with WS2812, WS2811, or compatible LED driver chips. The protocol timing is implemented in software, therefore it is available on any GPIO pin of the module.
+
+The color data can be loaded in five different format: as packed bytes, or as the little-endian or big-endian encoding of colors in the 32-bit format 0x00RRGGBB or 0x00BBGGRR. This data format is convenient when the colors are already represented by an array of 32-bit integers.
+
+\subsection{NPX Configuration}
+
+\begin{inicode}
+[NPX:neo@3]
+# Data pin
+pin=A0
+# Number of pixels
+pixels=32
+\end{inicode}
+
+\subsection{NPX Events}
+
+This unit generates no events.
+
+\subsection{NPX Commands}
+
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
+	\toprule
+	\textbf{Code} & \textbf{Name} & \textbf{Function} & \textbf{Payload}  \\	
+	\midrule	
+	
+	0x00 & CLEAR & Switch all LEDs off (sets them to black) & \\
+	0x01 & LOAD & Load a sequence of R,G,B bytes
+	& \makecell[tl]{
+		\fldreq
+		\tabitem For each LED: \\
+		~~\fldo{u8} red \\
+		~~\fldo{u8} green \\
+		~~\fldo{u8} blue \\
+	} \\
+
+	0x08 & LOAD\_U32\_ZRGB & Load 32-bit big-endian 0xRRGGBB (0,R,G,B)
+	& \makecell[tl]{
+		\fldreq
+		\fld{u32[]} color data BE
+	} \\
+
+	0x09 & LOAD\_U32\_ZBGR & Load 32-bit big-endian 0xBBGGRR (0,B,G,R)
+	& \makecell[tl]{
+		\fldreq
+		\fld{u32[]} color data BE
+	} \\
+
+	0x0A & LOAD\_U32\_RGBZ & Load 32-bit little-endian 0xBBGGRR (R,G,B,0)
+	& \makecell[tl]{
+		\fldreq
+		\fld{u32[]} color data LE
+	} \\
+
+	0x0B & LOAD\_U32\_BGRZ & Load 32-bit little-endian 0xRRGGBB (B,G,R,0)
+	& \makecell[tl]{
+		\fldreq
+		\fld{u32[]} color data LE
+	} \\
+
+	0x10 & GET\_LEN & Get number of LEDs in the strip
+	& \makecell[tl]{
+		\fldresp
+		\fld{u16} number of LEDs
+	} \\
+	\bottomrule
+\end{tabularx}
 
-\section{NeoPixel Unit}
 
-The NeoPixel unit implements the protocol needed to control a digital LED strip with WS2812, WS2811, or compatible LED driver chips. The protocol timing is implemented in software, therefore it is available on any GPIO pin of the module. The unit accepts sequences of RGB color values from the host and loads them into the LED strip.
 

ch.unit.sipo.tex

@@ -1,5 +1,58 @@
-\section{Shift Registers Driver Unit}
+\section{SIPO: Shift Registers Driver}
 
 The shift registers driver unit is designed for the loading of data into \textit{serial-in, parallel-out} (SIPO) shift registers, such as 74HC4094 or 74HC595. Those are commonly used to control segmented LED displays, LED matrices etc.
 
 This unit handles both the \textit{Shift} and \textit{Store} signals and is capable of loading multiple shift registers simultaneously, reducing visible glitches in the display. It's also possible to set the data lines to arbitrary level(s) before sending the Store pulse, which can be latched and used for some additional feature of the LED display, such as brightness control.
+
+
+\subsection{SIPO Configuration}
+
+\begin{inicode}
+[SIPO:display@9]
+# Shift pin & its active edge (1-rising,0-falling)
+shift-pin=A1
+shift-pol=1
+# Store pin & its active edge
+store-pin=A0
+store-pol=1
+# Clear pin & its active level
+clear-pin=A2
+clear-pol=0
+# Data port and pins
+data-port=A
+data-pins=3
+\end{inicode}
+
+\subsection{SIPO Events}
+
+This unit generates no events.
+
+\subsection{SIPO Commands}
+
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
+	\toprule
+	\textbf{Code} & \textbf{Name} & \textbf{Function} & \textbf{Payload}  \\	
+	\midrule	
+	
+	0x00 & WRITE & Load the shift registers and leave the data outputs in the "trailing data" state before sending the Store pulse.
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} trailing data \\
+		\tabitem For each output: \\
+		~~\fldo{u8[]} data to load
+	} \\
+	
+	0x01 & DIRECT\_DATA & Directly write to the data pins (same like the DO unit's WRITE command)
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} values to write
+	} \\
+
+	0x02 & DIRECT\_CLEAR & Pulse the Clear pin, erasing the registers' data & \\
+	0x03 & DIRECT\_SHIFT & Pulse the Shift pin & \\
+	0x04 & DIRECT\_STORE & Pulse the Store pin & \\
+	\bottomrule
+\end{tabularx}
+
+
+

ch.unit.spi.tex

@@ -1,7 +1,85 @@
 \section{SPI Unit}
 
-The SPI unit provides access to one of the microcontroller's SPI peripherals. It can be configured to use any of the different speeds, clock polarity and phase settings available in its control registers. The unit handles up to 16 slave select (NSS) signals.
+The SPI unit provides access to one of the microcontroller's SPI peripherals. It can be configured to use any of the different speeds, clock polarity and phase settings available in its control registers. 
+
+The unit handles up to 16 slave select (NSS) signals and supports message multi-cast (addressing more than one slaves at once). Protection resistors should be used if a multi-cast transaction is issued with MISO connected.
+
+The QUERY command of this unit, illustrated by figure \ref{fig:spi_query}, is flexible enough to support all types of SPI transactions: read-only, write-only, and read-write with different request and response lengths. The slave select pin is held low during the entire transaction.
+
+\begin{figure}[h]
+	\centering
+	\includegraphics[scale=1.1] {img/spi-query.pdf}
+	\caption{\label{fig:spi_query}SPI transaction using the QUERY command}
+\end{figure}
+
+\subsection{SPI Configuration}
+
+\begin{inicode}
+[SPI:spi@5]
+# Peripheral number (SPIx)
+device=1
+# Pin mappings (SCK,MISO,MOSI)
+#  SPI1: (0) A5,A6,A7     (1) B3,B4,B5
+#  SPI2: (0) B13,B14,B15
+remap=0
+# Prescaller: 2,4,8,...,256
+prescaller=64
+# Clock polarity: 0,1 (clock idle level)
+cpol=0
+# Clock phase: 0,1 (active edge, 0-first, 1-second)
+cpha=0
+# Transmit only, disable MISO
+tx-only=N
+# Bit order (LSB or MSB first)
+first-bit=MSB
+# SS port name
+port=A
+# SS pins (comma separated, supports ranges)
+pins=0
+\end{inicode}
+
+\subsection{SPI Events}
+
+This unit generates no events.
+
+\subsection{SPI Commands}
+
+\begin{tabularx}{\textwidth}{p{\fldwcode}lXp{\fldwpld}}
+	\toprule
+	\textbf{Code} & \textbf{Name} & \textbf{Function} & \textbf{Payload}  \\	
+	\midrule	
+	
+	0x00 & QUERY & Exchange bytes with a slave device
+	& \makecell[tl]{
+		\fldreq
+		\fld{u8} slave number 0--16 \\
+		\fld{u16} response padding \\
+		\fld{u16} response length \\
+		\fld{u8[]} bytes to write \\
+		\fldresp
+		\fld{u8[]} received bytes \\		
+	} \\
+	
+	0x01 & MULTICAST & Send a message to multiple slaves at once. The address is a bit map (e.g. 0x8002 = slaves 1 and 15).
+	& \makecell[tl]{
+		\fldreq
+		\fld{u16} addressed slaves \\
+		\fld{u8[]} bytes to write
+	} \\
+	\bottomrule
+\end{tabularx}
+
+
+
+
+
+
+
+
+
+
+
+
+
 
-Both write-only and read-write (query) transactions are implemented.
 
-\todo[inline]{Query diagram}

ch.unit.usart.tex

@@ -1,6 +1,14 @@
-
 \section{USART Unit}
 
 The USART unit provides access to one of the microcontroller's USART peripherals. All USART parameters can be configured to match the application's needs. 
 
 The clock output and hardware flow control may be enabled, as well as the Driver Enable (DE) output used by RS485 transceivers to switch between a reception and transmission mode.
+
+
+
+
+
+
+
+
+

document_config.tex

@@ -26,8 +26,14 @@
 
 \newminted{ini}{frame=leftline,autogobble=true}
 \newcommand{\tabitem}{~~\llap{\textbullet}~~}
-
+\newcommand{\tabitemo}{~~\llap{\textopenbullet}~~}
 \newcommand\fld[1]{\tabitem \verb|#1|:}
+\newcommand\fldo[1]{\tabitemo \verb|#1|:}
+\newcommand{\fldwcode}{2.2em}
+\newcommand{\fldwpld}{.32\textwidth}
+
+\newcommand{\fldreq}{\textit{Request}\\}
+\newcommand{\fldresp}{\textit{Response}\\}
 
 
 \newcommand{\uF}{\micro\farad}
@@ -39,7 +45,6 @@
 %\usepackage{lmodern}
 %\usepackage{cfr-lm}
 
-
 \usepackage[style=numeric,backend=biber,sorting=none]{biblatex}
 
 \usepackage{xpatch,letltxmacro}