Installation

#Download

BlueOS is a ground-up rewrite software to replace Companion. To use it you'll need to download and flash an SD card. It is compatible with Raspberry Pi 3¹, 4, and 5.

💡 SD cards come in a variety of speed and performance classes, to suit different applications. As an operating system, BlueOS should be run using a card with at least an A1 Application Performance Class, to avoid degraded performance and system throttling.

Critical use-cases are recommended to use A2 cards, and systems intended for onboard recording of one or more video streams should use cards with a suitable Video Speed Class rating (and appropriate total capacity) for the expected sustained data rates and file sizes.

Recommended operating system images of the latest stable version can be downloaded here:

Board Hardware	Image File (with Base OS)	Notes
Raspberry Pi 4B	ARMv7 (32-bit) Bullseye¹	Standard on Blue Robotics vehicles
Raspberry Pi 5	ARMv8 (64-bit) Bookworm²	Limited testing

Additional prebuilt operating system images are available in the releases, along with Docker images for ARMv7/ARMv8 and AMD64 platforms, as well as details of the main changes between different versions.

ARMv7 image can also be used for Raspberry Pi 3B boards, but doing so is not recommended for new projects, and is expected to stop being supported in future BlueOS versions.

ARMv8 image may also work for the Raspberry Pi 4B, but is not actively tested or supported.

#Flash

We recommend using a fresh SD card with at least 32GB³ capacity, although more storage is recommended for onboard data recording (especially for high bandwidth data like video streams and imaging sonar).

Download and install Balena Etcher
Insert the SD card to your computer (you may need an SD card reader)
Open Etcher, select the image you just downloaded, and flash it onto the SD card

SD cards with less than 8GB capacity are not expected to load BlueOS, and 16GB or below may suffer from reduced performance, particularly if also installing BlueOS Extensions.

#Run

Eject your SD card with the new BlueOS software
Insert it into your Raspberry Pi, and power it up!
- The first boot may take a couple of minutes, as it expands the filesystem to the new SD card capacity
  - It should take around 2 minutes for a 16GB class 10 SD card
BlueOS is a headless operating system, and uses a web interface rather than HDMI to a monitor
- See the Getting Started section for how to connect

#Updates

Once BlueOS is installed, updating to a different version is simple via the Version Chooser.

#Manual Installation

For developers with alternative hardware, or who would rather install over a pre-installed base operating system / image, BlueOS provides an install directory with utilities to help perform manual/software-based installations.

Sponsored by Blue Robotics Code under AGPLv3 / BlueOS Custom

BlueOS Documentation