Crate calibsession 

The live tag calibration, and the compass angles every CompassTag display shows, through the C++ core.

Session is a safe wrapper over the C interface in host/libraries/tagcore-c/calibsession_c.h, which wraps sensoranalysis’s Qt-free calibcore::CalibrationSession – the same code qtcalibrate’s CompassData now runs. So a Rust program calibrates exactly as qtcalibrate does: Freescale’s solver, eviction by leverage and outliers, the accelerometer’s own fit, the quality figures and the filtered live compass. display_angles and model_rotation are the conversions qtcalibrate’s displays apply to an orientation.

use calibsession::Session;
let mut session = Session::new()?;
for (i, (mag, accel)) in samples.iter().enumerate() {
    if session.add_sample(*mag, *accel) {
        // the solver accepted a new fit
    }
    if i % 2 == 1 {
        session.update_quality(); // the caller's tick
    }
}
let quality = session.quality();

Units are the calibration stream’s: magnetometer in µT, accelerometer in mg. Quaternions are [w, x, y, z].

Linking

As for taglogwriter: tagcore-c-sys links libtagcore_c, found through TAGCORE_C_LIB_DIR, statically on macOS and shared on Linux and Windows. It is the one crate that declares links = "tagcore_c", so a program may use this crate beside the other wrappers over the library.

Safety model

All unsafe is in this file. A Session owns exactly one C handle, never null, freed exactly once in Drop. Every pointer passed in points at Rust memory that lives until the call returns, sized as the header requires; the library keeps no pointer after a call. Output structs are #[repr(C)] mirrors of the header’s, zero-initialized before the call fills them. A session may move between threads but not be shared: Session is Send and not Sync, and every call that advances it takes &mut self.

Maintaining

The declarations, imported here as ffi, are tagcore_c_sys::tcs (host/libraries/tagcore-c-sys/src/tcs.rs), written by hand from calibsession_c.h. When the header changes, change the declaration and the safe method over it; if a signature, meaning or struct layout changed, the header raises TCS_ABI_VERSION, and ffi::TCS_ABI_VERSION must follow. Session::new refuses a library built from another version.

Structs

AccelFit

The accelerometer offset in force: the live fit, or one loaded from a tag.

Angles

Display angles of an orientation, before declination and battery direction.

Constants

The magnetometer calibration constants.

Evictions

Evictions from the full magnetometer buffer since the last clear.

Orientation

One solved compass orientation.

Quality

MagQuality’s figures; see magquality_core.h for what each means.

Session

One live calibration: the sample buffer, the solver, retention, the accelerometer fit, the quality figures and the filtered compass.

Enums

SessionError

Why a session could not be made.

Constants

SLOTS

Buffer slots in a session: Session::points never returns more.

Functions

display_angles

Display angles of an orientation quaternion [w, x, y, z]: the heading, pitch and roll every CompassTag display shows, before declination and battery direction.

model_rotation

The rotation qtcalibrate applies to its tag model, Rz(yaw) * Ry(roll) * Rx(pitch), degrees, yaw counter-clockwise; [w, x, y, z].