RIoT Control is a tool that automates the deployment of your Java code to a Raspberry Pi or similar device. It finds your device on a local network, copies your java archives to it, creates a service configuration file, and starts your application or sets it as a service.
Currently, it is only available as a plugin for the SBT build tool.
Creating an empty RIoT project
The easy way first: There's a template that will create an empty project that's already set up. After installing sbt, execute the following from your root git directory or similar:
sbt new riot-framework/streams.g8
Check the template's github template for more details.
Configuring your existing project to use RIoT Control
If you have an existing SBT project, add
sbt-riotctl to your
addSbtPlugin("org.riot-framework" % "sbt-riotctl" % "0.3")
RIoT Control depends on SBT's
JavaServerAppPackaging, and will only be active if you've enabled it in your
In general, RIoT Control will then try to use sane default for everything, including the host name, username, and password used to log in to your Pi (it will use Raspbian's defaults). If you need to override any of them, add the corresponding configuration to your project's settings in
build.sbt, for example:
lazy val root = (project in file(".")) .enablePlugins(JavaServerAppPackaging) .settings( // Deployment Targets (hostname, username, password): riotTargets := Seq( riotTarget("raspberrypi", "pi", "raspberry") ), // Port to use for remote debugging: riotDbgPort := 8000, // Packages and features needed by your code: riotPrereqs := "oracle-java8-jdk wiringpi", riotRequiresI2C := false, riotRequiresSPI := false )
Deploying your application
RIoT Control will deploy the files generated by SBT in the
stage directory, and use the scripts generated by
JavaServerAppPackaging to start your Application.
To copy your application to your device and run it:
Then press [Return] twice to terminate it.
To debug your application, similarly run:
and point your Remote Debugger to the device's address and the port defined in the
riotDbgPort setting (e.g.
If you want run the application in the background:
then stop it with:
Once you're happy with the result, you can enable the Service that RIoT has created for your Application, which will cause it to start automatically when your device boots:
To disable it, use the command:
In general, if issuing more than one command, it's considerably faster to start SBT in interactive mode:
then enter the commands above (without sbt, for example just
riotRun). This allows for quick development: Modify your code in the editor, then change to your terminal and execute
riotRun in the interactive SBT shell.
Many IDE have some sort of plugin to integrate with SBT, speeding up the development cycle even more.
Troubleshooting deployment issues
Problems tend to arise most often when installing prerequisite packages. This only happens during the first deployment of an Application, and may take a long time depending on the packages installed.
Out of memory when installing prerequisite packages
As the apt-get traffic is proxied through the installation tool (your Pi may not have internet access), it may run out of memory when downloading large packages (such as the Java JDK). The following error is an indication that this is happening:
[info] E: Failed to fetch http://debian.anexia.at/raspbian/raspbian/pool/main/o/openjdk-11/openjdk-11-jdk-headless_11.0.3+7-5_armhf.deb Connection failed [IP: 127.0.0.1 8080] [info] E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing?
If this is the case, make sure
sbt has enough memory. The easiest way to do this is to add a file named
.jvmopts in your project's root directory:
-Xms1024M -Xmx4096M -Xss2M -XX:MaxMetaspaceSize=1024M
Message 'Release file ... is not valid yet'
A freshly installed Pi without internet access will have a system date that is far in the past. RIoT tries to detect this and set the time to your development machine's time, but if this fails for some reason, subsequent package installations will fail with rather confusing messages such as:
[info] E: Release file for http://raspbian.raspberrypi.org/raspbian/dists/buster/InRelease is not valid yet (invalid for another 80d 10h 26min 56s). Updates for this repository will not be applied.
In this case, make sure your Pi's system clock is somewhat correct. It may help to wait for a while after the Raspberry Pi has booted, to allow it to synchronise to internet time sources or others.
What happens during deployment
RIoT control runs after
JavaServerAppPackaging, and uses the files it generates.
First, it checks that the prerequisite packages defined in the
riotPrereqs setting are installed (by default the JDK 8 and the WiringPi library), and otherwise installs them with
apt-get. A local SOCKS5 proxy is started locally through which
apt-get accesses the package repositories, so this step works even if your Pi has no direct internet access (this is often the case if it's connected directly to your laptop).
Then, it checks that certain features, such as SPI or I2C ports, are enabled, depending on the
stage directory is copied, in which
JavaServerAppPackaging has built or copied all JARs, and generated start scripts. The target directory on the Pi is
/usr/local/ followed by your project's name.
A systemd 'service unit configuration' file is generated in
/etc/systemd/system/ and named after your project (followed by
.service, as is the convention).
This systemd service is then started, stopped, enabled or disabled depending on the RIoT Control command issued.
How RIoT Control finds your Pi
RIoT Control will first try to access your Raspberry Pi by Hostname (e.g. if it is called 'raspberrypi', RIoT Control will attempt to connect to
If this fails, then RIoT Control will attempt to use mDNS (a service provided by Bonjour / Zeroconf) to discover an SSH service with the name provided. If your Raspberry Pi has the Avahi service installed and running (this is the case by default), it will publish its SSH port this way, as well as its current IP address.