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

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:

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)

For each interface, choose between:

• A static IP
• A dynamic IP
• A DHCP server
  • Serves the lease range 101-200 (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

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

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.

The Configure tab provides configuration and calibration options for the vehicle sensors and peripherals, including failsafes, and reverting parameters to their defaults.
New in 1.3

New in 1.4

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

• 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 "Configure" button

• 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

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

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

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

#Company Logo

• square images work best

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