Expand description
Rust API to the Bosch BSEC library.
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.
Getting started
Setup paths to the Bosch BSEC library
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);
}
}