motion-spec

motion-spec validates, compiles, builds, runs, and inspects guarded robot motion specifications. It accepts a .robmot model for the complete workflow and retains lower-level RDF, IR, code-generation, and archive commands for tools that need individual stages.

Quick start

motion-spec needs the rest of what it builds against — the authoring DSLs, the kinematics fork, the simulator wrapper — listed in the .repos manifests at the repository root. You import them with vcs; motion-spec setup builds and installs what was imported:

$ mkdir -p ws/src
$ git clone git@github.com:secorolab/motion-spec.git ws/src/motion-spec
$ vcs import ws/src < ws/src/motion-spec/motion_spec.repos
$ python3 -m venv ws/.venv && source ws/.venv/bin/activate
$ pip install -e ws/src/motion-spec            # the CLI, PyPI dependencies only
$ motion-spec health                           # the one apt line for what is missing
$ motion-spec setup --workspace ws --dev       # builds and installs what ws/src holds
$ source ws/setup-motion-spec.bash             # or .zsh, whichever setup wrote

ROS is optional, and the robot hardware drivers are installed only after vcs import ws/src < ws/src/motion-spec/motion_spec.real.repos and setup --real. Then run a model, replay the run it recorded, and run the same generation again:

$ motion-spec run model.robmot --run-id run-1 --headless
$ motion-spec replay "$MOTION_SPEC_GEN/latest/runs/run-1"
$ motion-spec rerun --run-id run-2 --headless

Run motion-spec --help or motion-spec COMMAND --help for the exact options supported by the installed version.

Where to go next

Start with Setup, read Concepts for the pipeline and artifact contracts, then work through Build and run to generate, build, and run one. Read DSL authoring when you author a model of your own rather than running an existing one.

Guide

• Setup
  • The Python environment
  • What setup installs
  • The environment file
  • Example models
  • Without ROS
  • Dependencies
  • Code generation
  • Health checks
  • As a library
  • Development checkout
• Concepts
  • Pipeline
  • Generations and runs
  • High-level commands
  • Low-level commands
  • Validation
  • Runtime recording
  • Replay
• motion-spec codegen architecture
  • 1. The pipeline
  • 2. The module set
  • 3. The two interfaces
  • 4. The layer boundary
  • 5. How this is verified
• Sim/real parity
  • The fork surface
  • The external-wrench law
  • What the gate covers
• Control loop timing
  • The contract
  • Where the loop waits
  • Why a stock kernel still overshoots
  • What the generated program does about it
  • The three cases, and the overrun
  • Who paces the loop
  • The four modes
  • Deliberately not done
  • Measuring it
• Dashboard
  • The pages
  • Organizing results
  • Returning to an investigation
  • Verification
  • Driving a simulated run
• Build and run
  • Generate, build, and run
  • Run one generation repeatedly
  • Validate and inspect

Authoring language

• DSL authoring
  • DSL concepts
  • Quantity expressions
  • DSL tutorials

About

• Acknowledgement