Sensor Library

The sensor library provides control over the sensors on the device. The files libsensor.h and sensor.h contain the functions, data types and constants that are required to make use of the sensor functionality.

You can create a sensor by calling sensor_new() with the type of sensor to be created (a list of sensor types may be found in sensor.h, e.g., SENSOR_TYPE_ACCELEROMETER).

Once you're finished with a sensor, you can delete it by calling sensor_delete(). Deleting an unused sensor frees memory and allows the sensor to be powered down, which reduces power usage and extends battery life.

To retrieve the latest event from a sensor, call sensor_get_event(). Similarly, your application can block until the next event is received from the sensor (or optionally until a timeout period has passed), by calling sensor_wait_event().

You can retrieve information about a sensor by calling sensor_get_info().

There may be points in time where you want to suspend the delivery of events from the sensor (e.g., the application is paused, switched to a menu screen, etc.). This can be done by calling sensor_pause(). When you want the sensor to resume delivering events, call sensor_resume().

Each sensor has an event polling period (i.e., the time between events) that you can retrieve by calling sensor_get_delay(), and set by calling sensor_set_delay().

To conserve battery power, the sensor can be automatically disabled when the device is in standby mode. However, if there is a need to receive sensor events when the screen is off, you can call sensor_set_background() with enable set to true. However, it is important to consider power consumption when using background mode, as it does use additional battery power.

Some applications need to ensure that no events from a sensor are missed. This can be achieved by using a client-specific queue of sensor events, which can be created by calling sensor_set_queue(), with enable set to true.

There may be a desire to skip duplicate sensor events, or events that are not significantly different from one another. This can be achieved by calling sensor_set_reduced_reporting() with enable set to true.

The following is an example of how to use the functions from libsensor.h in an application:

int sensor_read(void)
{
#define MY_SENSOR_PULSE_CODE 1
    struct sigevent ev;

    // Create a new accelerometer sensor handle.
    sensor_t *accel = sensor_new(SENSOR_TYPE_ACCELEROMETER);

    // Initialize sigevent, for later convenience; be sure to include sensor 
    // handle.
    SIGEV_PULSE_INIT(&ev, coid, SIGEV_PULSE_PRIO_INHERIT, MY_SENSOR_PULSE_CODE, 
                     accel);

    // Set up notification for new events.
    sensor_event_notify(accel, &ev);

    // Repeat as needed to create additional sensor handles.
    // Notice that you can reuse local sigevent if desired (i.e., each sensor 
    // handle caches a copy).
    // Be sure to change sensor handle (if populated).
    sensor_t *mag = sensor_new(SENSOR_TYPE_MAGNETOMETER);
    SIGEV_PULSE_INIT(&ev, coid, SIGEV_PULSE_PRIO_INHERIT, MY_SENSOR_PULSE_CODE, 
                     mag);
    sensor_event_notify(mag, &ev);

    // Set any specific sensor attributes.
    sensor_set_delay(accel, 1000000);
    sensor_set_background(mag, true);

    // A message receive thread.
    while (!term) {
        struct _pulse pulse;
        int rcvid = MsgReceive(chid, &pulse, sizeof(pulse), NULL);

        // If you populated the sigevent value pointer, retrieve it now.
        sensor_t *sensor = (sensor_t*) pulse.value.sival_ptr;

        // Get the sensor event that woke this thread up.
        sensor_event_t event;
        if (EOK == sensor_get_event(sensor, &event)) {
            printf("Event Type(%d), Data:\t%.2f\t%.2f\t%.2f\n", event.type, 
                   event.motion.dsp.x, event.motion.dsp.y, event.motion.dsp.z);
        }

        // Conveniently you can re-arm using the cached sigevent
        sensor_event_notify_rearm(sensor);
    }

    // Delete the sensor instances to free memory and save power.
    sensor_delete(&accel);
    sensor_delete(&mag);

    return EXIT_SUCCESS;
}
            

Last modified: 2013-12-21

comments powered by Disqus