Metadata-Version: 2.4
Name: nimbusos-sdk
Version: 0.1.0
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 `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
```

## Subscribe

```bash
cd NimbusOS/sdk
uv run nimbusos-subscribe telemetry
uv run nimbusos-subscribe state
uv run nimbusos-subscribe camera
```

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