Add more docs & hardware guides

knolleary · knolleary · commit 406f368ee3e6 · 2013-09-08T22:51:40.000+01:00
diff --git a/_includes/docs-toc.html b/_includes/docs-toc.html
@@ -1,5 +1,18 @@
-<li><a href="/docs/index.html" {% if page.url == "/docs/index.html" %}class="active"{% endif %}><i class="icon icon-caret-right"></i> Documentation</a></li>
-<li><a href="/docs/getting-started.html" {% if page.url == "/docs/getting-started.html" %}class="active"{% endif %}><i class="icon icon-caret-right"></i> Getting Started</a></li>
-<li><a href="/docs/configuration.html" {% if page.url == "/docs/configuration.html" %}class="active"{% endif %}><i class="icon icon-caret-right"></i> Configuration</a></li>
-<li><a href="/docs/writing-functions.html" {% if page.url == "/docs/writing-functions.html" %}class="active"{% endif %}><i class="icon icon-caret-right"></i> Writing Functions</a></li>
-<li><a href="/docs/creating-nodes.html" {% if page.url == "/docs/creating-nodes.html" %}class="active"{% endif %}><i class="icon icon-caret-right"></i> Creating Nodes</a></li>
+<li><a href="/docs/index.html" {% if page.url == "/docs/index.html" %}class="active"{% endif %}>Documentation</a></li>
+<li><a href="#">Getting Started</a>
+<ul>
+  <li><a href="/docs/getting-started/installation.html" {% if page.url == "/docs/getting-started/installation.html" %}class="active"{% endif %}>Installation</a>
+  <li><a href="/docs/getting-started/running.html" {% if page.url == "/docs/getting-started/running.html" %}class="active"{% endif %}>Running</a>
+  <li><a href="/docs/getting-started/first-flow.html" {% if page.url == "/docs/getting-started/first-flow.html" %}class="active"{% endif %}>Creating your first flow</a>
+</ul>
+</li>
+<li><a href="/docs/configuration.html" {% if page.url == "/docs/configuration.html" %}class="active"{% endif %}>Configuration</a></li>
+<li><a href="/docs/writing-functions.html" {% if page.url == "/docs/writing-functions.html" %}class="active"{% endif %}>Writing Functions</a></li>
+<li><a href="/docs/creating-nodes.html" {% if page.url == "/docs/creating-nodes.html" %}class="active"{% endif %}>Creating Nodes</a></li>
+<li><a href="#">Hardware</a>
+<ul>
+  <li><a href="/docs/hardware/arduino.html" {% if page.url == "/docs/hardware/arduino.html" %}class="active"{% endif %}>Arduino</a>
+  <li><a href="/docs/hardware/raspberrypi.html" {% if page.url == "/docs/hardware/raspberrypi.html" %}class="active"{% endif %}>Raspberry Pi</a>
+  <li><a href="/docs/hardware/beagleboneblack.html" {% if page.url == "/docs/hardware/beagleboneblack.html" %}class="active"{% endif %}>BeagleBone Black</a>
+</ul>
+</li>
diff --git a/css/style.css b/css/style.css
@@ -97,14 +97,14 @@ ul.toc {
     padding: 0;
     border: 1px solid #ccc;
 }
-ul.toc li {
+ul.toc > li {
     border-bottom: 1px solid #ccc;
     background: #eee;
 }
-ul.toc li:last-child {
+ul.toc > li:last-child {
     border-bottom: none;
 }
-ul.toc li a {
+ul.toc li  a {
     padding: 8px 10px;
     display: block;
     width: 100%;
@@ -115,17 +115,26 @@ ul.toc li a:hover {
     text-decoration:none;
     background:#ddd;
 }
-ul.toc li a.active {
+ul.toc > li > ul {
+    margin: 0;
+    padding:0;
+    list-style-type: none;    
+}
+    
+ul.toc > li > ul > li {
+    border-top: 1px solid #dadada;
+}
+ul.toc > li > ul > li a {
+    padding: 6px 6px 6px 30px;
+}
+
+
+ul.toc > li  a.active {
     color: #fff;
     background: #a8a8a8; /* Old browsers */
-    background: -moz-linear-gradient(top,  #a8a8a8 0%, #676767 100%); /* FF3.6+ */
-    background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#a8a8a8), color-stop(100%,#676767)); /* Chrome,Safari4+ */
-    background: -webkit-linear-gradient(top,  #a8a8a8 0%,#676767 100%); /* Chrome10+,Safari5.1+ */
-    background: -o-linear-gradient(top,  #a8a8a8 0%,#676767 100%); /* Opera 11.10+ */
-    background: -ms-linear-gradient(top,  #a8a8a8 0%,#676767 100%); /* IE10+ */
-    background: linear-gradient(to bottom,  #a8a8a8 0%,#676767 100%); /* W3C */
-    filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#a8a8a8', endColorstr='#676767',GradientType=0 ); /* IE6-9 */
 }
+
+
 h3.pagetitle {
     padding-bottom: 5px;
     padding-right: 10px;
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,5 +1,4 @@
 ---
-toc-index: 2
 layout: default
 title: Configuration
 ---
diff --git a/docs/creating-nodes.md b/docs/creating-nodes.md
@@ -1,7 +1,10 @@
 ---
-toc-index: 5
 layout: default
 title: Creating Nodes
 ---
 
-To be written...
+Each node is defined in a pair of files; a `.js` file that defines the server-side
+behaviour and a `.html` file that defines the node's properties, edit dialog and
+help text.  
+
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,5 +1,4 @@
 ---
-toc-index: 1
 layout: default
 title: Getting Started
 ---   
diff --git a/docs/getting-started/first-flow.md b/docs/getting-started/first-flow.md
@@ -0,0 +1,73 @@
+---
+layout: default
+title: Creating your first flow
+---
+
+#### 1. Add an Inject node
+
+The Inject node allows you to inject messages into a flow, either by clicking
+the button on the node, or setting a time interval between injects.
+
+Drag one onto the workspace from the palette.
+
+Open the sidebar (Ctrl-Space, or via the dropdown menu) and select the Info tab.
+
+Select the newly added Inject node to see information about its properties and a
+description of what it does.
+
+#### 2. Add a Debug node
+
+The Debug node causes any message to be displayed in the Debug sidebar. By
+default, it just displays the payload of the message, but it is possible to
+display the entire message object.
+
+#### 3. Wire the two together
+
+Connect the Inject and Debug nodes together by dragging between the output port
+of one to the input port of the other.
+
+#### 4. Deploy
+
+At this point, the nodes only exist in the editor and must be deployed to the
+server.
+
+Click the Deploy button. Simple as that.
+
+With the Debug sidebar tab selected, click the Inject button. You should see
+numbers appear in the sidebar. By default, the Inject node uses the number of
+milliseconds since January 1st, 1970 as its payload. Let's do something more
+useful with that.
+
+#### 5. Add a Function node
+
+The Function node allows you to pass each message though a JavaScript function.
+
+Wire the Function node inbetween the Inject and Debug nodes. You'll need to
+delete the existing wire (select it and hit delete on the keyboard).
+
+Double-click on the Function node to bring up the edit dialog. Copy the follow
+code into the function field: 
+
+    // Create a Date object from the payload
+    var date = new Date(msg.payload);
+    // Change the payload to be a formated Date string
+    msg.payload = date.toString();
+    // Return the message so it can be sent on
+    return msg;
+
+Click Ok to close the edit dialog and then click the deploy button.
+
+Now when you click the Inject button, the messages in the sidebar will be more
+readable time stamps.
+
+***
+
+#### Source
+
+The flow created in this example is represented by the following json. It can be
+imported straight into the editor by pasting the json into the Import dialog
+(Ctrl-I or via the dropdown menu).
+
+
+    [{"id":"58ffae9d.a7005","type":"debug","name":"","active":true,"complete":false,"x":640,"y":200,"wires":[]},{"id":"17626462.e89d9c","type":"inject","name":"","topic":"","payload":"","repeat":"","once":false,"x":240,"y":200,"wires":[["2921667d.d6de9a"]]},{"id":"2921667d.d6de9a","type":"function","name":"Format timestamp","func":"// Create a Date object from the payload\nvar date = new Date(msg.payload);\n// Change the payload to be a formated Date string\nmsg.payload = date.toString();\n// Return the message so it can be sent on\nreturn msg;","outputs":1,"x":440,"y":200,"wires":[["58ffae9d.a7005"]]}]
+    
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -0,0 +1,57 @@
+---
+layout: default
+title: Installation
+---   
+
+*Eventually, Node-RED will be installable using npm. Until then, the following
+guide will help you get started.*
+
+### Install node.js
+
+You can get the latest version from <http://nodejs.org/download/>.
+
+Or, you may want to use a version from your operating system's package manager:
+ <https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager>
+
+### Get Node-RED
+
+Clone the repository from GitHub:
+
+    $ git clone git@github.com:node-red/node-red.git
+
+*TODO: once we have a release, point at the zip as well*
+
+### Install the pre-requisite modules
+
+From the top-level directory of Node-RED, run:
+
+    $ npm install
+
+This will install the core pre-requisite modules.
+
+### Installing individual node dependencies
+
+*Eventually, nodes will be npm-installable themselves. This will take care of
+all of the dependency management. Until then, it is a bit more manual...*
+
+When Node-RED starts, it attempts to load the nodes from the `nodes/` directory.
+Each will have its own set of dependencies that will need to be installed before
+the node is available in the palette.
+
+To help identify the dependencies, Node-RED logs any modules it fails to find
+for a particular node. You don't have to install these unless you want or need
+that node to appear.
+
+Alternatively, a node's `.js` file can be examined to identify the modules it
+explicitly requires. For example, the Twitter node is defined in
+`nodes/social/27-twitter.js` and contains:
+
+	var RED = require("../../red/red");
+	var ntwitter = require('ntwitter');
+	var OAuth= require('oauth').OAuth;
+
+Of these, `ntwitter` and `oauth` are neither built-in modules nor ones provided
+by Node-RED itself. They can subsequently be installed by running:
+
+    $ npm install ntwitter oauth
+
diff --git a/docs/getting-started/running.md b/docs/getting-started/running.md
@@ -0,0 +1,18 @@
+---
+layout: default
+title: Running
+---   
+
+From the top-level directory, run:
+
+    $ node red.js
+
+You can then access Node-RED at <http://localhost:1880>.
+
+By default, Node-RED uses a file called `flows_<hostname>.json` to save the
+deployed configuration. You can point to a different flow file at start-up:
+
+    $ node red.js my_flows.json
+
+
+
diff --git a/docs/hardware/arduino.md b/docs/hardware/arduino.md
@@ -0,0 +1,69 @@
+---
+layout: default
+title: Arduino
+---
+
+There are two main ways for interacting with an Arduno using Node-RED. They
+both assume the Arduino is connected to the host computer via a USB connection.
+
+***
+
+### Serial
+
+As the Arduino appears as a Serial device, the Serial in/out nodes can be used
+to communicate with it.
+
+*TODO: add example of sketch for Serial*
+
+***
+
+### Firmata
+
+[Firmata](http://firmata.org/) is a protocol for communicating between an
+Arduino (as well as other microcontrollers) and the host computer, providing 
+direct access to the IO pins.
+
+#### Installation
+
+First you need to load the default Firmata sketch onto the Arduino using the
+standard Arduino software download tools. This is usually found under 
+*Files - Examples - Firmata - Standard Firmata*.
+
+To ensure you have the Arduino nodes in the Node-RED palette, install the
+firmata npm module and restart Node-RED 
+
+    $ cd node-red
+    $ npm install firmata
+    $ node red.js
+
+#### Blink
+
+To run a "blink" flow that uses LED 13, copy the following flow and paste it
+into the Import Nodes dialog (*Import From - Clipboard* in the dropdown menu, or
+Ctrl-I). After clicking okay, click in the workspace to place the new nodes.
+
+    [{"id":"d7663aaf.47194","type":"arduino-board","repeat":"25","device":"/dev/ttyUSB0"},{"id":"8c09ca6c.a975d","type":"arduino out","name":"","pin":"13","state":"OUTPUT","arduino":"d7663aaf.47194","x":509.16667556762695,"y":162.16666984558105,"wires":[]},{"id":"e37b6a97.610968","type":"inject","name":"tick","topic":"","payload":"","repeat":"0.5","once":false,"x":116.16668319702148,"y":62.16666507720947,"wires":[["60b4aeaa.800d58"]]},{"id":"60b4aeaa.800d58","type":"function","name":"Toggle output on input","func":"\n// initialise level as a context variable if currently undefined \n// (context variables persist between calls to the function)\ncontext.level = context.level || false;\n\n// if it's a 0 make it a 1 else make it a 0...\ncontext.level = !context.level;\n\n// set the payload to the level and return\nmsg.payload = context.level;\nreturn msg;","outputs":1,"x":298.1666793823242,"y":113.16665458679199,"wires":[["8c09ca6c.a975d"]]}]
+
+This flow is set to use `/dev/ttyUSB0`. If you need to change that, double click
+the node labelled `Pin 13` - the Arduino node. Click the pencil icon and change
+the port definition as needed.
+
+Click the deploy button and the flow should start running. LED 13 should start
+toggling on and off once a second.
+
+#### Capabilities
+
+The Arduino output node currently supports three modes of operation:
+
+ - Digital - 0 or 1
+ - Analogue - 0 to 255
+ - Servo - 0 to 180
+
+The Arduino input node, available in the palette but not used in this example,
+can support both Digital and Analog pins. The input will send a message whenever
+it detects a change. This may be okay for digital inputs as they tend to be
+fairly stable, but analog readings often end up being at the full sample rate
+(default: 40 times a second...). This can be changed in the configuration of the
+serial port to reduce it to a more manageable rate.
+
+Details of the node.js firmata library can be found [here](https://github.com/jgautier/firmata).
diff --git a/docs/hardware/beagleboneblack.md b/docs/hardware/beagleboneblack.md
diff --git a/docs/hardware/raspberrypi.md b/docs/hardware/raspberrypi.md
diff --git a/docs/writing-functions.md b/docs/writing-functions.md

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-toc-index: 2`
`3`	`2`	`layout: default`
`4`	`3`	`title: Configuration`
`5`	`4`	`---`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-toc-index: 1`
`3`	`2`	`layout: default`
`4`	`3`	`title: Getting Started`
`5`	`4`	`---`