Macros
#define	OM_METADATA_SIZE 448

#define	OmClearDataAndCommit(_deviceId) OmEraseDataAndCommit((_deviceId), OM_ERASE_QUICKFORMAT)

#define	OmCommit(_deviceId) OmEraseDataAndCommit((_deviceId), OM_ERASE_NONE)

#define	OM_ACCEL_DEFAULT_RATE 100

#define	OM_ACCEL_DEFAULT_RANGE 8

Enumerations
enum	OM_ERASE_LEVEL { OM_ERASE_NONE = 0, OM_ERASE_DELETE = 1, OM_ERASE_QUICKFORMAT = 2, OM_ERASE_WIPE = 3 }

Functions
int	OmGetDelays (int deviceId, OM_DATETIME startTime, OM_DATETIME stopTime)

int	OmSetDelays (int deviceId, OM_DATETIME startTime, OM_DATETIME stopTime)

int	OmGetSessionId (int deviceId, unsigned int *sessionId)

int	OmSetSessionId (int deviceId, unsigned int sessionId)

int	OmGetMetadata (int deviceId, char *metadata)

int	OmSetMetadata (int deviceId, const char *metadata, int size)

int	OmGetLastConfigTime (int deviceId, OM_DATETIME *time)

int	OmEraseDataAndCommit (int deviceId, OM_ERASE_LEVEL eraseLevel)

int	OmGetAccelConfig (int deviceId, int rate, int range)

int	OmSetAccelConfig (int deviceId, int rate, int range)

int	OmGetMaxSamples (int deviceId, int *value)

int	OmSetMaxSamples (int deviceId, int value)

Detailed Description

Functions to support reading and writing device settings and other meta-data, including clearing the device data storage.

The recording time can be set to a precise time window, see: OmGetDelays() and OmSetDelays().

The devices can be assigned a unique 'session identifier' to be used for a data set, see: OmGetSessionId() and OmSetSessionId().

User-defined data can be stored in a 'scratch buffer', see: OmGetMetadata() and OmSetMetadata().

Calls to OmSetDelays(), OmSetSessionId() and OmSetMetadata() are written to not alter existing session data on the device; instead they modify a (volatile at disconnect) stored state on the device and only take full effect only when the data is committed with OmEraseDataAndCommit(). Note that queries consult the volatile storage, so the non-permanent values will be read if they've not yet been committed.

See also: Example code clear.c and deploy.c, for examples of how to use the device Device settings and meta-data and metadata functions of the API.

Macro Definition Documentation

◆ OM_ACCEL_DEFAULT_RANGE

#define OM_ACCEL_DEFAULT_RANGE 8

Default accelerometer range configuration is +/- 8 G.

See also: OmSetAccelConfig()

Since: 1.3

Definition at line 761 of file omapi.h.

◆ OM_ACCEL_DEFAULT_RATE

#define OM_ACCEL_DEFAULT_RATE 100

Default accelerometer rate configuration is 100Hz.

See also: OmSetAccelConfig()

Since: 1.3

Definition at line 753 of file omapi.h.

◆ OM_METADATA_SIZE

#define OM_METADATA_SIZE 448

The number of bytes of metadata scratch area on the device.

Definition at line 653 of file omapi.h.

◆ OmClearDataAndCommit

#define OmClearDataAndCommit ( _deviceId ) OmEraseDataAndCommit((_deviceId), OM_ERASE_QUICKFORMAT)

Macro to quick-format a device and commit the metadata and settings.

This provides backwards compatibility for older versions of OMAPI.

Note: To modify the file system, the device prevents the computer from accessing the data store (by temporarily disconnecting it). Therefore, the operation will report failure if a download is in progress - the download must complete or first be cancelled with OmCancelDownload();

Parameters

_deviceId Identifier of the device.

Returns: OM_OK if successful, an error code otherwise.

See also: OmEraseDataAndCommit()

Definition at line 732 of file omapi.h.

◆ OmCommit

#define OmCommit ( _deviceId ) OmEraseDataAndCommit((_deviceId), OM_ERASE_NONE)

Macro to commit the metadata and settings without clearing.

This provides backwards compatibility for older versions of OMAPI. This is not recommended as it changes the metadata of an existing recording.

Note: To modify the file system, the device prevents the computer from accessing the data store (by temporarily disconnecting it). Therefore, the operation will report failure if a download is in progress - the download must complete or first be cancelled with OmCancelDownload();

Parameters

_deviceId Identifier of the device.

Returns: OM_OK if successful, an error code otherwise.

See also: OmEraseDataAndCommit()

Definition at line 745 of file omapi.h.

Enumeration Type Documentation

◆ OM_ERASE_LEVEL

enum OM_ERASE_LEVEL

Erase levels for OmEraseDataAndCommit() function.

See also: OmEraseDataAndCommit

Since: 1.2

Enumerator
OM_ERASE_NONE	Data file not erased but metadata just updated (this is not recommended as it could lead to a data/metadata mismatch).
OM_ERASE_DELETE	Data file is removed and a new one created with the current metadata.
OM_ERASE_QUICKFORMAT	Device file-system is re-created and a new data file is created with the current metadata.
OM_ERASE_WIPE	All blocks on the NAND flash memory are cleared, the file-system is cleanly re-created, and a new data file is created with the current metadata.

Definition at line 693 of file omapi.h.

Function Documentation

◆ OmEraseDataAndCommit()

int OmEraseDataAndCommit	(	int	deviceId,
		OM_ERASE_LEVEL	eraseLevel
	)

Erases the specified device storage and commits the metadata and settings.

To fully wipe a device, the caller can execute:

OmSetSessionId(deviceId, 0); 
OmSetMetadata(deviceId, NULL, 0); 
OmSetDelays(deviceId, OM_DATETIME_INFINITE, OM_DATETIME_INFINITE); 
OmSetAccelConfig(deviceId, OM_ACCEL_DEFAULT_RATE, OM_ACCEL_DEFAULT_RANGE);
OmEraseDataAndCommit(deviceId, OM_ERASE_WIPE); 

And similarly, to cleanly re-configure a device, the same sequence can be called with non-zero values.

Note: To modify the file system, the device prevents the computer from accessing the data store (by temporarily disconnecting it). Therefore, the operation will report failure if a download is in progress - the download must complete or first be cancelled with OmCancelDownload().

Parameters

deviceId	Identifier of the device.
eraseLevel	The erase level to use, one of: OM_ERASE_NONE, OM_ERASE_DELETE, OM_ERASE_QUICKFORMAT, OM_ERASE_WIPE

Returns: OM_OK if successful, an error code otherwise.

Since: 1.2

◆ OmGetAccelConfig()

int OmGetAccelConfig	(	int	deviceId,
		int *	rate,
		int *	range
	)

Queries the specified device's accelerometer configuration.

Parameters

	deviceId	Identifier of the device.
[out]	rate	Pointer to a value to receive the sampling rate in Hz (6 [=6.25], 12 [=12.5], 25, 50, 100, 200, 400, 800, 1600, 3200). Overloaded since 1.8 with negative ranges being "low power" mode.
[out]	range	Pointer to a value to receive the sampling range in +/- G (2, 4, 8, 16). Overloaded since 1.8 with the bits 16-32 being the synchronous gyro range in degrees/sec (125, 250, 500, 1000, 2000) with compatable devices.

Returns: OM_OK if successful, an error code otherwise.

See also: OmSetAccelConfig()

Since: 1.3, 1.8 for overloaded low-power and synchronous gyro range.

◆ OmGetDelays()

int OmGetDelays	(	int	deviceId,
		OM_DATETIME *	startTime,
		OM_DATETIME *	stopTime
	)

Gets the specified device's delayed activation start and stop times.

Parameters

	deviceId	Identifier of the device.
[out]	startTime	Pointer to a value to receive the start date/time.
[out]	stopTime	Pointer to a value to receive the stop date/time.

Returns: OM_OK if successful, an error code otherwise.

◆ OmGetLastConfigTime()

int OmGetLastConfigTime	(	int	deviceId,
		OM_DATETIME *	time
	)

Returns the date and time that the specified device was last configured.

Parameters

	deviceId	Identifier of the device.
[out]	time	Pointer to a value to receive the last configuration date and time.

Returns: OM_OK if successful, an error code otherwise.

◆ OmGetMaxSamples()

int OmGetMaxSamples	(	int	deviceId,
		int *	value
	)

Queries the specified device's 'maximum sample' value.

This should always be set to 0.

Parameters

	deviceId	Identifier of the device.
[out]	value	Pointer to a value to receive the max sample value.

Returns: OM_OK if successful, an error code otherwise.

See also: OmSetMaxSamples()

Since: 1.5

◆ OmGetMetadata()

int OmGetMetadata	(	int	deviceId,
		char *	metadata
	)

Gets the contents of the specified device's metadata scratch buffer.

Remarks: A suggested decoding of name/value pairs that preserves characters outside the non-control-ASCII range is URL-decoding to UTF-8 strings.

Parameters

	deviceId	Identifier of the device.
[out]	metadata	A pointer to a buffer to receive the metadata, must be at least (OM_METADATA_SIZE + 1) as the value will be null-terminated.

Returns: OM_OK if successful, an error code otherwise.

◆ OmGetSessionId()

int OmGetSessionId	(	int	deviceId,
		unsigned int *	sessionId
	)

Queries the specified device's session identifier.

Parameters

	deviceId	Identifier of the device.
[out]	sessionId	Pointer to a value to receive the session ID.

Returns: OM_OK if successful, an error code otherwise.

◆ OmSetAccelConfig()

int OmSetAccelConfig	(	int	deviceId,
		int	rate,
		int	range
	)

Sets the specified device's accelerometer configuration to be used at the next recording session.

Note: This API call does not alter the existing settings, and only takes full effect when OmEraseDataAndCommit() is called.

Parameters

deviceId	Identifier of the device.
rate	Sampling rate value in Hz (6 [=6.25], 12 [=12.5], 25, 50, 100, 200, 400, 800, 1600, 3200). Overloaded since 1.8 with negative ranges being "low power" mode.
range	Sampling range value in +/- G (2, 4, 8, 16). Overloaded since 1.8 with the bits 16-32 being the synchronous gyro range in degrees/sec (125, 250, 500, 1000, 2000) with compatable devices.

Returns: OM_OK if successful, an error code otherwise.

See also: OmGetAccelConfig()

Since: 1.3, 1.8 for overloaded low-power and synchronous gyro range.

◆ OmSetDelays()

int OmSetDelays	(	int	deviceId,
		OM_DATETIME	startTime,
		OM_DATETIME	stopTime
	)

Sets the specified device's delayed activation start and stop times to use for a new recording session.

To set the device to always record:

OmSetDelays(deviceId, OM_DATETIME_ZERO, OM_DATETIME_INFINITE);

To set the device to never record:

OmSetDelays(deviceId, OM_DATETIME_INFINITE, OM_DATETIME_INFINITE);

Note: This API call does not alter existing session data on the device, and only takes full effect when OmEraseDataAndCommit() is called.

Remarks: When not connected, a device would stop recording, even within the recording time window, if either storage or battery were to be exhausted. When not recording, devices keep themselves in a low power mode to conserve battery.

Parameters

deviceId	Identifier of the device.
startTime	The start date and time.
stopTime	The stop date and time.

Returns: OM_OK if successful, an error code otherwise.

See also: OmEraseDataAndCommit()

◆ OmSetMaxSamples()

int OmSetMaxSamples	(	int	deviceId,
		int	value
	)

Sets the specified device's 'maximum sample' value.

This should always be set to 0.

Note: This API call does not alter the existing settings, and only takes full effect when OmEraseDataAndCommit() is called.

Parameters

deviceId	Identifier of the device.
value	Value setting (should be 0)

Returns: OM_OK if successful, an error code otherwise.

See also: OmGetMaxSamples()

Since: 1.5

◆ OmSetMetadata()

int OmSetMetadata	(	int	deviceId,
		const char *	metadata,
		int	size
	)

Sets the specified device's metadata scratch buffer to be used for the next recording session.

Note: This API call does not alter existing session data on the device, and only takes full effect when OmEraseDataAndCommit() is called – after which, all existing metadata on the device will be replaced.

Remarks: A suggested encoding of name/value pairs that preserves characters outside the non-control-ASCII range is URL-encoding from UTF-8 strings.

Parameters

	deviceId	Identifier of the device.
[out]	metadata	A pointer to the metadata to store, or NULL if clearing the metadata.
	size	The size of the specified metaData. Can be 0 to clear the metadata. If larger than OM_METADATA_SIZE, additional bytes will be ignored.

See also: OmEraseDataAndCommit()

Returns: OM_OK if successful, an error code otherwise.

◆ OmSetSessionId()

int OmSetSessionId	(	int	deviceId,
		unsigned int	sessionId
	)

Sets the specified device's session identifier to be used at the next recording session.

Note: This API call does not alter existing session data on the device, and only takes full effect when OmEraseDataAndCommit() is called.

Parameters

deviceId	Identifier of the device.
sessionId	A value to set as the session ID.

Returns: OM_OK if successful, an error code otherwise.

See also: OmEraseDataAndCommit()

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OM_ACCEL_DEFAULT_RANGE

◆ OM_ACCEL_DEFAULT_RATE

◆ OM_METADATA_SIZE

◆ OmClearDataAndCommit

◆ OmCommit

Enumeration Type Documentation

◆ OM_ERASE_LEVEL

Function Documentation

◆ OmEraseDataAndCommit()

◆ OmGetAccelConfig()

◆ OmGetDelays()

◆ OmGetLastConfigTime()

◆ OmGetMaxSamples()

◆ OmGetMetadata()

◆ OmGetSessionId()

◆ OmSetAccelConfig()

◆ OmSetDelays()

◆ OmSetMaxSamples()

◆ OmSetMetadata()

◆ OmSetSessionId()