Installation… ah, the “joys” of modern computing!
1. Prerequisites
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:
- https://raspguide.wordpress.com
- https://github.com/raspberrypi/noobs#how-to-automatically-install-an-os
- 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 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
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
2016/01/26 11:57:28 starting HTTP server at localhost:8947
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 -http :8947 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).
The “-http :8947” option enables outside access to the hub’s web server on
port 8947.
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 be two servers running in the background: MQTT on port 1883 and HTTP on port 8947.
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:
jet- display JET’s exact version and build detailsjet config- list the persistent configuration, i.e. all retained messagesjet pub <topic> <value>- a way to manually publish a message to MQTTjet 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 file called “jet” with the example’s contents,
and adjust as follows:
- edit the file, changing the “PROG=…” line to
PROG=$HOME/jet-v4/hub - save and quit the editor, then make the script executable with:
chmod +x jet - consider moving the file to a dir on your $PATH for easy access from anywhere
- … otherwise you’ll only be able to run
jetby typing: “~/jet-v4/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 “MQTT=…” line to the target 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.