nos 0.1.1

Node Orchestration System (NOS) - A declarative DSL for ROS2 robotics

NOS: Node Orchestration System

A declarative domain-specific language (DSL) for ROS2 robotics development.

Overview

NOS reduces ROS2 boilerplate by 70-80% while maintaining full compatibility with existing ROS2 tooling. It provides:

• Declarative syntax for node, topic, and parameter definitions
• Type-safe interfaces with compile-time validation
• Robust Expression Parsing: Full support for mathematical and logical operators with standard precedence.
• Lifecycle management integrated into the language
• Launch file generation from unified definitions
• Code generation for both Python and C++ (C++ in Phase 2)

Current Progress

For detailed status on implementation, testing, and roadmap, see progress.md.

Why NOS?

Aspect	Native ROS2 Python	NOS	Reduction
Simple Node	~60 lines	~15 lines	75%
Lifecycle Node	~120 lines	~25 lines	79%
Launch File	~80 lines	~20 lines	75%
Parameters (10 params)	~50 lines	~10 lines	80%

Requirements

• Python 3.8 or higher
• ROS2 (for runtime usage)
• ANTLR4 Python runtime (installed automatically)

Installation

From Source

1. Clone the repository:

   git clone https://github.com/your-org/nos.git
   cd nos
   

2. Install in development mode:

   pip install -e .
   

Adding to PATH

To use the nos command from anywhere, ensure your Python script directory is in your system's PATH.

Windows:

1. Search for "Edit the system environment variables".
2. Click "Environment Variables".
3. Under "User variables", find Path and click "Edit".
4. Add the path to your Python Scripts folder (e.g., %APPDATA%\Python\Python3x\Scripts).

Linux/macOS: Add this to your .bashrc or .zshrc:

export PATH="$PATH:/home/user/.local/bin"

Quick Start: Turtlesim Circle

NOS allows you to define, compile, and run ROS2 nodes directly.

1. Create circle.node

package turtlesim_example
version "0.1.0"
depends: ["rclpy", "geometry_msgs"]

node CircleGenerator {
    publications {
        cmd_vel: geometry_msgs::Twist @topic("/turtle1/cmd_vel")
    }

    on_init -> {
        self.get_logger().info("Starting circular motion...")
        # Create a timer to publish at 10Hz
        self.create_timer(0.1, self.timer_callback)
    }

    on timer_callback() -> {
        msg = Twist()
        msg.linear.x = 2.0
        msg.angular.z = 1.0
        self.cmd_vel.publish(msg)
    }
}

2. Run Directly

You can skip the manual build process and run the node immediately from the source file:

# Start Turtlesim first in another terminal:
# ros2 run turtlesim turtlesim_node

# Compile and run the NOS node instantly
nos circle.node --run

The --run flag automatically handles code generation, temporary workspace setup, and execution.

Project Structure

nos/
├── grammar/          # ANTLR4 generated parser files (auto-generated)
├── ast/              # Abstract Syntax Tree
├── semantic/         # Semantic analysis
├── codegen/          # Code generation
├── runtime/          # Runtime library
├── compiler/         # Compilation pipeline
└── security/         # Security validation
tests/                # Test suite
├── unit/             # Unit tests
└── integration/      # Integration tests

Note: Files in grammar/ are auto-generated by ANTLR4 from grammar definitions. Do not edit them manually.

File Extensions

• .nos - System definition files (packages, imports, launch declarations)
• .node - Node component definitions
• .interface - Message/service/action interface definitions

Key Features

1. Declarative Parameters

parameters {
    max_velocity: float = 1.0 @range(0.0, 5.0) @unit("m/s")
    enable_filter: bool = true
}

2. Type-Safe Topics

subscriptions {
    scan: sensor_msgs::LaserScan @topic("/scan")
}

publications {
    processed: sensor_msgs::LaserScan @topic("/processed")
}

3. Launch File Generation

launch NavigationStack {
    group sensors @namespace("sensors") {
        lidar: LidarDriver { ... }
        camera: CameraDriver { ... }
    }
}

4. Lifecycle Integration

node MyNode {
    lifecycle: managed  # Enables lifecycle management
    
    on_init { ... }
    on_shutdown { ... }
}

Compilation Pipeline

NOS Source
      |
      v
+-------------+
|   Parse     |  ANTLR4 lexer/parser
|  (ANTLR4)   |  generates parse tree
+------+------+
       |
       v
+--------------+
|  Build AST   |  Parse tree converted
|              |  to typed AST
+------+-------+
       |
       v
+--------------+
|   Analyze    |  Semantic analysis
|              |  validates symbols
+------+-------+
       |
       v
+-------------+
|  Generate   |  Target code generated
|  (Python)   |  for ROS2 nodes
+-------------+

CLI Usage

# Basic compilation
nos input.node -o output_dir/

# With verbose output
nos input.node -v

# Dry run (validate only)
nos input.node --dry-run

# Multiple files
nos file1.node file2.nos -o generated/

# Show version
nos --version

Development

Running Tests

# Run all tests
pytest

# With coverage
pytest --cov=nos --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_ast_builder.py

Code Style

# Format code with black
black nos/ tests/

# Type checking
mypy nos/

# Linting
flake8 nos/ tests/

See CONTRIBUTING.md for detailed contribution guidelines.

Status

Phase 1: Core Language (Complete) ✓

• ANTLR4 grammar definitions
• AST and semantic analyzer
• Python code generator
• Launch file transpiler
• Runtime library
• Security validation
• Callback syntax & custom events (Issue #6)

Phase 2: Extended Features (Planned)

• C++ code generator
• Enhanced IDE support (LSP)
• Visual diagram generation
• Package management tools

See CHANGELOG.md for detailed release information.

Documentation

• Architecture Overview - Detailed design document
• Contributing Guide - Development setup and guidelines
• Changelog - Version history and changes

License

Apache License 2.0 - See LICENSE for details.

Acknowledgments

NOS was inspired by the verbosity challenges in ROS2 development and aims to provide a more ergonomic interface while maintaining full compatibility with the ROS2 ecosystem.