[manual] first version of introduction and deploying chapters

mote/v2/docs/manual/deploying.tex

@@ -0,0 +1,76 @@
+\chapter{Deploying}
+
+This chapter will guide you through the installation steps that should lead to your Fluksometer's successful deployment. Please consult the troubleshooting chapter if you experience any installation difficulties.
+
+
+\section{Networking}
+\label{sec:deploying_networking}
+
+Out of the box, a Fluksometer will report to the Flukso server via the wifi interface. Please refer to section~\ref{sec:deploying_networking_wifi} if you wish to use your Fluksometer in this reporting mode. As detailed in section~\ref{sec:introduction_pushbutton}, the Fluksometer's pushbutton can be used to toggle the reporting mode to ethernet. The networking setup for this case is described in section~\ref{sec:deploying_networking_eth}.
+
+\subsection{Wifi Mode}
+\label{sec:deploying_networking_wifi}
+Power up your Fluksometer and wait until the heartbeat LED starts to blink. Connect your computer to the Fluksometer's ethernet port. Then surf to \href{http://192.168.255.1}{192.168.255.1}. Configure the wifi page with the proper name and security key so that the Fluksometer gets connected with the internet via your local wifi network. After saving\footnote{While saving settings doesn't take long, restarting the whole wifi and networking stack with its dependencies can take more than a minute to complete. Be patient.} these settings, the globe LED on the Fluksometer should light up. To further test your configuration, try surfing to \href{http://www.flukso.net}{www.flukso.net} while the ethernet cable is still connected to the Fluksometer.
+
+\begin{aside}{Art thou WAN or LAN?}
+\label{note:deploying_networkig_wan_lan}
+The default settings listed on the network page will mostly work just fine. Should this not be the case, it's important to understand which section on the network page applies to which interface. In wifi mode, the \emph{Local Network} or \emph{LAN} section refers to the ethernet interface while the \emph{Internet Connection} or \emph{WAN} section is associated with the wifi interface. So if you want to assign a fixed IP address to the wifi interface, then you should set the \emph{Protocol} for the \emph{Internet Connection} to \emph{manual} and fill in the additional form fields. Conversely, if you wish to change the IP settings on the ethernet interface, then the \emph{Local Network} section should be edited.
+
+We understand this configuration aspect will be the cause of some confusion. We however cannot apply the \emph{ethernet} and \emph{wifi} naming to these sections directly since they are swapped when toggling the Fluksometer into ethernet mode. The \emph{Internet Connection} will in this case refer to the ethernet interface and the \emph{Local Network} to the wifi interface.
+\end{aside}
+
+\subsection{Ethernet Mode}
+\label{sec:deploying_networking_eth}
+When the reporting mode is toggled to ethernet, the ethernet interface will be set as a DHCP client. The wifi interface will be disabled. Connect the Fluksometer's ethernet port to your network and find out which IP address it has been assigned by your DHCP server. Power up your Fluksometer and wait until the heartbeat LED starts to blink. The globe LED should now be on. Surf to the Fluksometer's ethernet IP address. No further network configuration steps should be required. In case you do need to change something, you should read note~\ref{note:deploying_networkig_wan_lan} first. 
+
+\section{Configuring Sensors}
+
+The sensor configuration will be synchronized with the Flukso server each time you save the sensor page. A synchronization can only be successful when the Fluksometer has internet connectivity.  You should therefore make sure the globe LED is lit before commencing this configuration step. If not, then goto section~\ref{sec:deploying_networking}.
+
+\subsection{Services}
+Your Fluksometer will by default be configured to report its measurements to the Flukso server. Clear the checkbox if you want to stop all communication with the Flukso server. Since no HTTP calls will be initiated to the server anymore, the globe LED will be turned off.
+
+The Fluksometer can make its sensor measurements available through a local JSON/REST API as well. While the Flukso server allows you to analyze your historical data and derive trend information, this local API is useful for monitoring your sensors in real-time. Sixty datapoints with a second resolution will be made available via the local API. No historical data is stored on the Fluksometer itself. Set the checkbox if you wish to enable the local API feature.
+
+\subsection{Current Clamp Setup}
+Select the number of phases that apply for your current clamp setup. When selecting 3 phases, the three current clamp ports will be grouped and presented as a single sensor \#1. Sensors \#2 and \#3 will be disabled automatically after saving. When selecting 1 phase, each clamp port will be sampled seperately and mapped to sensors \#1, \#2 and \#3 respectively.
+
+\subsection{Sensors}
+As already indicated in the previous section, a sensor is a \emph{logical} entity that can aggregate multiple \emph{physical} screw terminal ports as defined in section~\ref{sec:introduction_ports_screw}. Since the screw terminal contains a maximum of six ports, six sensors per Fluksometer will suffice. A sensor is defined by a unique identifier. Sensors can be enabled or disabled individually. Leave sensors in a disabled state when not in use. An enabled sensor requires a name. This name will be used in the Flukso website's charts. It's important that you assign a distinct name for each enabled sensor associated with your account. By convention, we use \emph{main} for total household electricity consumption and \emph{solar} for photo-voltaic production. When adding other users to your chart on the Flukso website, the main sensors will be the ones on display. A sensor can only contain ports of the same class. Ports that have different classes cannot be aggregated into a single sensor. We now introduce each of the three classes in turn:
+
+\begin{description}
+
+\item[Analog] Ports \#1, \#2 and \#3 are analog ports. They accept Flukso split-core current clamps of 50A, 100A, 250A and 500A. A three-phase setup requires all current clamps to be identical. Besides the current range, you can also specify the line voltage for each clamp. The default is 230V, which applies to the mains electricity voltage in most European countries. Australia and New-Zealand have a 240V power grid. Please consult this Wikipedia \href{http://en.wikipedia.org/wiki/Mains_electricity_by_country}{article} if you are unsure about your country's mains voltage.
+
+\item[Pulse] Ports \#4 and \#5 on the screw terminal are pulse ports. They are mapped to sensors \#4 and \#5 respectively. A meterconstant defines the amount represented by each pulse. For electricity, the unit is Wh per pulse while water is specified in dl per pulse.
+
+\item[Uart] The RS-485 port \#6 is mapped to sensor \#6. The baud rate is set to a fixed 115200.
+
+\end{description}
+
+\section{Securing the Fluksometer}
+
+Disconnect all cables from the Fluksometer. Now find a suitable location near the fuse box to install the device. Mounting holes have been provisioned on the back of the Fluksometer. Alternatively, you can use a plastic cable tie or velcro.
+
+\section{Attaching Current Clamps}
+
+For safety reasons, switch off the main electricity supply when installing the current clamps. Attach a clamp to each non-neutral line in the fuse box. Close the clamps firmly. You should hear a double click. The lip should lie flush with the clamp's body.
+
+\section{Connecting Sensor Clamp Cables}
+
+Connect a cable from each current clamp to the Fluksometer's screw terminal. Use the red wire for positive polarity and the black one for negative polarity. 
+
+\section{Powering Up}
+
+Switch the main electricity supply back on. Activate the Fluksometer by inserting its power plug.
+
+\section{Registering}
+
+Vist \href{http://www.flukso.net/user/register}{www.flukso.net/user/register} and fill in the form to create your account. Once logged in, you can associate the Fluksometer with your account. Click on the \emph{My account $\rightarrow$ Devices} tab and submit the Fluksometer's serial number. You should now see this Fluksometer added to the device list.
+
+Point your browser to \href{http://www.flukso.net}{www.flukso.net}. A first reading should be visible on the hour chart within five minutes from powering up.
+
+
+\section{Congratulations}
+
+You are now part of the Flukso community!

mote/v2/docs/manual/installing.tex

@@ -1,3 +0,0 @@
-\chapter{Installing}
-
-This is a placeholder for a real, yet-to-be-written installation guide.

mote/v2/docs/manual/introduction.tex

@@ -0,0 +1,47 @@
+\chapter{Introduction}
+
+Let's kick off this manual with a short tour of a Fluksometer's externals. We will introduce each of the Fluksometer's ports, buttons and LEDs. 
+
+\section{Ports}
+
+\subsection{Screw Terminal}
+\label{sec:introduction_ports_screw}
+The screw terminal contains twelve inputs. A \emph{port} on the screw terminal is defined as a \emph{pair of adjacent inputs}. We have printed the port numbers on the side of the enclosure for easy reference, with the polarity denoted by + and -. Ports 1 to 3 are analog ports that are tuned to accept Flukso split-core current clamps. Ports 4 and 5 can be used for detecting pulses. This includes support for, but is not limited to, the S0 interface\footnote{S0 is an open-collector interface standardized in DIN EN 62053-31} common to DIN-rail energy meters. Finally, port 6 offers a half-duplex RS-485 serial interface. Contrary to the other ports, the RS-485 port has its polarity indicated by the letters a and b.
+
+\subsection{Ethernet}
+The ethernet port offers support for a 10baseT/100baseTx interface with auto-negotiation and auto MDI/MDI-X crossover detection.
+
+\subsection{Power Jack}
+The center-positive power jack accepts a DC voltage between 9V and 15V. The switching adapter should have a minimum rating of 500mA output current.
+
+
+\section{Pushbutton}
+\label{sec:introduction_pushbutton}
+
+The pushbutton has a dual function. Which function will be triggered depends on how long the button is pressed.
+
+\begin{description}
+
+\item[Toggle reporting mode] If you press the button for 2 to 5 seconds, the Fluksometer will toggle its reporting mode to the Flukso server from wifi to ethernet or vice-versa.
+\item[Restore defaults] If you press the button between 10 and 30 seconds, the Fluksometer will restore its default network settings.
+
+\end{description}
+
+
+\section{LEDs}
+The Fluksometer has five red LEDs on the top of its enclosure. Together these LEDs provide us with an overview of the Fluksometer's internal functioning, the status of its network interfaces and its ability to communicate with the Flukso server. From left to right, these LEDs are:
+
+\begin{description}
+
+\item[Wifi] If the wifi interface is enabled, the wifi LED will blink. A fast blink rate [approx. twice per second] signals that no wifi connection can be established. A slow blink rate [once every three seconds] signifies that a wifi connection has been successfully set up.
+
+\item[Ethernet]	The ethernet LED will be on when an ethernet link is established. This can either be a 10baseT or 100baseTX link in full- or half-duplex mode.
+
+\item[Globe] After the Fluksometer has finished its boot sequence, the globe LED will be on when it can access the Flukso server. Every time the Fluksometer reports to the Flukso server, the LED will blink in case of a successful call. The globe LED will be turned off when the call is not completed successfully. A successful call has been made when either a 200 or 204 HTTP response code is returned by the Flukso server.
+
+\item[Heartbeat] The heartbeat LED is positioned right next to the globe led. While the globe LED informs us about the status of the Fluksometer's external communication, the heartbeat LED allows us to monitor the Fluksometer's internal functioning. This LED will be on when the sensor board is running its firmware. From the moment the Flukso daemon is started during the boot sequence, it will start polling the sensor board every second for data. Each poll triggers a blink of this LED, thus mimicking a real heartbeat. Hence, a 'heartbeat' is an indication of a Fluksometer that has booted, a running Flukso daemon, a sensor board running its firmware and proper communication between the main board and sensor board.
+
+\item[Power] The power LED is directly connected to the internal 3.3V supply. A burning LED indicates that power has been applied to the device and the internal voltage regulators are working properly.
+
+\end{description}
+

mote/v2/docs/manual/makefile

@@ -1,11 +1,28 @@
 BOOK=manual
+PREFACE=preface.tex
+DIR=out
+
+COMMIT=$(shell git rev-parse HEAD | awk '{print substr($$0,1,16)}')
+URL=https://github.com/icarus75/flukso/commit/$(shell git rev-parse HEAD)
+
+SITE=$(USER)@flukso.net:~/www/public/files/
 
 pdf:
-	pdflatex -halt-on-error $(BOOK).tex
-	pdflatex -halt-on-error $(BOOK).tex
+	mkdir -p $(DIR)
+	cp *.tex *.sty $(DIR)
+	sed -i 's,\\COMMIT,$(COMMIT),g' $(DIR)/$(PREFACE)
+	sed -i 's,\\URL,$(URL),g' $(DIR)/$(PREFACE)	
+	pdflatex -halt-on-error -output-directory=$(DIR) $(DIR)/$(BOOK).tex
+	pdflatex -halt-on-error -output-directory=$(DIR) $(DIR)/$(BOOK).tex
 
 view: pdf
-	evince $(BOOK).pdf	
+	evince $(DIR)/$(BOOK).pdf	
+
+publish: pdf
+	scp $(DIR)/$(BOOK).pdf $(SITE)
 
 clean:
-	rm *.aux *.out *.toc *.log *.pdf
+	rm $(DIR).aux $(DIR).out $(DIR).toc $(DIR).log $(DIR).pdf
+
+pristine:
+	rm -rf $(DIR)

mote/v2/docs/manual/manual.tex

@@ -3,7 +3,7 @@
 
 \title{
     The Fluksometer Manual\\
-    \textit{Installing, Troubleshooting, Hacking}
+    \textit{Deploying, Troubleshooting, Hacking}\\
 }
 \author{Bart Van Der Meerssche}
 \date{May 2011}
@@ -20,8 +20,8 @@
 
 \mainmatter
 
-%\include{introduction}
-\include{installing}
+\include{introduction}
+\include{deploying}
 %\include{troubleshooting}
 %\include{hacking}
 %\include{contributing}

mote/v2/docs/manual/preamble.tex

@@ -1,15 +1,15 @@
-\documentclass{book}
-\usepackage{iwona,palatino}
+\documentclass[a4paper]{book}
+%\usepackage{iwona,palatino}
 \usepackage{pastie}
 \usepackage[
-    pdftitle={The Fluksometer Manual: Installing, Troubleshooting, Hacking},
+    pdftitle={The Fluksometer Manual: Deploying, Troubleshooting, Hacking},
     pdfauthor={Bart Van Der Meerssche},
     pdfsubject={The Fluksometer Bible.},
     pdfkeywords={Flukso, monitoring, energy},
     bookmarks, bookmarksopen,
     pdfstartview=FitH,
     colorlinks,linkcolor=blue,citecolor=blue,
-    urlcolor=red,
+    urlcolor=blue,
 ]{hyperref}
 \usepackage{float}
 \usepackage{fancybox}

mote/v2/docs/manual/preface.tex

@@ -1,3 +1,3 @@
 \chapter{Preface}
 
-This is a placeholder for a real, yet-to-be-written preface.
+This version of the Fluksometer Manual is based on commit \href{\URL}{\COMMIT} of the Flukso Git repository.