Docs

Adding Your Device


DevGuide

Horizon Beta

Interested parties are encouraged to try Horizon on their own machines.  Currently ARM (32bit and 64bit), x86, and IBM Power8 architectures are supported.  To run Horizon on your own machine you will normally install our Debian Linux package.

If you are installing on Raspberry Pi 2 or Pi 3 devices, it is simpler to download one of our preconfigurd Raspbian-based Images and just flash it.

Instructions below will guide you through installation of Horizon based on your variety of machine.  The links below will jump ahead to the instructions for that machine type:

If you wish to bring any other device not listed here onto Horizon, please contact the Horizon community by clicking the Forum tab at the top of this page.

 

ARM 32 bit, Raspberry Pi:

Hardware Requirements

  • Raspberry Pi 3 (recommended)
  • Raspberry Pi 2
  • MicroSD flash card (32GB recommended)
  • An appropriate power supply for your machine.  At least a 2 Amp power supply is recommended (and please note that more than 2 Amps may be required if power-hungry USB peripherals are being powered from your Raspberry Pi).
  • An internet connection for your machine, wired or WiFi (and please note that the Pi 2 will require additional hardware for WiFi)
  • Sensor hardware (optional, but most Horizon-Insight applications require optional special-purpose sensor hardware.  For example, Software Defined Radio (SDR) Insights require an SDR USB dongle with an antenna. However, Horizon's Netspeed application requires no additional hardware.  Please see our full hardware list to discover appropriate Raspberry Pi sensor hardware options.)

Procedure

  • Follow this link to download the appropriate MicroSD flash image for your Raspberry Pi model (and optionally verify its cryptographic hash)
  • Decompress the flash image (it is provided as a compressed "zip" archive)
  • Flash the image onto your MicroSD flash card (the Raspberry Pi Foundation provides good instructions for doing this for many platforms).  PLEASE NOTE: This flashing step will completely erase the MicroSD card and write the Horizon image onto the card.
  • Edit your flashed image to provide appropriate WPA2 WiFi credentials (unless you will be using a wired network connection):
    • Find and edit the file wpa_supplicant_cred.txt in the MicroSD card's top level folder
    • Add your WiFi credentials (i.e., your network's SSID name and your passphrase) using the format shown below.  That is, edit the example text below to replace YourSSID and YourPassphrase with values appropriate for your network.  PLEASE NOTE: Omit quotes for these fields, even if your SSID or passphrase contain spaces or tabs!
    wpa_ssid=YourSSID
    wpa_passphrase=YourPassphrase
    • Save and close the file.

 

  • Unmount the image properly (safely eject) so all of your changes will get written
  • Insert the MicroSD card into your Raspberry Pi, attach any optional sensor hardware (see above), then connect the power supply

Change The Default Password:

  • Once your Pi boots up, you are strongly advised to immediately change the default password.
  • In the Horizon Raspberry Pi flash images, the default account uses login name: "root", and has password: "horizon".
  • Login to this account then use the standard Linux passwd command to change the password, e.g.:
$ passwd
Enter new UNIX password: ...
Retype new UNIX password: ...
passwd: password updated successfully
$

Continue to the "Registering Your Horizon Machine" section below.

 

ARM 64 bit, NVIDIA Jetson:

Hardware Requirements

  • NVIDIA Jetson TX2 (recommended)
  • NVIDIA Jetson TX1
  • HDMI Monitor, USB hub, USB keyboard, USB mouse
  • Storage: >10GB (SSD recommended)
  • An internet connection for your machine (wired or WiFi)
  • Sensor hardware (optional, but most Horizon-Insight applications require optional special-purpose sensor hardware.  For example, Horizon Aural Insights require USB sound card, analog microphone, and headphones or speaker hardware, and Horizon Eye Insights require webcam hardware.  However, Horizon's Netspeed application requires no additional hardware.  Please see our full hardware list to discover appropriate Raspberry Pi sensor hardware options.)

 

Procedure

  • Begin by using these links to open source instructions, for TX1, or for TX2, to get the current NVIDIA JetPack installed on your machine.  These links also include instructions for setting up Docker and other prerequisites you will need before installing the Horizon software.
  • The steps below expect you to have root privileges, so if you are logged in as the nvidia user, execute this to begin:
    sudo -s
    
  • Now configure apt to be able to install the latest stable version of Horizon:
    wget -qO - http://pkg.bluehorizon.network/bluehorizon.network-public.key | apt-key add -
    
    cat <<EOF > /etc/apt/sources.list.d/bluehorizon.list
    deb [arch=arm64] http://pkg.bluehorizon.network/linux/ubuntu xenial-updates main
    deb-src [arch=arm64] http://pkg.bluehorizon.network/linux/ubuntu xenial-updates main
    EOF
    
    apt-get update
    
  • Install the latest Horizon software:
    apt-get install -y horizon bluehorizon bluehorizon-ui
    
  • Configure Horizon workload logging (recommended)
    cat <<'EOF' > /etc/rsyslog.d/10-horizon-docker.conf
    $template DynamicWorkloadFile,"/var/log/workload/%syslogtag:R,ERE,1,DFLT:.*workload-([^\[]+)--end%.log"
    
    :syslogtag, startswith, "workload-" -?DynamicWorkloadFile
    & stop
    :syslogtag, startswith, "docker/" -/var/log/docker_containers.log
    & stop
    :syslogtag, startswith, "docker" -/var/log/docker.log
    & stop
    EOF
    service rsyslog restart
  • Start the Horizon service:
    systemctl start horizon.service
    
  • At this point you no longer require root privileges, so can exit this privileged shell and return to running as the nvidia user:
    exit
    

Change The Default Password:

  • Once your NVIDIA TX2 or TX1 is up, you are strongly advised to immediately change the default password.
  • In the JetPack installation procedure the default account uses login name: "nvidia", and has password: "nvidia".
  • Login to this account then use the standard Linux passwd command to change the password, e.g.:
$ passwd
Enter new UNIX password: ...
Retype new UNIX password: ...
passwd: password updated successfully
$

Continue to the "Registering Your Horizon Machine" section below.

 

x86 Machines:

Hardware Requirements

  • 64 bit Intel or AMD machine or VM
  • An internet connection for your machine (wired or WiFi)
  • Sensor hardware (optional, and note that currently only Horizon's Netspeed insight application, which requires no additional sensor hardware is supported on x86 machines, although some of the other Horizon-Insight applications may work with appropriate sensor hardware and configuration)

Procedure

  • Install a recent Debian Linux variant (e.g., ubuntu 16.04, which is used for the instructions below)
  • Configure apt to be able to install the latest stable version of Horizon:
wget -qO - http://pkg.bluehorizon.network/bluehorizon.network-public.key | apt-key add -

cat <<EOF > /etc/apt/sources.list.d/bluehorizon.list
deb [arch=amd64] http://pkg.bluehorizon.network/linux/ubuntu xenial-updates main
deb-src [arch=amd64] http://pkg.bluehorizon.network/linux/ubuntu xenial-updates main
EOF

apt-get update
  • Install the latest Horizon software:
apt-get install -y horizon bluehorizon bluehorizon-ui
  • Configure Horizon workload logging (recommended)
cat <<'EOF' > /etc/rsyslog.d/10-horizon-docker.conf
$template DynamicWorkloadFile,"/var/log/workload/%syslogtag:R,ERE,1,DFLT:.*workload-([^\[]+)--end%.log"

:syslogtag, startswith, "workload-" -?DynamicWorkloadFile
& stop
:syslogtag, startswith, "docker/" -/var/log/docker_containers.log
& stop
:syslogtag, startswith, "docker" -/var/log/docker.log
& stop
EOF
service rsyslog restart
  • Start the Horizon service:
systemctl start horizon.service

Continue to the "Registering Your Horizon Machine" section below.

 

IBM Power8 Machines:

Horizon is moving toward support for cognitive and deep learning supercomputing platforms including the IBM Power8 Architecture with NVIDIA's PASCAL GPU.  Horizon has been tested and is running on a Power S814, 8 core machine, with 1TB RAM.

Begin by following these setup instructions for IBM Power8, then...

Continue to the "Registering Your Horizon Machine" section below.

 

Additional Platforms

Horizon is always extending the system to run on additional platforms. For more details on current beta development including participation with us, or just to get up to speed on our latest, contact us at our Discourse Forum.

 

Registering Your Horizon Machine

Once you have installed the Horizon software (using the instructions above) it will take a few minutes to get up and running.  It will usually take less than 10 minutes.  Once Horizon is running you can register and add your machine onto the Horizon network.  There are currently 2 ways to register:

Each of these approaches is described below.

 

Using the CLI to Register on Horizon

Optionally, it is recommended that you begin by verifying that Horizon has had time to come up and is "active" by running this command:

systemctl status horizon.service

The output of that command should contain lines similar to this:

 * horizon.service - Service for Horizon control system (cf. https://bluehorizon.network)
   Loaded: loaded (/etc/systemd/system/horizon.service; enabled)
   Active: active (running) since Thu 2017-07-06 13:35:54 UTC; 36min ago

Optionally, you may also wish to verify the version of Horizon on your machine:

dpkg -l | grep horizon
  ii  bluehorizon                     2.13.9~ppa~raspbian.jessie   armhf        Configuration for horizon package to use Blue Horizon backend
  ii  bluehorizon-ui                  2.13.9~ppa~raspbian.jessie   armhf        Web UI content for Bluehorizon instance of the Horizon platform
  ii  horizon                         2.13.9~ppa~raspbian.jessie   armhf        The open source version of the Horizon platform

The version should be 2.13.9 or later.

First you need to register your edge machine as a "node" in the Horizon Exchange.  You need a user account in the Horizon Exchange to do this, but if you are just using the "public" organization, an account will be created for you automatically when you register your new node.  You can make up any node ID, any node token (i.e., a password for this node), any username, and any password, and you must provide an email address as well, then run the "hzn exchange node create ..." command as shown below:

export NODE_ID=_____
export NODE_TOKEN=_____
export USERNAME=_____
export PASSWORD=_____
export EMAIL="_____@____.com"
hzn exchange node create
-u $USERNAME:$PASSWORD -e $EMAIL -n $NODE_ID:$NODE_TOKEN -o public

To register your edge machine you will need to select the deployment pattern that you wish to run on this machine.  You can list the available patterns for the "public" organization by passing your Horizon Exchange credentials in the command shown below:

hzn exchange pattern list -o public -u $USERNAME:$PASSWORD

Select an appropriate pattern from this list based upon the variety of edge machine you will be registering, and the hardware peripherals it has attached.  Depending upon the pattern you select, you may also need to provide configuration details required by that pattern.  For example, to run the public pattern "netspeed-arm" (appropriate only for ARM architecture machines) you must provide the location information it requires.  To do this you would create a file, say ./input.json containing something  like the following.  This example registers a machine near San Jose, California, USA (at GPS coordinates 37.0, -121.0) and specifies that the location of the machine should always be obfuscated somewhere within a radius of 5.0 km from the actual location before being shared:

{
  "global": [
    {
      "type": "LocationAttributes",
      "variables": {
        "lat": 37.0,
        "lon": -121.0,
        "use_gps": false,
        "location_accuracy_km": 5.0
      }
    }
  ]
}

In the current directory, create the input.json file shown above (but with the values shown in bold above changed to reflect your own location).  This input file is specific to the netspeed-arm pattern.  When that file is ready, use the command shown below to deploy this pattern onto your edge machine

export PATTERN=netspeed-arm
hzn register -n $NODE_ID:$NODE_TOKEN -f ./input.json public $PATTERN

Once the hzn register command succeeds without error, then the Horizon AgBots will be able to find it, and will begin trying to establish agreements with it.  You can check the configuration and current status of Horizon on your edge machine with the commands shown below and very soon you should see an agreement showing up, then shortly after that the docker containers for that agreement should start running:

hzn agreement list
hzn service list
hzn workload list

Note that you can get more detailed instructions for the hzn command by passing "--help", e.g.:

hzn --help

You can also get detailed instructions for hzn subcommands (like "register" by passing "--help", e.g.:

hzn register --help

Your machine Is now registered on Horizon!  Please continue to the "Welcome to Horizon!" section below.

 

Using a Web Browser to Register on Horizon

Please follow the steps below to register your machine with your browser:

1. Discover the IP address of your edge machine

Once your machine has booted, you need to discover its IP address on your local network.  You can do that in one of these ways:

  • Get it from your local router: If you have access to your router's web interface, you may be able to discover your edge machine's IP address or its Bonjour name.  These are usually found on a page listing the current DHCP client leases, or showing a list of currently attached devices.  Alternatively, if you have access to your router console, you may be able to use its command line interface to discover the device IP address of your edge machine.
  • Using the machine's CLI interface:  You can use the standard Linux `/sbin/ifconfig` command to find your machine's IP address.  This command should produce output similar to this:
$ /sbin/ifconfig
docker0   Link encap:Ethernet  HWaddr 56:84:7a:fe:97:99
          inet addr:172.17.42.1  Bcast:0.0.0.0  Mask:255.255.0.0
          inet6 addr: fe80::5484:7aff:fefe:9799/64 Scope:Link
          UP BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:12246 errors:0 dropped:0 overruns:0 frame:0
          TX packets:22770 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:679260 (663.3 KiB)  TX bytes:34290689 (32.7 MiB)

eth0      Link encap:Ethernet  HWaddr b8:27:eb:74:90:78
          inet addr:192.168.1.3  Bcast:192.168.123.255  Mask:255.255.255.0
          inet6 addr: fe80::ba27:ebff:fe74:9078/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:1235545 errors:0 dropped:23425 overruns:0 frame:0
          TX packets:108101 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:188991545 (180.2 MiB)  TX bytes:70163573 (66.9 MiB)
 
lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:65536  Metric:1
          RX packets:6 errors:0 dropped:0 overruns:0 frame:0
          TX packets:6 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:448 (448.0 B)  TX bytes:448 (448.0 B)

The example above shows a machine connected with a wired connection on the interface named eth0. The IPv4 address of this machine is shown in the inet addr field under this interface (in the example above that is, 192.168.1.3).  For a machine using a wireless network, the IP address might be shown under the wlan0 interface.  Interface names can vary a lot, but it is usually straightforward to scan this output and find any address on your local area network (all of the IPv4 addresses on your local area network will most likely contain the same first 3 numbers (e.g., 192.168.1. in the example shown above) so simply scan this output to try to find this prefix and you will see the address of your machine.

2. Visit the Horizon Registration Page on your edge machine

  • Use a web browser on a computer on your local network to navigate to the Pi's registration page at its IP address.

http://[your_device_IP]/

  • For the above example device, with address 192.168.1.3, you would use:

http://192.168.1.3/

  • The registration page should look similar to the image below: 

Horizon Registration Page
 

  • Register your device on the Horizon exchange:
    • Provide a Username, Password, and Email Address.  If this is your first registration on Horizon, a user account with these credentials will be created for you when you register this machine.
    • Choose an Edge Node Name for your device to use instead of the more complex Edge Node ID of your edge machine, based on its hardware serial number ("0000000123456789" in the example above).
    • Once you've filled in these details, click "Continue" and you will be taken to the next screen.
  • Specify a location for your device:

The next (Setup) page should contain an "Edge Node Location" pane similar to the one shown below:

Edge Node Location
 

Here you can state the location of your edge machine, in GPS coordinates. These coordinates will be automatically pre-populated using GeoIP for an approximate location based on information provided publicly by your internet service provider.  Refine the coordinates if you wish (e.g., you could use Google to search for the precise GPS coordinates of any address).  You may also choose how much location obfuscation should be done by specifying a "Location Accuracy" in kilometers.  If this field is nonzero, then instead of sharing your exact specified location, Horizon will compute a random location within the specified distance of your location, and will share that randomized location with workloads on the device (to protect the privacy of your real location).

  • Additional Node Setup:

On the Setup page you will also see other configuration panes like the ones shown below:

More Node Setup

If you have GPS hardware connected to your device, you can choose to turn on the "Share GPS location data" toggle.  With GPS enabled, your actual realtime location coordinates will be shared with workloads, and updated on the public Blue Horizon map.  That is, when this toggle is enable, no obfuscation of your actual location will be done by Horizon.

Optionally, you may enable Blockchain recording of the agreements this device participates in.

Currently, only "pattern registration" is supported, so that switch must remain on.  Soon we will resume support for regsitration of individual workloads.

When you are ready, tap "Continue" to proceed to the next page.

  • Select a Horizon pattern to apply to your edge machine:

The "Select a Pattern" page should look similar to the image shown below:

Select Pattern

On this page, use the pulldown menu to reveal the set of patterns available, and select one appropriate for your device, based on the additional hardware you have attached, and your preferences for sharing.  For example, if you have a Software Defined Radio (SDR) USB stick attached to your machine and you wish to provide location data, and run the Horizon Insight applications for Netspeed and SDR, then you could select the third pattern shown.

Make your selection then a new pane will open below, showing details for the selected pattern.

  • Confirm the pattern details:

Once you select a pattern you should see a pane similar to the image shown below, with the pattern you chose for your machine displayed at the top, and showing all of the Horizon Workloads that will be installed, and all of the Horizon Microservices that will be installed to support those Workloads:

Selected Pattern

Review these details, and click confirm to submit your pattern registration to Horizon for this machine.  This will take you to the Status page.

  • Observe your edge machine's configuration and status:

The Status page will look something like the image below.  On it you will see the easy-to-remember name you specified for your machine at the top left, and boxes for each of the agreements being offered by your machine to Horizon consumers.  Initially each of the boxes will show a status tab at the top right that says "Available for Agreement" as shown below:

Available For Agreement

Very quickly (typically within seconds) you should see the status tabs on these agreements changing.  When a proposal is received from a remove host for one of the agreements, the status of that agreement will change to "Agreement Proposed".  When this edge machine accepts an agreement, the status tab will show, "In Agreement".  The other fields in the box will become populated with dates times and other status as the agreement proceeds, software for the agreement is downloaded, cryptographically verified, and installed.  Once that software starts running, the status tab will transition to "Executing".  After some time all of the agreements should be in this state and depending on the type of agreement, additional information may be shown.  The image below shows the status page a few hours after registration:

Agreements Executing

Your machine Is now registered on Horizon!  Please continue to the "Welcome to Horizon!" section below.

 

Welcome to Horizon!

Once your machine registration and pattern assignment is completes, the Horizon AgBots discover your edge machine, propose agreements, and monitor their progress once your machine accepts them.  You should never again need to connect directly to the machine to insteall or update its software.  The "Horizon Insights" (in the pattern you selected) will now begin contracting with your device through the Horizon Exchange.  Once your device is in agreement, Horizon Microservices and Workloads (running in Docker containers) will be downloaded and will begin to run. Your device will soon be running the Horizon Insights you specified.

Soon your machine will be visible on the Horizon Unified Map.  Once you see your "dot" appear on that map, tap on it, and then select any of the Horizon Insight icons that appear (one for each of the Horizon Insights in your pattern).  When you select a Horizon Insight icon you will be taken to a page for that Horizon Insight where you can, for example, see visualizations of the data being sent from your machine, or interact directly with the hardware on your edge machine (depending upon the particular Horizon Insights you have selected).

Questions, Troubleshooting

If you have any difficulties with any of these steps, please contact the Horizon community for help by clicking on the Forum tab at the top of this page.  You can also report Horizon bugs in the forum.