can: protocol.tex

2 files changed, 152 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index acfe7e3..085d864 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,7 @@
 *.o
 *.pyc
 *.pyo
+
+*.aux
+*.log
+*.pdf
diff --git a/protocol.tex b/protocol.tex
new file mode 100644
index 0000000..a5828e0
--- /dev/null
+++ b/protocol.tex
@@ -0,0 +1,148 @@
+\documentclass[11pt]{article}
+\usepackage{xltxtra}
+\usepackage{longtable}
+\usepackage[usenames,dvipsnames]{xcolor}
+\usepackage[font=small,labelfont=bf]{caption}
+\setmainfont[Mapping=tex-text]{Delicious-Roman}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{6pt}
+
+\newsavebox\TBox
+\def\textoverline#1{\savebox\TBox{#1}%
+  \makebox[0pt][l]{#1}\rule[1.1\ht\TBox]{\wd\TBox}{0.4pt}}
+
+\begin{document}
+\title{subbus protocol}
+\maketitle
+
+\section{packet types}
+
+\begin{table}[h]
+  \caption{subbus packets}
+  \begin{tabular}{rll}
+  	address (hex) & usage & mode \\
+	\hline
+	\texttt{100-00000} &	time 					& src-periodic \\
+	\texttt{4c0-0\textcolor{blue}{B}\textcolor{blue}{AAA}} &
+				discovery/info (request)		& request/response \\
+	\texttt{cc0-\textcolor{blue}{SS}\textcolor{blue}{AAA}} &
+				light (data transport to destination)	& src-event, dst-periodic \\
+	\texttt{e60-00\textcolor{blue}{AAA}} &
+				sensors (data transport from source)	& src-periodic
+  \end{tabular}
+\end{table}
+
+\section{addressing}
+
+Sensors and lights share a 12-bit address space, located in the CAN address at
+the final 12 bit of the extended ID.  The address contained in the CAN extended
+ID specifies the device address concerned with the first byte of the data, the
+following bytes are associated with the addresses following after.  It is
+therefore possible to set 8 lights with one packet.
+
+Information about the device can be requested with the discovery protocol.  One
+sensor/light may occupy more than one byte of data space, the device then
+occupies multiple addresses because otherwise there would be a collision. The
+discovery information indicates the number of bytes used by the device.
+
+\section{time protocol}
+
+TBA
+
+\section{discovery protocol}
+
+The discovery protocol uses a CAN Remote Frame/RTR based request-response
+protocol. The querier sends an RTR frame to the discovery address; the device
+responds with the same address and the data payload.
+
+(Future extension: the querier could send a regular frame to the discovery
+address to write configuration/set options.)
+
+Discovery data consists of 16 information sub-blocks that are addressed with
+bit 16-19 of the CAN extended ID.  Block 0 is the root information block and
+describes generic device properties.  Block 8-15 carry a string description
+of the device.  The meaning of the remaining blocks depends on the root
+information block.
+
+\subsection{packet format}
+
+Information request (RTR frame):
+\begin{verbatim}
+0100 1100 000_ / 00 bbbb aaaa aaaa aaaa / RTR
+4    c    0    / 0  sub  deviceaddr
+\end{verbatim}
+
+Information response:
+\begin{verbatim}
+0100 1100 000_ / 00 bbbb aaaa aaaa aaaa / <data>
+4    c    0    / 0  sub  deviceaddr
+\end{verbatim}
+
+\begin{itemize}
+\item \texttt{bbbb} selects one of the 16 information sub-blocks.
+\item \texttt{aaaa aaaa aaaa} is the device address.
+\end{itemize}
+
+\subsection{information blocks}
+\subsubsection{root block}
+
+The root information block describes generic device properties and should
+always be queried to determine device characteristics:
+
+\begin{table}[h]\tt
+  \caption{\textnormal{information block 0 contents (root)}}
+  \begin{tabular}{rrl}
+  	offset & type & field \\
+	\hline
+	0	& uint8\_t & \textnormal{actor type} \\
+	1	& uint8\_t & \textnormal{sensor type} \\
+	2	& uint8\_t & \textnormal{flags / reserved} \\
+	3	& uint8\_t & \textnormal{data size (1-8 bytes)} \\
+	4	& uint16\_t & \textnormal{sublab grid location}
+  \end{tabular}
+\end{table}
+
+\subsubsection{type codes}
+
+Actor type codes (byte 0):
+
+\begin{longtable}{rl}
+	type code & type \\
+	\hline
+	\texttt{00}	& none (sensor or no function) \\
+	\hline
+	\texttt{01}	& light fixture, dimmable \\
+	\texttt{02}	& light fixture, not dimmable \\
+	\texttt{03}	& relais \\
+	\hline
+	\texttt{ff}	& custom / broken / ...
+\end{longtable}
+
+Sensor type codes (byte 1):
+
+\begin{longtable}{rl}
+	type code & type \\
+	\hline
+	\texttt{00}	& none (actor or no function) \\
+	\hline
+	\texttt{01}	& light dimming readback sensor \\
+	\texttt{02}	& temperature sensor \\
+	\texttt{03}	& generic single-bit digital input \\
+	\hline
+	\texttt{ff}	& custom / broken / ...
+\end{longtable}
+
+\section{sublab running nodes}
+\begin{longtable}{rlll}
+	address & actor type & sensor type & node \\
+	\hline
+	\texttt{100}	& \texttt{00}: ---	& \texttt{03}: digital		& door: left wing \\	% & {\footnotesize \parbox{5em}{0: open,\\1: closed}} \\
+	\texttt{101}	& \texttt{00}: ---	& \texttt{03}: digital		& door: light barrier \\% & {\footnotesize \parbox{5em}{0: blocked,\\1: normal}} \\
+	\texttt{102}	& \texttt{00}: ---	& \texttt{03}: digital		& door: lock bolt \\	% & {\footnotesize \parbox{5em}{0: open,\\1: closed}} \\
+	\texttt{103}	& \texttt{00}: ---	& \texttt{03}: digital		& door: right wing \\	% & {\footnotesize \parbox{5em}{0: open,\\1: closed}} \\
+	\hline
+	\texttt{440}-\texttt{47f} & \texttt{01}: dimmable & \texttt{01}: dimread	& DALI bus mapping
+\end{longtable}
+
+
+\end{document}