BlueOS-core
Function
BlueOS-core is the body of BlueOS, and runs all of the built in services, along with the main web interface. It contains the key components for running, configuring, and operating a robotic vehicle, as well as a variety of convenience features to aid with system introspection and development.
Codebase
BlueOS-core is open source, and lives within the broader BlueOS GitHub repository. Issues can be used to report bugs or suggest features, and Pull Requests fixing bugs or adding new features are welcomed.
BlueOS is set up with a GitHub Action that automatically builds and deploys a BlueOS-core image when changes are pushed to the GitHub repository.
If you want to make use of that functionality you'll need a DockerHub account, and will need to specify your DockerHub username (DOCKER_USERNAME
) and password (DOCKER_PASSWORD
) in your fork's GitHub secrets.
The BlueOS Version chooser can be used to install a custom image by either
- Changing the "Remote" to your DockerHub repository, then installing like you would normally
- Doing a "Manual Upload" of a
.tar
compressedBlueOS-core
Docker image
Structure
- Dockerfile (and corresponding
.dockerignore
file) for building the BlueOS-core Docker image **/install-*.sh
scripts that the Dockerfile uses to install the tools, libraries, and services- tools scripts used to install the underlying programs used by the service backends
- configuration files that the Dockerfile moves to appropriate locations for the programs they apply to
- start-blueos-core script that runs when the BlueOS-core container gets started
- Responsible for configuring and starting the services
- Supports disabling a comma-separated list of core services via the
BLUEOS_DISABLE_SERVICES
environment variable(New in 1.2)
- libs code libraries of shared functionality available to the service backends
- services code for running the services
- Mostly Python backend code, often wrapped around / making use of a program installed by
tools
- Some frontend code, for services that have a frontend that opens in its own window
- Mostly Python backend code, often wrapped around / making use of a program installed by
- frontend web code for displaying the BlueOS web interface, including the main interface elements for the services
/public
: browser tab icons and the like/src
:- Mostly Vuetify visual components and Typescript interface code
/assets
: styling, images, and models used throughout the web interface
Services
BlueOS provides automatic detection of Available Services, whereby any HTTP server with a title tag is found and listed. This is particularly helpful for testing out API calls, both for development and debugging purposes.
Documentation can also be parsed if
- it follows the Swagger / OpenAPI specification, and
- is available at
/docs
or/v1.0/ui
The services built into BlueOS are as follows:
Contributions
Adding a Flight Controller
Adding USB detection support for a new type of flight controller board is reasonably straightforward, but does require a few different steps:
Find the USB device information
- Connect your flight controller board via USB1 to a computer running BlueOS
- Go to the BlueOS Terminal page
- Open a Python console (run the
python3
command) - Run
from serial.tools.list_ports import comports
- Run
from pprint import pprint
- Run
[pprint(port.__dict__) for port in comports()]
- Get the
"product"
and"manufacturer"
values for your flight controller board
Non-USB serial connections are not yet supported.
Find the flight controller hardware information
- Go to the ArduPilot hardware definition files
- Find the folder corresponding to your flight controller board
- Find the
APJ_BOARD_ID
variable in thehwdef.dat
orhwdef.inc
file
Add the board, and confirm it works
- Fork the BlueOS repository
- You'll need a GitHub account to do this
- Click where it says
master
, and create a new branch (e.g.add-pixhawk-6C
) - Navigate to
core/services/ardupilot_manager/typedefs.py
and add your board's name and type to thePlatform
class- Use
PlatformType.Serial
for USB/serial connections -Linux
is reserved for sensor/peripheral expansion boards that run the autopilot firmware directly on the Onboard Computer
- Use
- Navigate to
core/services/ardupilot_manager/flight_controller_detector/board_identification.py
and add appropriateSerialBoardIdentifier
instances to theidentifiers
list (using the "product" and "manufacturer" values from earlier)- The "product" is more important/useful, because one "manufacturer" can make multiple different board types
- Navigate to
core/services/ardupilot_manager/firmware/FirmwareInstall.py
and add your board to theget_board_id
function (using theAPJ_BOARD_ID
value from earlier) - If you did your code modifications in GitHub skip to the next step - if you're editing the files in a local clone make sure to
git commit
andgit push
back up to your GitHub fork of the repository - GitHub should prompt you that there are recent changes in your new branch - click the prompt to submit a Pull Request to the upstream Blue Robotics repository
- The "files" tab of your pull request should look similar to this example
- Wait for the GitHub actions to complete (at the bottom of your pull request), then find the build action corresponding to your branch, and download the
BlueOS-core-docker-arm-v7
artifact from it - Go to the BlueOS Version Chooser, scroll down to the bottom, and "manual upload" the artifact you downloaded
- Once BlueOS has restarted, see whether the flight controller board is being detected as an autopilot in the Autopilot Firmware page