Generate, build, run and inspect guarded motion specifications

.github/workflows/gh-pages.yml

@@ -1,8 +1,10 @@
-name: Build and deploy documentation
+name: docs
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
   workflow_dispatch:
 
 permissions:
@@ -19,32 +21,40 @@ jobs:
     name: Build documentation
     runs-on: ubuntu-latest
     steps:
-      - name: Install dependencies
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Graphviz
         run: |
           sudo apt-get update
-          sudo apt-get install -y python3-sphinx python3-sphinx-rtd-theme
-      - name: Checkout motion-spec-ral
-        uses: actions/checkout@v4.2.0
+          sudo apt-get install -y graphviz
+      - uses: actions/setup-python@v5
         with:
-          path: motion-spec-ral
+          python-version: "3.12"
+      # conf.py imports nothing from motion_spec, so the package itself is not built.
+      # Keep this list in sync with the [docs] extra in pyproject.toml (minus sphinx-autobuild);
+      # installing the extra directly would pull workspace deps that are not on PyPI.
+      - name: Install documentation dependencies
+        run: pip install sphinx myst-parser furo matplotlib
       - name: Build documentation
-        run: |
-          sphinx-build -M html ${{ github.workspace }}/motion-spec-ral/docs/sphinx/source ${{ github.workspace }}/motion-spec-ral/build
+        run: sphinx-build -W -b html docs/sphinx/source docs/_build/html
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload artifacts
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ${{ github.workspace }}/motion-spec-ral/build/html
+          path: docs/_build/html
           retention-days: 1
 
+  # Build on every branch and PR so failures surface early; publish only from
+  # main or dev.
   deploy:
     name: Deploy documentation
+    needs: build
+    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-    needs: build
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/test.yml

@@ -0,0 +1,44 @@
+name: test
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      MOTION_SPEC_GEN: ${{ github.workspace }}/generations
+    steps:
+      # Where the manifest's layout puts it, so the test fixtures find thirdparty/motion-spec-dsl.
+      - uses: actions/checkout@v4
+        with:
+          path: thirdparty/motion-spec
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # PyPI's vcstool imports pkg_resources, which current setuptools no longer ships.
+      - name: Install motion_spec
+        run: |
+          sudo apt-get update -q && sudo apt-get install -y vcstool protobuf-compiler
+          pip install -e "thirdparty/motion-spec[test]"
+
+      # The Python packages motion_spec.repos lists, in its order: none are on PyPI, and most
+      # test modules import one, so leaving them out fails collection rather than a test.
+      - name: Import the manifest and install its Python packages
+        run: |
+          vcs import --input thirdparty/motion-spec/motion_spec.repos .
+          python - <<'EOF'
+          import subprocess, sys
+          from motion_spec.setup import STST_REPOSITORY, is_thirdparty, manifest_files, read_manifest
+          for repository in read_manifest(manifest_files()[0]):
+              if is_thirdparty(repository) and repository.path != STST_REPOSITORY:
+                  subprocess.run([sys.executable, "-m", "pip", "install", repository.path], check=True)
+          EOF
+
+      - name: Run tests
+        run: pytest -q thirdparty/motion-spec/tests

.gitignore

@@ -1,4 +1,22 @@
 __pycache__/
 comp-rob2b/
 
-build/
+build/
+.stst/
+generated/
+/runs/
+docs/_build/
+docs/sphinx/source/_static/dsl-paths/
+
+# Python packaging artifacts
+*.egg-info/
+dist/
+.eggs/
+
+# uv lock — not used by CI or the other monorepo packages
+uv.lock
+generations/
+
+# npx fetches prettier on demand; nothing here is installed into the repo
+node_modules/
+package-lock.json

.prettierignore

@@ -0,0 +1,3 @@
+# Vendored libraries are mirrored by scripts/vendor_frontend.py and pinned to their upstream
+# versions: reformatting them would make every future mirror a diff.
+src/motion_spec/dashboard/frontend/vendor/

.prettierrc

@@ -0,0 +1,3 @@
+{
+  "printWidth": 100
+}

README.md

@@ -1,17 +1,100 @@
-# motion-spec-ral
-Code base for RAL paper: *From Composable Models to Correct-by-Construction Software for Contact-Rich Robotic Mobile-Manipulation Tasks*
+# motion-spec
 
-## Documentation
+[![test](https://github.com/secorolab/motion-spec/actions/workflows/test.yml/badge.svg?branch=dev)](https://github.com/secorolab/motion-spec/actions/workflows/test.yml)
+[![docs](https://github.com/secorolab/motion-spec/actions/workflows/gh-pages.yml/badge.svg?branch=dev)](https://github.com/secorolab/motion-spec/actions/workflows/gh-pages.yml)
+
+Validate, compile, build, run, and inspect guarded robot motion specifications.
+
+`motion-spec` consumes the RDF dataset that
+[motion-spec-dsl](https://github.com/secorolab/motion-spec-dsl) emits from a `.robmot`
+model, validates it against the [metamodels](https://github.com/secorolab/metamodels) with
+SHACL, lowers it to an intermediate representation, and generates the C++ controller that
+runs it. Each execution is archived as a run that carries its own provenance: the model and
+contracts it came from, and a full-rate frame log that can be replayed or recovered back
+into RDF.
+
+## Install
+
+```bash
+mkdir -p ~/ws/src && cd ~/ws
+git clone https://github.com/secorolab/motion-spec.git src/motion-spec
+vcs import src < src/motion-spec/motion_spec.repos
+vcs import src < src/motion-spec/motion_spec.real.repos             # with --real only
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e src/motion-spec                                   # the CLI, PyPI dependencies only
+motion-spec setup --workspace . --dev                            # builds and installs what src/ holds
+source setup-motion-spec.bash                                    # .zsh under zsh
+motion-spec health
+motion-spec examples                                             # models to run, in src/ms-examples
+```
+
+With ROS, `--ros` builds the CMake packages with colcon, and the environment file sources the
+distribution and the overlay; the venv has to see the distribution's Python packages:
+
+```bash
+source /opt/ros/jazzy/setup.bash
+python3 -m venv --system-site-packages .venv && source .venv/bin/activate
+pip install -e src/motion-spec
+motion-spec setup --workspace . --dev --ros
+source setup-motion-spec.bash
+```
+
+What motion-spec builds against is listed in one place: the vcstool manifest
+`motion_spec.repos` — rdf-utils, the DSL compilers and rec under `thirdparty/`,
+then Orocos KDL, coord2b, mj_kdl_wrapper and STSTv4 — with the device drivers in
+`motion_spec.real.repos`. `setup` fetches nothing: it pip-installs the Python packages the
+imported checkouts hold into the active environment (or a `.venv` it creates), builds the CMake ones
+into `install/` with the arguments in the workspace's `colcon.meta`, and writes the environment
+file that is the one step between a new shell and a working workspace.
+
+| | |
+|---|---|
+| `--dev` | Python packages installed editable (`pip install -e`); without it they install as snapshots. Sources are in `WORKSPACE/src` either way |
+| `--real` | also install `motion_spec.real.repos`: serial, robotiq_driver_noros, robif2b |
+| `--repos FILE` | install other manifests instead of the shipped one |
+| `--ros` | build with colcon, and source the distro and the overlay instead of exporting paths |
 
-The documentation comprises
+A checkout already at a manifest path is never moved: it is built as it stands, with a warning
+when it is not on the pinned commit, and rebuilt on every run while it has uncommitted changes.
+`--clean` removes builds, installed files and markers, never a source tree. Details:
+**[Setup](https://secorolab.github.io/motion-spec/setup.html)**.
 
-* the [setup instructions](https://secorolab.github.io/motion-spec-ral/setup.html)
-* a [tutorial](https://secorolab.github.io/motion-spec-ral/tutorial.html).
+## Requirements
 
-## Third-party software
+What every model needs, whichever target it drives:
 
-* [`orocos-kdl`](thirdparty/orocos-kdl/) is a modified version that retains the GNU Lesser General Public License version 2.1 and originates from the OROCOS [Kinematics and Dynamics Library](https://github.com/orocos/orocos_kinematics_dynamics).
-* [`GEN3_URDF_V12.urdf`](thirdparty/kinova/GEN3_URDF_V12.urdf) is licensed under the BSD-3-Clause license and originates from Kinova's [ros_kortex](https://github.com/Kinovarobotics/ros_kortex).
+| Stage | Needs | For |
+|---|---|---|
+| Python | 3.11+, with Click, RDFLib, rdf-utils, Jinja, pySHACL and protobuf | the CLI, RDF loading, validation, the IR |
+| Authoring | motion-spec-dsl, scene-dsl, coord-dsl, textX | compiling `.robmot`, `.fsm` and `.scenex` sources |
+| Generation | STSTv4 and `protoc` | rendering the C++, and the frame-log codec |
+| | Git, a JDK and Ant | building STSTv4 itself — a JRE is not enough |
+| Build | CMake and a C++20 compiler | configuring and compiling a generated controller |
+| | coord2b, Eigen, Orocos KDL, toml++ | what every generated controller links |
+| MuJoCo | mj_kdl_wrapper, GLFW, OpenGL, EGL, `ffmpeg` | the simulation, its viewer, and the video recorder |
+
+PyPI packages arrive with `pip install`; `motion-spec setup` installs rdf-utils, the authoring
+packages and rec, and builds STSTv4, coord2b, Orocos KDL and mj_kdl_wrapper; vcstool, Eigen,
+toml++ and `protoc` come from apt. Orocos KDL
+must be the [secorolab fork](https://github.com/secorolab/orocos_kinematics_dynamics) —
+generated controllers call the Vereshchagin solvers with fixed joints, which
+`liborocos-kdl-dev` does not carry.
+
+Per-target and ROS dependencies are installed only when a model asks for them: mj_kdl_wrapper
+for MuJoCo, robif2b and urdfdom for a real robot, `rclcpp` and friends for a model that
+publishes a topic. `motion-spec health` checks all of it and, for anything missing, names what
+it is for and the command that installs it.
+
+## Documentation
+
+Full documentation: **<https://secorolab.github.io/motion-spec/>**
+
+- [Setup](docs/sphinx/source/setup.rst) — dependencies, installation, health checks
+- [Pipeline and artifact concepts](docs/sphinx/source/concepts.rst) — commands, generation layout, archives
+- [Dashboard](docs/sphinx/source/dashboard.rst) — browsing generations, live runs, replay
+- [CLI tutorials](docs/sphinx/source/tutorials/index.rst)
+- [DSL concepts and tutorials](docs/sphinx/source/dsl/index.md)
+- [Original RAL tutorial](docs/sphinx/source/tutorial.rst)
 
 ## Contributors
 
@@ -24,6 +107,25 @@ All Python scripts are licensed under the Mozilla Public License 2.0 (see [`LICE
 
 The models are licensed under the MIT No Attribution (see [`LICENSE.MIT-0`](LICENSE.MIT-0)) License.
 
+## Citation
+
+This is the companion code for *From Composable Models to Correct-by-Construction Software for
+Contact-Rich Robotic Mobile-Manipulation Tasks*, IEEE Robotics and Automation Letters 10(10),
+2025 — [10.1109/LRA.2025.3597864](https://doi.org/10.1109/LRA.2025.3597864). Please cite it if
+you use this software.
+
+```bibtex
+@ARTICLE{11122613,
+  author={Schneider, Sven and Kalagaturu, Vamsi and Bruyninckx, Herman and Hochgeschwender, Nico},
+  journal={IEEE Robotics and Automation Letters},
+  title={From Composable Models to Correct-by-Construction Software for Contact-Rich Robotic Mobile-Manipulation Tasks},
+  year={2025},
+  volume={10},
+  number={10},
+  pages={9894-9901},
+  doi={10.1109/LRA.2025.3597864}}
+```
+
 ## Acknowledgement
 
-This work is part of a project that has received funding from the European Union's Horizon 2020 research and innovation programme SESAME under grant agreement No 101017258.
+This work is part of a project that has received funding from the European Union's Horizon 2020 research and innovation programme SESAME under grant agreement No 101017258.