> For the complete documentation index, see [llms.txt](https://droneforge.gitbook.io/droneforge-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://droneforge.gitbook.io/droneforge-docs/nimbusos-sdk/python-api/quick-start.md).

# Quick Start

This page gives short examples for the most common SDK tasks.

{% hint style="info" %}
Live examples require a running NimbusOS instance connected to the configured ZeroMQ endpoints.
{% endhint %}

## Create a client

Use `NimbusClient` as a context manager when possible:

```python
from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for telemetry in client.telemetry(timeout_sec=1.0):
        print(telemetry.seq, telemetry.t_ns)
        break
```

Exiting the `with` block closes any publisher socket owned by that client.

## Publish a basic command

Arm NimbusOS and request takeoff:

```python
from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    client.publish_arm_state(True)
    client.publish_autonomy_request("takeoff")
```

## Subscribe to telemetry

Telemetry includes battery, attitude, and link information:

```python
from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for telemetry in client.telemetry(timeout_sec=5.0):
        print(f"battery={telemetry.battery.voltage:.2f}V")
        print(f"yaw={telemetry.attitude.yaw_deg:.1f}deg")
```

`timeout_sec` is the total lifetime of the iterator. If no message arrives before the timeout, the iterator ends.

## Subscribe to selected state

Selected state includes local-frame position, velocity, attitude, and orientation:

```python
from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for state in client.selected_state(timeout_sec=5.0):
        if not state.valid:
            continue
        print(state.position.x_m, state.position.y_m, state.position.z_m)
```

## Read camera frames

Save the first core-selected camera frame as a JPEG file:

```python
from pathlib import Path

from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    for frame in client.camera_frames(timeout_sec=5.0):
        Path("frame.jpg").write_bytes(frame.jpeg)
        print(frame.width, frame.height)
        break
```

Use `client.live_camera_frames()` to read the raw live camera stream instead of the core-selected `camera` stream.

## Publish a relative waypoint

Set the waypoint path speed and send an override waypoint in the drone body frame:

```python
from nimbusos_sdk import NimbusClient

with NimbusClient() as client:
    client.publish_waypoint_speed(0.45)
    client.publish_relative_waypoint(
        mode="override",
        forward=1.5,
        right=0.0,
        down=0.0,
        threshold_m=0.15,
        hold_time_s=0.0,
    )
```

`threshold_m` is the distance from the target that counts as reached. `hold_time_s` is the time to hold after reaching the waypoint.

## Use the command line

The package also installs CLI tools for quick smoke tests and manual commands:

```bash
nimbusos-subscribe telemetry --limit 1 --timeout 5
nimbusos-subscribe selected_state --limit 1 --timeout 5
nimbusos-arm
nimbusos-autonomy-request takeoff
nimbusos-autonomy-request relative_waypoint --mode override --forward 1.5 --right 0.0 --down 0.0
nimbusos-waypoint-speed 0.45
nimbusos-yaw-turn-command 0.52
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://droneforge.gitbook.io/droneforge-docs/nimbusos-sdk/python-api/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.