Advanced Usage

General Information

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.

Pirate Mode

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.

Interface Overview

Based On: blueos-frontend | Port:80

When you first open BlueOS, you'll see a window like the following:

Interface Overview

Header: Indicators and BlueOS Configuration

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, which are periodically updated during operation.


On the right side of the header you'll find:

  • Press the broom to clear notifications
  • Press the gear to toggle showing old messages
Wired network management (ethernet / USB-OTG)

Based On: Cable Guy | Port:9090

For each interface, choose between:

  • A static IP
  • A dynamic IP
  • A DHCP server

It is possible to have multiple connections per interface type.

Usb Otg
Wifi + Hotspot network management

Based On: Wifi Manager | Port:9000

  • Choose a wifi network to connect to
    • The BlueOS web interface is accessible via http://blueos-wifi.local when connected to the same wifi network as your device (including a mobile phone)
  • Forget, connect to, or a force a new password for a saved network
Wifi Example
  • Configure or turn on/off the BlueOS wireless hotspot, or display a QR code to easily connect to it from a phone
    • The hotspot SSID is named BlueOS (******) by default, where the asterisk field varies for each system
      • The default password for the hotspot is blueosap
    • The BlueOS web interface is accessible via http://blueos-hotspot.local and when your device is connected to the BlueOS hotspot network
Hotspot Example
Internet Status and Management
  • See whether the vehicle is connected to the internet (updates every 20 seconds)
  • Configure network priority ordering
    • Determines which network interface is used for internet connection
    • Generally wlan0 should be at the top (for internet via wifi)
    • Move eth0 to the top if using internet passthrough via the tether
Internet Network Priority
  • View and configure DNS name servers
Internet Dns Config
Display Mode Management
Display Mode
  • Pirate mode can be toggled via the happy robot / skull-and-crossbones icon
    • Access or hide advanced functionality
    • Advanced users only - pirate mode is not recommended for normal use
  • Light and dark display modes can be toggled between with the sun / moon icon
System status
System Status
  • Heartbeat icon pulses with vehicle heartbeat, and goes red if heartbeat is lost
  • On click shows onboard computer temperature, voltage, and current usage
  • Additional warning icons appear if a problem is detected on the onboard computer:
    • High disk usage
    • CPU overheating
    • CPU throttling
    • CPU under voltage
    • Connected wirelessly (instead of through a tether)
    • BlueOS cannot connect to its host computer

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.

Sidebar (pirate mode)
BlueOS Settings
  • Reset BlueOS settings
    • Remove existing camera/endpoint/bridges configuration
  • Remove log files from BlueOS services (to reduce space usage on the SD card)
  • Download log files from BlueOS services to report a problem
    • Old logs are aggregated and compressed with GZip, and automatically deleted if the space runs out (New in 1.2)
  • Re-enable the configuration wizard
Power (pirate mode)
  • Power off
    • Shut down onboard computer
    • Recommended before turning off vehicle power
  • Reboot
    • Reboot onboard computer
  • Restart core container (same as "Soft restart")
    • Restart the core BlueOS docker container
    • Generally sufficient for most 'reboot' requirements

Submit feedback about BlueOS via:


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.

Dashboard (pirate mode)

BlueOS Service Pages

Pages are sorted alphabetically.

Autopilot Firmware

Based On: ArduPilot Manager | Port:8000

The Autopilot Firmware page provides basic information about the active autopilot, along with options to:

  • Change board (select a connected board, or run an SITL simulation)
  • Start the autopilot
  • Stop the autopilot
  • Restart the autopilot
  • Update the firmware
    • ArduPilot family of firmwares only
    • Choose firmware to install
      • Select from the online repository
        • Select vehicle type (Sub / Rover / Plane / Copter)
        • Select desired release and stability level
          • Stable - A production-ready release.
            • The latest Stable is recommended for most users.
            • e.g. Stable-4.1.1
          • Beta - In-testing release, with new features and improvements, aiming to become stable. May have bugs.
          • Dev - Development branch, with all the newest features. Intentionally unstable (changes quickly), and possible untested/dangerous.
      • Upload a custom firmware file from the surface computer
      • Restore the default (ArduSub) firmware for the connected flight controller
    • Flash firmware onto a connected compatible flight controller board
Firmware (pirate mode)

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.

Firmware Serial

Autopilot Parameters

New in 1.1

The Autopilot Parameters page allows checking and changing the autopilot's configuration.

  • Includes fuzzy searching of names and descriptions, to help find relevant parameters
  • Allows loading parameters from a file, and saving the current parameters to a file

Available Services

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

and where relevant

  • its API documentation (in a live-testable form)
  • the current API version

The individual services are documented in the development documentation.

Available Services

Bag Editor

Based On: Bag of Holding | Port:9101

The Bag Editor is a helper service for advanced users, which allows modifying the database used to handle frontend interface changes.

Bag Editor

BlueOS Version

Based On: Version Chooser | Port:8081

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.

Version Chooser (pirate mode)
  • 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 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

File Browser

Based On: File Browser | Port:7777

The File Browser allows viewing, editing, downloading, and uploading BlueOS files.

File Browser

Log Browser

Based On: UAV LogViewer

  • Allows downloading telemetry .bin logs from Linux-based autopilots
    • Set the BRD_RTC_TYPES autopilot parameter to include MAVLINK_SYSTEM_TIME so the filenames use timestamps
  • Can stream logs from external flight controllers (e.g. Pixhawks) if the LOG_BACKEND_TYPE autopilot parameter is set to MAVLink
Log Browser
  • 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)
Log Viewer

Based On: ArduPilot Manager | Port:8000

The MAVLink Endpoints manager allows configuring the serial, UDP, and TCP endpoints for MAVLink-based services and programs to access.

Mavlink Endpoints
  • It is possible to switch from the default MAVLinkRouter to MAVP2P (New in 1.2)
    • This may use more CPU, so is only recommended if your system is having frequent "GCS Heartbeat Lost" errors
  • Endpoints intended for internal BlueOS operations are configured to the loopback IP
  • Server endpoints for external use are configured to the localhost IP
    • e.g.
    • may also work
  • Client endpoints for external use are configured to the external IP
  • Client endpoints seem to operate more stably than server ones
  • Unprotected endpoints can be removed or disabled
  • Modifying an endpoint is not possible - a new one must be created instead
    • e.g. some users may wish to set up a UDP endpoint for connecting to with Pymavlink from the surface:
Mavlink Endpoints Pymavlink Example

Based On: MAVLink2Rest | Port:6040

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
Mavlink Inspector

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).

Network Test

Based On: Pardal | Port:9120

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.

Network Test Local

The Internet Speed Test allows measuring the latency and upload and download speeds between BlueOS and its internet connection (if one is available).

Network Test Internet

NMEA Injector

Based On: NMEA Injector | Port:2748

  • Conveys GPS positions (from an NMEA device) to the vehicle via MAVLink messages
Nmea Injector
  • 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
Nmea Example

Ping Sonar Devices

Based On: Ping Service | Port:9110

New in 1.1

The Ping Sonar Devices page shows any detected sonars from the Ping family, including ethernet-configured Ping360s that are visible on the local network (e.g. via an Ethernet Switch).

  • 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
Ping Sonar Devices

Serial Bridges

Based On: Bridget | Port:27353

The Serial Bridges page allows creating high performance links between serial devices that are connected to the onboard computer, to a UDP port.

Replaces the Routing functionality from the old Companion Software.

For making connections to the autopilot, see MAVLink Endpoints.

Serial Bridges
  • NOTE: UDP-based systems do not guarantee packet delivery or sequential alignment
  • Bridges to the Control Station Computer will generally use the localhost IP, 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, which creates a local server
Serial Bridges Example

System Information

Based On: System Information | Port:6030

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.

System Info Processes
System Info Monitor
System Info Network
System Info Kernel
System Info Firmware

Update buttons are provided if the device is not running the latest stable versions of the Raspberry Pi firmware or USB controller.

System Info About


Based On: ttyd | Port:8088

The Terminal provides

  • A tmux session
    • Can split horizontally (CTRL+b ") and vertically (CTRL+b %), and use cursor to resize the panels
    • For more advanced tips, check out the tmux cheat sheet website
  • 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 services if necessary
  • 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)

Vehicle Setup

New in 1.1

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.

It is possible to override the displayed 3D model by placing an appropriate .glb file at userdata/modeloverrides/<vehicle_type>/<vehicle_frame>.glb (e.g. userdata/modeloverrides/sub/VECTORED_6DOF.glb), or userdata/modeloverrides/ALL.glb.

Documentation for the recommended process for creating a .glb file from a vehicle model is coming soon.

Vehicle Setup Overview

The PWM Outputs tab allows configuring the servo function mappings (for motors, lights, camera tilt, etc), as well as manually testing the motors.

Vehicle Setup Pwm Outputs

The Configure tab allows loading default parameter sets for a particular vehicle type.

Vehicle Setup Configure

In future this page will also allow

  • running ArduSub's automatic motor direction detection
  • calibrating the autopilot sensors
  • using custom highlighting logic for model components
  • displaying device statuses from extensions

Video Streams

Based On: MAVLink Camera Manager | Port:6020

  • BlueOS automatically detects H264-encoded video streams
  • MJPG and YUYV encoded streams are also detected in pirate mode, but currently only work when configured as RTSP streams
  • The first time BlueOS starts up it will auto-configure any cameras that are connected at that time, with UDP streams counting up from port 5600
    • e.g. a second camera at first startup would be streamed to port 5601
    • Auto-configuration also occurs if the settings are reset
      • applies to both global settings resets (via the sidebar) and
      • camera manager settings resets (via the settings icon in the bottom right)
  • After the initial startup, settings are saved and persistent across reboots
    • Further changes require manually re-configuring streams
    • New streams need to be manually added
      • UDP stream endpoints should be set to udp://<surface-IP>:<port>
        • e.g. udp://
      • RTSP stream endpoints are auto-configured with appropriate values
    • One video input can have multiple output streams by clicking the blue + symbol during stream configuration
      • This only works for streams of the same endpoint type (e.g. it is not currently possible to mix UDP and RTSP output streams for the same input)
Video Stream Example (pirate mode)
  • By default the streams are also presented via MAVLink, so QGroundControl (>=v4.1.7) can toggle between them without needing to know specific ports
  • It is possible to specify a stream as "thermal", which allows it to be overlaid on another stream in some viewing applications
  • Camera settings (brightness, exposure, etc) that are exposed via UVC can be configured with the "Configure" button
Video Config Example
  • Camera settings are also exposed via the MAVLink camera protocol, so are controllable in QGroundControl
  • Switching streams in QGroundControl while recording stops the current recording
    • If you are regularly switching streams it may be worth doing a screen recording either instead of or as well as recording the base video
  • QGroundControl does not yet support displaying multiple streams simultaneously
    • Additional streams can be processed/viewed/recorded by the options discussed here
      • 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:
      1. turn on via the settings button in the buttom right corner
      2. 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 QGroundControl to detect it automatically (via MAVLink)
Video (pirate mode)


Extensions Manager

New in 1.1

Based On: Kraken | Port:9134

The Extensions Manager is in charge of fetching, installing, updating, and managing Extensions.

The Store tab shows the available extensions, which can be clicked to see information about the extension (including the settings, permissions requirements, and developer information), and allows selecting the version to install:

Extensions Store
Extensions Store Example

The Installed tab shows the resource usage of the installed extensions, and allows configuring them, checking their logs, and restarting or disabling them:

Extensions Installed (pirate mode)

Developers can install custom extensions as relevant.

Extensions Installed Example

Interface Theme

Theme Content

Vehicle Icon

  • square images work best
  • consider getting an image of your 3D model from the Vehicle Setup page
Theme Vehicle

Vehicle Name and mDNS Hostname

  • the vehicle name makes it easier to determine which vehicle you are connected to
  • changing the mDNS hostname changes the address you connect to for the browser interface
Theme Name Mdns
  • square images work best
Theme Logo

Theme Styling

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:

Theme Style
: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, cancel/delete 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;

Edit this page on GitHub