nimbusos-sdk 0.1.9

Python SDK for NimbusOS.

NimbusOS Python SDK

This is the first narrow Python SDK surface for NimbusOS pubsub.

V1 supports:

• Subscribe to telemetry
• Subscribe to selected_state
• Subscribe to camera
• Subscribe to camera_overlay
• Subscribe to live_camera
• Subscribe to waypoint_status
• Subscribe to autonomy_status
• Publish arm_state
• Publish autonomy_request
• Publish waypoint_speed
• Publish yaw_turn_command
• Publish camera_overlay

It does not expose raw pubsub publishing, all-topic subscription, legacy route messages, navigation request messages, or internal control topics.

Install

cd NimbusOS/sdk
uv sync

Local Development Without PyPI

Use this loop before publishing. It builds the SDK exactly as a package, then installs that local wheel into the sandbox environment.

cd /Users/davidcrabtree/projects/droneforge_mvp/NimbusOS/sdk
uv run python scripts/refresh_schema.py --check
uv build

Create the sandbox virtualenv if it does not already exist:

cd /Users/davidcrabtree/projects/NimbusOS-sdk-sandbox
uv venv --python 3.12

Install the local SDK wheel into that sandbox:

cd /Users/davidcrabtree/projects/droneforge_mvp/NimbusOS/sdk
uv run python scripts/install_local_wheel.py /Users/davidcrabtree/projects/NimbusOS-sdk-sandbox/.venv/bin/python

Run sandbox checks directly from .venv/bin after installing the local wheel:

cd /Users/davidcrabtree/projects/NimbusOS-sdk-sandbox
.venv/bin/python examples_v0/smoke_import.py
.venv/bin/nimbusos-subscribe --help
.venv/bin/nimbusos-arm --help
.venv/bin/nimbusos-autonomy-request --help
.venv/bin/nimbusos-waypoint-speed --help
.venv/bin/nimbusos-yaw-turn-command --help

Do not run uv sync between the local wheel install and the sandbox checks. The sandbox dependency pin is for released packages, so syncing can replace the local wheel with the PyPI version.

Release Process

1. Bump version in pyproject.toml and refresh uv.lock.
2. Run uv run python scripts/refresh_schema.py --check.
3. Run uv build.
4. Install the built wheel into a clean environment with scripts/install_local_wheel.py.
5. Run the import and CLI smoke checks above.
6. Run the live sandbox examples against NimbusOS when the app/core is running.
7. Publish to TestPyPI.
8. Install from TestPyPI in a clean environment and repeat the smoke checks.
9. Publish the same artifacts to PyPI.
10. Update the sandbox package pin to the released version and run uv sync.

Subscribe

cd NimbusOS/sdk
uv run nimbusos-subscribe telemetry
uv run nimbusos-subscribe selected_state
uv run nimbusos-subscribe camera
uv run nimbusos-subscribe camera_overlay
uv run nimbusos-subscribe live_camera
uv run nimbusos-subscribe waypoint_status
uv run nimbusos-subscribe autonomy_status

camera is the core-selected camera stream. live_camera is the raw Chromium camera capture stream before core camera-source selection.

Publish Camera Overlays

camera_overlay is an inference visualization layer. It keeps camera pixels on the camera topic and sends only drawing instructions to NimbusOS/ui. Overlay coordinates are in the image coordinate system described by frame_width and frame_height; the UI scales them to the current camera frame before drawing.

from nimbusos_sdk import NimbusClient, box

with NimbusClient() as client:
    for frame in client.latest_camera_frames():
        client.publish_camera_overlay(
            camera_seq=frame.seq,
            frame_width=frame.width,
            frame_height=frame.height,
            source="my_detector",
            layers=[
                {
                    "name": "detections",
                    "primitives": [
                        box(120, 80, 180, 240, label="person", confidence=0.91),
                        {
                            "type": "arrow",
                            "tone": "warning",
                            "x": 210,
                            "y": 200,
                            "x2": 280,
                            "y2": 170,
                            "label": "motion",
                        },
                    ],
                }
            ],
        )

Python callers can decode waypoint status into a small typed object:

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for status in client.waypoint_status():
        print(status.active, status.reached, status.held, status.distance_m)

Python callers can decode selected state into a small typed object:

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for state in client.selected_state():
        print(state.valid, state.position.z_m, state.velocity.z_mps)

Python callers can decode autonomy status into a small typed object:

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for status in client.autonomy_status():
        if status.status == "landing_low_battery":
            print("landing because of low battery")

Publish Arm State

cd NimbusOS/sdk
uv run nimbusos-arm
uv run nimbusos-arm --disarm

Python callers use the same arm_state message:

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    client.publish_arm_state(True)

Publish Autonomy Requests

cd NimbusOS/sdk
uv run nimbusos-autonomy-request takeoff
uv run nimbusos-autonomy-request land
uv run nimbusos-autonomy-request return_home

Autonomy can also request a relative waypoint:

cd NimbusOS/sdk
uv run nimbusos-autonomy-request relative_waypoint --mode override --forward 1.5 --right 0.0 --down 0.0
uv run nimbusos-autonomy-request relative_waypoint --mode queue --forward 1.0 --right 0.5 --down 0.0 --hold-time 0.5

Relative waypoint fields are body-frame offsets:

• forward: meters forward/back in the drone's current body heading
• right: meters right/left in the drone's current body heading
• down: meters down/up relative to the current or queued waypoint base
• mode=override: replace the active waypoint
• mode=queue: append after the active waypoint

Publish Waypoint Speed

cd NimbusOS/sdk
uv run nimbusos-waypoint-speed 0.45

Python callers can change the waypoint path speed any time during a flight:

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
	client.publish_waypoint_speed(0.25)
	client.publish_relative_waypoint(
		mode="override",
		forward=1.5,
		right=0.0,
		down=0.0,
	)

    if target_detected:
        client.publish_waypoint_speed(0.60)
    else:
        client.publish_waypoint_speed(0.20)

The SDK uses the same speed range as the UI slider: 0.05 to 0.75 m/s.

Publish Yaw Turn Commands

cd NimbusOS/sdk
uv run nimbusos-yaw-turn-command 0.52

Python callers use the same relative yaw turn command:

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    client.publish_yaw_turn_command(0.52)

Endpoints

The client uses these defaults:

• publish: tcp://127.0.0.1:7771
• subscribe: tcp://127.0.0.1:7772

You can override them with:

• DF_ZMQ_PUB_ENDPOINT
• DF_ZMQ_SUB_ENDPOINT