How to Push Builds to a Raspberry Pi using Balena (Resin)

mitch

Would you like to be able to push builds to your Raspberry Pi without ever having to remove the SD card again? How about updating your cluster or robot army fleet with one simple command? This article will show you how, using a tool called git and two Web sites: github and balena (formerly resin.io).

How does the process work?

Before I walk you through the steps, let me give you a birds eye view of the process. I will provide detailed instructions below, where I will show you how to:

  • Create an account on balena.io
  • Use your balena dashboard to create what they call an "application"
  • Select what type of device your application will be hosted on (like a Raspberry Pi 3 B+)
  • Generate a disk image that you can download and burn to an SD card for your Pi fleet

Now wait a minute, didn't I say you would never have to deal with an SD card again? That is true. Once you plug the SD card into your Pi you won't need to remove it again to update your builds.

Do I have to create an application and download for every device?

No. Once you download that one image, you can burn it to as many devices as you want.

What about device naming?

Device names aren't burned into the image.

Does it support wifi?

Yes. When you setup an application, you can provide a username and password for your wifi network. When the Pi boots up it should connect to your network. That is why I always recommend testing the image with at least one Pi first - before burning it to several SD cards. In case there is a problem with the wifi settings.

How to deploy a build to your fleet

I will get into the details below, but sticking to the high level for now:

When you setup the SD image you can define how often to poll for a new build. The current default is every 10 minutes and you can't make it any lower (at least with the free version).

For a demo build, I'll show you how to install balena's simple NodeJS server example. Then you will be able to browse to your Pi to prove that it worked.

How to trigger a build

In the world of software there are a number of ways to trigger a build using a git repo or a site like github:

  • tag and release - push a new tag to a repo, triggering a build and release
  • push and release - any push to a branch triggers a build and a release
  • push to master and release - only a push to master triggers a release

This can also involve something known as a pull request and other external CI (continuous integration) services - but those subjects are beyond the scope of this article.

Balena uses a push to master and release approach. You clone a copy of your source code repo to their git servers. Then when you use git to push an updated master branch to their server, it triggers a new build. The next time members of your robot army poll for a new build, they will download the update.

Detailed Steps

Now that I've given you the high level view, it's time to get into the details.

Prerequisite

If you don't have a github account I would recommend creating a free one at https://github.com before proceeding.

Step 1: Create a free balenaCloud account

Free as in free

At the time of this writing, balena puts this message on their signup page:

"Your first ten devices are always free."
  1. Browse to https://www.balena.io
  2. Click on Signup - I recommend clicking "Login with GitHub", using the SSH key presented to you, etc.
  3. When you are done with signup, you should end up on your balenaCloud dashboard here: https://dashboard.balena-cloud.com

Step 2: Create an application

To create an application, do the following:

    1\. Set **Application Name**

For this tutorial, you can name the application desertbot.

    2\. Set **Device Type**

The balena description of an application may be a little confusing. When you define an application in balena you have to tie it to a particular device type (like Raspberry Pi 3). To deploy to a different type of hardware would require creating another application specific to a different device type.

    3\. Set **Application Type**

At the time of this writing the only free application type is Starter - so for this tutorial, select that.

    4\. Click **Create New Application**

Step 3: Add a device

Next you will be asked to add a device.

  1. Click Add device
  2. For Select Device Type - leave the default (Raspberry Pi 3)
  3. For Select BalenaOS Version - leave the selected default - usually the most recent and stable version
  4. For Select Edition lets keep things simple and select Production
  5. For Network Connection I'm using a Raspberry Pi 3 B+ which works on my internal 5G network. But if you are using an older Pi or dongle you may need to use your slower (2.4G) internal network.
  6. If you click Advanced you can see that the default is to check for an update only every 10 minutes. You can't set it any lower than that (at least for the free version).
  7. Click Download balenaOS

Step 4: Burn the image

  1. Put a Mini SD card that you can write over into your computer
  2. Install balenaEtcher

In previous articles I've shown how to use a tool called Etcher to burn the image to an SD card. The folks behind balena, also happen to be the folks behind Etcher. Etcher is now known as balenaEtcher and you can download the latest version from here:

I had an issue with the latest Mac installer where dragging balenaEtcher to my Mac's Application folder didn't work (it would try to drag the Application folder too - sort of like trying to pick something up and kicking it at the same time). So I had to scroll down the page and find a previous version of the installer to get it to work.

If you had a previous version of the older Etcher app, I would recommend deleting it and any aliases.

  1. Find the balenaEtcher app on your local drive and run it.
  2. Click Select Image (make sure you select the application image and not the etcher image if you just downloaded that too!)
  3. Click Flash and enter your password if prompted - then go get coffee
  4. Once the disk flashing is finished, eject.

Remember: there is nothing about the image that ties it to a device (like hostname). You can burn several cards using the same image and place them in several devices. But I would recommend testing one image first in a Pi, before burning several more.

Step 5: Put the SD card in your device

  1. Browse to your balenaCloud dashboard: https://dashboard.balena-cloud.com/apps
  2. Put the SD card into your Pi
  3. Plug in your Pi and watch your dashboard
  4. Hopefully the Pi will appear in a few minutes.

Troubleshooting

If the ACT (green) LED on your Pi is flashing 4 times, stopping, then repeating - that means it can't connect. Perhaps you entered the wrong wifi password?

Step 6: Deploy

To deploy the build to your devices, do the following:

1. Clone the demo app

Open up a terminal window and in a projects folder run this command:

git clone https://github.com/balena-io-projects/simple-server-node.git

2. Change into the projects directory:

cd simple-server-node

3. Add the balena remote

The dashboard creates a remote add statement at the top of your app that you can copy and paste to the command line in this format:

git remote add balena <USERNAME>@git.balena-cloud.com:<USERNAME>/<APPNAME>.git

So in MY case I would use the command below (replace gh_mitchallen with your balena username):

git remote add balena gh_mitchallen@git.balena-cloud.com:gh_mitchallen/desertbot.git

4. Deploy the code to all devices

git push balena master

You should see an ASCII unicorn on success!

If you look at the dashboard you should see your device status as "Updating."

When it is done it should say "Online."

Drill down on the device in the dashboard and expand the Logs view. You should see references to the project, a node command and a message that the app is listening on port 80.

5. Browse the app

Open up a browser and type in the ip address of the device that is shown in the dashboard.

Beyond Deployment

Now that I've covered the basics of how to deploy a build to a Raspberry Pi, here are a few extra things to know about:

Public URL

If you drill down in the dashboard for a device, you will see that there is an option to enable a public URL. That means that your Pi can be accessed from anywhere in the world. The URL has a format like this:

    *long unique number*__.balena-devices.com__

Unless you know what you are doing, I would recommend NOT doing that. I would want to avoid exposing my network to outside intruders or letting my Pi get hijacked as a crypto miner.

Identifying your device

If you have a fleet of devices and can't remember or figure out which is which, click the lightbulb icon in the balenaCloud dashboard for a device. This will cause the selected devices green LED to flash for 15 seconds.

Replacing the source code on the app

If you are just updating a fleet of devices with the same github repo, you just need to push your changes to update the devices.

But if you want to start over with a completely different repo you may need to use the --force flag when pushing for the first time from that repo:

git push balena master --force

Related articles

References

  • Get started with Raspberry Pi 3 and Node.js [1]