#LyX 2.0 created this file. For more info see http://www.lyx.org/
\lyxformat 413
\begin_document
\begin_header
\textclass article
\begin_preamble
\usepackage[long]{datetime}
\usepackage[toc]{multitoc}
\renewcommand\tableofcontents{%
    \@starttoc{toc}%
}
\usepackage{fancyhdr}
\pagestyle{fancy}
\chead{Sense/Net Bus Specification}
\lhead{}
\rhead{}
\end_preamble
\use_default_options true
\maintain_unincluded_children false
\language english
\language_package default
\inputencoding auto
\fontencoding global
\font_roman lmodern
\font_sans lmss
\font_typewriter lmtt
\font_default_family default
\use_non_tex_fonts false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100

\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\float_placement h
\paperfontsize default
\spacing single
\use_hyperref true
\pdf_bookmarks true
\pdf_bookmarksnumbered false
\pdf_bookmarksopen false
\pdf_bookmarksopenlevel 1
\pdf_breaklinks false
\pdf_pdfborder true
\pdf_colorlinks false
\pdf_backref false
\pdf_pdfusetitle true
\papersize default
\use_geometry true
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\use_mathdots 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\use_refstyle 1
\index Index
\shortcut idx
\color #008000
\end_index
\leftmargin 2cm
\topmargin 2cm
\rightmargin 2cm
\bottommargin 2cm
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_math_output 0
\html_css_as_file 0
\html_be_strict false
\end_header

\begin_body

\begin_layout Title
Soil Sensor Manual
\end_layout

\begin_layout Author
Nick Ames 
\begin_inset Formula $\cdot$
\end_inset

 Revision 2 
\begin_inset Newline newline
\end_inset

Copyright 2016 Sensiplicity Systems
\end_layout

\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0
use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
status open

\begin_layout Plain Layout
\begin_inset CommandInset toc
LatexCommand tableofcontents

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace 0.5cm
\end_inset


\end_layout

\begin_layout Section
Overview
\end_layout

\begin_layout Standard
The OSU Soil Sensor is a comprehensive sensor for monitoring plants.
 In addition to measuring soil moisture at multiple depths, it measures
 ambient light, ambient temperature, humidity, and soil temperature.
 Data and power are transferred over the Sense/Net bus, an inexpensive connectio
n system that allows up to 100 sensors to be daisy-chained with 4-conductor
 cables and modular RJ-11 connectors.
\end_layout

\begin_layout Section
API
\end_layout

\begin_layout Subsection
Sensor Data Format
\end_layout

\begin_layout Standard
A data packet from a soil sensor contains the following fields, in order:
\end_layout

\begin_layout Standard
\align left

\family typewriter
\begin_inset listings
inline false
status open

\begin_layout Plain Layout

uint16_t humidity; /* Ambient relative humidity.
 0=0%, 4096=100% */
\end_layout

\begin_layout Plain Layout

int16_t temp_ambient; /* Ambient temperature, in 1/16 (.125) degrees Celsius.
 */
\end_layout

\begin_layout Plain Layout

int16_t temp_soil_z0; /* Soil temperature of zone 0, in 1/16 (.125) degrees
 Celsius.
 */
\end_layout

\begin_layout Plain Layout

int16_t temp_soil_z1; /* Soil temperature of zone 0, in 1/16 (.125) degrees
 Celsius.
 */
\end_layout

\begin_layout Plain Layout

int16_t temp_soil_z2; /* Soil temperature of zone 0, in 1/16 (.125) degrees
 Celsius.
 */
\end_layout

\begin_layout Plain Layout

int16_t temp_soil_z3; /* Soil temperature of zone 0, in 1/16 (.125) degrees
 Celsius.
 */
\end_layout

\begin_layout Plain Layout

uint16_t light; /* Current light level.
 1-65535 (lower values indicate brighter light).
 */
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

uint8_t volt_idle; /* Idle supply voltage, in 1/32 volt increments.
 (160 = 5V).
 */
\end_layout

\begin_layout Plain Layout

uint32_t uptime; /* Number of seconds since this sensor was powered on.
 */
\end_layout

\begin_layout Plain Layout

uint32_t mtime; /* Uptime value at the time of measurement.
 */
\end_layout

\begin_layout Plain Layout

\end_layout

\begin_layout Plain Layout

uint8_t zones; /* Number of zones present on this sensor node.
 */
\end_layout

\begin_layout Plain Layout

uint16_t moisture_z0; /* Moisture level in zone 0.
 Calibration TBD.
 */
\end_layout

\begin_layout Plain Layout

uint16_t moisture_z1; /* Moisture level in zone 1.
 Calibration TBD.
 */
\end_layout

\begin_layout Plain Layout

uint16_t moisture_z2; /* Moisture level in zone 2.
 Calibration TBD.
 */
\end_layout

\begin_layout Plain Layout

uint16_t moisture_z3; /* Moisture level in zone 3.
 Calibration TBD.
 */
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Multi-byte fields are sent least significant byte first (little-endian).
\end_layout

\begin_layout Subsection
Commands
\end_layout

\begin_layout Standard
All standard Sense/Net commands are implemented, with additional firmware
 upgrade capability.
 A firmware upgrade is initiated by sending a Reboot command.
 The device replies with a Ready reply, then reboots.
 Rebooting takes approx.
 50ms.
 After a reboot, the device enters the bootloader and waits 300ms for an
 Enter Programming Mode command.
 While in the bootloader, the device responds only to the programming commands
 in table 
\begin_inset CommandInset ref
LatexCommand ref
reference "prog_commands"

\end_inset

 and the fast enumeration command.
 If an Enter Programming Mode command isn't received after 300ms, the device
 starts the normal firmware.
 After issuing Enter Programming Mode, commands to program flash pages should
 be sent.
 Programming each page takes 5ms.
 Once all pages have been programmed, send a Reboot command and wait 300ms
 for the device to start the normal firmware.
\end_layout

\begin_layout Standard
During normal operation, the device does not recognize Enter Programming
 Mode, Program Page, or Erase Page commands, resulting in an Invalid Command
 error.
\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset space \hfill{}
\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="5">
<features tabularvalignment="middle">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Command
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Data Bytes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Data
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Description
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Replies
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A4
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
-
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Enter programming mode.
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

Ready
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A5
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
33
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
<page # (1 byte)><data (32 bytes)>
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Program FLASH page.
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

Ready
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

Busy
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A6
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
-
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Reboot
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

Ready
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
A7
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
1
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
<page # (1 byte)>
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Erase page.
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

Ready
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

Busy
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\begin_inset space \hfill{}
\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
Firmware upgrade commands
\end_layout

\end_inset


\begin_inset CommandInset label
LatexCommand label
name "prog_commands"

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Float table
wide false
sideways false
status open

\begin_layout Plain Layout
\begin_inset space \hfill{}
\end_inset


\begin_inset Tabular
<lyxtabular version="3" rows="3" columns="3">
<features tabularvalignment="middle">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<column alignment="center" valignment="top" width="0">
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Status
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Data Bytes
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
Description
\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
D4
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

Ready
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
D5
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
0
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Plain Layout
\begin_inset Quotes eld
\end_inset

Busy
\begin_inset Quotes erd
\end_inset


\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\begin_inset space \hfill{}
\end_inset


\end_layout

\begin_layout Plain Layout
\begin_inset Caption

\begin_layout Plain Layout
Firmware upgrade replies
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsection
Firmware Checksum
\end_layout

\begin_layout Standard
To prevent booting a corrupted or incomplete firmware image, the firmware
 is protected by a CRC (the same used in Sense/Net communications).
 The Sense/Net CRC function can't handle more than 255 bytes, so a CRC is
 computed for sets of six pages individually.
 (The flash memory contains 192 32-byte pages.
 Computing the CRC for sets of six gives 32 CRCs.
 The last two bytes of the last page are excluded from the calculation.)
 The page set CRCs are stored in a little-endian uint16_t array, and an
 overall CRC is taken of the array.
 This final CRC is stored in the final two bytes of the last page of flash.
\end_layout

\begin_layout Subsection
Calibration
\end_layout

\begin_layout Standard
Due to variation between units, the soil moisture and light sensors must
 be calibrated.
\end_layout

\begin_layout Section
Copyright Information
\end_layout

\begin_layout Standard
The OSU Soil Sensor design, firmware, software, and documentation is copyright
 2016 Sensiplicity Systems.
 All rights reserved.
 
\end_layout

\begin_layout Standard
The firmware makes use of avr-libc, portions of which are Copyright (c)
 1999-2005 Keith Gudger, Bjoern Haase, Steinar Haugen, Peter Jansen, Reinhard
 Jessich, Magnus Johansson, Artur Lipowski, Marek Michalkiewicz, Colin O'Flynn,
 Bob Paddock, Reiner Patommel, Michael Rickman, Theodore A.
 Roth, Juergen Schilling, Philip Soeberg, Anatoly Sokolov, Nils Kristian
 Strom, Michael Stumpf, Stefan Swanepoel, Eric B.
 Weddington, Joerg Wunsch, Dmitry Xmelkov, The Regents of the University
 of California.
 All rights reserved.
\end_layout

\end_body
\end_document