LpSensor Library Documentation

The LpSensor library has been discontinued. Please use OpenZEN instead.

1 Overview
2 Important Classes
- 2.1 SensorManager
- 2.2 LpmsSensor
3 Example Code (C++)
- 3.1 Connecting to the an LPMS device
- 3.2 Setting and Retrieval of Sensor Parameters
4 Common Angle Conversion Routines
- 4.1 Conversion Quaternion to Matrix
- 4.2 Conversion Quaternion to Euler Angles (ZYX rotation sequence)

Overview

The LpSensor library contains classes that allow a user to integrate LPMS devices into their own applications. Library binaries for Windows Visual Studio are released together with our (deprecated) OpenMAT software package. Please download OpenMAT directly from the LP-Research website.

Compiling applications that use the LpSensor library requires the following components:

Header files (usually in C:/OpenMAT/include)

LpmsSensorManagerI.h - Contains the interface for the LpmsSensorManager class.

LpmsSensorI.h - Contains the interface for the LpmsSensor class

ImuData.h - Structure for containing output data from a LPMS device

LpmsDefinitions.h Macro definitions for accessing LPMS

DeviceListItem.h - Contains the class definition for an element of a LPMS device list

LIB files (usually in C:/OpenMAT/lib/x86)

LpSensorD.lib - LpSensor library (Debug version)

LpSensor.lib - LpSensor library (Release version)

DLL files (usually in C:/OpenMAT/lib/x86)

LpSensorD.dll - LpSensor library (Debug version)

LpSensor.dll - LpSensor library (Release version)

PCANBasic.dll - PeakCAN library DLL for CAN interface communication (optional).

ftd2xx.dll - The FTDI library to communicate with an LPMS over USB.

To compile the application please do the following:

Include LpmsSensorManagerI.h.
Add LpSensor.lib (or LpSensorD.lib if you are compiling in debug mode) to the link libraries file list of your application
Make sure that you set a path to LpSensor.dll / LpSensorD.dll, PCANBasic.dll (optional) and ftd2xx.dll so that the runtime file of your application can access them.
Build your application.

Important Classes

SensorManager

The sensor manager class wraps a number of LpmsSensor instances into one class, handles device discovery and device polling. For user applications the following methods are most commonly used. Please refer to the interface file SensorManagerI.h for more information.

NOTE: An instance of LpmsSensor is returned by the static function LpmsSensorManagerFactory(). See the example listing in the next section for more information how to initialize a LpmsSensorManager object.

NOTE: LpSensor automatically applies calibration parameters to raw sensor data and therefore records and outputs calibrated sensor data.

Method name	SensorManager(void)
Parameters	none
Returns	SensorManager object
Description	Constructor of a SensorManager object.

Method name	*LpSensor addSensor(int mode, string deviceId)**
Parameters	[ TO-DO ]
Returns	Pointer to LpSensor object.
Description	Adds a sensor device to the list of devices adminstered by the SensorManager object.

Method name	*void removeSensor(LpSensor sensor)**
Parameters	[ TO-DO ]
Returns	none
Description	Removes a device from the list of currently administered sensors.

Method name	*void listDevices(std::vector<DeviceListItem> v)**
Parameters	[ TO-DO ]
Returns	None
Description	Lists all connected LPMS devices. The device discovery runs in a seperate thread.For Bluetooth devices should take several seconds to be added to the devicelist. CAN bus and USB devices should be added after around 1s.

LpmsSensor

This is a class to access the specific functions and parameters of an LPMS. The most commonly used methods are listed below. Please refer to the interface file LpmSensorI.h for more information.

NOTE: The following units are used by LpmsSensor for measured and processed sensor data:

Data type	Units
Angular velocity (gyroscope)	rad/s
Acceleration (accelerometer)	g
Magnetic field strength (magnetometer)	uT
Euler angle	radians
Linear acceleration	g
Quaternion	normalized units
Barometric pressure	mPa
Altitude	M
Temperature	°C

Method name	void run(void)
Parameters	None
Returns	None
Description	Starts the data acquisition procedure.

Method name	void pause(void)
Parameters	None
Returns	None
Description	Pauses the data acquisition procedure.

Method name	int getSensorStatus(void)
Parameters	None
Returns	Sensor state identifier:
Description	Retrieves the current sensor status.

Method name	int getConnectionStatus(void)
Parameters	None
Returns	Connection status identifier:
Description	Retrieves the current connection status.

Method name	void startResetReference(void)
Parameters	None
Returns	None
Description	Resets the current accelerometer and magnetometer reference. Please see the ‘Operation’ chapter for details on the reference vector adjustment procedure.

Method name	void startCalibrateGyro(void)
Parameters	None
Returns	None
Description	Starts the calibration of the sensor gyroscope.

Method name	void startMagCalibration(void)
Parameters	None
Returns	None
Description	Starts the calibration of the LPMS magnetometer.

Method name	*CalibrationData getConfigurationData(void)**
Parameters	None
Returns	Pointer to CalibrationData object.
Description	Retrieves the CalibrationData structure containing theconfigurationparameters ofthe connected LPMS.

Method name	bool setConfigurationPrm(int parameterIndex, int parameter)
Parameters	Supported parameterIndex identifiers: Supported parameter identifiers for each parameter index: PRM_OPENMAT_ID Integer ID number between 1 and 255. PRM_FILTER_MODE PRM_PARAMETER_SET PRM_GYR_THRESHOLD_ENABLE PRM_GYR_RANGE PRM_ACC_RANGE PRM_MAG_RANGE
Returns	None
Description	Sets a configuration parameter.

Method name	*bool getConfigurationPrm(int parameterIndex, int parameter)**
Parameters	See setConfigurationPrm method for an explanation of supported paramer indices and parameters.
Returns	None
Description	Retrieves a configuration parameter.

Method name	void resetOrientation(void)
Parameters	None
Returns	None
Description	Resets the orientation offset of the sensor.

Method name	void saveCalibrationData(void)
Parameters	None
Returns	None
Description	Starts saving the current parameter settings to the sensor flash memory.

Method name	virtual void getCalibratedSensorData(float g[3], float a[3], float b[3])
Parameters	[ TO-DO ]
Returns	None
Description	Retrieves calibrated sensor data (gyroscope, accelerometer, magnetometer).

Method name	virtual void getQuaternion(float q[4])
Parameters	[ TO-DO ]
Returns	None
Description	Retrieves the 3d orientation quaternion.

Method name	virtual void getEulerAngle(float r[3])
Parameters	[ TO-DO ]
Returns	None
Description	Retrieves the currently measured 3d Euler angles.

Method name	virtual void getRotationMatrix(float M[3][3])
Parameters	[ TO-DO ]
Returns	None
Description	Retrievs the current rotation matrix.

Example Code (C++)

Connecting to the an LPMS device

#include "stdio.h"
#include "LpmsSensorI.h"
#include "LpmsSensorManagerI.h"

int main(int argc, char *argv[])
{
  ImuData d;
  
  // Gets a LpmsSensorManager instance
  LpmsSensorManagerI* manager = LpmsSensorManagerFactory();
  
  // Connects to LPMS-B sensor with address 00:11:22:33:44:55 
  LpmsSensorI* lpms = manager->addSensor(DEVICE_LPMS_B, "00:11:22:33:44:55");
  
  while(1) {
    // Checks, if connected
    if (lpms->getConnectionStatus() == SENSOR_CONNECTION_CONNECTED) {
    
    // Reads quaternion data
    d = lpms->getCurrentData();
    
    // Shows data
    printf("Timestamp=%f, qW=%f, qX=%f, qY=%f, qZ=%f\n", d.timeStamp, d.q[0], d.q[1], d.q[2], d.q[3]);
    }
  }

  // Removes the initialized sensor
  manager->removeSensor(lpms);
  
  // Deletes LpmsSensorManager object 
  delete manager;
  
  return 0;
  }

Setting and Retrieval of Sensor Parameters

/* Setting a sensor parameter. */
lpmsDevice->setParameter(PRM_ACC_RANGE, LPMS_ACC_RANGE_8G);

/* Retrieving a sensor parameter. */
lpmsDevice->setParameter(PRM_ACC_RANGE, &p);

Sensor and Connection Status Inquiry
/* Retrieves current sensor status */

int status = getSensorStatus();

switch (status) {
  case SENSOR_STATUS_RUNNING:
  std::cout << "Sensor is running." << std::endl;
  break;
  
  case SENSOR_STATUS_PAUSED:
  std::cout << "Sensor is paused." << std::endl;
  break;
}

status = lpmsDevice->getConnectionStatus();

switch (status) {
  case SENSOR_CONNECTION_CONNECTING:
  std::cout << "Sensor is currently connecting." << std::endl;
  break;
  
  case SENSOR_CONNECTION_CONNECTED:
  std::cout << "Sensor is connected." << std::endl;
  break;
}

Common Angle Conversion Routines

Conversion Quaternion to Matrix

typedef struct _LpVector3f {
  float data[3];
} LpVector3f;

typedef struct _LpVector4f {
  float data[4];
} LpVector4f;

typedef struct _LpMatrix3x3f {
  float data[3][3];
} LpMatrix3x3f;

void quaternionToMatrix(LpVector4f *q, LpMatrix3x3f* M)
{
  float tmp1;
  float tmp2;
  
  float sqw = q->data[0] * q->data[0];
  float sqx = q->data[1] * q->data[1];
  float sqy = q->data[2] * q->data[2];
  float sqz = q->data[3] * q->data[3];
  
  float invs = 1 / (sqx + sqy + sqz + sqw);
  
  M->data[0][0] = ( sqx - sqy - sqz + sqw) * invs;
  M->data[1][1] = (-sqx + sqy - sqz + sqw) * invs;
  M->data[2][2] = (-sqx - sqy + sqz + sqw) * invs;
  
  tmp1 = q->data[1] * q->data[2];
  tmp2 = q->data[3] * q->data[0];
  
  M->data[1][0] = 2.0f * (tmp1 + tmp2) * invs;
  M->data[0][1] = 2.0f * (tmp1 - tmp2) * invs;
  
  tmp1 = q->data[1] * q->data[3];
  tmp2 = q->data[2] * q->data[0];
  
  M->data[2][0] = 2.0f * (tmp1 - tmp2) * invs;
  M->data[0][2] = 2.0f * (tmp1 + tmp2) * invs;
  
  tmp1 = q->data[2] * q->data[3];
  tmp2 = q->data[1] * q->data[0];
  
  M->data[2][1] = 2.0f * (tmp1 + tmp2) * invs;
  M->data[1][2] = 2.0f * (tmp1 - tmp2) * invs;
}