17 April 2019 / Last updated: 18 Apr 2019

Control your balenaDash display with a web browser & HTTP API

Execution time: 1hr - 2hr
Difficulty: Low
Cost: Low
We’re keeping things moving on the balenaDash project and have just added some additional features to the project. Now you can control the display with a web interface and API, and easily connect to new WiFi networks!
Now that the balenaDash project has been out in the wild for a while, we’re getting some great constructive feedback and contributions from everyone who’s built the project and used the display day-to-day. We’re going to take a quick look at a great contribution from balenaDash user Richard Morrison (@mozz100) who is the author of Tohora, which, in his words: ”puts balenaDash under the instant control of anything that can talk http. That includes Slack, and curl, and web browsers.”
We thought this addon was awesome and so asked Richard to create a pull-request (PR), adding his project to balenaDash in order for everyone to enjoy the new features. The great news is that Richard went ahead with this and so all you have to do to get this is update your display by pushing the code again! There’s no need to flash the SD card again and no need to venture out into the wilderness and physically plug anything into your display; due to the fact it’s running on balenaCloud, you can do everything remotely from the comfort of your own laptop.
If you have any feedback, issues or feature requests for the Tohora addon, make sure to let Richard know on GitHub or start a thread in the forums.

Step 1: Update your display to the latest version of the code

The first thing to do is update your device to the latest version of the balenaDash application (found on GitHub). This is done in the same way as the code was pushed when you first set the display up; you don't need to download the OS again, nor flash any SD cards, or even go near your display!
The beauty of balenaCloud means we can update the display (or displays!), no matter where they are in the world, from the comfort of our desks.
To update, either download the latest code from GitHub again via the zip file download, or via git pull and then push this to your application using the balena CLI (balena push <appName>) or git push as you did originally. If you need a reminder on how to do this, check back on our original balenaDash setup guide.
Once you've updated successfully you should be able to see the additional wifi-connect service showing on the device page in your balenaCloud dashboard.

Step 2: Access the web interface

Now that your display has been updated with the latest version of the code, you’ll be able to access the Tohora web interface on port 8080.
Important note: you can now use the "Public Device URL" feature of balenaCloud to access and control your balenaDash display from anywhere in the world. However, be aware the interface does not yet have authentication so it is recommended that you disable this when you're not using it to prevent unauthorised access.
To access the interface locally from the same network you can use the local IP address of the device as shown on the dashboard:
Remember that the interface runs on port 8080 which means you'll need to append :8080 to the end of the URL like so:
As mentioned, you can also use the public URL facility to access the web UI from anywhere, but remember that the device has no authentication so it's recommended to disable this if you aren't using it.

Step 3: Automate your display

In addition to the web UI, you can now programmatically make changes to your display by making POST requests with a url parameter to /launch/ from any other app/language that can communicate over HTTP.
Here's an example using curl:
curl -d "url=https://www.balena.io/fin" -X POST https://<Device IP address>:8080/launch/
There are other examples including Slack integration provided in the README on the Tohora GitHub repo.
Richard also wrote a blog post around his project which gives some interesting use cases including automatically showing the menu at lunchtime using a cron job!

One more thing…

Along with the update that adds the web UI and API functionality as described above, we’ve also implemented WiFi Connect and added it to the project.
WiFi Connect runs in the background on your display and periodically checks for a functional internet connection. If no connection is found, the device is turned into a WiFi hotspot/access point which offers an interface that allows you to choose a new network to connect to. For example, if you’ve moved the display to a friend’s house and their WiFi network name and password are different, WiFi Connect makes it simple to switch.
As you’ll know if you’ve deployed this project (or any other balenaCloud device) on WiFi, you first specify the desired WiFi network and credentials when you add the device in the dashboard and download the image. You can then update these credentials again if required using the web terminal, SSH or by mounting the SD card. WiFi Connect means you can do all of this from your phone or laptop in a few simple steps.

Step 1: connect to the balenaDash network

Note: the balenaDash network will only exist if the device does not have an active/functional connection to the internet!

Step 2: choose the new network from the captive portal interface

The captive portal interface should appear automatically when you connect from a mobile device, but if for some reason it doesn’t, you can access it by visiting the IP address of the device in a web browser using the device you've joined the balenaDash network with:

Step 3: profit enjoy!

It will take a few moments for your display to change back to client mode and attempt a connection to the network you've specified. If the connection is unsuccessful, the balenaDash network will be available for you to try again. Once your device is connected to the new WiFi network, the balenaDash network will disappear, and you can continue using your display as usual, with the benefit that you can now instantly and programmatically change between amusing YouTube videos (or other, more productive things)...

Thanks for reading! If you have any further ideas for functionality or have built your own, go ahead and submit an issue or pull request on GitHub; the new web UI functionality was built by a community member and we’d love to see more of what you can come up with. Otherwise, join us in the forums and let us know how the update went!
by Chris Crocker-WhiteHardware Hacker turned Product guy turned co-CEO

Share this post