Ubuntu Platform API  1.1.0
A library helping with tight integration into the Ubuntu platform
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions and types to access sensor devices.

Data Structures

struct  ubuntu_sensor_accelerometer_reading
 
struct  ubuntu_sensor_proximity_reading
 
struct  ubuntu_sensor_ambient_light_reading
 
struct  ubuntu_sensor_observer
 

Typedefs

typedef void UASensorsAccelerometer
 Opaque type that models the accelerometer. More...
 
typedef void(* on_accelerometer_event_cb )(UASAccelerometerEvent *event, void *context)
 Callback type used by applications to subscribe to accelerometer events. More...
 
typedef void UASAccelerometerEvent
 Opaque type describing an accelerometer reading. More...
 
typedef void UASLightEvent
 Opaque type describing an ambient light sensor reading. More...
 
typedef void UASProximityEvent
 Opaque type describing an accelerometer reading. More...
 
typedef void UASensorsLight
 Opaque type that models the ambient light sensor. More...
 
typedef void(* on_light_event_cb )(UASLightEvent *event, void *context)
 Callback type used by applications to subscribe to ambient light sensor events. More...
 
typedef void UASensorsProximity
 Opaque type that models the proximity sensor. More...
 
typedef void(* on_proximity_event_cb )(UASProximityEvent *event, void *context)
 Callback type used by applications to subscribe to proximity sensor events. More...
 
typedef void(* on_new_accelerometer_reading )(ubuntu_sensor_accelerometer_reading *reading, void *context)
 
typedef void(* on_new_proximity_reading )(ubuntu_sensor_proximity_reading *reading, void *context)
 
typedef void(* on_new_ambient_light_reading )(ubuntu_sensor_ambient_light_reading *reading, void *context)
 

Enumerations

enum  UbuntuApplicationSensorsProximityDistance {
  U_PROXIMITY_NEAR = 1,
  U_PROXIMITY_FAR = 2
}
 Useful constants when inspecting readings from the proximity sensor. More...
 
enum  ubuntu_sensor_type {
  first_defined_sensor_type = 0,
  ubuntu_sensor_type_accelerometer = first_defined_sensor_type,
  ubuntu_sensor_type_magnetic_field,
  ubuntu_sensor_type_gyroscope,
  ubuntu_sensor_type_light,
  ubuntu_sensor_type_proximity,
  ubuntu_sensor_type_orientation,
  ubuntu_sensor_type_linear_acceleration,
  ubuntu_sensor_type_rotation_vector,
  undefined_sensor_type
}
 

Functions

UBUNTU_DLL_PUBLIC
UASensorsAccelerometer
ua_sensors_accelerometer_new ()
 Create a new object for accessing the accelerometer. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_enable (UASensorsAccelerometer *sensor)
 Enables the supplied accelerometer. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_disable (UASensorsAccelerometer *sensor)
 Disables the supplied accelerometer. More...
 
UBUNTU_DLL_PUBLIC uint32_t ua_sensors_accelerometer_get_min_delay (UASensorsAccelerometer *sensor)
 Queries the minimum delay between two readings for the supplied sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_get_min_value (UASensorsAccelerometer *sensor, float *value)
 Queries the minimum value that can be reported by the sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_get_max_value (UASensorsAccelerometer *sensor, float *value)
 Queries the maximum value that can be reported by the sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_get_resolution (UASensorsAccelerometer *sensor, float *value)
 Queries the numeric resolution supported by the sensor. More...
 
UBUNTU_DLL_PUBLIC void ua_sensors_accelerometer_set_reading_cb (UASensorsAccelerometer *sensor, on_accelerometer_event_cb cb, void *ctx)
 Set the callback to be invoked whenever a new sensor reading is available. More...
 
UBUNTU_DLL_PUBLIC uint64_t uas_accelerometer_event_get_timestamp (UASAccelerometerEvent *event)
 Query the timestamp of the sensor reading. More...
 
UBUNTU_DLL_PUBLIC UStatus uas_accelerometer_event_get_acceleration_x (UASAccelerometerEvent *event, float *value)
 Query the acceleration in x-axis direction. More...
 
UBUNTU_DLL_PUBLIC UStatus uas_accelerometer_event_get_acceleration_y (UASAccelerometerEvent *event, float *value)
 Query the acceleration in y-axis direction. More...
 
UBUNTU_DLL_PUBLIC UStatus uas_accelerometer_event_get_acceleration_z (UASAccelerometerEvent *event, float *value)
 Query the acceleration in z-axis direction. More...
 
UBUNTU_DLL_PUBLIC uint64_t uas_light_event_get_timestamp (UASLightEvent *event)
 Query the timestamp of the sensor reading. More...
 
UBUNTU_DLL_PUBLIC UStatus uas_light_event_get_light (UASLightEvent *event, float *value)
 Query the value measured by the ambient light sensor. More...
 
UBUNTU_DLL_PUBLIC uint64_t uas_proximity_event_get_timestamp (UASProximityEvent *event)
 Query the timestamp of the sensor reading. More...
 
UBUNTU_DLL_PUBLIC
UASProximityDistance 
uas_proximity_event_get_distance (UASProximityEvent *event)
 Query the discrete distance as reported by the proximity sensor. More...
 
UBUNTU_DLL_PUBLIC UASensorsLightua_sensors_light_new ()
 Create a new object for accessing the ambient light sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_enable (UASensorsLight *sensor)
 Enables the supplied ambient light sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_disable (UASensorsLight *sensor)
 Disables the supplied ambient light sensor. More...
 
UBUNTU_DLL_PUBLIC uint32_t ua_sensors_light_get_min_delay (UASensorsLight *sensor)
 Queries the minimum delay between two readings for the supplied sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_get_min_value (UASensorsLight *sensor, float *value)
 Queries the minimum value that can be reported by the sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_get_max_value (UASensorsLight *sensor, float *value)
 Queries the maximum value that can be reported by the sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_get_resolution (UASensorsLight *sensor, float *value)
 Queries the numeric resolution supported by the sensor. More...
 
UBUNTU_DLL_PUBLIC void ua_sensors_light_set_reading_cb (UASensorsLight *sensor, on_light_event_cb cb, void *ctx)
 Set the callback to be invoked whenever a new sensor reading is available. More...
 
UBUNTU_DLL_PUBLIC
UASensorsProximity
ua_sensors_proximity_new ()
 Create a new object for accessing the proximity sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_enable (UASensorsProximity *sensor)
 Enables the supplied proximity sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_disable (UASensorsProximity *sensor)
 Disables the supplied proximity sensor. More...
 
UBUNTU_DLL_PUBLIC uint32_t ua_sensors_proximity_get_min_delay (UASensorsProximity *sensor)
 Queries the minimum delay between two readings for the supplied sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_get_min_value (UASensorsProximity *sensor, float *value)
 Queries the minimum value that can be reported by the sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_get_max_value (UASensorsProximity *sensor, float *value)
 Queries the maximum value that can be reported by the sensor. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_get_resolution (UASensorsProximity *sensor, float *value)
 Queries the numeric resolution supported by the sensor. More...
 
UBUNTU_DLL_PUBLIC void ua_sensors_proximity_set_reading_cb (UASensorsProximity *sensor, on_proximity_event_cb cb, void *ctx)
 Set the callback to be invoked whenever a new sensor reading is available. More...
 
UBUNTU_DLL_PUBLIC void ubuntu_sensor_install_observer (ubuntu_sensor_observer *observer)
 
UBUNTU_DLL_PUBLIC void ubuntu_sensor_uninstall_observer (ubuntu_sensor_observer *observer)
 
UBUNTU_DLL_PUBLIC void ubuntu_sensor_enable_sensor (ubuntu_sensor_type sensor_type)
 
UBUNTU_DLL_PUBLIC void ubuntu_sensor_disable_sensor (ubuntu_sensor_type sensor_type)
 
UBUNTU_DLL_PUBLIC int32_t ubuntu_sensor_get_sensor_min_delay (ubuntu_sensor_type sensor_type)
 
UBUNTU_DLL_PUBLIC UStatus ubuntu_sensor_get_sensor_min_value (ubuntu_sensor_type sensor_type, float *value)
 
UBUNTU_DLL_PUBLIC UStatus ubuntu_sensor_get_sensor_max_value (ubuntu_sensor_type sensor_type, float *value)
 
UBUNTU_DLL_PUBLIC UStatus ubuntu_sensor_get_sensor_resolution (ubuntu_sensor_type sensor_type, float *value)
 

Detailed Description

Typedef Documentation

typedef void(* on_accelerometer_event_cb)(UASAccelerometerEvent *event, void *context)

Callback type used by applications to subscribe to accelerometer events.

Definition at line 41 of file accelerometer.h.

typedef void(* on_light_event_cb)(UASLightEvent *event, void *context)

Callback type used by applications to subscribe to ambient light sensor events.

Definition at line 41 of file light.h.

typedef void(* on_new_accelerometer_reading)(ubuntu_sensor_accelerometer_reading *reading, void *context)

Callback that is invoked for new accelerometer readings.

Parameters
reading[in] The new reading.
context[in] The callback context.

Definition at line 86 of file ubuntu_application_sensors.h.

typedef void(* on_new_ambient_light_reading)(ubuntu_sensor_ambient_light_reading *reading, void *context)

Callback that is invoked for new ambient light sensor readings.

Parameters
reading[in] The new reading.
context[in] The callback context.

Definition at line 100 of file ubuntu_application_sensors.h.

typedef void(* on_new_proximity_reading)(ubuntu_sensor_proximity_reading *reading, void *context)

Callback that is invoked for new proximity sensor readings.

Parameters
reading[in] The new reading.
context[in] The callback context.

Definition at line 93 of file ubuntu_application_sensors.h.

typedef void(* on_proximity_event_cb)(UASProximityEvent *event, void *context)

Callback type used by applications to subscribe to proximity sensor events.

Definition at line 41 of file proximity.h.

typedef void UASAccelerometerEvent

Opaque type describing an accelerometer reading.

Definition at line 34 of file accelerometer.h.

typedef void UASensorsAccelerometer

Opaque type that models the accelerometer.

Definition at line 35 of file accelerometer.h.

typedef void UASensorsLight

Opaque type that models the ambient light sensor.

Definition at line 35 of file light.h.

typedef void UASensorsProximity

Opaque type that models the proximity sensor.

Definition at line 35 of file proximity.h.

typedef void UASLightEvent

Opaque type describing an ambient light sensor reading.

Definition at line 34 of file light.h.

typedef void UASProximityEvent

Opaque type describing an accelerometer reading.

Definition at line 45 of file proximity.h.

Enumeration Type Documentation

Describes the sensor types known to the system

Enumerator
first_defined_sensor_type 
ubuntu_sensor_type_accelerometer 
ubuntu_sensor_type_magnetic_field 
ubuntu_sensor_type_gyroscope 
ubuntu_sensor_type_light 
ubuntu_sensor_type_proximity 
ubuntu_sensor_type_orientation 
ubuntu_sensor_type_linear_acceleration 
ubuntu_sensor_type_rotation_vector 
undefined_sensor_type 

Definition at line 67 of file ubuntu_application_sensors.h.

Useful constants when inspecting readings from the proximity sensor.

Enumerator
U_PROXIMITY_NEAR 

The reading indicates that something is near the sensor/device.

U_PROXIMITY_FAR 

The reading indicates that something is far away from the sensor/device.

Definition at line 34 of file proximity.h.

Function Documentation

UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_disable ( UASensorsAccelerometer sensor)

Disables the supplied accelerometer.

Returns
U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
Parameters
[in]sensorThe sensor instance to be disabled.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_enable ( UASensorsAccelerometer sensor)

Enables the supplied accelerometer.

Returns
U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
Parameters
[in]sensorThe sensor instance to be enabled.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_get_max_value ( UASensorsAccelerometer sensor,
float *  value 
)

Queries the maximum value that can be reported by the sensor.

Returns
The maximum value that can be reported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC uint32_t ua_sensors_accelerometer_get_min_delay ( UASensorsAccelerometer sensor)

Queries the minimum delay between two readings for the supplied sensor.

Returns
The minimum delay between two readings in [ms].
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_get_min_value ( UASensorsAccelerometer sensor,
float *  value 
)

Queries the minimum value that can be reported by the sensor.

Returns
The minimum value that can be reported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_accelerometer_get_resolution ( UASensorsAccelerometer sensor,
float *  value 
)

Queries the numeric resolution supported by the sensor.

Returns
The numeric resolution supported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UASensorsAccelerometer* ua_sensors_accelerometer_new ( )

Create a new object for accessing the accelerometer.

Returns
A new instance or NULL in case of errors.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC void ua_sensors_accelerometer_set_reading_cb ( UASensorsAccelerometer sensor,
on_accelerometer_event_cb  cb,
void *  ctx 
)

Set the callback to be invoked whenever a new sensor reading is available.

Parameters
[in]sensorThe sensor instance to associate the callback with.
[in]cbThe callback to be invoked.
[in]ctxThe context supplied to the callback invocation.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_disable ( UASensorsLight sensor)

Disables the supplied ambient light sensor.

Returns
U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
Parameters
[in]sensorThe sensor instance to be disabled.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_enable ( UASensorsLight sensor)

Enables the supplied ambient light sensor.

Returns
U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
Parameters
[in]sensorThe sensor instance to be enabled.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_get_max_value ( UASensorsLight sensor,
float *  value 
)

Queries the maximum value that can be reported by the sensor.

Returns
The maximum value that can be reported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC uint32_t ua_sensors_light_get_min_delay ( UASensorsLight sensor)

Queries the minimum delay between two readings for the supplied sensor.

Returns
The minimum delay between two readings in [ms].
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_get_min_value ( UASensorsLight sensor,
float *  value 
)

Queries the minimum value that can be reported by the sensor.

Returns
The minimum value that can be reported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_light_get_resolution ( UASensorsLight sensor,
float *  value 
)

Queries the numeric resolution supported by the sensor.

Returns
The numeric resolution supported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UASensorsLight* ua_sensors_light_new ( )

Create a new object for accessing the ambient light sensor.

Returns
A new instance or NULL in case of errors.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC void ua_sensors_light_set_reading_cb ( UASensorsLight sensor,
on_light_event_cb  cb,
void *  ctx 
)

Set the callback to be invoked whenever a new sensor reading is available.

Parameters
[in]sensorThe sensor instance to associate the callback with.
[in]cbThe callback to be invoked.
[in]ctxThe context supplied to the callback invocation.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_disable ( UASensorsProximity sensor)

Disables the supplied proximity sensor.

Returns
U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
Parameters
[in]sensorThe sensor instance to be disabled.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_enable ( UASensorsProximity sensor)

Enables the supplied proximity sensor.

Returns
U_STATUS_SUCCESS if successful or U_STATUS_ERROR if an error occured.
Parameters
[in]sensorThe sensor instance to be enabled.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_get_max_value ( UASensorsProximity sensor,
float *  value 
)

Queries the maximum value that can be reported by the sensor.

Returns
The maximum value that can be reported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC uint32_t ua_sensors_proximity_get_min_delay ( UASensorsProximity sensor)

Queries the minimum delay between two readings for the supplied sensor.

Returns
The minimum delay between two readings in [ms].
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_get_min_value ( UASensorsProximity sensor,
float *  value 
)

Queries the minimum value that can be reported by the sensor.

Returns
The minimum value that can be reported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UStatus ua_sensors_proximity_get_resolution ( UASensorsProximity sensor,
float *  value 
)

Queries the numeric resolution supported by the sensor.

Returns
The numeric resolution supported by the sensor.
Parameters
[in]sensorThe sensor instance to be queried.
UBUNTU_DLL_PUBLIC UASensorsProximity* ua_sensors_proximity_new ( )

Create a new object for accessing the proximity sensor.

Returns
A new instance or NULL in case of errors.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC void ua_sensors_proximity_set_reading_cb ( UASensorsProximity sensor,
on_proximity_event_cb  cb,
void *  ctx 
)

Set the callback to be invoked whenever a new sensor reading is available.

Parameters
[in]sensorThe sensor instance to associate the callback with.
[in]cbThe callback to be invoked.
[in]ctxThe context supplied to the callback invocation.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus uas_accelerometer_event_get_acceleration_x ( UASAccelerometerEvent event,
float *  value 
)

Query the acceleration in x-axis direction.

Returns
The acceleration in x-axis direction.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus uas_accelerometer_event_get_acceleration_y ( UASAccelerometerEvent event,
float *  value 
)

Query the acceleration in y-axis direction.

Returns
The acceleration in y-axis direction.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus uas_accelerometer_event_get_acceleration_z ( UASAccelerometerEvent event,
float *  value 
)

Query the acceleration in z-axis direction.

Returns
The acceleration in z-axis direction.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC uint64_t uas_accelerometer_event_get_timestamp ( UASAccelerometerEvent event)

Query the timestamp of the sensor reading.

Returns
The timestamp of the sensor reading in [µs], timebase: monotonic clock.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UStatus uas_light_event_get_light ( UASLightEvent event,
float *  value 
)

Query the value measured by the ambient light sensor.

Returns
The ambient light level.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC uint64_t uas_light_event_get_timestamp ( UASLightEvent event)

Query the timestamp of the sensor reading.

Returns
The timestamp of the sensor reading in [µs], timebase: monotonic clock.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC UASProximityDistance uas_proximity_event_get_distance ( UASProximityEvent event)

Query the discrete distance as reported by the proximity sensor.

Returns
The discrete distance as reported by the proximity sensor.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC uint64_t uas_proximity_event_get_timestamp ( UASProximityEvent event)

Query the timestamp of the sensor reading.

Returns
The timestamp of the sensor reading in [µs], timebase: monotonic clock.
Parameters
[in]eventThe reading to be queried.
Examples:
test_sensors_api.cpp.
UBUNTU_DLL_PUBLIC void ubuntu_sensor_disable_sensor ( ubuntu_sensor_type  sensor_type)

Disables the specified sensor type and starts data acquisition.

UBUNTU_DLL_PUBLIC void ubuntu_sensor_enable_sensor ( ubuntu_sensor_type  sensor_type)

Enables the specified sensor type and starts data acquisition.

UBUNTU_DLL_PUBLIC UStatus ubuntu_sensor_get_sensor_max_value ( ubuntu_sensor_type  sensor_type,
float *  value 
)

Returns the maximum valid value for the sensor_type.

UBUNTU_DLL_PUBLIC int32_t ubuntu_sensor_get_sensor_min_delay ( ubuntu_sensor_type  sensor_type)

Returns the minimum sensor sampling delay in Hz.

UBUNTU_DLL_PUBLIC UStatus ubuntu_sensor_get_sensor_min_value ( ubuntu_sensor_type  sensor_type,
float *  value 
)

Returns the minimum valid value for the sensor_type.

UBUNTU_DLL_PUBLIC UStatus ubuntu_sensor_get_sensor_resolution ( ubuntu_sensor_type  sensor_type,
float *  value 
)

Returns the resolution of valid values for the sensor_type.

UBUNTU_DLL_PUBLIC void ubuntu_sensor_install_observer ( ubuntu_sensor_observer observer)

Installs the supplied observer.

UBUNTU_DLL_PUBLIC void ubuntu_sensor_uninstall_observer ( ubuntu_sensor_observer observer)

Uninstalls the supplied observer.