Improve this doc
I want to get started with a using

Get started on developing with BeagleBone Black and C++

In this guide we'll cover:

  • Setting up your BeagleBone Black device and bringing it online on the balenaCloud dashboard
  • Deploying a C++ hello-world project on the device
  • Developing the sample project: making changes and testing them on the device in real-time

Once you've completed this guide you'll be equipped with the fundamentals needed to continue developing your application using balenaCloud and be on the path to deploying fleets of devices to production.

What you'll need

  • A Beaglebone Black or Beaglebone Green.
  • A 4GB or larger SD card. Both the Beaglebone Black and Green use a Micro SD card. The speed class of the card also matters - this determines its maximum transfer rate. We strongly recommend you get hold of a class 10 card or above.
  • An ethernet cable or WiFi adapter to connect your device to the internet. The WiFi adapter for the Beaglebone Black is known to be unstable at moment, it is recommended that you use a usb WiFi adapter with a large external antenna.
  • A mini USB cable the Beaglebone Black OR a micro USB cable for the Green.
  • [Optional] A 5VDC 1A power supply unit for the Beaglebone Black.
  • A balena account.

Note: Always run the board from 5VDC 1A minimum supply when using a WiFi Dongle. You may need to use a extension cable to move the dongle away from the planes of the PCB. We also have had instances where when placed in a metal case, there can be WiFi issues as well. It will also help to use a dongle with a real antenna on it.

Create a fleet

If you don't already have a balena account, make sure to sign up before continuing.

A fleet is a group of devices that share the same architecture and run the same code. Devices are added to fleets and can be moved between fleets at any time.

To create your first fleet, log into your balenaCloud dashboard and click the Create fleet button.

Create a fleet

Enter a fleet name, select the BeagleBone Black device type, choose the Starter fleet type, and click Create new fleet:

You'll then be redirected to the summary of the newly created fleet, where you can add your first BeagleBone Black.

Add a device and download OS

Add a device

To connect with balenaCloud, your BeagleBone Black needs a balenaOS image configured for your device type, fleet, and network. Start by clicking Add device in your fleet dashboard:

Add new device

Select an OS type of balenaOS, and you will see a list of available balenaOS versions with the latest preselected. Choose a Development version of the OS. The production OS does not facilitate the development workflow we'll be using. Find out more about the differences between Development and Production images.

Network configuration

Select the type of network connection you'll be using: Ethernet Only or Wifi + Ethernet. A network connection is required to allow the device to connect to balenaCloud. Selecting Wifi + Ethernet allows you to enter a Wifi SSID and Wifi Passphrase which is then built into the image.

Download Image

Finally, click the Download balenaOS button. When the download completes, you should have a zipped image file with a name like balena-First-Fleet-beaglebone-black-2.80.3+rev1-v12.7.0.img.zip.

Provision device

Locate the image file you downloaded and flash it to the SD card using Etcher. Etcher will prepare a bootable SD card and safely eject it when complete.

Put the SD card into your device, and connect either the ethernet cable or WiFi adapter. Now hold down the small black button marked s2 (located near the SD card slot) and power up the device by inserting the power or USB cable.

You should only need to hold the button down for about 5 seconds until the blue LEDs start flashing like crazy. Basically, by holding down the button, we are telling the Beaglebone that we want to boot from the SD card instead of the onboard flash. From there, the OS which is on the SD card is flashed onto the internal eMMC memory.

Warning: This will completely overwrite any data on your devices' internal eMMC, so make sure to make a backup of any important data.

After a short while you should see your device pop up in the dashboard. It will appear in a configuring state as it flashes balenaOS to the internal media. This step can take a little time.

After the internal media has been flashed, your device will shut itself down. At this point you will see the device in a Post-Provisioning state and all its LEDs should be off. Before booting the device again, make sure to remove the SD card. You may then simply press the power button situated nearest to the ethernet port or pull out and replug the power cable.

Your device should now start booting from internal eMMC and in a minute or so you should have a happy Beaglebone device in the Idle state on your dashboard. From here on you can deploy code to your device with ease.

Note: If you have an HDMI screen attached, you should see balena logo on the screen when the device boots. If instead you see rainbow colors or a blank screen, it could mean that the SD card was not burned correctly or is corrupted. Try burning the SD card again. If the issue persists, come and get help from our support team.

Install the balena CLI

Now that a device online in your fleet, it's time to deploy some code. We will use the balena CLI for this. Follow the instructions below to install balenaCLI for the operating system available on your system.

  1. Download the CLI installer.
  2. Double click the downloaded file to run the installer and follow the installer's instructions.
  3. To run balena CLI commands, open the Terminal app (Terminal User Guide).

  1. Download the CLI installer.
  2. Double click the downloaded file to run the installer and follow the installer's instructions.
  3. To run balena CLI commands, open a command prompt: Click on the Windows Start Menu, type PowerShell, and then click on Windows PowerShell.

  1. Download the standalone CLI.
  2. Extract the contents of the zip file to any folder you choose, for example /home/james. The extracted contents will include a balena-cli folder.
  3. Add that folder (e.g. /home/james/balena-cli) to the PATH environment variable. Check this StackOverflow post for instructions. Close and re-open the terminal window so that the changes to PATH can take effect.

For more detailed information, visit the detailed Linux installation instructions.


After balena CLI is installed, login to your balena account using the balena login command on the terminal:

$ balena login
 _            _
| |__   __ _ | |  ____  _ __    __ _
| '_ \ / _` || | / __ \| '_ \  / _` |
| |_) | (_) || ||  ___/| | | || (_) |
|_.__/ \__,_||_| \____/|_| |_| \__,_|


Logging in to cloud.com
? How would you like to login? (Use arrow keys)
❯ Web authorization (recommended)
  Credentials
  Authentication token
  I don't have a balena account!

You will be asked to choose an authentication method, choose Web authorization which will bring up a web browser window that allows you to login to your balenaCloud account. Click the Authorize button, and head back to the terminal after the login successful message appears.

Web authorization

Create a release

After login, test the balena CLI by running the balena fleets command, which should return information about the fleet you created in the previous step. Take a note of the FLEET NAME as you'll need this in the next step to push the code to your device(s) in that fleet.

$ balena fleets
ID    FLEET NAME   DEVICE TYPE          ONLINE DEVICES DEVICE COUNT
98264 First-Fleet  BeagleBone Black   0              0

A nice project to try is the balena-cpp-hello-world project. It's a C++ web server that serves a static page on port 80. To get started, download the project as a zipped file from GitHub, unzip it and open a terminal in the root of the extracted project directory.

To create a release, use the balena push First-Fleet command replacing First-Fleet with the name of your fleet. Ensure you are working from the root of the extracted project directory.

$ balena push First-Fleet

This command pushes the code to the balena builders, where it will be compiled, built, turned into a release, and applied to every device in the fleet.

You'll know your code has been successfully compiled and built when our friendly unicorn mascot appears in your terminal:

[hello-world]  Successfully built 51bd190f7530
[Info]       Generating image deltas from release 8acfdc579f7cb0fe424d1b800588b6f5 (id: 2186018)
[Success]    Successfully generated image deltas
[Info]       Uploading images
[Success]    Successfully uploaded images
[Info]       Built on builder05
[Success]    Release successfully created!
[Info]       Release: c0c593803588a304c173124827d96b99 (id: 2186339)
[Info]       ┌────────────────────┬────────────┬────────────┐
[Info]       │ Service            │ Image Size │ Build Time │
[Info]       ├────────────────────┼────────────┼────────────┤
[Info]       │ hello-world        │ 190.04 MB  │ 50 seconds │
[Info]       └────────────────────┴────────────┴────────────┘
[Info]       Build finished in 1 minutes, 4 seconds
                            \
                             \
                              \\
                               \\
                                >\/7
                            _.-(6'  \
                           (=___._/` \
                                )  \ |
                               /   / |
                              /    > /
                             j    < _\
                         _.-' :      ``.
                         \ r=._\        `.
                        <`\\_  \         .`-.
                         \ r-7  `-. ._  ' .  `\
                          \`,      `-.`7  7)   )
                           \/         \|  \'  / `-._
                                      ||    .'
                                       \\  (
                                        >\  >
                                    ,.-' >.'
                                   <.'_.''
                                     <'

The release will then be downloaded and started by all the devices in the fleet. You can see the progress of the device code updates on the device dashboard:

Service download progress

After the download, you should now have a C++ web server running on your device and see some logs on your dashboard.

To give your device a public URL, click the Public Device URL toggle on the device dashboard. Public device URL allow you to serve content from the device to the world easily without configuration as long as the server is running on port 80.

Enable public URLs

Follow the URL to view the welcome page with additional resources. Alternatively, you can point your browser to your device's local IP address to access the server running on your device. You can find the device's IP address on the device dashboard page. This is what you should be seeing.

Success screen 1

Developing your project

Now, let's try making some changes to this project and testing them right on the device. The project can be modified and pushed again using the same method as above, but since we are using a development version of the OS, we can enable Local mode and push directly to the device for a faster development cycle.

Activate local mode on the device via the dashboard.

Enable Local Mode

Once enabled, you can now use balena push again, but this time we will push directly to the local IP address of the device obtained via the dashboard.

Local IP address
$ balena push 10.19.0.153

The same build process as before is carried out, but this time instead of using the balena builders, the build takes place locally on the device itself.

[Info]    Streaming device logs...
[Live]    Watching for file changes...
[Live]    Waiting for device state to settle...
[Logs]    [8/26/2021, 11:58:18 AM] Creating network 'default'
[Logs]    [8/26/2021, 11:58:19 AM] Installing service 'hello-world sha256:...'
[Logs]    [8/26/2021, 11:58:20 AM] Installed service 'hello-world sha256:...'
[Logs]    [8/26/2021, 11:58:20 AM] Starting service 'hello-world sha256:...'
[Logs]    [8/26/2021, 11:58:23 AM] Started service 'hello-world sha256:...'
[Logs]    [8/26/2021, 11:58:24 AM] [hello-world] Starting server on port 80
[Live]    Device state settled

The balena CLI will now watch for changes to all the files within the project, and automatically push changes to the device when detected. Let's try making a change to title of our balena welcome page. Navigate to the index.html file present in the static directory of the project. Open the file and change the title from Welcome to balena! to Hello balena! and save the file. After saving the changes, you can observe balena CLI automatically start rebuilding only the parts of the Dockerfile that has been changed.

[Live]    Detected changes for container hello-world, updating...

...

[Live]    [hello-world] Restarting service...
[Logs]    [8/26/2021, 11:59:01 AM, 2:42:32 AM] Service exited 'hello-world sha256:...'
[Logs]    [8/26/2021, 11:59:04 AM, 2:42:35 AM] Restarting service 'hello-world sha256:...'
[Logs]    [8/26/2021, 11:59:05 AM, 2:42:36 AM] [hello-world] Starting server on port 80

When the rebuild is complete, take a look at the public device URL again to see your changes. The welcome page should have been updated with the new title.

Success screen 2

Next steps

Once you've finished making your changes, disable local mode and the device will revert back to running the latest release that's on your fleet. To update your fleet with the latest changes you've just worked on, use balena push <fleet name> once more to create a new release with those changes.

When it's finished building the device(s) will update as before. Remember anything pushed to the fleet in this way can be applied to 10+ or 1000+ devices with no extra effort! To continue learning, explore parts of the guide in more detail:

Enjoy balenafying all the things!