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:

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

Ethernet + static IP management

Based On: Cable Guy | Port:9090

Choose between:

A static IP
A DHCP server
A dynamic IP

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

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

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

Settings

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

Submit feedback about BlueOS via:

Issues on the GitHub repository (allows easily tracking changes, and notification when complete/fixed)
Posts on the Blue Robotics forum (allows easy discussion with the community)

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

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

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

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.

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
- Additional streams can be processed/viewed/recorded by the options discussed here
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

(MAVLink) Endpoints

Based On: ArduPilot Manager | Port:8000

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

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:

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:

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.

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.

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.

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

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

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

File Browser

Based On: File Browser | Port:7777

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

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

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

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

MAVLink Inspector

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

Future improvements will include plotting and comparisons, along with more powerful filtering options.

Edit this page on GitHub