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.

#Safe Mode

New in 1.4

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.

#Interface Overview

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

#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, 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:

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

#Notifications

• Press the broom to clear notifications
• Press the gear to toggle showing old messages

#Wired network management (ethernet / USB-OTG)

An ethernet connection can generally be accessed through the http://blueos-ethernet.local mDNS address.

When configuring a wired interface, choose between:

• A static IP
• A dynamic IP
• A DHCP server
  • Serves the lease range 101-200 (New in 1.4)
  • Can be configured as a backup, which only runs if no existing DHCP server is detected on the network (New in 1.4)

It is possible to have multiple connections per interface type.

#Wifi + Hotspot network management

• 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

• 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 http://192.168.42.1 when your device is connected to the BlueOS hotspot network

#Internet Status and Management

• See whether the vehicle is connected to the internet (updates every 20 seconds)

#Display Mode Management

• 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

• Heartbeat icon pulses with vehicle heartbeat, and goes red if heartbeat is lost
  • On click shows onboard computer temperature, voltage, and current usage
• GPS icon displays the number of visible satellites if a GPS is detected
  • On click shows the current GPS position estimate, and some GPS health/status values
  • Can show status for two connected GPS systems, and GPS-based yaw if both have valid position fixes (New in 1.4)

• 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

#Sidebar

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 theme content at the top is configurable

#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

• Power off
  • Shut down onboard computer
  • Recommended before turning off vehicle power
• Reboot
  • Reboot onboard computer

#Feedback

Submit feedback about BlueOS via:

• Issues on the GitHub repository
  • allows easily tracking changes, and notification when complete/fixed
• Report form submissions
  • Can be submitted at any time, and get sent to the developers when the control station computer next connects to the internet
• Posts on the Blue Robotics forum
  • allows easy discussion with the community

#Dashboard

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.

#BlueOS Service Pages

Pages are sorted alphabetically.

#Autopilot Firmware

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

• 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

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

#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
• Parameter descriptions can be overridden by including a metatdata_override.json file in the userdata folder in the File Browser (New in 1.4)
  • Parameter files can be generated from an ArduPilot firmware using this tool
• Allows loading parameters from a file, and saving the current parameters to a file

#BlueOS Version

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

#Log Browser

• 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
  • May be inconsistent

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

#Network Test

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

#Ping Sonar Devices

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

#System Information

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.

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

#PWM Outputs

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

#Autopilot Configuration

New in 1.3

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.

#Parameters

• Parameters can be reset to the default values defined and stored in the firmware
• Full sets of recommended parameters are available for Blue Robotics vehicles

#Gyroscope

• Gyroscope calibration affects the vehicle attitude (orientation) estimates, and particularly the measured rotation rates

#Accelerometer

• Accelerometer calibration affects the detected gravity direction, as well as speed estimates
  • Full calibration is a detailed calibration of all three axes, and requires rotating the vehicle
  • Quick calibration is a simplified, lower-quality calibration which only requires placing the vehicle on a level surface
    • This can be sufficient for vehicles that mostly operate in a level orientation

#Compass

• Compass calibration affects the vehicle yaw (heading) estimate
  • 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

#Barometer

• Barometer calibration sets the reference pressure for altitude/depth measurements, and the internal pressure for vehicles with enclosed electronics
  • It should generally be performed at the start of each dive/flight

#Lights

• ROV lights configuration allows specifying the output pins for two sets of PWM-controlled lights, and the number of steps the control is split into

#Failsafes

• 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

#Camera Gimbal

New in 1.4

• Pitch control for the camera gimbal requires specifying the PWM limits of the gimbal servo motor, and their relationship with its tilt angle range
• Auto-stabilization allows the camera to maintain its current pitch angle (relative to Earth), by compensating for pitch rotations of the vehicle

#Video Streams

• 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
    • 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://192.168.2.1:5602
    • 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)

• H264-encoded streams can be repackaged as WebRTC, and viewed and recorded in Cockpit
  • H265-encoded streams also work, but currently only on macOS (New in 1.4)
• By default 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 "Device Controls" button

• Camera settings are also exposed via the MAVLink camera protocol, so are controllable in applications like 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 Cockpit and QGroundControl to detect it automatically

#Extensions

#Extensions Manager

New in 1.1

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.

#Interface Theme

#Theme Content

The vehicle identifier components in the sidebar can be modified to suit your vehicle or use-case - just click to edit:

#Company Logo

• square images work best

#Vehicle Icon

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

#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
  • wired connection (ethernet tether / USB-OTG) -> http://custom.local
    • ethernet can also be accessed through http://custom-ethernet.local
  • wifi connection -> http://custom-wifi.local
  • BlueOS hotspot -> http://custom-hotspot.local
  • http://blueos.local will still be available for wired connections, as a fallback in case the custom name is forgotten
  • http://blueos-avahi.local is broadcast to all interfaces, for connecting when you're not sure which interface(s) are available
  • IP addresses are always available for the interfaces they're configured for, but they're less intuitive to remember than mDNS names
  • NOTE: mDNS is available on most modern operating systems, but
    • for Windows older than Windows 10, install Bonjour
    • for Linux run avahi-discover on the terminal to see if the avahi service is running
      • For reference: Debian, Arch

: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;
}

:root {
    --v-water-base: #AC2317 !important;
    --v-negative-base: #891A10 !important;
    --v-attention-base: #ECC19B !important;
    --v-positive-base: #514A3B !important;
    --v-neutral-base: #A15447 !important;
    --v-detail-base: #370502 !important;
    --v-outline-base: #FDF4C9 !important;
}