> For the complete documentation index, see [llms.txt](https://docs.auterion.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auterion.com/app-development/auterion-sdk/system-state-api.md).

# System State API

{% hint style="info" %}
Related C++ Header in the Auterion SDK:`<auterion_sdk/system_state/system_state.hpp>`
{% endhint %}

Auterion SDK provides an interface for subscribing to various states of the vehicle, such as the current position, attitude or battery status. These states can be queried by polling or by registering callbacks.

## Available data

The following states are available through the system state API:

| State           | Data type                  |
| --------------- | -------------------------- |
| Local Position  | `auterion::LocalPosition`  |
| Global Position | `auterion::GlobalPosition` |
| Attitude        | `Eigen::Quaternionf`       |
| Angular Rates   | `auterion::AngularRates`   |
| Armed           | `bool`                     |
| Home Position   | `auterion::HomePosition`   |
| Battery         | `auterion::BatteryStatus`  |
| VTOL State      | `auterion::VtolState`      |
| Manual Input    | `auterion::ManualInput`    |
| Wind            | `auterion::Wind`           |
| Airspeed        | `auterion::Airspeed`       |

## Subscribing to system states

Instantiate an `auterion::SystemState` object, then specify the states to subscribe to.

```cpp
auterion::SystemState system_state(sdk);
// Subscribe to the vehicle's local position, armed state and battery status
system_state.subscribeLocalPosition()
            .subscribeArmed()
            .subscribeBattery();
```

Each subscribed state will have an `auterion::Subcription` object associated with it. The `SystemState` class has accessor functions for each of the supported states, for example: `system_state.localPosition()`. These will be used to query the states and register callbacks.

### Querying the latest state

Poll the latest state value by calling the `last()` function of the corresponding `Subscription`. The return type will depend on what state is being queried.

```cpp
auterion::LocalPosition local_position = system_state.localPosition().last();
```

Note that `last()` will throw an exception if the state has not been subscribed to or if no data has been received for 500ms. To check that data is available and valid, use the `isLastValid()` function.

```cpp
if (system_state.localPosition().isLastValid()) {
    auterion::LocalPosition local_position = system_state.localPosition().last();
}
```

### Registering callbacks

When subscribing to a state, a callback can be provided that will run whenever new data is available.

```cpp
auterion::SystemState system_state(sdk);
// Subscribe to the vehicle's local position, armed state and battery status,
// and register a callback for the armed state.
system_state.subscribeLocalPosition()
            .subscribeArmed([](bool is_armed) {
                std::cout << is_armed ? "Armed" : "Disarmed" << std::endl;
            })
            .subscribeBattery();
```

It is possible to register one or more callbacks after subscribing to a state with the `onUpdate()` method of the appropriate `Subscription`.

```cpp
// Register an additional callback for the armed state
system_state.armed().onUpdate([](bool is_armed) {
    std::cout << "Armed? " << is_armed ? "yes" : "no" << std::endl;
});

// Register a callback for the battery state
system_state.battery().onUpdate([](auterion::BatteryStatus battery_status) {
    std::cout << "Battery voltage: " << battery_status.voltage_v << "V" << std::endl;
});
```


---

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

```
GET https://docs.auterion.com/app-development/auterion-sdk/system-state-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.