Skip to content

Latest commit

 

History

History
468 lines (344 loc) · 14.8 KB

sensor.imu.md

File metadata and controls

468 lines (344 loc) · 14.8 KB

sensor.imu

API for IMU, accelerometer, gyroscope, and magnetometer device drivers

Object filename description:

sensor.type.ndof.model.spin

type is one of: imu, accel, gyroscope, magnetometer (imu indicates a chip that incorporates two or more of the others)

ndof indicates the number of axes, or Degrees-of-Freedom the sensor supports (e.g., 3dof == 3-axis)

model indicates the manufacturer's model/part number of the sensor (e.g., lsm9ds1)

Base Methods

These are methods that are common to all IMU drivers

Method Description Param Returns
startx() Start driver using explicitly defined settings Notes 1-3 cog id+1
stop() Stop the driver n/a n/a
defaults() Set sensor factory default settings n/a n/a

Notes:

  1. For SPI-connected sensors:

    • startx(CS_PIN, SCK_PIN, MOSI_PIN, MISO_PIN): status
    • Some devices contain more than one slave device internally, and so may break the above convention, because of the need for additional CS and/or MOSI/MISO pins.
    • The preprocessor symbol MODEL_SPI must be defined when building, to use.
    • For some devices, a MODEL_SPI_BC variant exists, which directs the driver to use a bytecode-based engine that while much slower, doesn't use another cog.
    • Replace MODEL with the sensor model #. Example: LSM9DS1_SPI
    • For SPI-connected sensors: 4-wire SPI is used by default. If supported by the device, 3-wire SPI can be chosen by setting MOSI_PIN and MISO_PIN to the same I/O pin. The startx() method will check for this and set the device's 3-wire SPI mode register.

  2. For I2C-connected sensors:

    • startx(SCL_PIN, SDA_PIN, I2C_FREQ, ADDR_BITS): status
    • If no particular interface preprocessor symbol is defined when building, the driver will default to the PASM-based I2C engine.
    • For some devices, a MODEL_I2C_BC variant exists, which directs the driver to use a bytecode-based engine that while much slower, doesn't use another cog.
    • Not all devices support alternate I2C addresses.

  3. For all variants: There may be a RST_PIN parameter, for specifying an optional reset pin (device-dependent). The pin is only validated in the Reset() method, and is ignored if set outside the allowable range.

  4. startx() returns the launched cog number+1 of com engine used on success.

  5. startx() returns FALSE (0) if the driver fails to start, for these possible reasons:

    • No more cogs available
    • One or more specified I/O pins are outside allowed range
    • Bus frequency is outside allowed range
    • If supported by the device, dev_id() didn't return the expected value

  6. defaults() may simply call reset(), if sensible, as opposed to calling several other driver methods, in order to reduce memory usage.

  7. Most (but not all) drivers also provide the following methods:

Method Description Param Returns
dev_id() Read model-unique identification register n/a model/dev ID
reset() Perform a hard or soft-reset of the device n/a n/a

  1. Drivers may have one or more preset_() methods, that establish a set of pre-set settings.

  2. stop() performs the following tasks:

    • Stop any extra cogs that were started (if applicable)
    • Clear all global variable space used to 0

Accelerometers

Method Description
accel_bias() Read accelerometer calibration offset values
accel_data() Read accelerometer raw data
accel_data_rate() Set accelerometer output data rate
accel_g() Read accelerometer calibrated data
accel_scale() Set accelerometer full-scale
accel_set_bias() Write accelerometer calibration offset values
accel_word2g() Convert given accel ADC word to g's
calibrate_accel() Calibrate the accelerometer
pitch() Read pitch angle of accelerometer
roll() Read roll angle of accelerometer

accel_bias(x, y, z)

Read accelerometer calibration offset values

  • Parameters:
    • x, y, z: pointers to variables to read offsets to
  • Returns: none

accel_data(ptr_x, ptr_y, ptr_z)

Read accelerometer raw data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to
  • Returns: none

accel_data_cache()

Cache an accelerometer data sample

  • Parameters: none
  • Returns: none
  • NOTE: Call this to store a measurement in RAM for use by pitch() and/or roll()

accel_data_rate(rate)

Set accelerometer output data update rate

  • Parameters:
    • rate: rate, in Hz
  • Returns: currently set rate, if rate is outside the acceptable range

accel_g(ptr_x, ptr_y, ptr_z)

Read accelerometer scaled data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to (micro-g's)
  • Returns: none

accel_scale(scale)

Set accelerometer full-scale

  • Parameters:
    • scale: full-scale in g's
  • Returns: currently set scale, if scale is outside the acceptable range

accel_set_bias(x, y, z)

Write accelerometer calibration offset values

  • Parameters:
    • x, y, z: values to offset output data by, per axis
  • Returns: none
  • NOTE: The scale may differ among drivers.
  • NOTE: Some devices supply registers for storing offsets. For others, the offsets are stored in the MCU's RAM.

accel_word2g(accel_word)

Convert given accel ADC word to g's

  • Parameters:
    • accel_word: accelerometer ADC word
  • Returns: rate of acceleration in g's (units of Earth's gravity)

calibrate_accel()

Automatically find bias offsets for all sensor axes

  • Parameters: none
  • Returns: none
  • NOTE: Approximately one second of data is gathered, in order to average the samples.

pitch()

Read pitch angle of accelerometer

  • Parameters: none
  • Returns: angle in degrees
  • NOTE: accel_data_cache() must be called prior to calling this method, in order to store a sample in RAM.

roll()

Read roll angle of accelerometer

  • Parameters: none
  • Returns: angle in degrees
  • NOTE: accel_data_cache() must be called prior to calling this method, in order to store a sample in RAM.

Gyroscopes

Method Description
calibrate_gyro() Calibrate the gyroscope
gyro_bias() Read gyroscope calibration offset values
gyro_data() Read gyroscope raw data
gyro_data_rate() Set gyroscope output data rate
gyro_dps() Read gyroscope calibrated data
gyro_scale() Set gyroscope full-scale
gyro_word2dps() Convert given gyro ADC word to degrees per second
gyro_set_bias() Write gyroscope calibration offset values

calibrate_gyro()

Automatically find bias offsets for all sensor axes

  • Parameters: none
  • Returns: none
  • NOTE: Approximately one second of data is gathered, in order to average the samples.

gyro_bias(x, y, z)

Read gyroscope calibration offset values

  • Parameters:
    • x, y, z: pointers to variables to read offsets to
  • Returns: none

gyro_data(ptr_x, ptr_y, ptr_z)

Read gyroscope raw data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to
  • Returns: none

gyro_data_rate(rate)

Set gyroscope output data rate

  • Parameters:
    • rate: rate, in Hz
  • Returns: currently set rate, if rate is outside the acceptable range

gyro_dps(ptr_x, ptr_y, ptr_z)

Read gyroscope scaled data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to (micro-degrees per second)
  • Returns: none

gyro_scale(scale)

Set gyroscope full-scale

  • Parameters:
    • scale: full-scale in degrees per second
  • Returns: currently set scale, if scale is outside the acceptable range

gyro_word2dps(gyro_word)

Convert given gyro ADC word to degrees per second

  • Parameters:
    • gyro_word: gyroscope ADC word
  • Returns: angular rate in degrees per second

gyro_set_bias(x, y, z)

Write gyroscope calibration offset values

  • Parameters:
    • x, y, z: values to offset output data by, per axis
  • Returns: none
  • NOTE: The scale may differ among drivers.
  • NOTE: Some devices supply registers for storing offsets. For others, the offsets are stored in the MCU's RAM.

Magnetometers

Method Description
calibrate_mag() Calibrate the magnetometer
mag_bias() Read magnetometer calibration offset values
mag_data() Read magnetometer raw data
mag_data_rate() Set magnetometer output data rate
mag_gauss() Read magnetometer calibrated data
mag_scale() Set magnetometer full-scale
mag_tesla() Read magnetometer calibrated data
magx_word2gauss() Convert given mag ADC word to Gauss (X-axis)
magy_word2gauss() Convert given mag ADC word to Gauss (Y-axis)
magz_word2gauss() Convert given mag ADC word to Gauss (Z-axis)
magx_word2tesla() Convert given mag ADC word to Teslas (X-axis)
magy_word2tesla() Convert given mag ADC word to Teslas (Y-axis)
magz_word2tesla() Convert given mag ADC word to Teslas (Z-axis)

calibrate_mag()

Automatically find bias offsets for all sensor axes (hard iron calibration)

  • Parameters: none
  • Returns: none
  • NOTE: Approximately one second of data is gathered, in order to average the samples.

mag_bias(x, y, z)

Read magnetometer calibration offset values

  • Parameters:
    • x, y, z: pointers to variables to read offsets to
  • Returns: none

mag_data(ptr_x, ptr_y, ptr_z)

Read magnetometer raw data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to
  • Returns: none

mag_data_rate(rate)

Set magnetometer output data rate

  • Parameters:
    • rate: rate, in Hz
  • Returns: currently set rate, if rate is outside the acceptable range

mag_gauss(ptr_x, ptr_y, ptr_z)

Read magnetometer scaled data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to (micro-gauss)
  • Returns: none

mag_scale(scale)

Set magnetometer full-scale

  • Parameters:
    • scale: full-scale in Gauss
  • Returns: currently set scale, if scale is outside the acceptable range

mag_tesla(ptr_x, ptr_y, ptr_z)

Read magnetometer scaled data

  • Parameters:
    • ptr_x, ptr_y, ptr_z: pointers to variables to read data to (teslas)
  • Returns: none

magx_word2gauss(mag_word)

Convert given mag ADC word to Gauss (X-axis)

  • Parameters:
    • mag_word: magnetometer ADC word
  • Returns: magnetic field strength in micro-Gauss

magy_word2gauss(mag_word)

Convert given mag ADC word to Gauss (Y-axis)

  • Parameters:
    • mag_word: magnetometer ADC word
  • Returns: magnetic field strength in micro-Gauss

magz_word2gauss(mag_word)

Convert given mag ADC word to Gauss (Z-axis)

  • Parameters:
    • mag_word: magnetometer ADC word
  • Returns: magnetic field strength in micro-Gauss

magx_word2tesla(mag_word)

Convert given mag ADC word to Teslas (X-axis)

  • Parameters:
    • mag_word: magnetometer ADC word
  • Returns: magnetic field strength in Teslas

magy_word2tesla(mag_word)

Convert given mag ADC word to Teslas (Y-axis)

  • Parameters:
    • mag_word: magnetometer ADC word
  • Returns: magnetic field strength in Teslas

magz_word2tesla(mag_word)

Convert given mag ADC word to Teslas (Z-axis)

  • Parameters:
    • mag_word: magnetometer ADC word
  • Returns: magnetic field strength in Teslas

Availability of other methods vary by specific sensor type and model.

Built-in symbols

CON

    { Capabilities: DoF per sensor }
    ACCEL_DOF   = x
    GYRO_DOF    = x
    MAG_DOF     = x
    BARO_DOF    = x
    DOF         = ACCEL_DOF + GYRO_DOF + MAG_DOF + BARO_DOF

    { Scales and data rates used during calibration process }
    CAL_XL_SCL  = x
    CAL_G_SCL   = x
    CAL_M_SCL   = x
    CAL_XL_DR   = x
    CAL_G_DR    = x
    CAL_M_DR    = x

    { Axis-specific }
    X_AXIS      = 0
    Y_AXIS      = 1
    Z_AXIS      = 2

Note: 'x' indicates device driver-specific values

Global variables

VAR

    { variables to store sensor scaling factors}
    long _ares, _gres, _mres[MAG_DOF]

    { variables to store bias offsets }
    long _abias[ACCEL_DOF], _gbias[GYRO_DOF], _mbias[MAG_DOF]

File Structure

sensor.type.model.spin - driver object
|-- #include: sensor.imu.common.spinh - provides standard API
|-- OBJ: HW-specific constants (core.con.model.spin)
|-- OBJ: Low-level communications engine (I2C, SPI, OneWire, etc)

Build examples

Build the LSM9DS1 demo for P1, native code output, using the I2C engine:

flexspin -L$HOME/spin-standard-library/library -DLSM9DS1_I2C LSM9DS1-Demo.spin

or flexspin -L$HOME/spin-standard-library/library LSM9DS1-Demo.spin

The same, but building to bytecode output:

flexspin --interp=rom -L$HOME/spin-standard-library/library LSM9DS1-Demo.spin

The same, but using the SPI engine:

flexspin --interp=rom -L$HOME/spin-standard-library/library -DLSM9DS1_SPI LSM9DS1-Demo.spin

The same, but using the bytecode-based SPI engine:

flexspin --interp=rom -L$HOME/spin-standard-library/library -DLSM9DS1_SPI_BC LSM9DS1-Demo.spin