Metadata-Version: 2.4
Name: nimbusos-sdk
Version: 0.1.7
Summary: Python SDK for NimbusOS.
Author: Droneforge
License-Expression: GPL-3.0-only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: flatbuffers>=25.12.19
Requires-Dist: pyzmq>=26.0.0

# 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

```bash
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.

```bash
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:

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

Install the local SDK wheel into that sandbox:

```bash
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:

```bash
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

```bash
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:

```python
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

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

Python callers use the same `arm_state` message:

```python
from nimbusos_sdk import NimbusClient

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

## Publish Guidance Requests

```bash
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:

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

## Publish Waypoint Commands

```bash
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

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

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

```python
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

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

Python callers use the same relative yaw turn command:

```python
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`
