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

# Device Management

> Set up capture defaults, storage, time, location, BLE access, and reboot

Device management uses the USB or BLE control plane. Open the device before
calling these methods; no live video data plane is required.

## Persistent capture configuration

The M1 boots with a stored resolution, frame rate, and codec.
`set_configuration()` updates these defaults while the device is `IDLE`:

```cpp theme={null}
dev.set_configuration(1920, 1200, 30, COMPRESSION_MODE::H265);
```

Valid values come from the device's enabled capability menu:

```cpp theme={null}
Capabilities caps = dev.get_device_information().capabilities;
for (const SupportedMode& m : caps.modes)
    std::printf("%dx%d @ %d\n", m.resolution.width, m.resolution.height, m.fps);
```

A session can override the stored configuration through `InitParameters`.

## Storage

Query device storage before a long device-local recording:

```cpp theme={null}
uint64_t free_bytes = 0;
uint64_t total_bytes = 0;
ERROR_CODE ec = dev.get_storage(free_bytes, total_bytes);
```

Check free space before starting a long device-local recording. Storage
exhaustion causes recording setup to return `STORAGE_FULL`.

## Time

`open()` aligns the device clock to the host automatically. Re-align a
long-running session or read the device clock directly:

```cpp theme={null}
dev.sync_time();
Timestamp t;
dev.get_device_time(t);   // device CLOCK_REALTIME, ns since epoch
```

`sync_time()` writes host wall time to the device. `get_device_time()` performs
a control round-trip and returns the device's current epoch timestamp. Use
`Mat::getTimestamp()` and `ImuSample::timestamp` for capture timestamps.

## Location

The device stamps recordings with a `LocationFix`. Persist a location (until
changed) or read the effective one:

```cpp theme={null}
dev.set_location(37.7749, -122.4194);   // lat, lon [, altitude, covariance]
Location loc;
dev.get_location(loc);
```

The persistent location applies to later recordings. For one session, set
`RecordingParameters::has_location` and `location`.

## Control password

One password covers both transports (factory default `123456`). BLE control is
always gated by it; USB is gated once the device is locked. Rekey it:

```cpp theme={null}
dev.set_ble_password("123456", "new-password");   // over BLE, or over locked USB
dev.set_ble_password("",       "new-password");   // over UNLOCKED USB only
```

The form that omits the old password allows physical access to reset a forgotten
credential, and it is available only while USB is unlocked. Once the device is
locked, that form is unavailable and `factory_reset()` is the remaining route.

The method retains the name `set_ble_password` for source compatibility, but it
has applied to both transports since the USB lock was introduced. Locking,
at-rest encryption, key handling and recovery are covered in [Access Control and
Encryption](/device/security).

## State and reboot

```cpp theme={null}
DEVICE_STATE s = dev.get_state();   // CLOSED / IDLE / STREAMING / UPDATING
ERROR_CODE ec = dev.reboot();
```

`get_state()` never blocks; it returns the last known state. Calls that are
invalid for the current state return `INVALID_FUNCTION_CALL` without contacting
the device.

Stop capture, recording, upload, health, or update work before rebooting. The
SDK closes the handle when the reboot command is accepted, or when the link
disappears because the reboot began before the reply arrived. Reconnect with
`open()` after the device returns.

## CLI setup commands

```sh theme={null}
ef-cli config
ef-cli config set 1920 1200 30 h265
ef-cli storage
ef-cli sync-time
ef-cli time
ef-cli location
ef-cli location set 37.7749 -122.4194
ef-cli set-password <new>          # over unlocked USB
ef-cli --ble <MAC> set-password <old> <new>
ef-cli lock on|off                 # gate the USB control plane
ef-cli reboot
```