How to install JET/Hub Jan 2016
Installation… ah, the “joys” of modern computing!
To try out JET, you need:
- a Raspberry Pi, Odroid, OLinuXino, or similar ARM-based Linux board
- a working Linux setup on your particular board, e.g. Raspbian or Ubuntu
- the ability to login on your system via SSH over the network
- some basic familiarity with Linux and the “shell” command line
- a link to the latest JET release on GitHub: here it is …
- a bit of patience to skim through this setup guide (yep, go right ahead!)
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:
- or just google for “getting started with raspberry pi and ssh”, etc
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
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:
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
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:
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: “
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 “
~/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 -
When properly set up, you get some nice conveniences for use from the command line, such as:
jet- display JET’s exact version and build details
jet config- list the persistent configuration, i.e. all retained messages
jet pub <topic> <value>- a way to manually publish a message to MQTT
jet sub <topic>- subscribe to an MQTT topic (for example: “
jet sub '#'”)
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 “
instead of “
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)
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 “
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.