ROOP Language Support

Version: 1.0.0
Target: Robot-Oriented Operational Programming (ROOP) + VS Code

ROOP is a task-oriented scripting language for robots and automation. You describe what should happen using readable verbs and semantic selectors, and modules handle how it runs on real hardware and services.

This repository contains the VS Code extension and associated tooling for ROOP:

• Syntax highlighting and editor configuration for .roop scripts
• Language server (completion, hover, diagnostics, formatting, folding)
• Schema-driven validation for configuration files
• Commands and tasks exposed in VS Code
• roop-cli command-line utilities for init, validation, discovery, and calibration
• Optional integration with the separate roopmodule module library

1. Features Overview

1.1 Editor & Language Server

• TextMate grammar for .roop
• Automatic indentation and on-enter rules
• Bracket and quote auto-closing, comment toggling
• Snippets for common ROOP patterns (tasks, triggers, concurrency, error handling)

Language server capabilities:

• Code completion for:
  • Keywords and language constructs
  • Common actions and spatial relations
  • Module IDs and capabilities (when a module registry is present)
• Hover information for:
  • Language keywords
  • Referenced classes, devices, modules, and capabilities
• Diagnostics:
  • Structural errors (unclosed tasks, missing colons, bad indentation)
  • Schema validation errors in configuration files
• Formatting and folding support for .roop documents

1.2 Schema-Driven Configuration

Built-in JSON Schemas provide validation, completion, and hover help for:

• config/device_lib.yaml – device library
• joints/*.joint.yaml|yml|json – joint / actuator configuration
• robots/*.profile.yaml|yml|json – robot profiles
• *.roopmodule.json – ROOP module manifests

Benefits:

• Strong validation in the editor (types, ranges, required fields)
• ID completion for class_id, device_id, joint_module, etc.
• Easier refactoring and safer configuration changes

1.3 roop-cli Tooling

The roop-cli script (Node.js) provides command-line helpers and backs several VS Code commands:

• Project and configuration initialization:
  • init project
  • init robot
  • init joint
• Configuration validation:
  • validate (device library, joints, profiles)
• Device discovery:
  • Match detected hardware to entries in device_lib
  • Optionally write discovered mappings back to robot profiles
• Calibration helpers:
  • Joint direction sign (mount.direction_sign)
  • IMU gravity orientation

These commands can be used directly in a terminal or invoked from the VS Code command palette.

1.4 Run Report & World Model (Offline “Dry Runs”)

The extension includes a lightweight offline execution and reporting layer:

• Run a task from a .roop file and produce a RunReport
• Summaries include:
  • Modules and capabilities used
  • Resource usage and conflicts
  • Safety-related warnings (limits, potential risks)
  • World effects (object interactions, navigation intents, etc.)
• The World Model view in the Activity Bar shows:
  • Status of the last run
  • Manipulation and I/O summaries
  • Stability and safety summaries
  • Logs and key events

This is intended for debugging and reviewing task logic without connecting to real hardware.

1.5 VS Code Integration

• Dedicated ROOP container in the Activity Bar:
  • Modules view
  • Tasks view
  • World Model view
• VS Code tasks and problem matchers for ROOP:
  • Validate, format, run, and smoke-test tasks
  • Diagnostics integrated into the Problems panel
• Getting-started walkthrough and example project generator

2. Installation

2.1 Requirements

• Visual Studio Code 1.84.0 or later
• Node.js (recommended for roop-cli and extension development workflows)

2.2 Installing the Extension

You can install from a packaged .vsix file:

1. Open VS Code
2. Go to Extensions → click the … menu in the title bar
3. Select Install from VSIX…
4. Choose the ROOP Language Support .vsix file

Or install from the Marketplace entry once published under the name:

ROOP: Robot-Oriented Operational Programming

The extension activates automatically when a workspace contains .roop files.

3. Recommended Project Layout

A typical ROOP workspace might look like this:

your-workspace/
  roop/
    main.roop
  config/
    device_lib.yaml
  catalog/
    device_lib.yaml
    joint_module_lib.yaml
    robot_classes.yaml
  joints/
    shoulder.joint.yaml
    elbow.joint.yaml
  robots/
    my_robot.profile.yaml
  modules/             # optional, for roopmodule / module manifests
    index.yaml
    examples/...

The extension and CLI tools will look for these locations by default when validating and generating configs.

4. Quick Start

4.1 Generate an Example Project

Open the command palette (Ctrl+Shift+P / Cmd+Shift+P) and run:

• ROOP: Create Example Project

This creates a folder (for example roop-examples/) with:

• basic.roop – minimal task example
• events.roop – event and trigger examples
• control_flow.roop – conditionals and loops
• concurrency.roop – parallel tasks and sub-tasks
• modules/ExampleArm.roopmodule.json – a simple module manifest

4.2 Run a Task (Offline)

1. Open roop-examples/basic.roop

2. Place the cursor inside a start task ... end task block

3. Run the command:

   • ROOP: Run Current Task

4. Check:

   • The Output panel for a text run report
   • The World Model view for a structured summary

4.3 Insert a Task Template

In a .roop file, use:

• Ctrl+I (Windows/Linux) or Cmd+I (macOS)

This inserts a task skeleton:

start task "NewTask"
  say "Hello"
end task

4.4 Open the Language Reference

Run:

• ROOP: Open Language Reference

This opens the bundled language reference, which documents syntax and common patterns.

5. ROOP Language Basics (Short Overview)

A few core constructs:

5.1 Tasks

start task "HelloWorld"
  say "Hello, world."
end task

5.2 Triggers

when object "mug" appears:
  say "Found a mug."

at time "07:00":
  say "Good morning."

every 5 min:
  notify "Periodic check."

5.3 Control Flow

if sensor "Door" == "open":
  say "Door is open."
else:
  say "Door is closed."

repeat 3 times:
  say "Trying again."

5.4 Concurrency

parallel:
  run "ScanArea"
  detached run "WatchEmergencyStop"
await run "MoveToDock"

5.5 Error Handling

grasp with Gripper1
on failure:
  retry after 2 s

move Arm1 to "Home"
on timeout:
  fallback:
    say "Timeout: switching to safe procedure."

For the full language specification, refer to the language reference opened via ROOP: Open Language Reference.

6. Configuration Schemas

The extension ships JSON Schemas and hooks them into VS Code so that relevant YAML/JSON files receive validation and completion automatically.

6.1 Device Library (config/device_lib.yaml)

Defines physical devices and their properties, such as:

• device_id
• vendor and model information
• power and communication details

Robot profiles reference these devices by device_id, with editor completion and hover help.

6.2 Joint Configuration (joints/*.joint.yaml)

Describes joint modules or actuators, such as:

• motion limits
• gearing
• mounting orientation
• driver type and communication settings

The CLI tools can update some fields (e.g., direction sign) as part of calibration steps.

6.3 Robot Profiles (robots/*.profile.yaml)

Robot profiles tie everything together:

• class_id (mapped to robot class definitions in catalog/robot_classes.yaml)
• references to devices and joints
• base type and motion configuration
• additional metadata for tasks and safety

All fields are validated against the schema and support completion where appropriate.

6.4 Module Manifests (*.roopmodule.json)

Module manifests describe capabilities, parameters, interfaces, and safety rules for a module. They are validated by a dedicated schema and can be generated via the corresponding VS Code command.

A minimal example:

{
  "schemaVersion": "1.0",
  "module": {
    "id": "loop.arm.v1",
    "name": "6-DoF Robotic Arm",
    "version": "1.0.0",
    "vendor": "Loop Robotics",
    "category": "manipulation"
  },
  "capabilities": [
    {
      "id": "manipulation.move",
      "title": "Arm motion",
      "verbs": ["move", "approach", "align"]
    }
  ]
}

7. roop-cli Usage

roop-cli is a Node.js script used both inside and outside VS Code. From the ROOP folder:

node scripts/roop-cli.js <command> [options]

7.1 Validate Configs

node scripts/roop-cli.js validate

This runs schema validation for known config files (device library, joints, profiles).

7.2 Initialize Project / Robot / Joint

# Initialize a new ROOP project structure
node scripts/roop-cli.js init project my_project

# Initialize a robot profile based on a class
node scripts/roop-cli.js init robot my_robot --class=diff_drive_robot

# Initialize a joint configuration using a template and profile
node scripts/roop-cli.js init joint shoulder \
  --template=loop.joint.position_v1 \
  --profile=robots/my_robot.profile.yaml

These commands create skeleton files that conform to the schemas.

7.3 Device Discovery

node scripts/roop-cli.js discover devices \
  --device-lib=config/device_lib.yaml \
  --mode=can \
  --detected=detected.json \
  --apply-profile=robots/my_robot.profile.yaml

• Reads detected device information (from a JSON dump or stub)
• Matches devices against device_lib
• Writes suggestions to a separate file
• Optionally applies mappings back to the robot profile

7.4 Calibration Helpers

Joint direction:

node scripts/roop-cli.js calibrate joint-direction \
  --file=joints/shoulder.joint.yaml \
  --before=10 --after=-5

IMU gravity:

node scripts/roop-cli.js calibrate imu-gravity \
  --gx=0.1 --gy=9.7 --gz=0.2 \
  --file=config/imu_mount.yaml

The CLI updates configuration files to reflect the computed calibration settings.

8. Optional: Using With roopmodule

This repository is focused on the VS Code extension and core tooling. It can be combined with a separate roopmodule library that provides:

• .roopmodule / .roopmodule.yaml files describing modules
• A modules/index.yaml registry for module lookup
• Python tooling for validating and generating code from module definitions

When a module registry is present in the workspace (modules/index.yaml and related files), the ROOP extension can:

• Offer completion for use module "<module_id>" based on module IDs in the registry
• Show hover information for module capabilities and commands

These features are optional but recommended for larger systems with many hardware modules.

9. Development

To work on the extension itself, from the ROOP directory:

npm install
npm run compile

9.1 Launch Extension Host

1. Open the ROOP folder in VS Code

2. Press F5 to start an Extension Development Host

3. Open a .roop file in the host window to test:

   • Syntax highlighting
   • Language server behavior
   • Commands and views

9.2 Useful Scripts

npm run lint          # lint source files
npm run format        # apply formatting rules
npm run compile       # compile TypeScript
npm run validate:configs
npm run doc:schemas   # generate schema documentation
npm run smoke         # basic smoke tests

9.3 Packaging

To produce a .vsix package:

npx vsce package

The resulting .vsix can be installed locally or published to the VS Code Marketplace (with an appropriate publisher and token).

10. Troubleshooting

• No highlighting or features active Check that the file extension is .roop and that you have opened a folder as a workspace (not just a single file).

• Schema validation errors for YAML/JSON Use the Problems panel to locate the exact field. Errors typically involve:

  • Missing required fields
  • Invalid types
  • Out-of-range values

• No completion for devices, joints, or classes Ensure that:

  • config/device_lib.yaml exists and passes validation
  • catalog/*.yaml files exist for robot classes and joint modules
  • The workspace is opened at the correct root

• Run task or world model view not updating Confirm you are running ROOP: Run Current Task within a start task ... end task block and that the extension is activated.

11. License

This project is licensed under the MIT License. See the LICENSE file for details.