Crate bsec[−][src]

Expand description

This documentation will use bsec to refer to this crate, while Bosch BSEC is used to refer to the original BSEC library provided by Bosch.

Important license information

The Bosch BSEC library is proprietary. Thus, the Bosch BSEC library and its documentation cannot be included in the bsec Rust crate and need to be obtained separately.

While the bsec documentation covers the Rust crate itself, you will likely have to refer to the Bosch BSEC documentation at some points to get a full understanding.

You are responsible for adhering to the Bosch BSEC lincese terms in your products, despite the Rust API in this crate being published under a permissive license.

To be able to use this crate, it needs to know where to find the Bosch BSEC header files and library on your system. These paths are provided as the configuration options besc_include_path and bsec_library_path to the Rust compiler.

You can do this by creating a .cargo/config file in your crate with the following content (adjust the paths accordingly):

[build]
rustflags = [
    '--cfg', 'bsec_include_path="/path/to/BSEC_1.4.8.0_Generic_Release/algo/normal_version/inc"',
    '--cfg', 'bsec_library_path="/path/to/BSEC_1.4.8.0_Generic_Release/algo/normal_version/bin/target-arch"',
]

(You might want to also have a look at the instructions for libalgobsec-sys providing the actual low-level bindings.)

Implement necessary traits

To be able to use the bsec crate, you need implementations of the Clock and BmeSensor traits

Clock

The Clock traits allows the BSEC algorithm to obtain timestamps to schedule sensor measurements accordingly. Your implementation might depend on your hardware platform or you can use the generic implementation clock::TimePassed.

BmeSensor

The BmeSensor trait allows the BSEC algorithm to communicate with your BME sensor and obtain measurements. You can implement it yourself or use a ready-made implementation shipped with bsec:

BME680 implementation is provided as bme::bme680::Bme680Sensor; requires the use-bme680 feature.

Usage

The following example demonstrates the basic bsec usage. Essentially, you need to

acquire an instance of the library (only one can be in use at any given time),
subscribe to the desired outputs,
and perform measurements in accordance with the sampling rate.

The outputs of the BSEC algorithm are also considered virtual sensors. The inputs to the BSEC algorithm are the sensor measurements and are considered physical sensors (though there are some special input that do not actually correspond to any physical sensor).

use bsec::{Bsec, Input, InputKind, OutputKind, clock::Clock, SampleRate, SubscriptionRequest};
use nb::block;
use std::time::Duration;

// Acquire handle to the BSEC library.
// Only one such handle can be acquired at any time.
let mut bsec: Bsec<_, TimePassed, _> = Bsec::init(sensor, &clock)?;

// Configure the outputs you want to subscribe to.
bsec.update_subscription(&[
    SubscriptionRequest {
        sample_rate: SampleRate::Lp,
        sensor: OutputKind::Iaq,
    },
])?;

// We need to feed BSEC regularly with new measurements.
loop {
    // Wait for when the next measurement is due.
    sleep_for(Duration::from_nanos((bsec.next_measurement() - clock.timestamp_ns()) as u64));

    // Start the measurement.
    let wait_duration = block!(bsec.start_next_measurement())?;
    sleep_for(wait_duration);

    // Process the measurement when ready and print the BSEC outputs.
    let outputs = block!(bsec.process_last_measurement())?;
    for output in &outputs {
        println!("{:?}: {}", output.sensor, output.signal);
    }
}

Features

use-bme680: Enables the bme680 module providing a BmeSensor implementation for the BME680 sensor to use it with bsec.
test-support: Provides additional classes for unit testing.

Modules

bme	Interface to BME sensors to read physical measurements.
clock	Interface to measure time.
error	Error types.

Structs

Bsec	Handle to encapsulates the Bosch BSEC library and related state.
Input	Encapsulates data read from a BME physical sensor.
Output	Single virtual sensor output of the BSEC algorithm.
RequiredInput	Describes a physical BME sensor that needs to be sampled.
SubscriptionRequest	Describes a virtual sensor output to request from the Bosch BSEC library.

Enums

Accuracy	Sensor accuracy level.
InputKind	Identifies a physical BME sensor.
OutputKind	Bosch BSEC virtual sensor output.
SampleRate	Valid sampling rates for the BSEC algorithm.

Functions

get_version

Return the Bosch BSEC version.