Nexus

Signed-off-by: Yadunund <[email protected]>

.github/workflows/nexus_integration_tests.yaml

@@ -0,0 +1,38 @@
+name: integration_tests
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+defaults:
+  run:
+    shell: bash
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        docker_image: ['ros:humble-ros-base']
+    container:
+      image: ${{ matrix.docker_image }}
+    timeout-minutes: 30
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/cache@v3
+      with:
+        path: ~/.cache/ccache
+        key: ccache
+    - name: vcs
+      run: |
+        vcs import . < abb.repos
+    - name: rosdep
+      run: |
+        apt update
+        apt install -y clang clang-tools lld ccache
+        colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
+        colcon mixin update default
+        rosdep update
+        rosdep install --from-paths . -yir
+    - name: build
+      run: /ros_entrypoint.sh colcon build --packages-up-to nexus_integration_tests --mixin release lld --cmake-args -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
+    - name: test
+      run: . ./install/setup.bash && cd nexus_integration_tests && RMW_IMPLEMENTATION=rmw_cyclonedds_cpp /ros_entrypoint.sh python3 -m unittest

.github/workflows/style.yaml

@@ -0,0 +1,27 @@
+name: style
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+defaults:
+  run:
+    shell: bash
+jobs:
+  linter:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        docker_image: ['ros:humble-ros-base']
+    container:
+      image: ${{ matrix.docker_image }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@v2
+      - name: uncrustify
+        run: |
+          sudo apt update && sudo apt install -y ros-humble-rmf-utils
+          /ros_entrypoint.sh ament_uncrustify -c /opt/ros/humble/share/rmf_utils/rmf_code_style.cfg . --language C++ --exclude nexus_endpoints/nexus_endpoints.hpp
+      - name: pycodestyle
+        run: |
+          sudo apt update && sudo apt install -y pycodestyle curl
+          pycodestyle nexus_network_configuration/

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+/thirdparty/
+.vscode/
+*.ikcache

README.md

@@ -0,0 +1,132 @@
+# NEXUS
+![](https://github.com/OpenSourceRobotics/nexus/workflows/style/badge.svg)
+![](https://github.com/OpenSourceRobotics/nexus/workflows/integration_tests/badge.svg)
+
+![](./docs/media/nexus_architecture.png)
+
+A ROS 2 framework which enables configuration and orchestration of process workflows for both individual robotic cells and sets of cells (line). NEXUS facilitates the integration of hardware agnostic industrial robotics and traditional automation components, specifying each cell or line processes through re-configurable behaviour trees. Cells in a line, or hardware components in a cell, can be triggered concurrently or sequentially according to recipes, managed through the orchestrator, departing from traditional Programmable Logic Controllers.
+
+For details on architecture and concepts [see](./docs/concepts.md).
+
+## Requirements
+* [ROS 2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) on `Ubuntu 22.04`
+
+## Setup
+
+### Install system dependencies
+It is recommended to build the workspace with clang as compiler and lld as linker.
+Hence we install these dependencies along with some `colcon-mixin` shortcuts to simplify build instructions.
+```bash
+sudo apt update && sudo apt install -y clang clang-tools lld libstdc++-12-dev
+colcon mixin add default https://raw.githubusercontent.com/colcon/colcon-mixin-repository/master/index.yaml
+colcon mixin update default
+```
+
+### Setup the NEXUS workspace
+
+```bash
+mkdir ~/ws_nexus/src -p
+cd ~/ws_nexus/src/
+git clone [email protected]:OpenSourceRobotics/nexus
+vcs import . < nexus/abb.repos
+cd ~/ws_nexus
+rosdep install --from-paths src --ignore-src --rosdistro humble -y -r
+```
+
+### Build the NEXUS workspace
+```bash
+export CX=clang
+export CXX=clang++
+source /opt/ros/humble/setup.bash
+colcon build --mixin release lld
+```
+
+## Configuration
+
+The workcell and system orchestrators rely on behavior trees for orchestration. `NEXUS` provides several BT skills that may be reused for a variety of applications.
+See sample BTs for [system_orchestrator](nexus_integration_tests/config/system_orchestrator_bt.xml) and [workcell_orchestrator](nexus_integration_tests/config/workcell_1_bts/place_on_conveyor.xml) for a pick & place application.
+
+At present, capabilities are registered as plugins with the `orchestrator` at runtime.
+We support [these capabilities](./nexus_capabilities/src/capabilities/plugins.xml) out of the bo
+Each plugin may register one or more behavior tree nodes which can then be used to define processes as seen in the `place_on_conveyor.xml`.
+The framework to register capabilities and map them to processes that can be performed in ongoing work. See [this discussion](https://github.com/OpenSourceRobotics/nexus/discussions/369) for more details.
+
+### Visualization [experimental]
+![](./docs/media/bt_example.png)
+
+At present, behavior trees can be viewed and modified using [Groot](https://github.com/BehaviorTree/Groot). Once `Groot` is launched, click "Load palette from file" and select [nexus_tree_nodes.xml](./nexus_tree_nodes.xml). Then any of the configured BTs can be loaded via the "Load Tree" button.
+A current limitation of this approach is the need to manually update the palette file when the plugins loaded by a task capability changes. In the future, the goals is to more closely couple the generation of this file and the skill plugins the orchestrators are capable of loading.
+
+### Generating Zenoh bridge configurations
+
+The script in `nexus_network_configuration` helps to simplify configuration of Zenoh bridges for multiple machines. The Zenoh bridge files are generated from [NEXUS Network Configuration](nexus_integration_tests/config/zenoh/nexus_network_config.yaml) and [nexus_endpoints.redf.yaml](./nexus_endpoints.redf.yaml). After configuring the [NEXUS Network Configuration](nexus_integration_tests/config/zenoh/nexus_network_config.yaml), you can run `ros2 run nexus_network_configuration nexus_network_configuration -n <PATH_TO_NEXUS_NETWORK_CONFIG> -r <PATH_TO_REDF_CONFIGS> -o <ZENOH_CONFIGS_OUTPUT_DIRECTORY>` to generate the Zenoh bridges.
+
+Further detailed instructions on running the Zenoh bridges with said configurations are in the [package README](nexus_network_configuration/README.md)
+
+## Demos
+
+![](./docs/media/nexus_demo.png)
+
+Follow instructions [here](nexus_integration_tests/README.md) to run pick and place demonstrations with a line comprising of two workcells that perform different types of tasks.
+
+TODO: Add a dedicated demo package.
+
+
+## Generating Endpoints
+
+The `nexus_endpoints` package contains ROS topics, services and actions used by NEXUS. The package is generated from [nexus_endpoints.redf.yaml](./nexus_endpoints.redf.yaml) using `redf`. rust is required to generated the package, the easiest way to install rust is via [rustup](https://rustup.rs/).
+
+With rust installed, clone the redf repo at https://github.com/OpenSourceRobotics/redf, then run
+```bash
+cargo install --path .
+```
+
+With redf installed, run `generate_endpoints.sh` to generate the package.
+
+## Contributing
+All contributions are welcome! Please ensure the following guidelines are followed when submitting pull requests:
+
+### Signed commits
+* Ensure all commits are [signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+### Endpoints
+Ensure your code does not directly import interface definitions or use hardcoded strings for ROS 2 endpoints.
+All endpoint properties must be retrieved from [nexus_endpoints.hpp](nexus_endpoints/nexus_endpoints.hpp).
+If an endpoint is missing, first add its definition to [nexus_endpoints.redf.yaml](./nexus_endpoints.redf.yaml) and then follow the instructions [above](#generating-endpoints) to re-generate `nexus_endpoints.hpp`.
+
+### Code style
+#### C++
+The NEXUS codebase adheres to C++ style format as used in the [Open-RMF](https://github.com/open-rmf/rmf) project.
+The linter of choice is `uncrustify` and the configuration used may be referenced [here](https://github.com/open-rmf/rmf_utils/blob/main/rmf_utils/test/format/rmf_code_style.cfg).
+Instead of invoking `uncrustify` directly, use `ament_uncrustify` instead which is a wrapper around a specific version of `uncrustify`.
+You may locally run the linter as follows
+```bash
+sudo apt update && sudo apt install -y ros-humble-rmf-utils # This is a one-time step
+source /opt/ros/humble/setup.bash
+cd ~/ws_nexus/src/nexus
+ament_uncrustify -c /opt/ros/humble/share/rmf_utils/rmf_code_style.cfg . --language C++ --exclude nexus_endpoints/nexus_endpoints.hpp
+```
+To automatically reformat the code, append `--reformat` to the `ament_uncrustify` line above.
+It is highly recommended to audit the changes by the linter before committing.
+
+#### Python
+The NEXUS codebase adheres to [PEP8](https://peps.python.org/pep-0008/) style format for python scripts.
+A linter such as `pycodestyle` may be used for linting.
+
+## Known Issues
+
+### Unable to scale speeds of cartesian motions in Humble
+The `humble` version of `moveit2` [lacks support](https://github.com/ros-planning/moveit2/issues/1967) for scaling velocity and accelerations of motion plans generated from cartesian interpolation.
+The fixes are likely to land in further distro releases.
+
+The workaround for now is to rely on fixes incorporated into custom forks of `moveit2` packages which are compatible with `humble`.
+
+>Note: First make sure all `moveit2` binaries are purged from the system via `sudo apt purge ros-humble-moveit*`.
+
+Then as part of the workspace setup, clone in repositories from the [thirdparty.repos](./thirdparty.repos) file.
+Follow the reset of the Setup and Build instructions from above.
+
+```bash
+cd ws_nexus/src/
+vcs import . < nexus/thirdparty.repos
+```

abb.repos

@@ -0,0 +1,21 @@
+repositories:
+  thirdparty/abb/abb_libegm:
+    type: git
+    url: https://github.com/yadunund/abb_libegm.git
+    version: feature/scara
+  thirdparty/abb/abb_librws:
+    type: git
+    url: https://github.com/ros-industrial/abb_librws.git
+    version: master
+  thirdparty/abb/abb_egm_rws_managers:
+    type: git
+    url: https://github.com/yadunund/abb_egm_rws_managers.git
+    version: feature/scara
+  thirdparty/abb/abb_ros2_msgs:
+    type: git
+    url: https://github.com/gbartyzel/abb_ros2_msgs.git
+    version: rolling
+  thirdparty/abb/abb_ros2:
+    type: git
+    url: https://github.com/yadunund/abb_ros2.git
+    version: main

docs/concepts.md

@@ -0,0 +1,24 @@
+# NEXUS Architecture and Concepts
+
+## Guiding Principles
+
+- **Hardware agnosticism**: The core logic of the system should be independent of the brand or type of hardware component.
+- **Scalability**: The system should adapt to additions, subtractions or changes in layout of subsystems providing services.
+- **Reusability**: To facilitate scalability, components of the system throughout the architecture stack should be designed for reuse
+- **Reliability**: Ensure resilience to hard failures as the system scales
+- **Speed**: Ensure efficient operations and minimize added latency
+
+NEXUS is responsible for the coordination of actions within a facility composed of multiple heterogeneous workcells. We define a workcell as a subsystem that provides a specific capability such as pick and place of boxes. Such a workcell may in turn have several subsystems, eg, vision system for object detection and robotic arms for pick and place, etc. The fulfillment of a task would thus require coordination in execution of various subsystems within a workcell and potentially among workcells. A single node to manage such complex workflows is susceptible to a number of problems including
+
+- **Robustness**: A single point of failure for the entire system
+- **Scalability**: Adding new workcells to the system would require rewriting core coordination logic
+- **Complexity**: Several asynchronous events need to be managed for each mechanical system
+- **Network traffic**: The single node needs to discover every other node in the system and this would lead to a network storm of message and discovery packets. This would increase latency or worse lead to messages being dropped.
+
+## Core Design Elements
+
+![](media/nexus_architecture.png)
+
+The adopted architecture is a decentralized yet modular with the following core concepts:
+
+TODO

generate_endpoints.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+here="$(dirname "$0")"
+redf -g=cpp -o="$here/nexus_endpoints" "$here/nexus_endpoints.redf.yaml"