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

1. Changing the "Remote" to your DockerHub repository, then installing like you would normally
2. Doing a "Manual Upload" of a .tar compressed BlueOS-core Docker image

Structure

1. Dockerfile (and corresponding .dockerignore file) for building the BlueOS-core Docker image
2. **/install-*.sh scripts that the Dockerfile uses to install the tools, libraries, and services
3. tools scripts used to install the underlying programs used by the service backends
4. configuration files that the Dockerfile moves to appropriate locations for the programs they apply to
5. 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)
6. libs code libraries of shared functionality available to the service backends
7. 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
8. 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

1. Connect your flight controller board via USB¹ to a computer running BlueOS
2. Go to the BlueOS Terminal page
3. Open a Python console (run the python3 command)
4. Run from serial.tools.list_ports import comports
5. Run from pprint import pprint
6. Run [pprint(port.__dict__) for port in comports()]
7. Get the "product" and "manufacturer" values for your flight controller board

Find the flight controller hardware information

1. Go to the ArduPilot hardware definition files
2. Find the folder corresponding to your flight controller board
3. Find the APJ_BOARD_ID variable in the hwdef.dat or hwdef.inc file

Add the board, and confirm it works

1. Fork the BlueOS repository
   • You'll need a GitHub account to do this
2. Click where it says master, and create a new branch (e.g. add-pixhawk-6C)
3. Navigate to core/services/ardupilot_manager/typedefs.py and add your board's name and type to the Platform 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
4. Navigate to core/services/ardupilot_manager/flight_controller_detector/board_identification.py and add appropriate SerialBoardIdentifier instances to the identifiers list (using the "product" and "manufacturer" values from earlier)
   • The "product" is more important/useful, because one "manufacturer" can make multiple different board types
5. Navigate to core/services/ardupilot_manager/firmware/FirmwareInstall.py and add your board to the get_board_id function (using the APJ_BOARD_ID value from earlier)
6. 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 and git push back up to your GitHub fork of the repository
7. 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
8. 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
9. Go to the BlueOS Version Chooser, scroll down to the bottom, and "manual upload" the artifact you downloaded
10. Once BlueOS has restarted, see whether the flight controller board is being detected as an autopilot in the Autopilot Firmware page