Macros
#define	OM_MEMORY_HEALTH_ERROR 1

#define	OM_MEMORY_HEALTH_WARNING 8

Enumerations
enum	OM_LED_STATE { OM_LED_AUTO = -1, OM_LED_OFF = 0, OM_LED_BLUE = 1, OM_LED_GREEN = 2, OM_LED_CYAN = 3, OM_LED_RED = 4, OM_LED_MAGENTA = 5, OM_LED_YELLOW = 6, OM_LED_WHITE = 7 }

Functions
int	OmGetVersion (int deviceId, int firmwareVersion, int hardwareVersion)

int	OmGetDeviceSerial (int deviceId, char *serialBuffer)

int	OmGetDevicePort (int deviceId, char *portBuffer)

int	OmGetDevicePath (int deviceId, char *pathBuffer)

int	OmGetBatteryLevel (int deviceId)

int	OmSelfTest (int deviceId)

int	OmGetMemoryHealth (int deviceId)

int	OmGetBatteryHealth (int deviceId)

int	OmGetAccelerometer (int deviceId, int x, int y, int *z)

int	OmGetTime (int deviceId, OM_DATETIME *time)

int	OmSetTime (int deviceId, OM_DATETIME time)

int	OmSetLed (int deviceId, OM_LED_STATE ledState)

int	OmIsLocked (int deviceId, int *hasLockCode)

int	OmSetLock (int deviceId, unsigned short code)

int	OmUnlock (int deviceId, unsigned short code)

int	OmSetEcc (int deviceId, int state)

int	OmGetEcc (int deviceId)

int	OmCommand (int deviceId, const char command, char buffer, size_t bufferSize, const char expected, unsigned int timeoutMs, char *parseParts, int parseMax)

Detailed Description

Functions to support querying the device version, battery level, health and time, and setting of the time and LED indicator.

The version of the firmware and hardware on the device, an internal self-test status, and Flash memory health can be queried with OmGetVersion(), OmSelfTest(), OmGetMemoryHealth().

The devices incorporate a rechargeable battery, the charge level and battery health can be determined with OmGetBatteryLevel() and OmGetBatteryHealth().

The on-board real time clock can be accessed with the functions: OmGetTime(), OmSetTime().

The on-board triaxial accelerometer can be accessed to give an instantaneous reading with: OmGetAccelerometer().

The device's 7-colour external LED indicator can be directly controlled with OmSetLed().

The anti-tamper lock can be queried and controlled with OmIsLocked(), OmSetLock(), OmUnlock().

Error-correcting code status can be set and queried with OmSetEcc() and OmGetEcc().

Advanced commands can be sent with OmCommand().

See also: Example code test.c, for an example of how to use the device status functions of the API.

Macro Definition Documentation

◆ OM_MEMORY_HEALTH_ERROR

#define OM_MEMORY_HEALTH_ERROR 1

Threshold at or below which the OmGetMemoryHealth() result should be treated as a failure.

Since: 1.2

Definition at line 431 of file omapi.h.

◆ OM_MEMORY_HEALTH_WARNING

#define OM_MEMORY_HEALTH_WARNING 8

Threshold at or below which the OmGetMemoryHealth() result should be treated as a warning.

Since: 1.2

Definition at line 432 of file omapi.h.

Enumeration Type Documentation

◆ OM_LED_STATE

enum OM_LED_STATE

Enumeration of LED colours.

Note: In the OM_LED_AUTO setting, when connected, the device fades from off to yellow when charging; and from off to white when charged. The device will fade to and from red instead of off when the computer has recently written data to the mass storage drive (but this should not typically be observed through API access).

Remarks: Values are from the bit pattern: 0b00000RGB.

See also: OmSetLed()

Enumerator
OM_LED_AUTO	Automatic device-controlled LED to indicate state (default).
OM_LED_OFF	rgb(0,0,0) Off
OM_LED_BLUE	rgb(0,0,1) Blue
OM_LED_GREEN	rgb(0,1,0) Green
OM_LED_CYAN	rgb(0,1,1) Cyan
OM_LED_RED	rgb(1,0,0) Red
OM_LED_MAGENTA	rgb(1,0,1) Magenta
OM_LED_YELLOW	rgb(1,1,0) Yellow
OM_LED_WHITE	rgb(1,1,1) White

Definition at line 484 of file omapi.h.

Function Documentation

◆ OmCommand()

int OmCommand	(	int	deviceId,
		const char *	command,
		char *	buffer,
		size_t	bufferSize,
		const char *	expected,
		unsigned int	timeoutMs,
		char **	parseParts,
		int	parseMax
	)

Issues a direct command over the CDC port for a particular device.

Waits for a line with the specified response (until the timeout is hit). If the response is found, and parsing is required (parseParts != NULL), it parses the response (at '=' and ',' places) up to 'parseMax' token.

Note: This method is not generally recommended – incorrect results could lead to unspecified behaviour.

Parameters

	deviceId	Identifier of the device.
	command	The command string to send (typically followed with CRLF).
[out]	buffer	A buffer to hold the response, or NULL if not required.
	bufferSize	The size (in bytes) of the output buffer.
	expected	The expected response prefix, or NULL if not specified (command will timeout if a response buffer is specified).
	timeoutMs	The time, in milliseconds, after which the command will time-out and return.
[out]	parseParts	A buffer to hold the parsed response, or NULL if parsing is not required.
	parseMax	The maximum number of entries the parsePoints buffer can hold.

Returns: The offset in the buffer of the start of the expected response, if found; or the offset in the buffer of the start of the error response string; otherwise the length of the unrecognized response.

Since: 1.2

◆ OmGetAccelerometer()

int OmGetAccelerometer	(	int	deviceId,
		int *	x,
		int *	y,
		int *	z
	)

Gets the specified device's current accelerometer values.

A sample consists of three consecutive signed 16-bit numbers (representing the X-, Y- and Z-axes), with units of 1/256 g.

Parameters

	deviceId	Identifier of the device.
[out]	x	Pointer to receive the x-axis value.
[out]	y	Pointer to receive the y-axis value.
[out]	z	Pointer to receive the z-axis value.

Returns: OM_OK if successful, an error code otherwise.

◆ OmGetBatteryHealth()

int OmGetBatteryHealth ( int deviceId )

Determine the health of the battery on the specified device.

The device maintains an internal count of significant recharge cycles.

Remarks: The device is rated to preserve 90% of its capacity (sufficient for 14-day data collection) after 500 recharge cycles.

Parameters

deviceId Identifier of the device.

Returns: A non-negative value indicates the number of significant recharge cycles of the battery (a smaller number is better). A negative value indicates an error code for an issue within the API.

◆ OmGetBatteryLevel()

int OmGetBatteryLevel ( int deviceId )

Queries the specified device for the current battery charging level.

Parameters

deviceId Identifier of the device.

Returns: A non-negative value indicates the battery percentage level (0-99% = charging, 100% = fully charged). A negative value indicates an error code for an issue within the API.

◆ OmGetDevicePath()

int OmGetDevicePath	(	int	deviceId,
		char *	pathBuffer
	)

Return the path to specified device's filesystem.

Parameters

	deviceId	Identifier of the device.
[out]	pathBuffer	A buffer to receive the path to the device's filsystem (of size OM_MAX_PATH).

See also: OmGetDataFilename()

Since: 1.7

◆ OmGetDevicePort()

int OmGetDevicePort	(	int	deviceId,
		char *	portBuffer
	)

Return the path to specified device's communication port.

Parameters

	deviceId	Identifier of the device.
[out]	portBuffer	A buffer to receive the path to the device's communication port (of size OM_MAX_PATH).

See also: OmGetDevicePath()

Since: 1.7

◆ OmGetDeviceSerial()

int OmGetDeviceSerial	(	int	deviceId,
		char *	serialBuffer
	)

Return the full USB serial string identity for the specified device.

Parameters

	deviceId	Identifier of the device.
[out]	serialBuffer	A buffer to receive the string of the device'sUSB serial string identity (of size OM_MAX_PATH).

Since: 1.8

◆ OmGetEcc()

int OmGetEcc ( int deviceId )

Gets the error-correcting code flag for the specified device.

Parameters

deviceId Identifier of the device.

Returns: OM_TRUE if ECC enabled, OM_FALSE if ECC disabled, an error code otherwise.

Since: 1.2

◆ OmGetMemoryHealth()

int OmGetMemoryHealth ( int deviceId )

Determine the health of the NAND flash memory on the specified device.

The device incorporates a wear-levelling 'Flash Translation Layer', error-correcting codes (ECC), and data checksums to minimize any data loss. To do this, the device must maintain a set of spare memory blocks on each memory 'plane'.
This call retrieves the number of spare blocks on the NAND memory on the plane with the least spare blocks.

Parameters

deviceId Identifier of the device.

Returns: A non-negative value indicates the health of the NAND memory (a larger number is better, 0 indicates the device is unusable). A negative value indicates an error code for an issue within the API.

◆ OmGetTime()

int OmGetTime	(	int	deviceId,
		OM_DATETIME *	time
	)

Queries the specified device's internal real time clock.

Parameters

	deviceId	Identifier of the device.
[out]	time	Pointer to a value to receive the current date/time.

Returns: OM_OK if successful, an error code otherwise.

◆ OmGetVersion()

int OmGetVersion	(	int	deviceId,
		int *	firmwareVersion,
		int *	hardwareVersion
	)

Returns the firmware and hardware versions of the specified device.

Parameters

	deviceId	Identifier of the device.
[out]	firmwareVersion	Pointer to a value to hold the firmware version, or NULL if not required.
[out]	hardwareVersion	Pointer to a value to hold the hardware version, or NULL if not required.

Returns: OM_OK if successful, an error code otherwise.

◆ OmIsLocked()

int OmIsLocked	(	int	deviceId,
		int *	hasLockCode
	)

Checks whether the device is currently locked.

Parameters

	deviceId	Identifier of the device.
[out]	hasLockCode	Pointer to a value that receives a flag indicating whether the device has a non-zero lock code and will be locked whenever connected (OM_FALSE or OM_TRUE).

Returns: The current lock state: OM_FALSE if unlocked, OM_TRUE if locked, an error code otherwise.

Since: 1.2

◆ OmSelfTest()

int OmSelfTest ( int deviceId )

Performs a firmware-specific self-test on the specified device (e.g.

test peripherals).

Remarks: A positive, non-zero self-test diagnostic code should be treated as an opaque, firmware-specific value indicating failure.

Parameters

deviceId Identifier of the device.

Returns: OM_OK if a the device successfully completed its self-test. A positive value indicates the device failed its self-test with the returned diagnostic code. A negative value indicates an error code for an issue within the API.

◆ OmSetEcc()

int OmSetEcc	(	int	deviceId,
		int	state
	)

Sets the error-correcting code flag for the specified device.

Parameters

deviceId	Identifier of the device.
state	OM_TRUE to enable ECC, OM_FALSE to disable ECC.

Returns: OM_OK if successful, an error code otherwise.

Since: 1.2

◆ OmSetLed()

int OmSetLed	(	int	deviceId,
		OM_LED_STATE	ledState
	)

Sets the specified device's LED colour.

Remarks: The default LED status, OM_LED_AUTO, allows the device to control its LED to indicate its state.

Parameters

deviceId	Identifier of the device.
ledState	LED state.

Returns: OM_OK if successful, an error code otherwise.

◆ OmSetLock()

int OmSetLock	(	int	deviceId,
		unsigned short	code
	)

Sets the lock code for the device when it is connected.

The device will not be locked immediately, only when next connected.

Parameters

deviceId	Identifier of the device.
code	Lock code to use. 0 = no lock, 0xffff is reserved for internal use.

Returns: The 'initial lock' state: OM_FALSE if unlocked, OM_TRUE if locked. Or an error code otherwise.

Since: 1.2

◆ OmSetTime()

int OmSetTime	(	int	deviceId,
		OM_DATETIME	time
	)

Sets the specified device's internal real time clock.

Parameters

deviceId	Identifier of the device.
time	the date/time to set.

Returns: OM_OK if successful, an error code otherwise.

◆ OmUnlock()

int OmUnlock	(	int	deviceId,
		unsigned short	code
	)

Sets the lock code for the device when it is connected.

The device will not be locked immediately, only when next connected.

Parameters

deviceId	Identifier of the device.
code	Unlock code to use (0 is reserved to indicate no lock code, 0xffff is reserved for internal use).

Returns: The current lock state: OM_FALSE if unlocked, OM_TRUE if the unlock code was not accepted, an error code otherwise.

Since: 1.2

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ OM_MEMORY_HEALTH_ERROR

◆ OM_MEMORY_HEALTH_WARNING

Enumeration Type Documentation

◆ OM_LED_STATE

Function Documentation

◆ OmCommand()

◆ OmGetAccelerometer()

◆ OmGetBatteryHealth()

◆ OmGetBatteryLevel()

◆ OmGetDevicePath()

◆ OmGetDevicePort()

◆ OmGetDeviceSerial()

◆ OmGetEcc()

◆ OmGetMemoryHealth()

◆ OmGetTime()

◆ OmGetVersion()

◆ OmIsLocked()

◆ OmSelfTest()

◆ OmSetEcc()

◆ OmSetLed()

◆ OmSetLock()

◆ OmSetTime()

◆ OmUnlock()