> ## Documentation Index > Fetch the complete documentation index at: https://docs.efference.ai/llms.txt > Use this file to discover all available pages before exploring further. # Core Types > The data structures returned by the device ## Mat An owned image buffer filled by `retrieve_image()`. The fields are private (the SDK is the sole producer) and consumers read through accessors: | Accessor | Returns | Meaning | | ------------------------------------------------ | -------------------- | --------------------------------------------- | | `getPtr()` | `uint8_t*` | raw pixel bytes (owning buffer) | | `getFrameId()` | `uint32_t` | monotonic frame counter | | `getTimestamp()` | `Timestamp` | capture time, device clock | | `getWidth()` / `getHeight()` / `getResolution()` | `int` / `Resolution` | frame geometry | | `getDataType()` | `MAT_TYPE` | element layout (`U8_C1/C3/C4`, `NV12`) | | `getView()` | `VIEW` | the view it was retrieved as | | `getMemoryType()` | `MEM` | destination memory (`CPU`; `GPU` unsupported) | | `getStep()` | `int` | bytes per row (first plane) | | `getSizeInBytes()` | `size_t` | total buffer size | | `isInit()` | `bool` | whether a buffer is allocated | Copies and assignment are deep. `alloc(w, h, type)` / `free()` manage a standalone buffer, and `copyTo(dst)` deep-copies pixels; `MEM::GPU` is not supported and returns `UNSUPPORTED`. ## ImuSample / SensorsData ```cpp theme={null} struct ImuSample { Timestamp timestamp; // device clock uint64_t sequence; // monotonic; gaps = wire loss float acceleration[3]; // m/s^2 float angular_velocity[3]; // rad/s float temperature_c; }; struct SensorsData { // filled by retrieve_imu() std::vector samples; // all samples since the last drain uint64_t dropped; // host ring overruns MOTION_STATE motion_state; // STATIC / MOVING / FALLING }; ``` ## Timestamp Nanoseconds since epoch with unit accessors: `nanoseconds()`, `microseconds()`, `milliseconds()`, `seconds()`. ## DeviceInformation Cached at `open()`, returned by `get_device_information()`: ```cpp theme={null} struct DeviceInformation { std::string serial; // full serial (may be non-numeric) unsigned int serial_number; // numeric form; 0 when not numeric MODEL model; std::string model_name; std::string hw_rev; unsigned int firmware_version; std::string firmware_version_str; // human-readable "XX.XX.XX" INPUT_TYPE input_type; CameraConfiguration camera_configuration; // resolution, fps, codec, calibration SensorsConfiguration sensors_configuration; // IMU params + extrinsics WirelessConfiguration wireless; // WiFi/BT state Capabilities capabilities; // enabled modes + codecs // Access + at-rest state, reported on the ungated GetDeviceInformation, so a // host can read these before authenticating. bool usb_locked; // USB gates like BLE; authenticate first bool session_unlocked; // read WITH usb_locked, not instead of it bool encryption_enabled; // new recordings will be encrypted bool encryption_key_present; // a key exists std::string encryption_key_id; // "" when absent; never the key itself ENCRYPTION_ALGORITHM encryption_algorithm; }; ``` * `CameraConfiguration::calibration` holds the double-sphere intrinsics (`fx fy cx cy xi alpha`) plus `rectify` and `fov_scale`. See [Calibration](/device/calibration). * `SensorsConfiguration::camera_imu_transform` is the 4×4 camera→IMU extrinsic. The struct also round-trips the full IMU field calibration: `accel_bias`, `gyro_bias`, `accel_scale_misalign` and `gyro_scale_misalign` (3×3 row-major, identity when uncalibrated), and `time_offset_ns`. * `Capabilities::modes` is the selectable resolution/fps menu; values outside it are rejected at `open()`. Each `SupportedMode` carries `resolution`, `fps`, and `binning` (`"none"` or `"2x2"`, how the mode derives from the full sensor). * `hw_rev` is currently baked per firmware build, so every unit on a given image returns the same value. Treat `"1.00"` as an unknown revision. * `session_unlocked` is reported *alongside* `usb_locked`, which remains true. The stored policy is still locked, but gated verbs respond until the device is re-locked or loses power. See [Access Control and Encryption](/device/security). ## WirelessConfiguration The `wireless` block of `DeviceInformation`. All fields come from the cached snapshot, so call `refresh_device_information()` before relying on them from a long-lived handle. | Field | Meaning | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `wifi_mac_address` / `bt_mac_address` | radio addresses; empty when unprovisioned | | `ble_connected` | a BLE central currently holds the link; requires firmware newer than v00.09.16, and reads `false` on earlier firmware | | `wifi_connected` | associated with an access point | | `wifi_ssid` / `wifi_ip_address` / `wifi_rssi` | the current association, RSSI in dBm | | `internet_reachable` | the device reached the wider network, beyond the access point | | `wifi_state` | `connected`, `connecting`, `disconnected`, `auth_failed`, or `unknown` | | `wifi_link_speed` | negotiated PHY rate, Mbps | | `wifi_freq_mhz` | channel frequency, which distinguishes 2.4 from 5 GHz | | `wifi_security` | `WPA2`, `WPA3`, `WPA2/WPA3`, or `Open` | | `saved_networks` | every provisioned SSID | `unknown` is set host-side when a refresh could not complete, and is distinct from an empty `wifi_state`, which means the firmware did not report one. The association detail fields are best-effort for the same reason: empty or `0` indicates a value not reported by this firmware rather than a measured zero. `bt_paired` is deprecated and never populated. The device clears the Bluetooth bond on every disconnect, so no persistent paired state exists to report. Use `ble_connected` instead, which reports whether a central currently holds the link. Because a false value cannot be distinguished from a field the firmware does not report, treat `false` as "not reported" rather than as a positive indication that no central is connected. ## Status structs ```cpp theme={null} struct HealthStatus { CAMERA_STATE camera; // live availability SENSOR_STATE imu; bool passed; // last sweep: no probe failed bool deep; // stress tier included std::vector checks; // per-probe {name, passed, detail} Timestamp timestamp; }; struct RecordingStatus { std::string name; RECORDING_TARGET target; bool recording; bool encrypted; // read off the file, not from the setting STOP_REASON stopped_reason; // why the session ended (>= v00.09.16) bool partial; // unrepaired power-loss torso, served as-is uint64_t bytes, frames, duration_ms; uint64_t storage_free_bytes, storage_total_bytes; UPLOAD_STATE upload; // + upload_bytes_sent / _total ERROR_CODE last_error; }; struct EncryptionKey { ENCRYPTION_ALGORITHM algorithm; std::vector key; // 32 bytes for AES-256-GCM std::string key_id; // first 4 bytes of SHA-256(key), hex bool present; // false from delete: `key` is the destroyed copy }; struct UpdateAvailability { bool available; // false when current, or nothing published unsigned int target_version; // version of the bundle at `url` std::string target_version_str; // display only std::string url; // empty unless available std::string notes; // optional one-line service message std::string service_error; // why no answer was usable }; struct UpdateStatus { bool active; UPDATE_STATE state; // current UPDATE_STATE phase int progress; // 0-100, -1 indeterminate std::string message; std::string running_version; // human-readable current firmware uint32_t running_version_int, target_version_int; ERROR_CODE last_error; }; ``` `EncryptionKey::key` is populated only by the calls that hand the key over, meaning `create_encryption_key`, `get_encryption_key`, and `delete_encryption_key` returning what it destroyed. Everywhere else the device reports `key_id` alone, which names a key without revealing it. `RecordingStatus::encrypted` comes from the container magic on disk rather than from the current setting, so it stays correct for recordings written before the setting last changed. ## DeviceProperties One row of `get_device_list()`: | Field | Meaning | | -------------------------- | ------------------------------------------------------------------------ | | `input_type` | `USB` or `STREAM` (BLE) | | `device_id` | index for `InitParameters::device_id` | | `serial` | USB descriptor serial | | `ble_address` / `ble_name` | BLE identity (STREAM rows); `ble_name` is the name the device advertises | ## Location `latitude`, `longitude`, `altitude` and `covariance_diag`, written into each recording's `LocationFix`.