How to install JET/Hub Jan 2016

Installation… ah, the “joys” of modern computing!

1. Prerequisites

To try out JET, you need:

Because JET/Hub is going to run as an unattended background task (next to the MQTT server), we need to set up a few things to automate this process (marked in bold in the diagram below):

And since the idea is to make this as painless as possible: let’s get started!

2. Hardware setup

This will depend on what board you have and is beyond the scope of this guide, but here are some links you might want to check out to get going:

You need to get to a state where your board is running properly, is connected to the internet (because you’ll need to fetch a few files), and you are logged in with the ability to become “superuser” via sudo or su (again, because you’ll need to install a package into the system).

If Linux is new to you: there are lots of ways to get familiar with it, for example with this book.

3. Software setup

You’ll need to get two packages installed and running: the JET/Hub core and the MQTT server. Start with the latter: for MQTT, install a package called Mosquitto - it should be available as standard package, so on systems such as Raspbian, Debian, or Ubuntu, just run this command:

sudo apt-get install mosquitto

Press “y” when asked to accept the installation. If all goes well, Mosquitto will be installed and set up to automatically run in the background, also after reboots of the system.

Part two is to download and run the latest JET/Hub binary from the Releases page on GitHub. You should create a fresh directory, download the package, and unpack as follows:

mkdir ~/jet-v4
cd ~/jet-v4
wget <url-of-hub-linux-arm.gz>   # from the above Releases page
gunzip hub-linux-arm.gz
chmod +x hub-linux-arm
ls -l hub-linux-arm

That last command should produce output similar to this:

-rwxr-xr-x 1 jcw jcw 6664656 Jan 26 11:56 hub-linux-arm

That’s it. The essential parts of JET are now installed.

4. Starting JET for the first time

It’s time to launch the hub (Mosquitto will already be running, see above), and the first time around you should do it manually by entering this command:

./hub-linux-arm

Here is what should appear (this was done with a slightly older version):

2016/01/26 11:57:28 [JET/Hub] v4.0-2-gd80ce94 2016-01-26 (go1.5.3)
2016/01/26 11:57:28 connected as hub/384389 to tcp://localhost:1883
2016/01/26 11:57:28 opening data store: store.db

Are you seeing something similar? Then all is well - congratulations! If not, please verify all the above steps, and if you can’t fix the problem, get in touch via the Forum, Gitter, or GitHub.

At this point the hub is running, but if you press CTRL-c or log out, it will stop again.

5. Launching JET automatically

We need a more permanent setup, which doesn’t require login or manually starting up the JET system. One way to do this is via the “crontab” utility, which can set up commands to launch the moment the system starts up, even when you are not logged in.

Let’s edit our “crontab” entry (every user has a different one). Enter the following command:

crontab -e

An editor screen pops up, allowing you to edit text. Add the following line at the end of the file:

@reboot sleep 5 && cd ~/jet-v4 && ./hub-linux-arm 2>&1 >out.log

Then save these changes and exit the editor. With the default “nano” editor, instructions for this will be on-screen (to change the default editor: “update-alternatives --config editor”).

The “sleep 5” adds a little time for the rest of the system startup to complete (such as MQTT).

From now on, the hub will automatically start when you power up your board. Log output will be saved in a file called out.log (use “tail -f ~/jet-v4/out.log” to watch the latest output).

There’ll now be an MQTT server running in the background on port 1883.

6. JET admin utility

There is one last step to make it easier to tinker with a running JET system. See this example shell script - which is a special wrapper to control a running system, called - drumroll - “jet” !

When properly set up, you get some nice conveniences for use from the command line, such as:

More admin, control, and debugging options will be added once the hub’s functionality grows.

To set this up, create a little wrapper script called “jet” with the following contents:

#!/bin/sh
# jet -- Command-line admin interface to a running JET/Hub instance
# Note: this command never starts up a new hub, it's ONLY an admin front-end!
exec "$HOME/jet-v4/hub-linux-arm" -admin tcp://127.0.0.1:1883 "$@"

Then do “chmod +x jet” to make the script executable and move it to a directory on your $PATH (perhaps $HOME/bin), so you can use it as “jet“ instead of “./jet”.

This utility can also be used from a different machine, i.e. you can perform the above actions without logging in to your Linux box by adjusting the “-admin” arg to the remote IP address. Note that you’ll need to install a second copy of the hub, but built for the originating machine! (never mind if this doesn’t make sense yet - for local use the above instructions should be fine)

7. Security

Once installed, an internet connection is no longer strictly required, but at a minimum you’ll probably want to keep the local network enabled for SSH and web browser access (unless you use a keyboard and monitor, and attach all your devices directly to your board). JET will never connect to anything “out there”, nor accept any incoming connections - unless you tell it to.

JET does not require superuser privileges, but you may have to fix some permissions to enable permanent access to the serial ports (tip: try “sudo usermod -aG dialout <username>” if you run into this particular issue). JET should run fine with just standard user permissions.

The current JET setup does not have any access control. Authentication and TLS will be added later, both in MQTT (via Mosquitto’s config file) and in the hub.

Weblog © Jean-Claude Wippler. Generated by Hugo.