Struct DeviceGuard 

pub struct DeviceGuard { /* private fields */ }

A guard that automatically disconnects from the device when dropped.

This provides RAII-style management of BLE connections. When the guard is dropped, it will attempt to disconnect from the device.

Example

use aranet_core::{Device, DeviceGuard};

async fn read_with_guard() -> Result<(), Box<dyn std::error::Error>> {
    let device = Device::connect("Aranet4 12345").await?;
    let guard = DeviceGuard::new(device);

    // Use the device through the guard
    let reading = guard.read_current().await?;
    println!("CO2: {}", reading.co2);

    // Device is automatically disconnected when guard goes out of scope
    Ok(())
}

Implementations

impl DeviceGuard

pub fn new(device: Device) -> Self

Create a new device guard.

pub fn into_inner(self) -> Device

Take ownership of the device, preventing automatic disconnect.

After calling this, you are responsible for disconnecting the device.

pub fn device(&self) -> &Device

Get a reference to the device.

pub fn device_mut(&mut self) -> &mut Device

Get a mutable reference to the device.

Methods from Deref<Target = Device>

pub async fn is_connected(&self) -> bool

Check if the device is connected (queries BLE stack state).

Note: This only checks the BLE stack’s connection state, which may be stale, especially on macOS. For a more reliable check, use [validate_connection].

pub async fn validate_connection(&self) -> bool

Validate the connection by performing a lightweight read operation.

This is more reliable than is_connected() as it actively verifies the connection is working. Uses battery level read as it’s fast and always available on Aranet devices.

This method is useful for detecting “zombie connections” where the BLE stack thinks it’s connected but the device is actually out of range.

Returns

true if the connection is active and responsive, false otherwise.

pub async fn is_connection_alive(&self) -> bool

Check if the connection is alive by performing a lightweight keepalive check.

This is an alias for [validate_connection] that better describes the intent when used for connection health monitoring.

Example

// In a health monitor loop
if !device.is_connection_alive().await {
    // Connection lost, need to reconnect
}

pub fn config(&self) -> &ConnectionConfig

Get the current connection configuration.

pub async fn signal_quality(&self) -> Option<SignalQuality>

Get the current signal quality based on RSSI.

Returns None if RSSI cannot be read.

pub async fn disconnect(&self) -> Result<()>

Disconnect from the device.

This will:

1. Abort all active notification handlers
2. Disconnect from the BLE peripheral

Important: You MUST call this method before dropping the Device to ensure proper cleanup of BLE resources.

pub fn name(&self) -> Option<&str>

Get the device name.

pub fn address(&self) -> &str

Get the device address or identifier.

On Linux and Windows, this returns the Bluetooth MAC address (e.g., “AA:BB:CC:DD:EE:FF”). On macOS, this returns a UUID identifier since MAC addresses are not exposed.

pub fn device_type(&self) -> Option<DeviceType>

Get the detected device type.

pub async fn read_rssi(&self) -> Result<i16>

Read the current RSSI (signal strength) of the connection.

Returns the RSSI in dBm. More negative values indicate weaker signals. Typical values range from -30 (strong) to -90 (weak).

pub async fn read_characteristic(&self, uuid: Uuid) -> Result<Vec<u8>>

Read a characteristic value by UUID.

This method includes a timeout to prevent indefinite hangs on BLE operations. The timeout is controlled by ConnectionConfig::read_timeout.

pub async fn read_characteristic_with_timeout( &self, uuid: Uuid, read_timeout: Duration, ) -> Result<Vec<u8>>

Read a characteristic value with a custom timeout.

Use this when you need a different timeout than the default, for example when reading large data.

pub async fn write_characteristic(&self, uuid: Uuid, data: &[u8]) -> Result<()>

Write a value to a characteristic.

This method includes a timeout to prevent indefinite hangs on BLE operations. The timeout is controlled by ConnectionConfig::write_timeout.

pub async fn write_characteristic_with_timeout( &self, uuid: Uuid, data: &[u8], write_timeout: Duration, ) -> Result<()>

Write a value to a characteristic with a custom timeout.

pub async fn read_current(&self) -> Result<CurrentReading>

Read current sensor measurements.

Automatically selects the correct characteristic UUID based on device type:

• Aranet4 uses f0cd3001
• Aranet2, Radon, Radiation use f0cd3003

pub async fn read_battery(&self) -> Result<u8>

Read the battery level (0-100).

pub async fn read_device_info(&self) -> Result<DeviceInfo>

Read device information.

This method reads all device info characteristics in parallel for better performance.

pub async fn read_device_info_essential(&self) -> Result<DeviceInfo>

Read essential device information only.

This is a faster alternative to [read_device_info] that only reads the most critical characteristics: name, serial number, and firmware version. Use this for faster startup when full device info isn’t needed immediately.

pub async fn subscribe_to_notifications<F>( &self, uuid: Uuid, callback: F, ) -> Result<()>

where F: Fn(&[u8]) + Send + Sync + 'static,

Subscribe to notifications on a characteristic.

The callback will be invoked for each notification received. The notification handler task is tracked and will be aborted when disconnect() is called.

pub async fn unsubscribe_from_notifications(&self, uuid: Uuid) -> Result<()>

Unsubscribe from notifications on a characteristic.

pub async fn cached_characteristic_count(&self) -> usize

Get the number of cached characteristics.

This is useful for debugging and testing to verify service discovery worked.

pub async fn get_history_info(&self) -> Result<HistoryInfo>

Get information about the stored history.

pub async fn download_history(&self) -> Result<Vec<HistoryRecord>>

Download all historical readings from the device.

pub async fn download_history_with_options( &self, options: HistoryOptions, ) -> Result<Vec<HistoryRecord>>

Download historical readings with custom options.

Device Support

• Aranet4: Downloads CO₂, temperature, pressure, humidity
• Aranet2: Downloads temperature, humidity
• AranetRn+ (Radon): Downloads radon, temperature, pressure, humidity
• Aranet Radiation: Not supported - returns an error. The device protocol for historical radiation data requires additional documentation. Use Device::read_current() to get current radiation readings.

Adaptive Delay

If options.use_adaptive_delay is enabled, the read delay will be automatically adjusted based on the connection’s signal quality.

Checkpointing

If a checkpoint callback is set, progress will be saved periodically to allow resuming interrupted downloads.

pub async fn download_history_v1(&self) -> Result<Vec<HistoryRecord>>

Download history using V1 protocol (notification-based).

This is used for older devices that don’t support the V2 read-based protocol. V1 uses notifications on the HISTORY_V1 characteristic.

pub async fn get_interval(&self) -> Result<MeasurementInterval>

Get the current measurement interval.

pub async fn set_interval(&self, interval: MeasurementInterval) -> Result<()>

Set the measurement interval.

The device will start using the new interval after the current measurement cycle completes.

Note: This method does not verify the write succeeded. For verified writes, use [set_interval_verified].

pub async fn set_interval_verified( &self, interval: MeasurementInterval, ) -> Result<()>

Set the measurement interval with verification.

This method writes the new interval and then reads it back to verify the change was applied successfully. Use this for critical settings changes where confirmation is needed.

Errors

Returns Error::WriteFailed if the read-back value doesn’t match the requested interval.

pub async fn set_smart_home(&self, enabled: bool) -> Result<()>

Enable or disable Smart Home integration.

When enabled, the device advertises sensor data that can be read without connecting (passive scanning).

Note: This method does not verify the write succeeded. For verified writes, use [set_smart_home_verified].

pub async fn set_smart_home_verified(&self, enabled: bool) -> Result<()>

Enable or disable Smart Home integration with verification.

This method writes the setting and then reads it back to verify the change was applied successfully.

Errors

Returns Error::WriteFailed if the read-back value doesn’t match the requested setting.

pub async fn set_bluetooth_range(&self, range: BluetoothRange) -> Result<()>

Set the Bluetooth range.

Note: This method does not verify the write succeeded. For verified writes, use [set_bluetooth_range_verified].

pub async fn set_bluetooth_range_verified( &self, range: BluetoothRange, ) -> Result<()>

Set the Bluetooth range with verification.

This method writes the setting and then reads it back to verify the change was applied successfully.

Errors

Returns Error::WriteFailed if the read-back value doesn’t match the requested setting.

pub async fn get_calibration(&self) -> Result<CalibrationData>

Read calibration data from the device.

pub async fn get_settings(&self) -> Result<DeviceSettings>

Read device settings from the SENSOR_STATE characteristic.

This reads the device configuration including:

• Smart Home integration status
• Bluetooth range setting
• Temperature display unit
• Radon display unit (for Aranet Radon devices)
• Buzzer settings
• Calibration settings

Trait Implementations

impl Deref for DeviceGuard

type Target = Device

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for DeviceGuard

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Drop for DeviceGuard

fn drop(&mut self)

Executes the destructor for this type.