nimbusos-sdk 0.1.7

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 state
• Subscribe to camera
• Subscribe to live_camera
• Subscribe to waypoint_status
• Publish arm_state
• Publish guidance_request
• Publish waypoint_command
• Publish waypoint_speed
• Publish yaw_turn_command

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-guidance-request --help
.venv/bin/nimbusos-waypoint-command --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 state
uv run nimbusos-subscribe camera
uv run nimbusos-subscribe live_camera
uv run nimbusos-subscribe waypoint_status

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

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)

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 Guidance Requests

cd NimbusOS/sdk
uv run nimbusos-guidance-request go
uv run nimbusos-guidance-request land
uv run nimbusos-guidance-request return_home

Guidance can also request a relative waypoint:

cd NimbusOS/sdk
uv run nimbusos-guidance-request relative_waypoint --forward 1.5 --right 0.0 --down -1.0

Publish Waypoint Commands

cd NimbusOS/sdk
uv run nimbusos-waypoint-command --mode override --forward 1.5 --right 0.0 --down -1.0
uv run nimbusos-waypoint-command --mode queue --forward 1.0 --right 0.5 --down -1.0

Waypoint command fields match the core schema:

• forward: meters forward/back in the drone's current body heading
• right: meters right/left in the drone's current body heading
• down: absolute local-frame down target
• 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_waypoint_command(
        mode="override",
        forward=1.5,
        right=0.0,
        down=-1.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