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. This consumes the guard, so the device cannot be “already taken” — the Option is only None during Drop.

Methods from Deref<Target = Device>

pub async fn is_connected(&self) -> bool

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

Returns false if the Bluetooth stack reports an error or doesn’t answer within the connection’s validation_timeout (3 s by default, set with ConnectionConfig::validation_timeout). On macOS the stack stops answering once the sensor has dropped the connection.

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

pub async fn validate_connection(&self) -> bool

Validate the connection by reading the current measurements.

This reads the characteristic that Self::read_current uses, so the check needs no pairing that a reading doesn’t need (unpaired Aranet2 and AranetRn+ sensors answer it) and never starts a pairing that a reading wouldn’t. It fails only if the read fails or takes longer than the connection’s validation_timeout (3 s by default, set with ConnectionConfig::validation_timeout).

This is more reliable than is_connected() as it actively verifies the connection is working. It detects “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 reading the current measurements.

This is an alias for Self::validate_connection that better describes the intent when used for connection health monitoring. Like it, it needs no pairing that a reading doesn’t need, and fails only if the read fails or takes longer than the connection’s validation_timeout.

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

Returns Error::Timeout if the Bluetooth stack doesn’t confirm the disconnect within 5 s. The disconnect runs as a background task on aranet-core’s own runtime, or on the caller’s runtime if aranet-core’s can’t be started, so it completes even if this future is dropped, for example by a caller’s timeout. Returns Error::Io if there is no runtime to run it on at all, or if the task panicked or its runtime shut down before it finished.

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

Returns Error::Timeout if the Bluetooth stack doesn’t answer within the connection’s read_timeout (10 s by default, set with ConnectionConfig::read_timeout).

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
• an unknown type tries f0cd3001, then f0cd3003 if the device doesn’t have it

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 Self::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 is called on a background task with the value of each notification the characteristic sends, until unsubscribe_from_notifications or disconnect is called or the device is dropped.

Subscribing to the same characteristic again replaces its callback. If subscribing fails, the previous callback keeps running.

Opening the notification stream and enabling notifications on the device each give up with Error::Timeout after the connection’s write_timeout (set with ConnectionConfig::write_timeout).

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

Unsubscribe from notifications on a characteristic.

Stops the characteristic’s callback first, then tells the device to stop sending notifications. Once this returns, the callback is not called again, even if the device call fails.

Waiting for the callback to stop and the device call each give up after the connection’s write_timeout (set with ConnectionConfig::write_timeout); the device call then fails with Error::Timeout.

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 Self::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 Self::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 Self::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.