Metadata-Version: 2.4
Name: osiris_agent
Version: 0.4.0
Summary: OSIRIS agent for ROS 2 (Humble and later)
Home-page: https://github.com/nicolaselielll/osiris_agent
Author: Nicolas Tuomaala
Author-email: nicolas.tuomaala00@gmail.com
License: Apache-2.0
Keywords: ros2 humble jazzy agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets
Requires-Dist: psutil
Requires-Dist: pyzmq
Requires-Dist: msgpack
Requires-Dist: Pillow
Provides-Extra: ros
Requires-Dist: rclpy; extra == "ros"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

# OSIRIS Agent

![PyPI](https://img.shields.io/pypi/v/osiris_agent.svg)
![Python](https://img.shields.io/pypi/pyversions/osiris_agent.svg)
![License](https://img.shields.io/pypi/l/osiris_agent.svg)
![CI](https://github.com/nicolaselielll/osiris_agent/actions/workflows/ci.yml/badge.svg)

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:
```bash
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:
```bash
pip3 install --break-system-packages osiris-agent
```

## Quick Start

### 1. Add token to your environment

```bash
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:

```yaml
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

```bash
osiris
```

## Usage & Configuration

### Environment Variables

- `OSIRIS_AUTH_TOKEN` (required): your robot's token from the Osiris platform
- `OSIRIS_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:

1. Enable Groot2 monitoring in your code
2. Use the standard Groot2 ZMQ ports (1667/1668), or set `bt_server_port` and `bt_publisher_port` to 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.

```yaml
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_enabled` with `battery_topic` and `battery_min_percent`: reject below a battery percentage.
- `dock_check_enabled` with `dock_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:

```bash
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](CONTRIBUTING.md) for how to report a bug or send a change, and [SECURITY.md](SECURITY.md) for reporting a security problem privately.

## License

Apache-2.0 — see the LICENSE file.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for what changed in each version, and GitHub Releases for the release notes.
