osiris-bridge 0.5.0__tar.gz

osiris_bridge-0.5.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 nicolaselielll
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

osiris_bridge-0.5.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: osiris-bridge
+Version: 0.5.0
+Summary: Osiris bridge: connects a ROS 2 robot (Humble and later) to Osiris
+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 kilted lyrical robotics monitoring bridge osiris
+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 bridge
+
+![PyPI](https://img.shields.io/pypi/v/osiris-bridge.svg)
+![Python](https://img.shields.io/pypi/pyversions/osiris-bridge.svg)
+![License](https://img.shields.io/pypi/l/osiris-bridge.svg)
+![CI](https://github.com/nicolaselielll/osiris_agent/actions/workflows/ci.yml/badge.svg)
+
+The Osiris bridge connects a ROS 2 robot to [Osiris](https://osirislabs.io), where you watch it live, record bags, look back through its history and ask an AI what it is doing.
+
+It runs on the robot as one ROS 2 node, `osiris_node`. It connects out to the Osiris gateway over a WebSocket, sends up what the robot reports, and takes requests back down: subscribe to a topic, record a bag, drive or spin. The connection is outbound only, so nothing has to be opened, forwarded or exposed on the robot's network.
+
+It is published on PyPI as `osiris-bridge` and started with the `osiris` command.
+
+## Requirements
+
+- Linux on x86_64 or arm64 (aarch64).
+- ROS 2 Humble, Jazzy, Kilted or Lyrical, sourced in the shell that starts the bridge.
+- A robot added in Osiris, for its token.
+
+## Install
+
+```bash
+pip3 install osiris-bridge
+```
+
+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-bridge
+```
+
+### Upgrading from osiris-agent
+
+Up to 0.4.0 the bridge was published as `osiris-agent`. Remove it before installing `osiris-bridge`, since both install the same files:
+
+```bash
+pip3 uninstall -y osiris-agent && pip3 install osiris-bridge
+```
+
+On Ubuntu 24.04 and newer, add `--break-system-packages` to both commands. Your token, settings and the `osiris` command stay the same.
+
+## Connect a robot
+
+1. In Osiris, add the robot. The **Configure bridge** popup opens with the commands below, filled in for your robot.
+2. Copy the two lines from step 2 of the popup into the shell (or service) that will run the bridge:
+
+   ```bash
+   export OSIRIS_WS_URL=<your Osiris install's gateway address>
+   export OSIRIS_AUTH_TOKEN=<this robot's token>
+   ```
+
+3. Start the bridge:
+
+   ```bash
+   osiris
+   ```
+
+Osiris shows the robot as connected within a few seconds.
+
+The token is shown only once, when the robot is created or its token is rotated. If it's lost, an owner of the workspace rotates it in **Configure bridge** (robot menu > Bridge) and the bridge needs the new one. Treat the token like a password.
+
+A token only works with the Osiris install that issued it. On the hosted Osiris, `OSIRIS_WS_URL` can be left out. On a self-hosted install it's required: without it the bridge connects to the hosted Osiris, which refuses the token.
+
+## What it sends
+
+With no configuration at all:
+
+- the ROS graph: nodes, topics, actions, services, lifecycle states and QoS
+- CPU, memory, disk, network and battery telemetry, and the busiest processes
+- action goals: their status, feedback and outcome
+- node parameters
+- Nav2's behavior tree, if Nav2 runs
+
+Topic data is sent only for the topics someone subscribes to from Osiris, within rate and size limits (see [Parameters](#parameters)). Raw images are re-encoded to JPEG and point clouds are subsampled before they leave the robot. Node logs (`/rosout`) are a topic like any other: they are sent once `/rosout` is subscribed.
+
+Off until you turn them on: the TF tree (`tf_tree_enabled`), `ros2_control` controllers and hardware (`ros2_control_enabled`), a custom BT.CPP tree (`bt_mode: btcpp`), and robot commands (`commands_enabled`).
+
+Everything is stamped with the robot's own clock, so keep it in sync (`timedatectl set-ntp true`).
+
+## Configuration
+
+The bridge runs in one of two modes, for every setting at once:
+
+1. **Cloud Config** (`osiris` with no parameters): the bridge waits for the configuration saved in Osiris, in the **Cloud Config** tab of **Configure bridge**, and applies it. Changes saved there apply while the bridge runs. A setting Cloud Config leaves out uses its default.
+2. **A parameters file** (`osiris --ros-args --params-file osiris_params.yaml`, or any setting given with `-p`): the bridge applies the file at startup and ignores Cloud Config for the whole run, even for settings the file doesn't mention. Editing the file needs a restart.
+
+Two exceptions:
+
+- `bag_output_dir` is set on the robot only, never from Cloud Config. Setting only it keeps Cloud Config in effect: `osiris --ros-args -p bag_output_dir:=/data/bags`.
+- Robot commands always need **Allow robot commands** in Osiris, and Osiris applies its own limits too, whichever mode the bridge runs in. See [Robot commands](#robot-commands).
+
+A parameters file sets any of the parameters below under `osiris_node`:
+
+```yaml
+osiris_node:
+  ros__parameters:
+    tf_tree_enabled: true
+    bt_mode: nav2
+    battery_topic: /battery_state
+    topic_data_rate_hz: 50.0
+```
+
+### Parameters
+
+| Parameter | Default | What it does |
+|---|---|---|
+| `telemetry_enabled` | `true` | CPU, memory, disk, network and battery telemetry. |
+| `goals_enabled` | `true` | Action goal status and feedback. |
+| `params_enabled` | `true` | Node parameters. |
+| `tf_tree_enabled` | `false` | TF tree monitoring, from `/tf` and `/tf_static` (or the ones under the bridge's namespace). |
+| `tf_tree_poll_interval` | `0.2` s | How often the TF tree is checked for changes. |
+| `ros2_control_enabled` | `false` | `ros2_control` controllers and hardware interfaces. |
+| `ros2_control_poll_interval` | `2.0` s | How often they are read. |
+| `bt_mode` | `nav2` | Behavior tree source: `nav2`, `btcpp` or `off`. See [Behavior trees](#behavior-trees). |
+| `bt_host` | `127.0.0.1` | Where the BT.CPP Groot2 publisher runs (`btcpp` only). |
+| `bt_server_port` | `1667` | Groot2 server port (`btcpp` only). |
+| `bt_publisher_port` | `1668` | Groot2 publisher port (`btcpp` only). |
+| `graph_debounce_interval` | `1.0` s | Wait after a graph change before sending it. `0` sends every change at once. |
+| `battery_topic` | `/battery_state` | `sensor_msgs/msg/BatteryState` topic for battery telemetry and the battery check. |
+| `battery_check_enabled` | `false` | Refuse robot commands below `battery_min_percent`. |
+| `battery_min_percent` | `30.0` | Battery threshold for that check. |
+| `dock_check_enabled` | `false` | Refuse robot commands while docked. |
+| `dock_status_topic` | `/dock_status` | `opennav_docking_msgs/msg/DockStatus` topic for that check. |
+| `commands_enabled` | `false` | Accept drive and spin commands. See [Robot commands](#robot-commands). |
+| `command_max_speed_mps` | `0.5` m/s | Fastest drive. |
+| `command_max_distance_m` | `5.0` m | Longest drive, either direction. |
+| `command_max_angle_deg` | `360.0`° | Largest spin, either direction. |
+| `command_max_time_allowance_s` | `120.0` s | Longest time allowance for a drive or spin. |
+| `bag_output_dir` | `~/ros2_bags` | Where bags recorded from Osiris are saved. Robot only. |
+| `topic_data_rate_hz` | `50.0` Hz | Most messages per second sent for each subscribed topic. `0` is no limit. |
+| `topic_data_max_bytes_per_sec` | `0.0` | Most bytes per second for each subscribed topic. `0` is no limit. |
+| `global_topic_data_max_bytes_per_sec` | `0.0` | Most bytes per second for all subscribed topics together. `0` is no limit. |
+| `global_topic_data_max_msgs_per_sec` | `0.0` | Most messages per second for all subscribed topics together. `0` is no limit. |
+| `image_jpeg_quality` | `70` | JPEG quality (1 to 95) for raw `sensor_msgs/Image` frames. Compressed images are sent as they are. |
+| `image_max_dimension` | `640` px | Longest edge of a raw image after resizing. `0` never resizes. |
+| `pointcloud_max_points` | `10000` | Most points per `PointCloud2` frame; larger frames are subsampled. `0` never subsamples. Never more than 300000. |
+| `pointcloud_keep_intensity` | `false` | Keep each point's intensity. |
+| `pointcloud_keep_rgb` | `false` | Keep each point's color. |
+| `pointcloud_default_rate_hz` | `1.0` Hz | Rate for point cloud topics without their own. `0` is no limit. |
+
+In Cloud Config, a topic can also get its own rate, size, image and point cloud limits, from its row in the Graph pane. A parameters file sets only the defaults above.
+
+### Environment variables
+
+| Variable | Required | What it does |
+|---|---|---|
+| `OSIRIS_AUTH_TOKEN` | Yes | The robot's token. The bridge won't start without it. |
+| `OSIRIS_WS_URL` | On a self-hosted install | The gateway to connect to, for example `wss://osiris.example.com/gateway`. Defaults to the hosted Osiris. |
+| `OSIRIS_ROBOT_MODEL` or `ROBOT_MODEL` | No | The robot model shown in Osiris. Read from `/proc/device-tree/model` when unset. |
+
+## Behavior trees
+
+- **Nav2** (`bt_mode: nav2`, the default) follows Nav2's own `/behavior_tree_log`, with nothing to set up. A Nav2 under a namespace publishes `<namespace>/behavior_tree_log`; the bridge follows the one in its own namespace, else the only one there is.
+- **A custom BT.CPP tree** (`bt_mode: btcpp`) needs Groot2 monitoring turned on in your tree's code (`BT::Groot2Publisher`). Set `bt_host`, `bt_server_port` and `bt_publisher_port` if the publisher isn't on this machine's default ports 1667 and 1668. This mode also sends the tree's blackboard.
+
+Only one mode runs at a time.
+
+## Robot commands
+
+The bridge can run Nav2's `drive_on_heading` and `spin` actions when asked from Osiris. This is **off by default**: while it's off, every motion command is refused. Stopping a running command always works.
+
+An owner of the robot's workspace turns commands on with **Allow robot commands** in **Configure bridge**, where the limits are set too. Osiris sends a motion command only when both Osiris and the bridge allow it, and the stricter limits apply. A parameters file can turn commands off or set stricter limits on this robot, but it can't turn them on while they're off in Osiris:
+
+```yaml
+osiris_node:
+  ros__parameters:
+    commands_enabled: true              # still needs Allow robot commands in Osiris
+    command_max_speed_mps: 0.3
+```
+
+A command is refused before it reaches Nav2 when:
+
+- a value is over a limit, or missing or not a number,
+- another goal is already moving the robot, such as a Nav2 navigation,
+- `battery_check_enabled` is on and the battery is below `battery_min_percent`, or has no reading from the last 10 seconds,
+- `dock_check_enabled` is on and the robot is docked, or has no reading from the last 10 seconds.
+
+The refusal says which.
+
+## Bags
+
+Bags recorded from Osiris are saved on the robot, one folder per recording, in `bag_output_dir` (default `~/ros2_bags`). Set it on the robot:
+
+```bash
+osiris --ros-args -p bag_output_dir:=/data/bags
+```
+
+Osiris lists and downloads only finished recordings directly in that folder (folders with a `metadata.yaml`). A download skips anything a symlink points to. The user running the bridge needs write access to the folder.
+
+## Several robots on one ROS network
+
+Run each robot's bridge in that robot's namespace, so it follows that robot's Nav2, TF and behavior tree and sends commands to the right one:
+
+```bash
+osiris --ros-args -r __ns:=/robot1
+```
+
+## Troubleshooting
+
+- **`OSIRIS_AUTH_TOKEN environment variable must be set`**: export the token in the shell or service that runs `osiris`.
+- **The robot never connects, on a self-hosted install**: `OSIRIS_WS_URL` isn't set where `osiris` runs, so the bridge went to the hosted Osiris. Copy both lines from **Configure bridge**.
+- **`Authentication failed: Invalid token`**: `OSIRIS_WS_URL` points at another install than the one that issued the token, or the token was copied wrong. Otherwise rotate the token.
+- **`Authentication failed: This token was replaced by a newer one`**: someone rotated the token. Use the newest one.
+- **`Authentication failed: This token's robot or its workspace no longer exists`**: the robot was deleted. Add it again and use its new token.
+- **`Authentication failed: Server error`**: the gateway couldn't check the token. Don't rotate it: the bridge keeps retrying and connects once the server is back.
+- **`certificate verify failed`, on a self-hosted install**: the robot doesn't trust the install's certificate. Copy the install's root certificate to the robot (on Ubuntu, into `/usr/local/share/ca-certificates/`, then `sudo update-ca-certificates`).
+- **`osiris: command not found` after switching from osiris-agent**: `osiris-agent` was removed after `osiris-bridge` was installed, which deletes the bridge's files. Run `pip3 install --force-reinstall osiris-bridge`.
+- **`externally-managed-environment` when installing**: use `pip3 install --break-system-packages osiris-bridge`.
+- **Connected, but no nodes or topics**: ROS 2 isn't sourced in the shell that runs the bridge, or `ROS_DOMAIN_ID` differs from the robot's.
+- **Empty TF tree**: turn on `tf_tree_enabled`. With several robots, run the bridge in its robot's namespace.
+- **Empty behavior tree**: see [Behavior trees](#behavior-trees).
+- **No battery data**: `battery_topic` doesn't match the robot's topic (under a namespace it's `<namespace>/battery_state`).
+- **History at the wrong times**: the robot's clock is off. Turn on time sync.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/nicolaselielll/osiris_agent. See [CONTRIBUTING.md](https://github.com/nicolaselielll/osiris_agent/blob/main/CONTRIBUTING.md) to report a bug or send a change, and [SECURITY.md](https://github.com/nicolaselielll/osiris_agent/blob/main/SECURITY.md) to report a security problem privately.
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/nicolaselielll/osiris_agent/blob/main/LICENSE).
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/nicolaselielll/osiris_agent/blob/main/CHANGELOG.md) for what changed in each version.