Improve this doc
Get started with and

Get started with BeagleBone Black and Go

Introduction

In this guide, we will build a simple Go web server project on a BeagleBone Black. At its most basic, the process for deploying code to a BeagleBone Black consists of two major steps:

  • Setting up your BeagleBone Black with balenaOS, the host OS that manages communication with balenaCloud and runs the core device operations.
  • Pushing your Go project to the balena image builder, which pulls in all necessary dependencies and creates the container image for your fleet.

Once you complete these steps, your BeagleBone Black will download the container image, start your application, and begin sending logs to your balena dashboard!

What you will 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.

Account setup

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

Create a fleet

A fleet is a group of devices that share the same architecture and run the same code. When you provision a device, it is added to a specific fleet, but can be migrated to another fleet at any time.

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

Create a fleet

Select the BeagleBone Black device type, choose a fleet type, enter a name, and click Create new fleet:

Note: To create a fleet with multiple containers, you'll want to use the Starter or Microservices fleet type. The Starter fleets are full-featured and free for all users, with a limit of up to 10 total devices across all Starter fleets.

After the fleet has been created, you will be redirected to the dashboard for the newly created fleet, where you can add your first BeagleBone Black.

Add your first 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 a device

For most fleets, you will have the option to select a device type. By default, the device type you chose when you first created the fleet will be selected. Fleets can, however, support any devices that share the same architecture, so you can choose another device type if needed.

After selecting a device type, select an OS type of balenaOS, and you will see a list of available balenaOS versions. In general, you should use the most recent version available. You can also select whether to use a Development or Production edition with the respective toggle:

Add new device

Note: When you're getting started, a Development image is the most useful, as it permits many testing and troubleshooting features. For production use, be sure to switch to a Production image. More details on the differences between Development and Production images are detailed here.

A toggle is also used to select whether your network connection will be through Ethernet Only or with the option for Wifi + Ethernet. Selecting Wifi + Ethernet allows you to enter a Wifi SSID and Wifi Passphrase:

Network configuration

Clicking Advanced presents the option to select the rate at which your device checks for updates:

Advanced options

Once you have finished your image configuration, click the Download balenaOS button. When the download completes, you should have a zipped image file with a name like balena-First-Fleet-2.47.1+rev1-v10.6.27.img.zip, where First-Fleet is the name you gave your fleet on the dashboard. Alternatively, by clicking on the toggle section of the download button, you also have the option to download just a configuration file (config.json) rather than an entire image.

Advanced options

Provision device

The next step is to flash the downloaded image onto your SD card using Etcher, a simple, cross-platform SD card writer and validator. Once you have Etcher installed, start it up. To give Etcher access to your SD card, your system may prompt you to grant administrative privileges.

To create a bootable balenaOS SD card, follow these steps:

  1. Click Select image and find your fleet's balenaOS image file.
  2. If you haven't already done so, insert your SD card into your computer. Etcher will automatically detect it. If you have more than one SD card inserted, you will need to select the appropriate one.
  3. Click the Flash! button.

Etcher will prepare a bootable SD card and validate that it was flashed correctly. This can take roughly 3 or more minutes, depending on the quality of your SD card. You'll receive a notification when it completes, and Etcher will safely eject the SD card for you.

Note: You can burn several SD cards with the same image file, and all the devices will boot and provision into your fleet. You can also disable the auto-ejecting or validation steps from the Etcher settings panel.

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 we have a device or two connected to a balena fleet, it's time to deploy some code. We will use the balena CLI for this. Follow the instructions below to install it on your computer (development workstation). Choose the tab for your operating 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 the balena CLI is installed, login to your balena account with the balena login command on the terminal:

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


Logging in to balena-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. Choosing Web authorization will bring up a web browser window that allows you to login to your balenaCloud account. When asked to authorize the CLI, click the Authorize button and head back to the terminal.

Web authorization

Note: Other authentication methods include using your username and password credentials or obtaining an authentication token from the dashboard. Authentication tokens come in two types, API tokens, and JSON Web Token (JWT) session tokens. While API tokens do not expire, JWT session tokens do after 7 days.

Add release

After logging in, test out the balena CLI by running the balena fleets command, which should return information about the fleet you created in the previous step. Take note of the FLEET NAME as you'll need this in the next step to push your code to all devices in that fleet.

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

Note: See all the commands available with balena CLI by running balena help

A nice first project to get started is a simple Go hello world program, which will print a Hello, world! message to the logs on the dashboard. All the project source code can be found here on GitHub. Download a zipped file of the project from here,and when downloaded, unzip the file and open a terminal in the root of the project directory.

Note: You may also use git to deploy code to a device. If you wish to deploy via git, see the instructions here.

Now to deploy this code to all device(s) in the fleet, use the balena push First-Fleet command replacing First-Fleet with the name of your fleet. Ensure you are in the root of the project directory before issuing this command or specify the --source option to provide an alternate location of the project directory.

$ balena push First-Fleet

This command will package up and push the code from the local directory to the balena builders, where it will be compiled, built and deployed 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:

[main]     Successfully built d5f1de77fad3
[Info]     Uploading images
[Success]  Successfully uploaded images
[Success]  Release successfully created!
[Info]     Release: f4e3925bf7d32226365225e1b7201b90 (id: 89693)
[Info]     ┌─────────┬────────────┬────────────┐
[Info]     │ Service │ Image Size │ Build Time │
[Info]     ├─────────┼────────────┼────────────┤
[Info]     │ main    │ 205.13 MB  │ 1 second   │
[Info]     └─────────┴────────────┴────────────┘
[Info]     Build finished in 7 seconds
                \
                 \
                  \\
                   \\
                    >\/7
                _.-(6'  \
               (=___._/` \
                    )  \ |
                   /   / |
                  /    > /
                 j    < _\
             _.-' :      ``.
             \ r=._\        `.
            <`\\_  \         .`-.
             \ r-7  `-. ._  ' .  `\
              \`,      `-.`7  7)   )
               \/         \|  \'  / `-._
                          ||    .'
                           \\  (
                            >\  >
                        ,.-' >.'
                       <.'_.''
                         <'

Your release will then be downloaded and started by all the devices you have connected in your fleet. The first push is slower to deploy, but all subsequent pushes are much faster due to Docker layer sharing. You can see the progress of the device code updates on the device dashboard:

Service download progress

You should now have the hello world program running on your device and see some logs, including the Hello, world! message, on your dashboard.

To give your device a public URL, access the device page, and choose the Public Device URL toggle. You may also activate this for many devices in your fleet at the same time via the Actions menu on the device list within a fleet.

Enable public URLs

Follow the URL to view a page with additional balena learning resources and next steps. Alternatively, you can point your browser to your device's IP address.

Next steps

  • Head to balenaHub, for more ready-to-deploy fleets, or have a go at building and sharing your own cool projects using balenaBlocks.
  • Try out local mode, which allows you to build and sync code to your device locally for rapid development.
  • Take a modular approach to application development with multiple containers.
  • Manage your device fleet with the use of configuration.
  • Pass named values, parameters and data to your application using variables.
  • Visit our blog to find step-by-step tutorials for some classic balena projects.
  • If you find yourself stuck or confused, help is just a click away.

Enjoy balenafying all the things!