Data Structures
struct	OM_READER_HEADER_PACKET

struct	OM_READER_DATA_PACKET

Macros
#define	OM_MAX_SAMPLES (120)

#define	OM_MAX_HEADER_SIZE (2 * 512)

#define	OM_MAX_DATA_SIZE (512)

Typedefs
typedef void *	OmReaderHandle

Enumerations
enum	OM_READER_VALUE_TYPE { OM_VALUE_LIGHT = 7, OM_VALUE_TEMPERATURE_MC = 108, OM_VALUE_AXES = 12, OM_VALUE_SCALE_ACCEL = 13, OM_VALUE_SCALE_GYRO = 14, OM_VALUE_SCALE_MAG = 15, OM_VALUE_ACCEL_AXIS = 16, OM_VALUE_GYRO_AXIS = 17, OM_VALUE_MAG_AXIS = 18 }

Functions
OmReaderHandle	OmReaderOpen (const char *binaryFilename)

int	OmReaderDataRange (OmReaderHandle reader, int dataBlockSize, int dataOffsetBlocks, int dataNumBlocks, OM_DATETIME startTime, OM_DATETIME *endTime)

const char *	OmReaderMetadata (OmReaderHandle reader, int deviceId, unsigned int sessionId)

int	OmReaderDataBlockPosition (OmReaderHandle reader)

int	OmReaderDataBlockSeek (OmReaderHandle reader, int dataBlockNumber)

int	OmReaderNextBlock (OmReaderHandle reader)

short *	OmReaderBuffer (OmReaderHandle reader)

OM_DATETIME	OmReaderTimestamp (OmReaderHandle reader, int index, unsigned short *fractional)

int	OmReaderGetValue (OmReaderHandle reader, OM_READER_VALUE_TYPE valueType)

OM_READER_HEADER_PACKET *	OmReaderRawHeaderPacket (OmReaderHandle reader)

OM_READER_DATA_PACKET *	OmReaderRawDataPacket (OmReaderHandle reader)

void	OmReaderClose (OmReaderHandle reader)

Detailed Description

Functions to read a binary data file.

A handle to a binary data file reader is obtained with OmReaderOpen() and closed with OmReaderClose().

The file is read in blocks by repeatedly calling OmReaderNextBlock(), and the unpacked data is accessed through OmReaderBuffer(), and the precise sample timestamps are interpolated with OmReaderTimestamp().

Advanced uses are supported with direct access to the buffer through OmReaderRawHeaderPacket() and OmReaderRawDataPacket().

See also: Example code convert.c, for an example of how to use the binary file Binary data file reader functions of the API.

Macro Definition Documentation

◆ OM_MAX_DATA_SIZE

#define OM_MAX_DATA_SIZE (512)

Macro for the maximum number of bytes in a data packet.

Since: 1.3.1

Definition at line 1148 of file omapi.h.

◆ OM_MAX_HEADER_SIZE

#define OM_MAX_HEADER_SIZE (2 * 512)

Macro for the maximum number of bytes in a header packet.

Since: 1.3.1

Definition at line 1141 of file omapi.h.

◆ OM_MAX_SAMPLES

#define OM_MAX_SAMPLES (120)

Macro for the maximum number of samples in a block.

Since: 1.3.1

Definition at line 1134 of file omapi.h.

Typedef Documentation

◆ OmReaderHandle

typedef void* OmReaderHandle

Handle to a reader object.

Obtained by calling OmReaderOpen(), and disposed of with OmReaderClose().

See also: OmReaderOpen(), OmReaderClose()

Definition at line 1127 of file omapi.h.

Enumeration Type Documentation

◆ OM_READER_VALUE_TYPE

enum OM_READER_VALUE_TYPE

Reader value indexes for OmReaderGetValue() function.

See also: OmReaderGetValue

Since: 1.3

Enumerator
OM_VALUE_LIGHT	Raw light sensor reading.
OM_VALUE_TEMPERATURE_MC	Temperature sensor reading in milli-centigrade.
OM_VALUE_AXES	Number of axes per sample. Synchronous axes are [GxGyGz]AxAyAz[[MxMyMz]], 3=A, 6=GA, 9=GAM
OM_VALUE_SCALE_ACCEL	Scaling: number of units for 1g: CWA=256, AX6=2048 (+/-16g), 4096 (+/-8g), 8192 (+/-4g), 16384 (+/-2g)
OM_VALUE_SCALE_GYRO	Scaling: number of degrees per second that (2^15=)32768 represents: AX6= 2000, 1000, 500, 250, 125, 0=off.
OM_VALUE_SCALE_MAG	Scaling: number of units for 1uT: AX6=16.
OM_VALUE_ACCEL_AXIS	Axis index for Accel-X (-Y and -Z follow), AX3=0, AX6(A)=0, AX6(GA/GAM)=3, not-present=-1.
OM_VALUE_GYRO_AXIS	Axis index for Gyro-X (-Y and -Z follow), AX6(GA/GAM)=0, not-present=-1.
OM_VALUE_MAG_AXIS	Axis index for Mag-X (-Y and -Z follow), AX6(GAM)=6, not-present=-1.

Definition at line 1245 of file omapi.h.

Function Documentation

◆ OmReaderBuffer()

short* OmReaderBuffer ( OmReaderHandle reader )

Obtains a pointer to the buffer of samples read, and unpacked, by OmReaderNextBlock().

The number of samples available is specified by the return value of the previous OmReaderNextBlock() call. Each sample consists of three consecutive signed 16-bit numbers (representing the X-, Y- and Z-axes), with units of 1/256 g.

Note: The buffer contents are only guaranteed until the next call to OmReaderNextBlock() or OmReaderClose().

Parameters

reader The handle to the reader.

Returns: A pointer to the buffer of samples just read.

See also: OmReaderTimestamp()

◆ OmReaderClose()

void OmReaderClose ( OmReaderHandle reader )

Closes the specified reader handle.

Frees any resources allocated to the reader.

Parameters

reader The handle to the reader to close.

See also: OmReaderOpen()

◆ OmReaderDataBlockPosition()

int OmReaderDataBlockPosition ( OmReaderHandle reader )

Return the current block index of the reader.

Parameters

reader The handle to the reader.

Returns: If non-negative, the block position within the file, an error code otherwise.

◆ OmReaderDataBlockSeek()

int OmReaderDataBlockSeek	(	OmReaderHandle	reader,
		int	dataBlockNumber
	)

Seeks the file reader to the specified data block.

Parameters

reader	The handle to the reader.
dataBlockNumber	If positive, the data block index from the start of the file (after any header blocks); if negative, the data block index from the end of the file.

Returns: OM_OK if successful, an error code otherwise.

◆ OmReaderDataRange()

int OmReaderDataRange	(	OmReaderHandle	reader,
		int *	dataBlockSize,
		int *	dataOffsetBlocks,
		int *	dataNumBlocks,
		OM_DATETIME *	startTime,
		OM_DATETIME *	endTime
	)

Read the size, time-range, and internal chunking of the binary file.

Parameters

	reader	The handle to the reader.
[out]	dataBlockSize	A pointer to a value to receive the block size of the data (512 bytes), or NULL if not required.
[out]	dataOffsetBlocks	A pointer to a value to receive the offset of the data in blocks (same as the header size: 2 blocks), or NULL if not required.
[out]	dataNumBlocks	A pointer to a value to receive the size of the data buffer in blocks, or NULL if not required.
[out]	startTime	A pointer for the start time of the data, or NULL if not required.
[out]	endTime	A pointer for the end time of the data, or NULL if not required.

Returns: OM_OK if successful, an error code otherwise.

◆ OmReaderGetValue()

int OmReaderGetValue	(	OmReaderHandle	reader,
		OM_READER_VALUE_TYPE	valueType
	)

Returns a specific value type from the buffer read by OmReaderNextBlock().

Parameters

reader	The handle to the reader.
valueType	The value to return.

Returns: The raw value requested for the current block.

See also: OM_READER_VALUE_TYPE

Since: 1.3

◆ OmReaderMetadata()

const char* OmReaderMetadata	(	OmReaderHandle	reader,
		int *	deviceId,
		unsigned int *	sessionId
	)

Read the device id, session id and metadata of the binary file.

Parameters

	reader	The handle to the reader.
[out]	deviceId	A pointer to a value to receive the device id, or NULL if not required.
[out]	sessionId	A pointer to a value to receive the session id, or NULL if not required.

Returns: A pointer to a value to receive the pointer to the metadata, or NULL if the reader handle is not valid.

◆ OmReaderNextBlock()

int OmReaderNextBlock ( OmReaderHandle reader )

Reads the next block of data from the binary file.

Parameters

reader The handle to the reader.

Return values

>0	a positive number of samples in the buffer successfully read.
0	this block is unreadable but additional blocks remain (call OmReaderNextBlock() again).
-1,the	end-of-file has been reached.
Otherwise,an	error code.

See also: OmReaderBuffer(), OmReaderTimestamp()

◆ OmReaderOpen()

OmReaderHandle OmReaderOpen ( const char * binaryFilename )

Opens a binary data file for reading.

Parses the file header and places the stream at the first block of data.

Parameters

binaryFilename The file name of the binary file to open.

See also: OmReaderNextBlock(), OmReaderClose()

Returns: If successful, a handle to the reader object, otherwise NULL

◆ OmReaderRawDataPacket()

OM_READER_DATA_PACKET* OmReaderRawDataPacket ( OmReaderHandle reader )

Accesses the contents of a raw data packet.

This would not typically be used by an API client. The packet is loaded by calls to OmReaderNextBlock(), and remains valid until the next call of OmReaderNextBlock() or OmReaderClose() for the same reader handle.

Note: If OmReaderNextBlock() returns 0, the reader has detected a checksum failure in the buffers contents, and any data values should be treated with caution.

Parameters

reader The handle to the reader.

Returns: A pointer to the bytes in the raw data packet, or NULL if none is available.

◆ OmReaderRawHeaderPacket()

OM_READER_HEADER_PACKET* OmReaderRawHeaderPacket ( OmReaderHandle reader )

Accesses the contents of a raw header packet.

The packet will have already been loaded by the call to OmReaderOpen(), and will remain valid until OmReaderClose() is called for the same reader handle. This would not typically be used by an API client.

Parameters

reader The handle to the reader.

Returns: A pointer to the bytes in the raw header packet.

◆ OmReaderTimestamp()

OM_DATETIME OmReaderTimestamp	(	OmReaderHandle	reader,
		int	index,
		unsigned short *	fractional
	)

Determines the timestamp of the specified sample in the buffer read by OmReaderNextBlock().

Actual readings from the real-time-clock are stored once per block (with precise offset information). As the true sampling rate is subject to error (it is subject to the accelerometer device's internal sampling) this function must interpolate over these timestamps to produce the actual real-time value for each sample.

Parameters

	reader	The handle to the reader.
	index	The sample index, must be >= 0 and < the number of samples returned from OmReaderNextBlock().
[out]	fractional	A pointer to a value to hold the 1/65536th of a second fractional time offset, or NULL if not required.

Returns: The packed date/time value of the sample at the start of the buffer, or 0 if none (e.g. an invalid index).

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OM_MAX_DATA_SIZE

◆ OM_MAX_HEADER_SIZE

◆ OM_MAX_SAMPLES

Typedef Documentation

◆ OmReaderHandle

Enumeration Type Documentation

◆ OM_READER_VALUE_TYPE

Function Documentation

◆ OmReaderBuffer()

◆ OmReaderClose()

◆ OmReaderDataBlockPosition()

◆ OmReaderDataBlockSeek()

◆ OmReaderDataRange()

◆ OmReaderGetValue()

◆ OmReaderMetadata()

◆ OmReaderNextBlock()

◆ OmReaderOpen()

◆ OmReaderRawDataPacket()

◆ OmReaderRawHeaderPacket()

◆ OmReaderTimestamp()