Metadata-Version: 2.4
Name: nimbusos-sdk
Version: 0.1.1
Summary: Python SDK for NimbusOS.
Author: Droneforge
License-Expression: LicenseRef-Proprietary
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`
- Publish `arm_state`
- Publish `guidance_request`
- Publish `waypoint_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
```

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

## 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

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