Skip to main content

BalenaOS Installation

pir

What is balenaOS?​

balenaOS is an operating system optimized for running Docker containers on embedded devices, with an emphasis on reliability over long periods of operation, as well as a productive developer workflow inspired by the lessons learned while building balena.

The core insight behind balenaOS is that Linux containers offer, for the first time, a practical path to using virtualization on embedded devices. VMs and hypervisors have led to huge leaps in productivity and automation for cloud deployments, but their abstraction of hardware, as well as their resource overhead and lack of hardware support, means that they are not suitable for embedded scenarios. With OS-level virtualization, as implemented for Linux containers, both those objections are lifted for Linux devices, of which there are many in the Internet of Things.

What is balenaCloud?​

balenaCloud is a comprehensive cloud-based device deployment and management infrastructure hosted by balena. It allows even the most novice fleet owner to build applications in any language, seamlessly provision devices, quickly test new features, and easily manage their device fleet. Docker container technology enables safe, secure, and reliable updates through a single command while devices remain online and fully functional. Users can view and manage their entire device fleet using the balenaCloud dashboard or they can choose to interact directly with the API.

Quickstart with balenaOS on ODYSSEY - X86​

The easiest way to install balenaOS on the ODYSSEY - X86, along with balenaCloud, involves just a few steps:

  • Create a device fleet on balenaCloud
  • Flash the balenaOS image to a USB drive
  • Connect a USB drive to ODYSSEY - X86 and boot live image
  • Booted ODYSSEY - X86 appears on balenaCloud dashboard

Now let's proceed!

Prerequisites​

Prepare the following before getting started:

Create a device fleet on balenaCloud​

  • Step 1. Sign up for a balena account and log in

  • Step 2. After logging in, click Create fleet to create your first device fleet

pir

Note: 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.

  • Step 3. Type a name for the fleet, select Seeed ODYSSEY-X86 as the default device type, keep Starter as the Fleet type and finally click Create new fleet

pir

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.

  • Step 4. Click + Add device to add ODYSSEY - X86 board to this fleet and connect it with balenaCloud

pir

  • Step 5. Here device type will be already selected and version will be selected as the latest available one. Select Development as the edition, since it is recommended for first time users. You can also select the network connection as either Ethernet only or Wifi + Ethernet.

pir

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.

  • Step 6. Click + Advanced to select the rate at which your device checks for updates

pir

Flash and run balenaOS image from a USB drive​

  • Step 1. Once the image configuration is done, click the arrow next to Flash, and select Download balenaOS

pir

When the download completes, you should have a zipped image file with a name like balena-cloud-ODYSSEY-fleet-odyssey-x86-2.88.15+rev2-v12.11.16.img, where ODYSSEY-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.

  • Step 2. Open balenaEtcher, click Flash from file and select the zip file that we downloaded before.

pir

  • Step 3. Connect a USB flash drive to the PC, select the target as the connected flash drive and then click Flash

Next, we will run this image on the ODYSSEY - X86

  • Step 4. Connect Flash drive to ODYSSEY - X86 board and turn on the board

  • Step 5. While turning on the board, keep pressing DELETE key to enter BIOS setup

  • Step 6. Go to Boot section and set the Boot Option #1 to UEFI: USB, Partition 1

pir

  • Step 7. Go to Save & Exit and select Save Changes and Reset

Now the OS will be successfully booted from the USB Flash Drive

Manage ODYSSEY - X86 from balenaCloud dashboard​

  • Step 1. Open balenaCloud dashboard again and the ODYSSEY - X86 board will appear after about a minute!

pir

  • Step 2. Click on the device from the list to access the device dashboard

pir

If you can't get the device online, please visit balena support channel

FAQ​

Q1: How can I run balenaOS image from HDD/ SSD?​

If you want to run the balenaOS image from HDD/ SSD rather than running from a USB drive, you can follow the steps below

  • Step 1. Follow from step 1 - step 7 in above Flash and run balenaOS image from a USB drive section

  • Step 2. After booting successfully, turn off the board from balenaCloud dashboard

pir

Note: We need to boot once after flashing because the resin-data partition will grow to take up the remaining space on the flash drive, and we will use that space to store the image we need to flash to the HDD/SSD.

  • Step 3. Remove the flash drive from the ODYSSEY - X86 and connect to the PC

  • Step 4. Extract the zipped image file downloaded before

  • Step 5. Open a terminal window and copy the extracted balena-cloud-ODYSSEY-fleet-odyssey-x86-2.88.15+rev2-v12.11.16.img image to the resin-data folder inside resin-data partition of the flash drive

sudo cp balena-cloud-ODYSSEY-fleet-odyssey-x86-2.88.15+rev2-v12.11.16.img /media/username/resin-data/resin-data

Note: Change username to the username of your PC

  • Step 6. Remove Flash drive from PC and connect to the ODYSSEY - X86 board. Also connect an external HDD/ SSD to the ODYSSEY board.

  • Step 7. After the board is booted, navigate to balenaCloud dashboard and access the Terminal. Here click on the Select a target drop-down-menu, select Host OS and click Start terminal session

pir

  • Step 8. Type the following command on the terminal
fdisk -l

pir

We can see that the connected HDD as /dev/sda

  • Step 9. Flash the balena-cloud-ODYSSEY-fleet-odyssey-x86-2.88.15+rev2-v12.11.16.img file that we copied before to the connected HDD/SSD using dd utility
dd if=/resin-data/balena-cloud-ODYSSEY-fleet-odyssey-x86-2.88.15+rev2-v12.11.16.img of=/dev/sda

Note: Replace /dev/sda with the name corresponding to the connected HDD/SSD

  • Step 10. Once flashing is done, poweroff the ODYSSEY - X86

  • Step 11. Remove the USB Flash drive and turn on the ODYSSEY - X86

  • Step 12. While turning on the board, keep pressing DELETE KEY to enter BIOS setup

  • Step 13. Go to BOOT section and set the Boot Option #1 to UEFI OS xxxxx

pir

  • Step 14. Go to Save & Exit and select Save Changes and Reset

Now the OS will be successfully booted from the HDD/SSD

Q2: How can I access ODYSSEY - X86 using terminal?​

You can access ODYSSEY - X86 via terminal but you need to have Balena CLI installed on the host PC. Balena CLI is a Command Line Interface for balenaCloud or openBalena. It is a software tool available for Windows, macOS and Linux, used through a command prompt / terminal window. It can be used interactively or invoked in scripts.

  • Step 1. Follow this link to install Balena CLI according to your operating system.

Note: For this tutorial, we will use Balena CLI on Ubuntu. However, the instructions will be similar for other systems.

  • Step 2. Connect an Ethernet cable to the ODYSSEY - X86 board from your router

Note: Make sure host PC and ODYSSEY - X86 are on the same network

  • Step 3. Open a terminal window and scan for BalenaOS devices on the local network
sudo balena scan

pir

  • Step 4. SSH into the board using the IP address
balena ssh <ip address>
example:
balena ssh 192.168.1.78

Now we are inside the ODYSSEY - X86 running BalenaOS!

pir

Learn more about balena CLI here

Q3: How can I compile balenaOS from source code​

Eventhough we can obtain the balenaOS image from the balenaCloud dashboard as explained before, if you feel adventurous, you can go ahead and compile the balenaOS image from source code!

Manual Compilation on Local Machine​

Now we will move on to manually compiling the BalenaOS system image for ODYSSEY - X86 using Yocto via the command line.

Note: This guide was written after testing on a host PC with Ubuntu 20.04 installed. However, it will work for other Linux systems.

  • Step 1. Prepare the development environment on the host PC by installing the following packages
sudo apt update
sudo apt install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat python3-distutils

Note: If the host PC is running a different Linux distribution, please check here

  • Step 2. Clone the following repo and enter the repo
git clone https://github.com/balena-os/balena-seeed-x86
cd balena-seeed-x86
  • Step 3. Download all the required dependencies
git submodule update --init --recursive
  • Step 4. Run the build script
./balena-yocto-scripts/build/barys

Now the compilation process will start. Wait patiently until the compilation is finished. The compilation time will depend on the hardware specifications of the build machine.

Find the Compiled Image​

After compilation is finished, run the following command to check whether the system image is successfully generated

cd build/tmp/deploy/images/odyssey-x86/;ls -lh *balenaos-img

pir

  • balena-image-odyssey-x86 is used to boot directly from external storage (Flash Drive, SSD, HDD) connected to ODYSSEY - X86.
  • balena-image-flasher-odyssey-x86 is used to boot directly from internal eMMC storage on ODYSSEY - X86. So this flasher image is burned onto a Flash Drive that is used for the initial boot. When booted, this flasher image will automatically install BalenaOS on internal eMMC storage.

Using the Compiled Image​

By default, the images have the file extension .balenaos-img. Before moving onto flashing these images, you need to rename the file extension to .img.

For example:

  • Rename balena-image-odyssey-x86.balenaos-img to balena-image-odyssey-x86.img.
  • Rename balena-image-flasher-odyssey-x86.balenaos-img to balena-image-flasher-odyssey-x86.img

Resources​

Tech Support & Product Discussion​

Thank you for choosing our products! We are here to provide you with different support to ensure that your experience with our products is as smooth as possible. We offer several communication channels to cater to different preferences and needs.

Loading Comments...