bluerobotics / blueos

The open source platform for ROV, USV, robotic system operation, development, and expansion.

BlueOS

BlueOS is a modular, robust, and efficient platform for managing a vehicle or robot from its onboard computer. It is the evolution of the Companion project, which aimed to route a vehicle's video stream and communications to its control station computer. Recognizing the need for a more sophisticated and scalable system, BlueOS was created from the ground up, embracing modularity to ensure portability, robust updating, and extensibility.

Quick Links ⚡

• Official documentation
• Development documentation
• Contributions
• Code of Conduct
• Registered Extensions
• Install directory (for custom installations)

Principles and Goals 📖

The development of BlueOS is driven by the following core principles:

• An interface that is simple by default but powerful when needed - the user has the power to change anything they desire and customize the full experience
• Designed to focus on what matters, improving user access to information and controls with a human-friendly UI and UX
• Make complex tasks simpler and improve ease of use by reusing design patterns from other applications (based on the material UI guidelines)
• Advanced error handling and detection, making any problems clear to the user and developers, along with how to fix them
• Simplify development, providing full access to our services API and modular development model
• Portable and flexible, you should be able to run on a Raspberry Pi 3/4 or any SBC with Linux operating system, contributions are welcomed
• Highly functional with low CPU usage, the entire system is built to run efficiently
• Developed on solid foundations, critical parts or intensive workforce services are designed using the most advanced languages and features available for stability

The design, organization, and future releases of BlueOS are aligned with these principles, striving to provide an optimized and enriched user experience.

Release Types ✨

BlueOS is available in three release types:

• Stable: Officially tested and validated versions with long-term support. Recommended for most users.
• Beta: Lightly tested rolling releases with new features, bug fixes, and improvements.
• Master: Bleeding-edge development releases with almost daily changes. These are the very latest features that may not have been tested yet.

Vehicle Support 🛸

BlueOS has been designed with a focus on vehicle and platform agnosticism. Our aim is to facilitate broad compatibility across a wide spectrum of applications. Currently, BlueOS officially supports the following vehicle types:

Boats (ArduRover)

ArduRover is an open-source, uncrewed boat platform. Whether you are commanding a leisure boat or a research vessel, BlueOS's compatibility with ArduRover ensures that you can navigate the waters smoothly 🌊.

BlueBoat is supported by default.

Submarines (ArduSub)

ArduSub is the go-to control system for remotely operated underwater vehicles (ROVs) 🐟. BlueOS offers seamless integration with ArduSub, enabling efficient management and operation of underwater vehicles.

BlueROV2 is supported out of the box.

Generic (ArduPilot / PX4)

BlueOS provides generic support for a wide variety of terrestrial, aerial, and marine uncrewed vehicles that use ArduPilot and PX4 autopilots. This extends the range of vehicles that can be managed using our system, from drones to autonomous cars and more.

Note: Specific vehicle configuration may be necessary to ensure optimal performance with BlueOS.

Supported Architectures 👨🏻‍💻

BlueOS is designed to perform optimally across a wide range of systems. Our latest releases are automatically built for the following architectures:

• armv7: This is a common architecture for embedded devices. Covers Raspberry Pi models up to and including the Raspberry Pi 3.

• armv8/arm64: This is used by more recent, high-performance devices. You can run BlueOS on a Raspberry Pi 4, or in a computer with Apple Silicon.

• amd64: This is the architecture used by most desktop and laptop computers. A typical example is any modern PC running a 64-bit version of Linux. Not fully supported.

Right now we officially support the Raspberry Pi 3 and 4, but the system should "just work" on all listed architectures with the correct docker binds.

Development Environment

Docker based development environment is available for via the core/compose/compose.yml docker compose file. This will start a development environment with all the required services as well as mount all of the needed directories in this repository for development.

docker compose pull # Ensure that docker is up-to-date
docker compose -f core/compose/compose.yml up

When restarting the development environment you may need to remove the volumes to ensure that the development environment is clean.

docker compose -f core/compose/compose.yml down

blueos's Issues

install VERSION variable conflicts with docker install step

root@raspberrypi:/home/pi# export REMOTE=https://raw.githubusercontent.com/jaxxzer/companion-docker
root@raspberrypi:/home/pi# export VERSION=r3
root@raspberrypi:/home/pi# curl -fsSL https://raw.githubusercontent.com/jaxxzer/companion-docker/r3/install/install.sh | bashChecking if network and remote are available.
Starting hardware configuration.
https://raw.githubusercontent.com/jaxxzer/companion-docker/r3/install/boards/configure_board.sh
Detecting board type
Detected BCM27XX via device tree
Configuring BCM27XX board (Raspberry Pi 4)..
- compile spi0 device tree overlay.
- Enable I2C, SPI and UART.
enable_uart=1
dtoverlay=uart1
dtoverlay=uart2
dtoverlay=uart3
dtoverlay=uart4
dtparam=i2c_arm=on
dtoverlay=i2c0
dtoverlay=i2c1
dtoverlay=i2c4,pins_6_7
dtoverlay=i2c6,pins_22_23
dtparam=spi=on
dtoverlay=spi0-led
dtoverlay=spi1-3cs
- Set up kernel modules.
bcm2835-v4l2
i2c-bcm2835
i2c-dev
- Configure serial.
Checking for blocked wifi and bluetooth.
Checking for available space.
Checking for docker.
bash: line 45: docker: command not found
# Executing docker install script, commit: 3d8fe77c2c46c5b7571f94b42793905e5b3e42e4
+ sh -c apt-get update -qq >/dev/null
+ sh -c DEBIAN_FRONTEND=noninteractive apt-get install -y -qq apt-transport-https ca-certificates curl >/dev/null
+ sh -c curl -fsSL "https://download.docker.com/linux/raspbian/gpg" | apt-key add -qq - >/dev/null
Warning: apt-key output should not be parsed (stdout is not a terminal)
+ sh -c echo "deb [arch=armhf] https://download.docker.com/linux/raspbian buster stable" > /etc/apt/sources.list.d/docker.list
+ sh -c apt-get update -qq >/dev/null
INFO: Searching repository for VERSION 'r3'
INFO: apt-cache madison 'docker-ce' | grep 'r3.*-0~raspbian' | head -1 | awk '{$1=$1};1' | cut -d' ' -f 3

ERROR: 'r3' not found amongst apt-cache madison results

Failed to start docker, something is wrong.

Bootstrap curses interface needs to be refactored/encapsulated

Log: Save services output

bootstrap is crazy when core stops or is killed

cable-guy api yaml does not match server setup

https://github.com/bluerobotics/companion-docker/blob/c5f3eb73dc58d3789fcbd7e670d678832e44cdac/core/services/cable_guy/main.py#L56
vs
https://github.com/bluerobotics/companion-docker/blob/master/core/services/cable_guy/swagger/cable-guy.yaml#L8

bootstrap does not fetch json file when donwloading new image

Related to #69
When the image fail to download bootstrap get in a loop where it fails to download docker, if you update the json file bootstrap is still downloading the old image in the json file.

Problems with installation script VERSION and REMOTE

Reference: #121 (comment)

CI: expose test coverage html

Refactor: Move to pyproject.toml over setup.py

pyproject is the default way to manage software development with python3
https://www.python.org/dev/peps/pep-0518/

Add code coverage

Separate ArduPilotManager and main

Currently, ArduPilotManager is a class declared inside main. In the case of adding functionality to main (e.g. creating a CLI for ArduPilotManager), it's purpose would be unclear and bloated. Giving ArduPilotManager its own file would make things clear.

install steps are creating bad urls

When using custom remote + version:

in step 1 install.sh, we set $REMOTE to github.com/branch.
in step 2 configure board, we set $REMOTE to github.com/branch/branch, this leads to curl 404

bootstrap: Failing when bootstrap image changes and install script is called again

install: unblock wifi

Install: Add swapfile for low memory boards

Add build instructions

Add instructions related to docker build, to create images, upload, configure and etc

Deploy docker image name as branch name

ArduPilotManager fails when running on Desktop

File "companion-docker/core/services/ardupilot_manager/flight_controller_detector/Detector.py", line 5, in <module>
    from smbus2 import SMBus
ModuleNotFoundError: No module named 'smbus2'

It would be good to at least catch this.

service: housekeeper

Housekeeper is a future service that will manage all others service, the service has the following responsibilities:

• Manage default settings for 3rd party software
• Start and manager all others companion-core services
  • stop, start, restart, health status, log (?)

Video: Move from tmux to service

• Create basic working progress
• Handle UDP for now
• Work with multiple videos or code structure for that

Move bootstrap to use a library

Add a formatting/linting helper

perhaps a one-liner that runs black, mypy, and pylint?

docker cache: Somehow we are loosing our github docker cache

For more information:
https://github.com/bluerobotics/companion-docker/pull/82/checks?check_run_id=1814418247

break hardware configuration from bcm into bcm27 and bcm28 (pi[0-3], pi4)

This is related to the i2c4 configuration #55

Installation script fails installing docker for archarm

pacman -S docker works fine

Add a mechanism for syncing clock time with topside

Install default programs

• file: For file information <1MB
• locate: To find files <1MB
• tmux: Better mult terminal support <1MB
• unzip: To download and unzip stuff < 1MB
• nano: A friendly editor
  • oh-my-nano: nano syntax highlight 100kB
• htop: System resources manager tool < 1MB
• tig: Git visualization 100MB
• mtr: For internet ping 100MB
  • ping: Used in place of mtr < 1MB
• bat: For file visualization 2MB
• wget: To download stuff 10MB
• oh-my-zsh: A friendly and powerful bash 300MB
• ip: For network configuration and settings visualization ~3MB

RUN apt install -y file locate tmux unzip nano htop iputils-ping wget iproute2
RUN sh -c "$(wget -O- https://raw.githubusercontent.com/scopatz/nanorc/master/install.sh)" # oh-my-nano

Refactor: Add js/html linters

I'm used to eslint

bootstrap: Add feature to load docker images from files

core: add dockerignore

Log: Save dmesg output

The dmesg output should be saved for debug.
We should save at least the latest N dmesg outputs or a fixed size like 100MB.

ardupilot udp output in master branch appears to be not working

Image caching in deploy.yml action is not working

The action never finds a cached images.
Apparently the cron is not working.

Add environment variable to control number of threads used to build

I can't use my pc in peace while building since I don't have control over it 😿

Move to Python 3.8

Some of the features that would be available include new type hints:

• Literal
• TypedDict

Add Python linter

change bootstrap to use debian:buster-slim as base image

bootstrap: Improve README

Add information about:

• Access information of the running service
• Restart it to run the new config file
• Where the config should be by default

Bootstrap: download status is flooding the screen.

It needs to be updated to print the output of the low_level_api nicely here

high cpu usage in kernel while running video stream inside docker with rtsp server

Add a place where the user can extract parameters, logs and etc to help us with debug in a single click

Refactor: move mavlink_routerd to tools and install before services

Install script fails at enabling Docker Daemon

This was noticed on a fresh Raspbian Lite installation, running on a RaspberryPi 4.

mavlink_proxy: Add latency test

Use mavlink PING message to calculate the latency between our tool and the flight-controller

consider using supervisord instead of tmux for managing services

Error: the input device is not a TTY

This happens when starting bootstrap docker in the install script

Refactor: consider moving from js to typescript

navigator: add i2c4 to the devicetree overlay

#51 (comment)

at least, for raspberry pi 4

Neither Mavproxy nor MavlinkRouter are installed by default

Companion needs at least one of them to connect to the autopilot.

Include SITL in ArduPilotManager

Opens the possibility for the users to test the Companion functionalities without a Pixhawk or Navigator connected.