reorganised the documentation dir.

Documentation/Datasheet/IAQ_Wired_Sensor_Datasheet.out

@@ -0,0 +1,15 @@
+\BOOKMARK [1][-]{section.1}{\376\377\000S\000p\000e\000c\000i\000f\000i\000c\000a\000t\000i\000o\000n\000s}{}% 1
+\BOOKMARK [2][-]{subsection.1.1}{\376\377\000E\000l\000e\000c\000t\000r\000i\000c\000a\000l\000\040\000S\000p\000e\000c\000i\000f\000i\000c\000a\000t\000i\000o\000n\000s}{section.1}% 2
+\BOOKMARK [2][-]{subsection.1.2}{\376\377\000S\000e\000n\000s\000i\000n\000g\000\040\000S\000p\000e\000c\000i\000f\000i\000c\000a\000t\000i\000o\000n\000s}{section.1}% 3
+\BOOKMARK [2][-]{subsection.1.3}{\376\377\000I\000n\000t\000e\000r\000f\000a\000c\000e\000\040\000S\000p\000e\000c\000i\000f\000i\000c\000a\000t\000i\000o\000n\000s}{section.1}% 4
+\BOOKMARK [2][-]{subsection.1.4}{\376\377\000C\000o\000n\000n\000e\000c\000t\000o\000r\000s\000\040\000P\000i\000n\000o\000u\000t}{section.1}% 5
+\BOOKMARK [3][-]{subsubsection.1.4.1}{\376\377\000M\000a\000i\000n\000\040\000C\000o\000n\000n\000e\000c\000t\000o\000r\000\040\000P\000i\000n\000o\000u\000t}{subsection.1.4}% 6
+\BOOKMARK [3][-]{subsubsection.1.4.2}{\376\377\000P\000r\000o\000g\000r\000a\000m\000m\000i\000n\000g\000\040\000C\000o\000n\000n\000e\000c\000t\000o\000r\000\040\000P\000i\000n\000o\000u\000t}{subsection.1.4}% 7
+\BOOKMARK [1][-]{section.2}{\376\377\000C\000o\000m\000m\000u\000n\000i\000c\000a\000t\000i\000o\000n\000\040\000S\000p\000e\000c\000i\000f\000i\000c\000a\000t\000i\000o\000n}{}% 8
+\BOOKMARK [2][-]{subsection.2.1}{\376\377\000P\000h\000y\000s\000i\000c\000a\000l\000\040\000L\000a\000y\000e\000r\000\040\000-\000\040\000R\000S\0004\0008\0005}{section.2}% 9
+\BOOKMARK [2][-]{subsection.2.2}{\376\377\000D\000a\000t\000a\000\040\000L\000i\000n\000k\000\040\000L\000a\000y\000e\000r\000\040\000-\000\040\000M\000o\000d\000b\000u\000s\000\040\000R\000T\000U}{section.2}% 10
+\BOOKMARK [3][-]{subsubsection.2.2.1}{\376\377\000M\000o\000d\000b\000u\000s\000\040\000r\000e\000g\000i\000s\000t\000e\000r\000\040\000s\000p\000a\000c\000e}{subsection.2.2}% 11
+\BOOKMARK [2][-]{subsection.2.3}{\376\377\000I\000A\000Q\000S\000W\000-\0000\0001\000\040\000M\000o\000d\000b\000u\000s\000\040\000r\000e\000g\000i\000s\000t\000e\000r\000s}{section.2}% 12
+\BOOKMARK [3][-]{subsubsection.2.3.1}{\376\377\000I\000n\000p\000u\000t\000\040\000r\000e\000g\000i\000s\000t\000e\000r\000s}{subsection.2.3}% 13
+\BOOKMARK [3][-]{subsubsection.2.3.2}{\376\377\000H\000o\000l\000d\000i\000n\000g\000\040\000r\000e\000g\000i\000s\000t\000e\000r\000s}{subsection.2.3}% 14
+\BOOKMARK [1][-]{section.3}{\376\377\000M\000e\000c\000h\000a\000n\000i\000c\000a\000l\000\040\000D\000i\000m\000e\000s\000i\000o\000n\000s}{}% 15

Documentation/Datasheet/IAQ_Wired_Sensor_Datasheet.tex

@@ -0,0 +1,303 @@
+\documentclass[a4paper,12pt,oneside]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[english]{babel}
+\usepackage{fancyhdr}
+\usepackage{graphics}
+\usepackage{graphicx}
+\usepackage{multicol}
+\usepackage{capt-of}
+\usepackage[table]{xcolor}
+\usepackage{hyperref} % for internal section links
+
+% ONLY FOR TEMPLATE
+\usepackage{blindtext}
+
+%
+% Sensor name definition 
+%
+\newcommand{\sensor}{IAQSW-01}
+
+\pagestyle{fancy}
+\fancyhf{}
+%\fancyhead[LE,LO]{\includegraphics[scale=0.075]{./fig/VelesLabsLogo.png}}
+%\fancyhead[RE,RO]{\sensor{}\\DATASHEET v. 1.0}
+%\fancyfoot[LE,LO]{\leftmark}
+%\fancyfoot[RE,RO]{\thepage}
+
+\fancyhead[LO]{\includegraphics[scale=0.075]{./fig/VelesLabsLogo.png}}
+\fancyhead[RO]{\sensor{}\\DATASHEET v. 1.0}
+\fancyfoot[LO]{\leftmark}
+\fancyfoot[RO]{\thepage}
+
+\renewcommand{\headrulewidth}{2pt}
+\renewcommand{\footrulewidth}{2pt}
+\setlength{\headheight}{35pt}
+
+\begin{document}
+%TODO: TITLEPAGE
+
+\begin{multicols*}{2}
+\includegraphics[width=0.45\textwidth]{./fig/iaq_wired_sensor.png}
+\section*{Features}
+\begin{itemize}
+\setlength\itemsep{0cm}
+\item Measures all important indoor air quality values: $\mathrm{CO_2}$, T, RH, VOC
+\item Communicates via Modbus RTU (RS-485)
+\item Wide input voltage range 5 - 30V
+\item Indicates $\mathrm{CO_2}$ (carbon dioxide) level using LED for quick air quality assesment
+\item Easy to setup using Raspberry Pi and open-source Veles Sensors python library
+\item Carbon dioxide measurement range 0 - 40000 ppm 
+\item Temperature range -40 - 125 °C
+\item Relative humidity range 0 - 100 \%
+\item VOC (volatile organic compounds) index range 1 - 500 VOC index points
+\item Fully opensource
+\end{itemize}
+\section*{Description}
+\sensor{} is a wired indoor air quality sensor measuring temperature, relative humidity, carbon dioxide and volatile organic compounds. Communication over RS-485 using Modbus RTU protocol makes it easy to interface with the sensor using PLC or any PC with RS-485 to USB converter. Open-source Python libraries are available to ease sensor configuration and readout using PC and embedded computers (e.g. Raspberry Pi).
+
+On-board RGB LED enables user to quickly assess air quality with single glance. Two quality-to-color schemes are available: continuous color change and tri-state (semaphore) mode. Thresholds for color change are user-configurable.
+
+Wide input voltage range makes it possible to integrate sensor to many different systems, ranging from house-wide 12V bus to 5V USB connected to local computer.
+
+Extended version of this sensor \sensor{}-PM adds particulate matter (dust) measurement option.
+
+Fully open-source ecosystem: sensor hardware, case, firmware and connected Python libraries are open-sourced under permissive licence.
+
+\section*{Application}
+\begin{itemize}
+\setlength\itemsep{0cm}
+\item IAQ measurement for home and office spaces, ventilation control
+\end{itemize}
+\end{multicols*}
+\pagebreak
+
+\tableofcontents
+\listoffigures
+\listoftables
+
+\pagebreak
+
+\section{Specifications}
+\subsection{Electrical Specifications}
+\begin{table}[h]
+\scriptsize
+\begin{tabular}{|p{5cm}|p{2cm}|p{1cm}|p{1cm}|p{1cm}|p{1cm}|}
+\hline
+\rowcolor{lightgray}\textbf{Parameter}                       							& \textbf{Symbol} 	& \textbf{Min.} 	& \textbf{Typ.} 	& \textbf{Max.} 	& \textbf{Unit} 		\\ \hline
+Input voltage                                 							& $\mathrm{V_{DD}}$        		& 5             		& 12            		& 24            			& V             			\\ \hline
+Average supply current                        					& $\mathrm{I_{DD}}$        		&               		& 50            		&               			& mA            			\\ \hline
+RS485 Single-Ended Output High                				& $\mathrm{V_{OH}}$        		& 2.2           		&               		&               			& V             			\\ \hline
+RS485 Single-Ended Output Low                 				& $\mathrm{V_{OL}}$        		&               		&               		& 0.8           			& V             			\\ \hline
+RS485 Differential Output                     					& $\mathrm{V_{OD}}$        		& 2.0           		&               		&               			& V             			\\ \hline
+RS485 Receiver Differential Threshold Voltage 		& $\mathrm{V_{TH}}$        		& -200          		& -105          		& -10           			& mV            			\\ \hline
+\end{tabular}
+\normalsize
+\caption{Electrical Specifications}
+\label{tab:specifications_electrical}
+\end{table}
+\vfill
+\subsection{Sensing Specifications}
+\begin{table}[h]
+\scriptsize
+\begin{tabular}{|p{5cm}|p{3cm}|p{4.25cm}|}
+\hline
+\rowcolor{lightgray}\textbf{Parameter}                       							& \textbf{Conditions} 					& \textbf{Value} 										\\ \hline
+CO$_2$ measurement range                              		& \multicolumn{1}{c|}{-}           	& 0 $\div$ 40000 ppm								\\ \hline
+CO$_2$ measurement accuracy                        		&  400 ppm – 2000 ppm 	       		& ($\pm$50 ppm + 5\% of reading)          	\\ \hline
+CO$_2$ measurement repeatability                          & Typical           		      					& $\pm$10 ppm											\\ \hline
+T measurement range                								&  \multicolumn{1}{c|}{-}             &  –40 $\div$ +125 $^{\circ}$C       			\\ \hline
+T measurement accuracy                 						&  Typical                         				& $\pm$0.2 $^{\circ}$C         					\\ \hline
+T measurement repeatability                 					&  Typical                         				& $\pm$0.2 $^{\circ}$C         					\\ \hline
+RH measurement range                    						&  \multicolumn{1}{c|}{-}             & 0 $\div$ 100 \%RH            						\\ \hline
+RH measurement accuracy 									&  Typical        	          					& $\pm$1.8 \%RH           							\\ \hline
+RH measurement repeatability 								&  \multicolumn{1}{c|}{-}        	    	& $\pm$0.08 \%RH           							\\ \hline
+\end{tabular}
+\normalsize
+\caption{Sensing Specifications}
+\label{tab:specifications_sensing}
+\end{table}
+\vfill
+
+\subsection{Interface Specifications}
+\begin{table}[h]
+\scriptsize
+\begin{tabular}{|p{3.75cm}|p{9cm}|}
+\hline
+\rowcolor{lightgray}\textbf{Parameter}                       							& \textbf{Value} 							\\ \hline
+Used Protocol						                              		& Modbus RTU           					\\ \hline
+Default Baudrate                        								&  19200 Baud 	       						\\ \hline
+Usable  Baudrates                      								&  4800, 9600, 14400, 19200,  28800, 38400, 57600, 76800, 119200 Baud 	      \\ \hline
+Data Bytes                          									& 8           		      							\\ \hline
+Parity                														&  Even             								\\ \hline
+Stop Bits                 												&  1                         						\\ \hline
+\end{tabular}
+\normalsize
+\caption{Sensing Specifications}
+\label{tab:specifications_interface}
+\end{table}
+\vfill
+\pagebreak
+
+\subsection{Connectors Pinout}
+\subsubsection{Main Connector Pinout}
+\begin{figure}[h]
+\begin{minipage}[c]{0.5\linewidth}
+	\centering
+	\includegraphics[width=0.5\textwidth]{./fig/connector_pins.png}
+	\caption{Main Connector Pinout}
+	\label{fig:connector_pinout}
+\end{minipage}
+\begin{minipage}[c]{0.5\linewidth}
+	\centering
+		\scriptsize
+	\begin{tabular}{|p{0.75cm}|p{1.25cm}|p{3cm}|}
+
+		\hline
+\rowcolor{lightgray}\textbf{Pin} & \textbf{Name} & \textbf{Description} \\ \hline
+		1 & VDD & Supply Voltage \\ \hline
+		2 & A & RS485 A+ \\ \hline
+		3 & B & RS485 B- \\ \hline
+		4 & GND & Ground \\ \hline
+	\end{tabular}
+	\captionof{table}{Main Connector Pinout}
+	\label{tab:connector_pinout}
+\end{minipage}
+\end{figure}
+
+\subsubsection{Programming Connector Pinout}
+\begin{table}[h]
+\scriptsize
+	\centering
+	\begin{tabular}{|p{0.75cm}|p{1.55cm}|p{3cm}|}
+		\hline
+\rowcolor{lightgray}		\textbf{Pin} & \textbf{Name} & \textbf{Description} \\ \hline
+		1 & 3V3 & 3.3V Sensing \\ \hline
+		2 & GND & Ground \\ \hline
+		3 & SWDIO & SWD Data \\ \hline
+		4 & SWCLK & SWD Clock \\ \hline
+		5 & NRST & MCU Reset \\ \hline
+	\end{tabular}
+	\caption{Programming Connector Pinout}
+	\label{tab:swd_connector_pinout}
+\end{table}
+
+\section{Communication Specification}
+
+For physical layer RS-485 is used. This enables communication to be robust and resistant to EMI (electro-magnetic interference). On top of physical layer Modbus RTU is used as a data link layer. This protocol is widely supported by number of PLCs and other devices. To interface with PC (or any computer with USB port) USB to RS485 converter may be used in conjunction with Veles Sensors python library.
+
+\subsection{Physical Layer - RS485}
+
+RS-485 is a full-duplex serial bus ideally suited for low-speed, noise-resistant communication over long distances (up to 1200 m, more if repeaters are used). Linear bus topology is preferable over star or ring configurations. To prevent signal reflections, each sensor is equipped with 120 $\Omega$ termination resistor, therefore optimal cable for connecting sensors to each other and to master node is twisted pair cable with 120 $\Omega$ characteristic impedance.
+
+\subsection{Data Link Layer - Modbus RTU}
+
+Modbus is well-tested, openly-published and royalty free data communications protocol. Developed for industrial applications, it aims to be simple and robust. It is a client/server (master/slave) type protocol. Maximum number of client nodes on a Modbus bus is 247.
+
+Limitation of Modbus-based buses is that there is no arbitration in case of address conflict. This means that nodes should be either added one by one or node addresses should be configured beforehand.
+
+Address 0 can be used as a broadcast message (e.g. instructing all sensors to turn off LED). No slave response is generated.
+
+(TODO note: random address assignment command?)
+
+\subsubsection{Modbus register space}
+
+Modbus supports four types of registers:
+
+\begin{table}[h]
+\scriptsize
+	\centering
+	\begin{tabular}{|p{3cm}|p{3cm}|p{3cm}|p{3cm}|}
+		\hline
+		\rowcolor{lightgray}		\textbf{Object type} & \textbf{Access} & \textbf{Size} & \textbf{Address space} \\ \hline
+		Coil             & read / write & 1 bit   & 00001 - 09999 \\ \hline
+		Discrete input   & read         & 1 bit   & 10001 - 19999 \\ \hline
+		Input register   & read         & 16 bits & 30001 - 39999 \\ \hline
+		Holding register & read / write & 16-bits & 40001 - 49999 \\ \hline
+	\end{tabular}
+	\caption{Modbus register space}
+	\label{tab:modbus_register_space}
+\end{table}
+\vfill
+
+\pagebreak
+\subsection{\sensor{} Modbus registers}
+
+\subsubsection{Input registers}
+
+Input registers contain measured values. They are read-only and 16-bit in size.
+
+\begin{table}[h]
+	\scriptsize
+		\centering
+		\begin{tabular}{|p{4cm}|p{2.5cm}|p{2cm}|p{3.6cm}|}
+			\hline
+		\rowcolor{lightgray}		\textbf{Register name} & \textbf{Register address} & \textbf{Dimension} & \textbf{Note} \\ \hline
+		Temperature                             & 30010 & °C            & \\ \hline
+		Temperature                             & 30011 & °F            & \\ \hline
+		Relative humidity                       & 30012 &  \%           & \\ \hline
+		$\mathrm{CO_2}$ concentration           & 30013 & ppm           & \\ \hline
+		VOC index                               & 30014 & VOC index     & see \hyperref[inputReg:note1]{Note 1} \\ \hline
+		VOC ticks                               & 30015 & raw VOC ticks & Raw value from VOC sensor \\ \hline
+		Temperature from $\mathrm{CO_2}$ sensor & 30028 & °C            & \\ \hline
+		Temperature from $\mathrm{CO_2}$ sensor & 30029 & °F            & \\ \hline
+		RH from $\mathrm{CO_2}$ sensor          & 30030 & \%            & \\ \hline
+		\end{tabular}
+		\caption{Modbus input registers for \sensor{}}
+		\label{tab:modbus_input_registers}
+\end{table}
+
+\paragraph{Note 1}
+\label{inputReg:note1}
+VOC index has range 1-500 with 100 being the average. After sensor start-up VOC index is 0 until sufficient amount of data has been measured.
+
+\subsubsection{Holding registers}
+
+Holding registers can be written to by master node. Sensor \sensor{} offers following configuration registers:
+
+\begin{table}[h]
+	\scriptsize
+		\centering
+		\begin{tabular}{|p{4cm}|p{2cm}|p{6.5cm}|}
+			\hline
+			\rowcolor{lightgray}		\textbf{Register name} & \textbf{Address} & \textbf{Note} \\ \hline
+			LED on                             & 40001 & set to 0 to turn off LED; set to 1 to turn LED on  \\ \hline
+			LED brightness                     & 40002 & range from 0 (off) to 100 (full intensity)  \\ \hline
+			LED smooth                         & 40003 & see \hyperref[holdingReg:note1]{Note 1}  \\ \hline
+			$\mathrm{CO_2}$ alert limit 1      & 40004 & see \hyperref[holdingReg:note2]{Note 2} \\ \hline
+			$\mathrm{CO_2}$ alert limit 2      & 40005 & see \hyperref[holdingReg:note2]{Note 2} \\ \hline
+			$\mathrm{CO_2}$ temperature offset & 40006 & see \hyperref[holdingReg:note2]{Note 3} \\ \hline
+			Device Modbus address              & 40007 & see \hyperref[holdingReg:note2]{Note 4} \\ \hline
+			Modbus baudrate                    & 40008 & see \hyperref[holdingReg:note2]{Note 5} \\ \hline
+			Reset device                       & 40100 & see \hyperref[holdingReg:note2]{Note 6} \\ \hline
+		\end{tabular}
+		\caption{Modbus holding registers for \sensor{}}
+		\label{tab:modbus_holding_registers}
+\end{table}
+
+\paragraph{Note 1}
+\label{holdingReg:note1}
+Setting LED smooth register to 1 will turn on LED color interpolation, meaning LED will have color in continuous spectrum from green to red according to $\mathrm{CO_2}$ level. Setting this register to 0 will turn off interpolation and set LED to semaphore (tri-state) mode. Depending on $\mathrm{CO_2}$ level LED color will then be either green, yellow or red.
+
+\paragraph{Note 2}
+\label{holdingReg:note2}
+Registers $\mathrm{CO_2}$ alert limit 1 and 2 set threshold for LED color change (see \hyperref[holdingReg:note1]{Note 1}). Limit 1 is threshold between green and yellow color, limit 2 is threshold betweek yellow and red color.
+
+\paragraph{Note 3}
+\label{holdingReg:note3}
+SCD41 is $\mathrm{CO_2}$ sensing device used in \sensor{} sensor. It is also able to measure temperature, however it may be subject to offset due to internal heating of SCD41. This register allows user to compensate this offset.
+
+\paragraph{Note 4}
+\label{holdingReg:note4}
+Device Modbus address may be changed by writing to this register. Allowed values are in range from 1 to 247. Device will start using new address immediately and cease to respond at previous address. Reset is not needed. It is the responsibility of a user to prevent address collisions on a bus.
+
+\paragraph{Note 5}
+\label{holdingReg:note5}
+Modbus baudrate in bits/s. May be one of: 4800, 9600, 14400, 19200, 28800, 38400, 57600, 76800, 115200. Please be aware that lower baudrates are more reliable for long distance communication.
+
+\paragraph{Note 6}
+\label{holdingReg:note6}
+Writing magical constant 0xABCD to this device will instruct device to soft-reset.
+\vfill
+\section{Mechanical Dimesions}
+\includegraphics[angle=90,origin=c,scale=0.99]{./fig/IAQ_Sensor_Enclosure-Enclosure_TOP.pdf}
+\end{document}

Documentation/Datasheet/Makefile

@@ -0,0 +1,6 @@
+FILE=IAQ_Wired_Sensor_Datasheet
+
+all:
+	texi2pdf $(FILE).tex
+	rm *aux *log *lof *lot *toc
+	mupdf $(FILE).pdf