Agent
How to run Airbotics on your robots.
The Agent is an open-source program that always runs on your robots, it manages communication between the Airbotics cloud and ROS 2 (and optionally the Docker daemon) on your robot.
System requirements
- Ubuntu 22.04 Jammy Jellyfish.
- ROS 2 Humble.
- Docker Engine (optional).
Installing
Install the latest release from pip:
It is best practice to create Python venv before installing.
pip3 install airbotics-agent
Running
Ensure you’ve created a new robot and set the following environment variables before you attempt to run the agent for the first time.
export AIR_TENANT_UUID="0000000-*****-******-******"
export AIR_ROBOT_ID="my-bot"
export AIR_TOKEN="art_************************"
You can then start the agent from the terminal:
airbotics
In production, you may want to consider a robust process management system such as systemd to manage the lifecycle of the agent.
Flags
The following flags can be passed to the agent:
| Flag | Description |
|---|---|
--debug | Log at the debug level and above. |
--daemonize | Daemonize the agent and detach from terminal. Log output is written to ~/.airbotics/airboticsd.log and a PID file is written to ~/.airbotics/airboticsd.pid. |
Configuration
Config can be set from:
Any configuration set with environment variables will overwrite variables in the config.toml.
The following config can be set:
| Option | Default | Description |
|---|---|---|
AIR_ROBOT_ID | The ID of robot | |
AIR_TENANT_UUID | The ID of the tenant who owns the robot | |
AIR_TOKEN | Auth token for robot to authenticate with | |
AIR_ENABLE_CONTAINERS | true | Connect agent to the docker daemon |
AIR_ROS_DISTRO | humble | ROS distro |
AIR_MQTT_HOST | broker.airbotics.io | The MQTT host |
AIR_MQTT_PORT | 15603 | The MQTT port |
AIR_MQTT_KEEP_ALIVE | 60 | The MQTT keep alive in seconds |
AIR_CONTAINER_REGISTRY_URL | https://index.docker.io/v1/ | Container registry url |
AIR_CONTAINER_REGISTRY_USERNAME | Container registry username, if using private repos | |
AIR_CONTAINER_REGISTRY_PASSWORD | Container registry password, if using private repos |
Environment variables
The agent will parse configuration from environment variables.
TOML file
The agent will also look in ~/.airbotics/config.toml for configuration.
Providing a config.toml is completely optional and is provided for convenience.
Logging
The agent produces logs at the following levels:
| Level | Description |
|---|---|
DEBUG | Verbose information for debugging, visible with --debug flag. |
INFO | General information about expected agent execution. |
WARNING | Warnings arising from unexpected situations that are not serious. |
ERROR | Errors arising from situations that affect the agent execution. |
CRITICAL | Critical errors arising from extreme situations that cause agent termination. |
Logs are always written to ~/.airbotics/airbotics.log.
When the agent is run without the --daemonize flag, logs will also be displayed on the console.
Critical errors
There are 3 conditions that produce critical errors and result in the agent terminating:
AIR_TENANT_UUID,AIR_ROBOT_IDorAIR_TOKENare not set in the configuration.- ROS 2 libraries cannot be imported.
AIR_ENABLE_CONTAINERSis set totrueand the Docker daemon cannot be reached.
Changelog
2023.08.08
- Initial release.
2023.08.14
- Added configuration to vitals allowing collection to be toggled.