This documentation page is for detailed information about the services and pages
in the BlueOS web interface. For a higher level list and direct comparison of
features see the Overview instead.
The default BlueOS interface is simplified, and shows only the major tools that
most people are likely to find useful. Full functionality is available via
"Pirate Mode", which can be enabled from the header bar.
Note that Pirate Mode is advanced/development mode, and should be used with care.
This documentation by default shows the full functionality interface, to provide
an overview of all functionality instead of a limited subset, but if you're only
interested in the basic functionality you can click the button below:
For clarity of this documentation, any pages that are extended by (or only available
in) Pirate Mode are shown in dark mode, and described
with grey text.
Operating a vehicle involves some risks to both the vehicle and the operator. When
BlueOS detects that the vehicle is armed it engages safe mode, which requires explicit
confirmation to access functionality like BlueOS and autopilot firmware updates.
On the left side of the header there is space for widgets, which can be accessed by
right clicking and selecting the desired widgets to display. Widgets can be reordered
by clicking and dragging.
There are currently widgets available for displaying the CPU and Disk (storage) usage
as percentages, as well as local network usage, which are periodically updated during
operation:
Widgets are also generated for any enabled network interfaces, which allows monitoring
real time data bandwidth being downloaded/received by the BlueOS computer and
uploaded/transmitted from it (New in 1.4):
There is also a prominent indicator when the vehicle is in Safe Mode:
The burger menu at the top left of the header opens up the sidebar, for
conveniently accessing available pages, tools, and services. When the page
is wide enough, the sidebar automatically stays open.
The "Dashboard" page provides an overview of the available pages. In future it
will provide an overview of the vehicle state and main configuration options.
Click the BlueOS logo to return to the dashboard at any point.
Systems with a
Navigator
flight controller also have the option to configure serial-compatible ports from
the onboard computer (including USB ports) as serial ports accessible to the
autopilot.
💡 It's highly recommended to flash the default parameters for the vehicle when a firmware downgrade or upgrade is done.
Check the vehicle setup for more information.
The Available Services page provides developer access to the underlying http
server interfaces of the services upon which BlueOS is based. Each service is
listed with
The Version Chooser is a major component in the robust backbone of BlueOS. It
runs independently from the main interface, and is monitored such that if it
somehow fails a backup version will be run in its place.
The simplified interface provides an easy way to update to the latest version
that is as stable or more stable than the currently installed version
The full interface supports easily changing forwards and backwards between
versions
Previously-installed versions are kept locally on the device, unless
manually deleted, which provides an easy route for roll-backs to undesired
changes (e.g. during development)
Allows updating the bootstrap image to match the current version
Allows loading remote versions (including from custom docker-hub repositories)
Allows logging in to one or more docker registries, to access private repositories,
and to help avoid rate limiting
By default, logs in to the registry for Docker Hub
Custom registries can be authenticated to by specifying the relevant registry index after enabling the switch
Credentials are saved to .docker/config.json, by default for the normal pi user (and optionally the root user)
Accounts authenticated to the root user are displayed with a shield icon, and are valid for sudo docker commands
Allows manually uploading docker images from the surface computer
If an undetected failure somehow occurs in BlueOS (or if a broken version gets
installed) it's possible to easily roll back to a working version from
on the device
manual upload, or
downloaded from the internet
If necessary, the underlying service can be accessed directly
The File Browser allows viewing, editing, downloading, and uploading BlueOS files.
Vehicles using a Navigator flight controller board with a recent ArduPilot firmware can access Lua
drivers and scripts at configs/ardupilot/firmware/scripts. (New in 1.2)
Press the green play button to access the built in Log Viewer, to visualise and
analyse vehicle telemetry (including position if a positioning system is equipped)
The MAVLink Inspector provides real-time access to the MAVLink messages being
sent to the topside computer. It is possible to
filter for particular messages
view past and current messages
click on messages to see their full details
Future improvements will include plotting and comparisons, along with more
powerful filtering options.
For tracking the latest value of a single message type, use the "watcher"
functionality of the MAVLink2REST service (access via the
Available Services page).
The Local Network Test measures real-time latency between BlueOS and the surface
computer, and allows checking the upload and download speeds between them.
A plot is provided of each test, to help diagnose intermittent issues.
The Internet Speed Test allows measuring the latency and upload and download
speeds between BlueOS and its internet connection (if one is available).
Conveys GPS positions (from an NMEA device) to the vehicle via MAVLink messages
Setup requires a UDP or TCP socket for the NMEA device to connect to, and a MAVLink ID
for the component that will send the location data to the vehicle
Allows configuring Ping Sonar distance estimates to send as MAVLink
DISTANCE_SENSOR
messages to the autopilot, for viewing in the Control Station Software and
logging as part of the telemetry stream
Provides a viewing utility for devices connected via USB/serial, to show
which port they are plugged into
NOTE: UDP-based systems do not guarantee packet delivery or sequential alignment
Bridges to the Control Station Computer
will generally use the localhost IP 0.0.0.0, which creates a UDP server that waits
for a UDP client on the control computer to connect to it
other IP addesses create a UDP client on the onboard computer, which expects the
serial device to initiate communication before the connected UDP server (on the
control computer) can respond
NOTE: a client should communicate with the server at least once every 10 seconds
to avoid being disconnected
Bridges to internal programs can use the loopback IP 127.0.0.1, which creates a
local server
Allows setting a custom UDP port for a UDP client bridge to listen to responses at
The System Information page provides useful information about the processes,
network configuration, and computer system BlueOS is running on. It can be
useful for troubleshooting, and finding if a particular program is using
excessive resources.
Update buttons are provided if the device is not running the latest stable versions of
the Raspberry Pi firmware or USB controller.
Direct access into the core BlueOS docker container
Ready access to the tmux sessions of the core services (CTRL+b s)
Useful for seeing logs as they update live
Can kill (CTRL+c) services, and start them again (↑ ⏎)
Access to the underlying device via the red-pill utility
Can return to the core container using the exit command, or pressing CTRL+d
Can list available docker images (including extensions) with docker image list
Can list active docker containers (including extensions) with docker ps -a
For BlueOS host computers that do not have the default user as "pi", a custom username
can be specified using the -u argument (e.g. red-pill -u myusername) (New in 1.2)
The Vehicle Setup page provides an overview of the vehicle, including its sensors and
peripherals. The 3D model can be rotated, and can be panned by clicking and dragging
while holding SHIFT. The camera icon can be used to capture a screenshot of the current
view of the model, with a transparent background.
The PWM Outputs tab allows configuring the servo function mappings
(for motors, lights, camera tilt, etc), as well as manually testing the motors,
and an automated check to detect motors that spin backwards. Relevant motors can be
set to run on reversed control signals, so they spin in the expected direction.
Hovering over a motor or output function will attempt to highlight the related component
in the 3D model.
Clicking on an output in the right side table allows changing its assigned function,
and configuring its PWM limits and trim value (New in 1.4):
The Configure tab provides configuration and calibration options for the vehicle sensors and peripherals,
including failsafes, and reverting parameters to their defaults.
💡 Pages with configurable options usually include info icons above the interface components, which can be
hovered over for extra information about the underlying autopilot parameters.
It compensates for constant magnetic effects caused by the vehicle structure, and large scale
compass declination effects using a world magnetic model, but cannot compensate for local
magnetic interference
The world magnetic model requires an estimate of the vehicle's position, and can get
outdated when using an old autopilot version
In case there is no global positioning sensor available, an option is provided to
determine a rough position estimate using GeoIP,
or to specify coordinates manually
A rough position estimate is saved persistently when calibrating, but may need to be changed
in the autopilot parameters
if the vehicle is operating in a significantly different part of the world to where it was configured
Full onboard calibration is a detailed calibration which requires rotating the vehicle about
all three of its axes
Large vehicle calibration is a simplified, lower-quality calibration which only requires
pointing the vehicle (true) North
Results can be improved afterwards using Compass Learn
Compass Learn calibrates the compasses automatically through operation of the vehicle
It requires a valid global position estimate, and a period of driving the vehicle around
Log-based calibration analyses a log from a previous flight, and usually provides the best results
It is not currently available through the Vehicle Setup page, but can be accessed via the Mag Fit
tool in the Log Browser (when replaying a log), and the resulting values can be
copied across to the autopilot parameters
Available compasses can be disabled or reordered, and flagged as internal or external to the flight
controller board
Failsafe configuration exposes important autopilot failsafe features through an intuitive interface
Failsafes should be set up as part of responsible operation, and can provide early warnings of
problems, and trigger automated safe behaviours if a critical issue occurs
Note that some playback applications (e.g. VLC) treat odd-numbered ports
as audio channels, so relevant video streams should only use even-numbered
ports
UDP streams have the option to download an SDP file (or copy a URL to it),
for easier video playback in applications like VLC (New in 1.1)
Raspberry Pi cameras are supported (New in 1.1)
Detection requires turning on legacy camera support:
turn on via the settings button in the buttom right corner
reboot the onboard computer to enable
It is possible to use the "Redirect source" element to make an ethernet camera
available via the BlueOS camera manager, which allows Cockpit and QGroundControl
to detect it automatically
The Extensions Manager is in charge of fetching, installing, updating, and managing
Extensions.
The Store tab shows the available extensions, with a default filter which excludes
the development example extensions. Beta versions show a red marker on the card corner.
Clicking an extension card displays the developer information, default application settings
and permissions, a description / basic usage instructions, and a dropdown to select which
version of the extension to install (or uninstall):
By default, the store searches the
BlueOS Extensions Repository
for available extensions, but it is also possible to specify your own external collections
of extensions:
The Installed tab shows the resource usage of the installed extensions, and allows
configuring them, checking their logs, and restarting or disabling them:
The blue "+" button in the bottom right corner allows installing custom extensions as relevant.
The "Edit" button on installed extension listings allows changing to alternative/development
versions by setting the docker tag.
It is possible to customise the styling of the BlueOS interface by adding a
theme_style.css file at userdata/styles/ in the File Browser.
The File Browser can also be used to modify the file, in which case the styles
are updated at the next page refresh after the file is saved. The save button is
in the top right corner.
CSS is commonly used for styling
HTML webpages, and has an extensive set of features available. For the purposes of
adjusting the BlueOS theme, the most important thing to understand is
how to specify colors. It can be
helpful to use tools like colorhexa when
choosing a palette of colors, including for checking accessibility for various
color vision deficiencies.
For reference, here is an example with most of the main BlueOS colors changed,
together with the theme file that created it:
:root {
--v-primary-base: #CAB1E5 !important; /* sidebar highlights, submit buttons */
--v-info-base: #BA55E5 !important; /* info boxes (often same as primary base) */
--v-warning-base: #EDD1E5 !important; /* warnings and skip buttons */
--v-error-base: #AC1D1C !important; /* notifications, pirate icons, negative buttons */
--v-anchor-base: #5A11ED !important; /* hyperlinks */
}
/* light theme background, light to dark */
div.light-background {
background-color: #BAFF1E !important;
background-image: linear-gradient(160deg, #BAFF1E 0%, #5CA1E5 100%) !important;
}
/* dark theme background, light to dark */
div.dark-background {
background-color: #5EABED !important;
background-image: linear-gradient(160deg, #5EABED 0%, #BA55E5 100%) !important;
}
/* light theme header bar background, light to dark, translucent */
header.light-background-glass {
background-color: #DEADBA55 !important; /* fallback if gradient not available */
background-image: linear-gradient(160deg, #DEADBA88 0%, #5111CA88 100%) !important;
backdrop-filter: blur(4.5px) !important;
-webkit-backdrop-filter: blur(10px) !important;
}
/* dark theme header bar background, light to dark, translucent */
header.dark-background-glass {
background-color: #5111CA55 !important; /* fallback if gradient not available */
background-image: linear-gradient(160deg, #5111CA88 0%, #0B5E5588 100%) !important;
backdrop-filter: blur(4.5px) !important;
-webkit-backdrop-filter: blur(10px) !important;
}
The explanatory diagram colours are also configurable (New in 1.4):