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
Sidebar
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
- e.g.
- 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
- Select from the online repository
- 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
- e.g. a second camera at first startup would be streamed to port
- 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 stream endpoint should be set to
- 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 pressingCTRL+d
- Can return to the docker using the
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.