OSIRIS Agent
A ROS 2 node (Humble and later) that bridges your robot to the OSIRIS remote monitoring platform via WebSocket.
Install
Install the OSIRIS agent on your robot:
pip3 install osiris-agent
On Ubuntu 24.04 and newer (ROS 2 Jazzy and later), pip refuses to install into the system's Python unless told to:
pip3 install --break-system-packages osiris-agent
Quick Start
1. Add token to your environment
export OSIRIS_AUTH_TOKEN=your-token-here
2. (Optional) Monitor a custom BT.CPP tree
Nav2's own behaviour tree is monitored by default (bt_mode: nav2). For a custom BT.CPP tree with Groot2 monitoring, set bt_mode to btcpp, in Configure agent in the Osiris app or in a ROS 2 parameters file:
osiris_node:
ros__parameters:
bt_mode: btcpp # off | nav2 (default) | btcpp
bt_host: 127.0.0.1 # where the Groot2 publisher runs
bt_server_port: 1667
bt_publisher_port: 1668
3. Start agent
osiris
Usage & Configuration
Environment Variables
OSIRIS_AUTH_TOKEN(required): your robot's token from the Osiris platformOSIRIS_WS_URL(optional): the gateway's WebSocket address, for a self-hosted Osiris. Defaults to the hosted Osiris.
Every other setting is a ROS 2 parameter of the osiris_node node, or comes from Configure agent in the Osiris app.
BT.CPP Integration
The agent collects behaviour tree events from BT.CPP when bt_mode is btcpp. Your BT.CPP application must:
- Enable Groot2 monitoring in your code
- Use the standard Groot2 ZMQ ports (1667/1668), or set
bt_server_portandbt_publisher_portto match
The collector uses BT.CPP's standardized Groot2 protocol, so it works with any behaviour tree without custom configuration.
Robot commands
The agent can run Nav2 spin and drive_on_heading actions when asked from the Osiris platform. This is off by default: while disabled, every motion command is rejected. Cancelling a running command always works.
An owner of the robot's workspace turns commands on with Allow robot commands in Configure agent in the Osiris app, where the limits below are set too. Osiris sends a motion command only when both the app and the agent allow it, and the stricter limits apply.
When a ROS 2 parameters file is passed, it takes precedence over the cloud configuration for every setting the agent applies. For commands, a parameters file can turn them off or set stricter limits on this robot, but it can't turn them on while they're off in the app.
osiris_node:
ros__parameters:
commands_enabled: true # still needs Allow robot commands in the app
command_max_speed_mps: 0.5 # default 0.5
command_max_distance_m: 5.0 # default 5.0
command_max_angle_deg: 360.0 # default 360.0
command_max_time_allowance_s: 120.0 # default 120.0
A command that exceeds one of the limits is rejected before it reaches Nav2, as is one with a missing or non-numeric value. Two optional safety checks reject commands while a condition holds:
battery_check_enabledwithbattery_topicandbattery_min_percent: reject below a battery percentage.dock_check_enabledwithdock_status_topic: reject while the robot is docked.
Bags
Bags recorded from the Osiris app are saved on the robot, one folder per recording, in the agent's bag_output_dir (default ~/ros2_bags). The folder is set on the robot only, never from the app:
osiris --ros-args -p bag_output_dir:=/data/bags
Setting only bag_output_dir, this way or in a parameters file, keeps the configuration from the app in effect; a parameters file that sets other fields replaces it, as above. The app lists and downloads only finished ROS 2 bags directly in that folder (folders with a metadata.yaml), and a download skips anything a symlink points to.
Upgrading from 0.3.123 or earlier: the app can no longer change the bag folder. If you had set one there, recordings go back to the robot's own bag_output_dir; set it on the robot as above to keep using your folder.
Contributing
Bug reports and pull requests are welcome at https://github.com/nicolaselielll/osiris_agent. See CONTRIBUTING.md for how to report a bug or send a change, and SECURITY.md for reporting a security problem privately.
License
Apache-2.0 — see the LICENSE file.
Changelog
See CHANGELOG.md for what changed in each version, and GitHub Releases for the release notes.
1 maintainer
Metadata
1 maintainer
Release files for osiris-agent 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| osiris_agent-0.4.0.tar.gz | 409.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| osiris_agent-0.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 803.4 kB
Release files / osiris_agent-0.4.0.tar.gz
| Download URL | osiris_agent-0.4.0.tar.gz |
|---|---|
| Size | 409.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
38c31d2cf9f3cf619300ce2d96d4991537fd959648280bdff8b7950690990508
|
|
BLAKE2b-256 checksum How to use checksums |
60a9dbebccef7b24f556464bb312c21e67b0e7780a21969e95aae9a40228db75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Release files / osiris_agent-0.4.0-py3-none-any.whl
| Download URL | osiris_agent-0.4.0-py3-none-any.whl |
|---|---|
| Size | 393.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4105b0b49ddb6b18f22695748b5a091f90e0b481cd4e6ea2b6d0b09286964341
|
|
BLAKE2b-256 checksum How to use checksums |
fa37392b1dbec399b8057bdcc46f3353ed99ae38f90710e408c04f042a0ebc21
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.0
|
Security for osiris-agent 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
