\documentclass[11pt]{article}
\usepackage[usenames,dvipsnames]{xcolor}
\usepackage{hyperref}
\hypersetup{colorlinks=true,linkcolor=blue}
\usepackage{xltxtra}
\usepackage{longtable}
\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

\tableofcontents

\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}

The following information blocks can be requested from a node through the
discovery protocol:

\begin{table}[h]\tt
  \caption{\textnormal{information blocks}}
  \begin{tabular}{rl}
	block & usage\\
	\hline
	0	& \textnormal{root information block} \\
	1-3	& \textnormal{reserved} \\
	4-7	& \textnormal{device specific} \\
	8-15	& \textnormal{text description of the sensor (64 bytes max, 0-padded)}
  \end{tabular}
\end{table}

\newpage
\subsection{block 0: 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}{rll}
  	offset & type & field \\
	\hline
	0	& uint8\_t & \textnormal{actor type} \\
	1	& uint8\_t & \textnormal{sensor type} \\
	2	& uint8\_t & \textnormal{block 4-7 usage} \\
	3	& uint8\_t & \textnormal{data size (1-8 bytes)} \\
	4	& uint16\_t & \textnormal{sublab grid location} \\
	6	& uint16\_t & \textnormal{reserved for future use}
  \end{tabular}
\end{table}

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}

Block 4-7 usage (byte 2):

\begin{longtable}{rl}
	type code & type \\
	\hline
	\texttt{00}	& none (unused) \\
	\hline
	\texttt{01}	& DALI device information \\
\end{longtable}

\subsection{DALI (subtype 0x01) information blocks}

\subsubsection{block 4: reserved}

Block 4 is not currently used with DALI devices.

\subsubsection{block 5: direct bus access}
Direct DALI bus access. TBA.

\subsubsection{block 6: device ROM information}

Requesting information block 6 from a DALI device acquires ROM information and the random search
address from the device.  The request will take about 0.3s to complete since the information is
not cached.

\begin{table}[h]\tt
  \caption{\textnormal{DALI information block 6 contents (6 bytes)}}
  \begin{tabular}{rll}
  	offset & type & field \\
	\hline
	0	& uint8\_t	& \textnormal{DALI version number} \\
	1	& uint8\_t	& \textnormal{DALI device type} \\
	2	& uint8\_t	& \textnormal{DALI physical minimum dimming level} \\
	3	& uint8\_t[3]	& \textnormal{DALI device search address} \\
  \end{tabular}
\end{table}

\subsubsection{block 7: device state}

Requesting information block 7 from a DALI device polls all volatile and writable nonvolatile state.
The request will take about 0.3s to complete since the information is not cached.  It is intended
that this block can be written to.

\begin{table}[h]\tt
  \caption{\textnormal{DALI information block 7 contents (8 bytes)}}
  \begin{tabular}{rll}
  	offset & type & field \\
	\hline
	0	& uint8\_t	& \textnormal{DALI current actual power level} \\
	1	& uint8\_t	& \textnormal{DALI maximum level} \\
	2	& uint8\_t	& \textnormal{DALI minimum level} \\
	3	& uint8\_t	& \textnormal{DALI power on level} \\
	4	& uint8\_t	& \textnormal{DALI system failure level} \\
	5	& uint8\_t	& \textnormal{DALI fade rate / fade time} \\
	6	& uint8\_t	& \textnormal{DALI status information} \\
	7	& uint8\_t	& \textnormal{DALI short address} \\
  \end{tabular}
\end{table}

\newpage

\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}
