Tidy Beaglebone Docs again.

Author: Dave Conway-Jones

docs/hardware/beagleboneblack.md

@@ -3,50 +3,53 @@ layout: default
 title: Running on BeagleBone Boards
 ---
 
-We recommend using the latest SD card images based on Debian Stretch - from https://beagleboard.org/latest-images
+We recommend using the latest Debian 9 Stretch based SD card images - from
+ <a href="https://beagleboard.org/latest-images" target="_new">beagleboard.org</a>.
 
 The 4GB images for BeagleBone boards already have Node-RED pre-installed and set to auto-start, so you can just boot
 and point your browser at your BeagleBone, port 1880.
 
 To view the Node-RED log
 
-        sudo journalctl -f -u node-red -o cat
+    sudo journalctl -f -u node-red -o cat
 
 To stop Node-RED
 
-        sudo service node-red stop
+    sudo service node-red stop
 
 To start Node-RED
 
-        sudo service node-red start
+    sudo service node-red start
 
 
-The 2GB console version suitable for flashing to older eMMC versions of the BBB will need to be installed as per below.
+The 2GB console version suitable for flashing to older eMMC versions of the BBB will need to be manually installed as per below.
 
 ---
 
 #### Upgrading
 
 The latest Debian images already have Node-RED and Node.js installed - the easiest way to upgrade is to use the built in upgrade tool:
 
-        sudo apt update
-        sudo apt upgrade nodejs bb-node-red-installer
+    sudo apt update
+    sudo apt upgrade nodejs bb-node-red-installer
 
 This should also restart the Node-RED service - but you will need to refresh any open browser sessions.
 
-If you are on the 2017 Debian 9.2 version you may need to run `sudo apt dist-upgrade` first.
+If you are on the 2017 Debian 9.2 version you may need to run `sudo apt full-upgrade` first.
 
 **Note**: Do NOT use the Raspberry Pi / Debian upgrade script (`update-nodejs-and-nodered`) as it will re-install
 both Node.js and Node-RED in different locations and will conflict with and break the existing systemd configuration files.
 
 ---
 
-#### Before you start
+### Manual installation
 
 <div class="doc-callout">
 This section is deprecated in favour of using the images with Node-RED built in. See above.
 </div>
 
+#### Before you start
+
 If you are using the 2GB eMMC version of Debian it has been stripped right down so you may need to install some
 utility functions first
 
@@ -68,7 +71,7 @@ We recommend using Node.js LTS 6.x or 8.x
     sudo apt-get install -y build-essential nodejs
     hash -r
 
-### Installing Node-RED
+#### Installing Node-RED
 
 The easiest way to install Node-RED is to use node's package manager, npm:
 
@@ -82,30 +85,27 @@ this flag avoids this - or rather, shows up any real errors instead.
 
 For other install options, e.g. to run in development mode from GitHub, see the [main installation instructions](../getting-started/installation#install-node-red).
 
-#### BBB specific nodes
+#### Beaglebone specific nodes
 
-There are some BBB specific nodes that give you direct access to the I/O pins in the simplest possible manner.
+There are some Beaglebone specific nodes that give you direct access to the I/O pins in the simplest possible manner.
 The easiest way to install them is direct from npm.
 
-For Debian based builds with kernel 4.x run the following commands in the user
-directory of your Node-RED install. This is usually `~/.node-red`
+To install manually run the following command:
 
     sudo npm install -g --unsafe-perm beaglebone-io johnny-five node-red-contrib-gpio
 
+*Note*: There is also a set of BBB specific nodes that can be used. However they are built on a no longer supported
+library (octalbonescript), and so are not recommended for future use, but are noted for having some extra capabilities
+beyond the generic gpio nodes.
 
-### Starting Node-RED
-
-Due to the constrained memory available on the BBB, it is advisable to
-run Node-RED with the `node-red-pi` command. For details and other options such
-as auto-starting on boot, follow the [Running Node-RED](../getting-started/running)
-instructions.
+    sudo npm install -g --unsafe-perm node-red-node-beaglebone
 
-To access the GPIO pins it is currently necessary to run as root :
+### Starting Node-RED
 
-    sudo node-red-pi
+Due to the constrained memory available on the Beaglebone boards, it is advisable to
+run Node-RED with the command:
 
-There are ways to avoid this using udev rules and groups and so on - but that is
-beyond the scope of this readme. Google is your friend.
+    node-red-pi
 
 #### Auto-starting