progress

ch.introduction.tex

@@ -1,12 +1,12 @@
 \chapter{Introduction}
 
-Prototyping, design evaluation and the measurement of physical properties in experiments make a daily occurrence in the engineering praxis. This task involves the generation and capture of electrical signals coming to and from specialized sensors, actuators and other circuitry. As the technology advanced, driven by the consumer electronics market in the pursuit of miniaturization and lower cost, a multitude of integrated sensors with digital interfaces became available. Those devices can provide a sufficient accuracy and precision for the task at hand while keeping the circuit complexity down by integrating a large portion of the necessary circuit, often including the sensor itself, on a single chip or in a compact module.
+Prototyping, design evaluation and the measurement of physical properties in experiments make a daily occurrence in the engineering praxis. This task typically involves the generation and capture of electrical signals coming to and from specialized sensors, actuators and other circuitry. As the technology advanced, mainly driven by the consumer electronics market and the automotive industry, a variety of affordable integrated sensors became available. Those devices can provide a sufficient accuracy and precision for the task at hand while keeping the circuit complexity down by integrating a large portion of the necessary circuitry together with the sensor on a single chip or in a compact module. Those modern components gives as a low cost alternative to expensive laboratory equipment and much larger instruments previously used.\todo{concrete examples}
 
-The drive for miniaturization and the advent of modern hardware buses, in particular USB (Universal Serial Bus), however, simultaneously lead to the disappearance of low level computer ports, such as the once ubiquitous parallel port, that would provide an easy way of connecting those digital devices and low level hardware in general to personal computers.
+However, the drive for miniaturization and the advent of modern hardware buses, in particular USB (Universal Serial Bus), lead to the disappearance of low level computer ports, such as the once ubiquitous parallel port, that would provide an easy way of connecting those digital devices (and low level hardware in general) to personal computers. 
 
-With those developments, we on the one hand have an easy access to interesting integrated devices that would make the mentioned experiments and evaluations easier, on the other, our means of interfacing them have become more complicated. When an engineer today wants to perform some measurements using a digital sensor, they are often left having to implement an embedded firmware for a microcontroller that can be connected to the PC through USB, commonly through a USB-USART adapter. This approach lets one optimize the solution for a particular task and possibly achieve higher performance, however it is time-consuming and requires knowledge of the embedded system design that is entirely removed from the desired measurement.
+Today, when one wants to perform some measurements using a digital sensor, the usual route is to implement an embedded firmware for a microcontroller that can be connected to the PC through USB. This approach makes it possible to optimize the solution for a particular task and achieve high performance. However, building such a specialized tool, or even writing the firmware alone, is time-consuming and requires domain knowledge that is entirely removed from the measurements we want to perform with it.
 
-Clearly it would be advantageous to have a way to easily attach those integrated devices and low level hardware in general to a PC without having to burden ourselves with technicalities of the connection. The design and implementation of such a system is the object of this work.
+Clearly it would be advantageous to have a way to easily attach those integrated devices and low other level hardware to a PC without having to burden ourselves with technicalities of the connection, even at the cost of lower performance compared to a specialized device or a professional tool. The design and implementation of such a user-friendly, general purpose hardware interfacing system is the object of this work.
 
 
 

ch.requirements.tex

@@ -1,51 +1,64 @@
 \chapter{Goals and Requirements}
 
-This chapter analyzes the project requirements and presents a vision of the final outcome.
+This chapter discusses the project requirements and presents our expectations of the final outcome.
+
+The work's main objective is the implementation of a reconfigurable embedded firmware, a physical module providing the required digital buses, signal generation and acquisition capabilities, and the PC libraries to work with it. It's expected that several prototypes of the hardware platform will be developed to evaluate different form factors.
 
 \section{Project Name}
 
-Referring to the project only as "the project" or "the device" would be clumsy and lead to confusion. Henceforth, the project should be known as \textbf{GEX}, an acronym originating in the term \textit{GPIO Expander}, which, although not describing its scope perfectly, alludes to the project's primary purpose of providing low level GPIO capabilities to personal computers.
+Every project needs a memorable name. During the development, the name "GEX" was chosen, an acronym originating in the term \textit{GPIO Expander}, which, although not describing its scope perfectly, alludes to the project's primary purpose of providing low level GPIO capabilities to personal computers. The term GEX may be used through the text to refer to the whole project or hardware modules developed for it.
 
 \section{Expected Use-Cases}
 
-A first step must necessarily be to consider the situations in which the device is expected to be useful. As was mentioned in the introduction, one of the problems addressed is making it possible to easily attach electronic circuits and components to a PC. This could be in order to familiarize oneself with a new chip or a module, to measure a characteristic curve of a component, to collect experimental data from a test setup, or, for instance, to control a positioning motor.
+First, we must consider in which situations the module could be helpful. As we explained in the introduction, GEX should allow the user to connect digital sensors and electronic circuits to a PC and work with them using high level application software.
+
+This could be used to get familiar with a new chip or a module before using it in some hardware project, to measure characteristic curves of a component, to collect experimental data from a test setup, or, for instance, to control a positioning motor.
 
-The applications can have a temporary character, a simple setup that is used once and then dismantled, or a more permanent one. An example of the latter could be laboratory tasks where the measurement framework and user interface is prepared beforehand and connecting the circuit or simply performing measurements while varying some physical properties is left as an exercise to students. Another example could be the use of GEX as a data acquisition module, replacing more expensive professional devices.
+The applications can have a temporary character, a simple setup that is used once and then dismantled, or a more permanent one. An example of the latter could be students' laboratory tasks where the measurement setup is prepared beforehand by an instructor. Another example could be the use of GEX as a data acquisition module for process or environment monitoring.
 
-As such, the device must be easy to configure without having to modify the embedded firmware and should provide the hardware interfaces and functions that are be needed for such applications. The module can be either attached directly to a PC via USB or controlled wirelessly. It would also be possible to design it as a PCI Express card, however that would limit its use to desktop computers and make the installation and software support more complicated. The wireless connection will find use in mobile robotic projects, when installed in less accessible places, or outdoors.
+The module should either be directly attached to the PC via a USB port, or controlled wirelessly (possibly powered by a battery or a solar cell). A wireless connection can find use in mobile robotic projects where the wired attachment isn't practical, or when used outdoors or in hardly accessible places.
 
-\section{Hardware Interfaces to Implement}
+\section{Supported Hardware Interfaces}
 
-Given the project's broad range of potential applications, predicting precisely what hardware interfaces and connections might be needed is hardly possible. A good approach appears to be to implement the most common protocols and interfaces and provide access to selected low level features offered by the used microcontroller, like timers and direct pin access, while keeping the firmware open to future expansions should the need arise.
+The project's scope is very broad and it's hardly possible to enumerate all the use cases. To achieve the greatest flexibility, it appears as a good strategy to divide the features into smaller functional blocks that can be used independently or combined as needed.
 
 \subsection{Direct Digital Input/Output}
 
-The most basic form of interaction with hardware is by changing the logic levels of output pins and reading input pins. With this feature alone it would be possible to analyze logic circuits, trigger some transient effect we want to observe using an oscilloscope, read a contact state, sense a button push, drive LED displays and more. Almost anything digital that doesn't require precise or fast timing could be achieved by this simple function.
+The most basic interaction with hardware is simply changing the logic levels of output pins, and reading input pins. With this feature alone it would be possible to analyze logic circuits, trigger some transient effect we want to observe using an oscilloscope, sense a button push, drive LED displays and more. Almost anything digital that doesn't require precise or fast timing\footnote{We're limited by the latencies of USB and the PC software.} could be achieved by this simple function.
 
 To make this feature more versatile, it should be possible to receive an asynchronous event on a pin state change, avoiding the need for polling loops in the control application.
 
 \subsection{Common Digital Buses}
 
-A popular way to attach peripheral devices to a microcontroller are hardware buses, the most well known of which are SPI (\textit{Serial Peripheral Interface}), I$^2$C (or IIC, \textit{Inter-Integrated-Circuit}) and USART (\textit{Universal Synchronous Asynchronous Receiver Transmitter}), in the asynchronous variant referred to as UART. A large majority of peripheral integrated circuits, digital-interface sensors and modules can be accessed using those buses. They also have hardware support in most microcontrollers, removing the burden of precise timing from the firmware.
+A popular way to attach peripheral devices to a microcontroller are hardware buses, the most well known of which are SPI (\textit{Serial Peripheral Interface}), I$^2$C (or IIC, \textit{Inter-Integrated-Circuit}) and USART (\textit{Universal Synchronous Asynchronous Receiver Transmitter}). There is a hardware support in most microcontrollers for those buses, removing the burden of precise timing from the firmware.
 
-Another hardware interface that might fall into this category is I$^2$S (or IIS, \textit{Inter IC Sound}). I$^2$S is used for streaming sampled audio streams or analog samples and finds far less use than the previously mentioned buses.
-
-More information about those interfaces (excluding I$^2$S) can be found in later chapters. \todo{link to actual place}
+More information about those interfaces can be found in later chapters. \todo{link to actual place}
 
 \subsection{Specialized Buses}
 
-Some devices exist that do not use any of the common buses, instead requiring their own proprietary protocol. An example of this group is the Dallas Semiconductor\footnote{Acquired by Maxim Integrated in 2001}\todo{source} 1-Wire bus, used by the popular DS18x20 digital thermometers. Another example might be some types of addressable LED strips.
+Some devices exist that use their own proprietary protocol, usually to reduce the number of data pins. An example of this group is the Dallas Semiconductor\footnote{Acquired by Maxim Integrated in 2001} 1-Wire bus, used by the popular DS18x20 digital thermometers. Another such protocol is used by some types of addressable LED strips.
 
-A common characteristic of those buses is that they require precise timing and have no native hardware support like the above mentioned common buses. This means that we can't depend on the direct GPIO access and have to implement low level driver utilities to achieve reliable communication.
+A common characteristic of those buses is that they require precise timing and have no native hardware support in the microcontroller. We can't use the direct GPIO access here due to latencies and jitter; those protocols need a custom low level routine in the firmware that performs such "bit banging" more accurately.
 
 \subsection{Analog Input/Output}
 
-Microcontrollers typically include an ADC (\textit{Analog to Digital Converter}) with a 10-12 bits of resolution, sometimes accompanied by a DAC (\textit{Digital to Analog Converter}), its output counterpart. In the lack of a real DAC, the analog output, albeit with worse dynamic parameters, can be realized using a PWM signal (\textit{Pulse Width Modulation}, pulse train) followed by a low-pass filter.
+Microcontrollers typically include a 10-12 bit ADC (\textit{Analog to Digital Converter}), often accompanied by a DAC (\textit{Digital to Analog Converter}), its output counterpart. In the lack of a real DAC, the analog output, albeit with worse dynamic parameters, can be realized using a PWM signal (\textit{Pulse Width Modulation}, pulse train) followed by a low-pass filter.
+
+While we mainly focused on digital interfaces thus far, providing means of generating and capturing analog signals is also valuable. This capability makes it possible to read sensors with voltage output and it can substitute a simple oscilloscope when sampled periodically at a sufficient speed. 
+
+The analog output and input together can be used for automated characterization of electronic components, or for analog feedback regulation. Should the analog output be modulated, we could further use them to measure frequency-dependent characteristics, such as the frequency response of analog filters.
+
+\subsection{Frequency Measurement and Generation}
+
+Some sensors have a variable frequency or a pulse-width modulated (PWM) output. To capture those signals and convert them to a more useful digital value, we can use the Input Capture or External Clock function of a general purpose timer/counter in the used microcontroller. Those timers have a wide range of possible configurations and can be also used for pulse counting or PWM generation.
 
-While we mainly focused on digital interfaces thus far, providing means of generating and capturing analog signals is also valuable. This capability makes it possible to read sensors with voltage output and it can substitute a simple oscilloscope when sampled periodically at a sufficient frequency. Analog input channels, even with lower resolution or sample rate, may in some cases avoid the need for a dedicated acquisition device.
+\section{User Interface}
 
-In conjunction, the analog output and input can be used for automated characterization of electronic components, such as diodes. Should the analog output be modulated, we could further use them to measure frequency-dependent characteristics, such as the frequency response of analog filters.
+USB will be the primary way of connecting the module to a PC. Thanks to USB's flexibility, GEX can present itself to the computer as any kind of device, or even multiple devices at once. 
 
+The most straightforward method of interfacing the board is by passing binary messages in a fashion similar to USART. This can be done either using a "Virtual COM port" driver (the CDC/ACM class), or through a raw access to the corresponding USB endpoints. Using a raw access avoids potential problems with the operating system's driver interfering or not recognizing the device correctly; on the other hand, having GEX appear as a serial port makes it easier to integrate into older development platforms that have a good serial port support (such as National Instruments LabWindows CVI).
 
+As for configuring the module, given the possible permanent nature of the experimental setups built with it, it makes sense to store the settings inside its flash memory; it should at the same time be possible to temporarily change them as needed. 
 
+We could load those settings using the serial interface, and indeed this should be implemented for its flexibility. The serial interface will be, in some form, also used for the wireless connection. However, having the power of USB at our disposal, we can make the board appear as a mass storage device and expose the configuration as text files. This approach, inspired by ARM mbed\footnote{A similar mechanism is used for flashing firmware images to mbed-enabled development kits}, avoids the need to create a configuration utility and can work cross-platform thanks to using the same driver as a real removable disk. Further, we can expose any useful information (such as a README file with instructions, or a pin-out reference) using this virtual disk as separate files.
 

ch.usb.tex

@@ -0,0 +1,99 @@
+\chapter{Universal Serial Bus}
+
+This chapter presents an overview of the USB Full Speed interface, with focus on the features used in the GEX firmware. USB is a versatile but complex interface, thus explaining it in its entirety is beyond the scope of this text. References to external materials which explain the protocol in greater detail will be provided for the interested reader.\todo{add those refs}
+
+\section{Basic Principles and Terminology}
+
+USB is a hierarchical bus with a single master (\textit{host}) and multiple slave devices. A USB device that provides functionality to the host is called a \textit{function}. Communication between the host and a function is organized into virtual channels called \textit{pipes}. Each pipe is identified by an \textit{endpoint} number. 
+
+Endpoints can be either unidirectional or bidirectional; the direction from the host to a function is called \textit{OUT}, the other direction (function the host) is called IN. A bidirectional endpoint is technically composed of a IN and OUT endpoint with the same number. All transactions (both IN and OUT) are initiated by the host; functions have to wait for their turn. Endpoint 0 is bidirectional, always enabled, and serves as a \textit{control endpoint}. The host uses the control endpoint to read information about the device and configure it as needed.
+
+There are four types of transfers: control, bulk, isochronous, and interrupt. Each endpoint is configured for a fixed transfer type. 
+
+\begin{itemize}
+	\item \textit{Control} - initial configuration after device plug-in; also used for other aplication-specific control messages that can affect other pipes.
+	\item \textit{Bulk} - used for burst transfers of large messages, commonly e.g. for mass storage devices
+	\item \textit{Isochronous} - streaming with guaranteed low latency; designed for audio or video streams where some data loss is preferred over stuttering
+	\item \textit{Interrupt} - low latency short messages, used for human interface devices like mice and keyboards
+\end{itemize}
+
+The endpoint transfer type and other characteristics, together with other information about the device, such as the serial number, are defined in a \textit{descriptor table}. This is a tree-like binary structure defined in the function's memory. The descriptor table is loaded by the host to learn about the used endpoints and to attach the right driver to it.
+
+The function's endpoints are grouped into \textit{interfaces}. An interface describes a logical connection of endpoints, such as the reception and transmission endpoint that belong together. An interface is assigned a \textit{class} defining how it should be used. Standard classes are defined by the USB specification to provide a uniform way of interfacing devices of the same type, such as human-interface devices (mice, keyboards, gamepads) or mass storage devices. The use of standard classes makes it possible to re-use the same driver software for devices from different manufacturers. The class used for the GEX's "virtual COM port" function was originally meant for telephone modems, a common way of connecting to the Internet at the time the first versions of USB were developed. A device using this class will show as \verb|/dev/ttyACM0| on Linux and as a COM port on Windows, provided the system supports it natively or the right driver is installed.
+%TODO add reference to the document
+
+%function - https://technet.microsoft.com/en-us/library/cc939102.aspx
+
+\section{USB Physical Layer}
+
+USB uses differential signaling with NRZI encoding (\textit{Non Return to Zero Inverted}) and bit stuffing. The encoding, together with frame formatting, checksum verification, retransmission, and other low level aspects of the USB connection are entirely handled by the USB block in the microcontroller's silicon. Normally we do not need to worry about those details. What needs more attention are the electrical characteristics of the bus, which need to be understood correctly for a successful PCB design.
+
+The USB cable contains 4 conductors:
+
+\begin{itemize}\setlength\itemsep{.2em}
+	\item V$_\mathrm{BUS}$ (+5\,V)
+	\item D+
+	\item D--
+	\item Ground
+\end{itemize}
+
+D+ and D-- are commonly labeled DP and DM. The differential pair should be routed in parallel and keep approximately the same length. The USB speed is determined by the presence of a 1.5\,k$\Omega$ pull-up resistor to 3.3\,V on one of the data lines: for Low Speed, D-- is pulled high, for Full Speed it's the D+ line. The polarity of the differential signals is inverted depending on the used speed. Some microcontrollers integrate the correct pull-up resistor inside the USB block, removing the need for an external resistor.
+
+When the function needs the host to re-enumerate it, that is, reload the descriptors and re-attach the correct drivers, it can momentarily remove the pull-up resistor. In the case of an internal pull-up, this can be done by flipping a control bit. An external resistor could be connected through a transistor to facilitate re-enumeration, or it might be driven directly by a GPIO pin.
+
+%https://www.eevblog.com/forum/projects/driving-the-1k5-usb-pull-up-resistor-on-d/
+%http://www.beyondlogic.org/usbnutshell/usb2.shtml
+
+The V$_\mathrm{BUS}$ line provides a power supply to the function in the case of \textit{bus-powered} devices. \textit{Self-powered} devices can leave this pin unconnected and instead use an external power supply. The current that can be drawn from the V$_\mathrm{BUS}$ line is configured using a descriptor and should not be exceeded. However, this limitation is often not enforced, especially when USB hubs are used, and can't be relied upon as a safety measure.
+
+\section{USB Classes}
+
+This section explains the function of the Mass Storage class and the CDC/ACM class that find use in the GEX firmware. A list of all standard classes with a more detailed explanation can be found in \todo{link to the ref manual}.
+
+\subsection{Mass Storage Class}
+
+The Mass Storage class (MSC) is natively supported by all modern operating systems (MS Windows, MacOS, GNU/Linux, FreeBSD etc.) and finds use in thumb drives, external disks, memory card readers and other storage devices. 
+%http://www.usb.org/developers/docs/devclass_docs/Mass_Storage_Specification_Overview_v1.4_2-19-2010.pdf
+%http://www.usb.org/developers/docs/devclass_docs/usbmassbulk_10.pdf
+
+The MSC specification defines multiple \textit{transport protocols} that can be selected using the descriptors. For it's simplicity, the \textit{Bulk Only Transport} (BOT) will be used. BOT uses two bulk endpoints for reading and writing blocks of data and for the exchange of control commands and status messages. For the device to be recognized by the operating system, it must also implement a \textit{command set}. Most mass storage devices use the \textit{SCSI Transparent command set} 
+\footnote{To confirm this assertion, the descriptors of five thumb drives and an external hard disk were analyzed using \verb|lsusb|. All but one device used the SCSI command set, one (incidentally the oldest) used \textit{SFF-8070i}. A list of possible different command sets can be found in TODO (usb spec overview)}.
+The defined commands let the host read information about the attached storage, such as its capacity, and check for media presence and readiness to write or detach.
+
+
+% weird flash - SFF-8070i subclass
+
+% usb spec overview https://cscott.net/usb_dev/data/devclass/msco_v109.pdf
+
+%https://bits4device.wordpress.com/2013/05/24/usb-mass-storage-class-msc-bulk-only-transfer-bot/
+
+%http://janaxelson.com/mass_storage_faq.htm
+
+The MSC class together with the SCSI command set are rather complicated, thankfully a driver library is provided by ST Microelectronics that can be used as given, or customized. The library also includes a CDC/ACM implementation.
+
+In order to emulate a mass storage device without having a physical storage medium, we need to generate and parse the filesystem on-the-fly, as the host OS tries to access it. This will be discussed in chapter ??\todo{chapter num}.
+
+\subsection{CDC/ACM Class}
+
+%https://www.keil.com/pack/doc/mw/USB/html/group__usbd__cdc_functions__acm.html
+
+Historically meant for modem communication, this class is now the de facto standard way of making USB devices appear as serial ports on the host OS. The CDC (\textit{Communication Device Class}) class uses three endpoints: bulk IN and OUT, and an interrupt endpoint. 
+
+The interrupt endpoint is used for commands and notifications about the modem line, while the bulk endpoints are used for useful data. ACM stands for \textit{Abstract Control Model} and it's a CDC's subclass that defines the control messages format. Since we don't use any physical serial port in this implementation and the line is virtual both on the PC and in the end device, the interrupt endpoint can mostly be ignored.
+
+An interesting property of this class is that the bulk endpoints transport raw data without any wrapping frames. By changing the device class in the descriptor table to 255 (\textit{Vendor Specific Class}), we can retain the messaging functionality of the designated endpoints and access the device directly using e.g. libUSB, whereas the OS will ignore the device and won't try to attach the serial port driver, which would otherwise interfere. The same trick can be used to hide the mass storage class, when not needed.
+
+\subsection{Interface Association: Composite Class}
+
+Since it's creation, the USB specification expected that each function will have only one interface enabled at a time. After it became apparent that there is a need for having multiple unrelated interfaces work in parallel, a workaround called the \textit{Interface Association Descriptor} (IAD) was devised. IAD is an entry in the descriptor table that defines which interfaces belong together and should be handled by the same driver.
+
+To use the IAD, the function's class must be set to 239 (EFh), subclass 2, protocol 1 (in the top level descriptor), so the OS knows to look for the presence of IADs before binding drivers to any interfaces. 
+
+In GEX, the IAD is used to tie together the CDC and ACM interfaces while leaving out the MSC interface which should be handled by a different driver. To make this work, a new \textit{composite class} had to be created as a wrapper for the library-provided MSC and CDC/ACM implementations.
+
+%http://www.usb.org/developers/docs/whitepapers/iadclasscode_r10.pdf
+
+\todo{examples of descriptors?}
+
+
+

document_config.tex

@@ -12,6 +12,8 @@
 \usepackage{sectsty}
 \usepackage{titlecaps}
 
+\usepackage{bigfoot} % verbatin in footnote
+
 \newcommand{\uF}{\micro\farad}
 \newcommand{\nF}{\nano\farad}
 \newcommand{\cm}{\centi\metre}

thesis.tex

@@ -19,6 +19,7 @@
 \input{ch.introduction}
 \input{ch.requirements}
 \input{ch.existing_solutions}
+\input{ch.usb}
 
 \appendix % začátek příloh