BlueOS Documentation
Usage Integrations
Hardware
Required Hardware Recommended Extra Hardware Additional Components and Peripheral Devices

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 settings in the sidebar. 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:

Any pages that are extended by (or only available in) Pirate Mode are shown in dark mode, and described with grey text.

Main

Based On: blueos-frontend | Port:80

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

Main (pirate mode)

Indicators and Network Configuration

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

Notifications
  • Press broom to clear notifications
  • Press cog to toggle showing old messages
Notifications
Ethernet + static IP management

Based On: Cable Guy | Port:9090

Choose between:

  • A static IP
  • A DHCP server
  • A dynamic IP
Ethernet
Ethernet Example
Wifi network management

Based On: Wifi Manager | Port:9000
  • Choose a network to connect to
  • Forget, connect to, or a force a new password for a saved network
Wifi
Wifi Example
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
System Status

The burger menu at the top left of the header opens up the side-bar, for conveniently accessing available pages, tools, and services.

Sidebar (pirate mode)
Settings
Settings (pirate mode)
  • Reset BlueOS settings
    • Remove existing camera/endpoint/bridges configuration
  • Pirate mode toggle
    • Access or hide advanced functionality
    • Advanced users only - pirate mode is not recommended for normal use
  • Dark mode toggle
    • Change between light and dark viewing modes
Power
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
Feedback
Feedback (pirate mode)

Submit feedback about BlueOS via:

  • Messages in the Blue Robotics Slack (for internal use)

Vehicle

General

The "General" page provides basic info about the active autopilot, along with options to:

  • Change board (select a connected board, or run an SITL simulation)
  • Restart the autopilot
  • Start the autopilot
  • Stop the autopilot
General (pirate mode)

Firmware

Based On: ArduPilot Manager | Port:8000
  • 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
        • Official - The latest stable release. Recommended for most users.
        • Stable - A production-ready release. Suitable for most users.
          • e.g. Stable-4.0.3
        • 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

Log Browser

Based On: UAV LogViewer
  • Built in log viewer for powerful analysis of vehicle telemetry
  • Currently only set up to fetch logs automatically from Linux-based autopilots
    • e.g. Pixhawk not yet supported
Log Browser

Video

Based On: MAVLink Camera Manager | Port:6020
  • BlueOS automatically detects H264-encoded video 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
  • It's also possible to manually reset only the camera settings by deleting the file /root/.config/mavlink-camera-manager/settings.json via the file browser or the terminal, or starting the camera manager inside the tmux session with the --reset flag
  • 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
      • The stream endpoint should be set to udp://<surface-IP>:<port>
      • e.g. udp://192.168.2.1:5601
  • The streams are also presented via MAVLink, so QGroundControl (>=v4.1.7) can toggle between them without needing to know specific ports.
Qgc_switch_streams
  • Camera settings (brightness, exposure, etc) that are exposed via UVC can be configured with the "Configure" button
  • 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
  • Raspberry Pi cameras are not yet supported in the pre-built releases/images
    • It is possible to do a custom installation on Raspberry Pi OS Buster or manually enable the legacy camera stack on Bullseye if necessary
Video (pirate mode)

Based On: ArduPilot Manager | Port:8000

The endpoint manager allows managing the serial and UDP MAVLink endpoints and routing configurations.

Endpoints
  • Endpoints intended for internal BlueOS operations are configured to the loopback IP 127.0.0.1
  • Server endpoints for external use are configured to the localhost IP (e.g. 0.0.0.0; 192.168.2.2 may also work)
  • Client endpoints for external use are configured to the external IP (e.g. 192.168.2.1)
  • Client endpoints seem to operate more stably than server ones
  • Unprotected endpoints can be removed or disabled:
Endpoints Disable Delete
  • 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:
Endpoints Pymavlink ExampleExample

Tools

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 About

Network Test

Based On: Pardal | Port:9120

The Network Test page measures real-time latency between BlueOS and the surface computer, and allows checking the upload and download speeds between them.

Network Test

Version Chooser

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 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
    • e.g. http://blueos.local:8081

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

  • the port it is served at
  • a meaningful name
  • a web-page link using the active network configuration, and where relevant
  • its API documentation (in a live-testable form)
  • the current API version

Any service that provides an http server with a title tag will be displayed. Documentation can also be parsed if

  • it follows the swagger/open api spec, and
  • is available at /docs or /v1.0/ui
Available Services

(Serial-UDP) Bridges

Based On: Bridget | Port:27353

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

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 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
  • Bridges to internal programs can use the loopback IP 127.0.0.1, which creates a local server
Bridges Example

File Browser

Based On: File Browser | Port:7777

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

File Browser

NOTE: There is a known issue where the File Browser does not load properly with certain browsers. It is fixed in the 1.1.x beta releases, but in the interim for current stable releases it's possible to access the underlying service at http://blueos.local:7777

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

Terminal

Based On: ttyd | Port:8088

The terminal provides

  • A tmux session
  • 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 docker using the exit command, or pressing CTRL+d
Terminal

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.