3.9.1.3 Classes

The following classes are provided by the Sensor module:

class Sensor

The Sensor class represents a physical sensor which delivers (possibly filtered) events. By default, events are not filtered. A filter can be applied by using the set_event_filter method. An example for an event filter is given by OrientationEventFilter, which can be applied to an acceleration sensor of the device.

In case different filters must be used for the same physical sensor, different Sensor objects have to be created for the same physical sensor.

__init__( sensor_id, category_id): Initialises the Sensor object. sensor_id and category_id must represent a valid sensor id and category id, respectively. This means that the ids passed on to __init__ must also appear in the dictionary returned by the sensors function. In case sensor_id and category_id do not represent a valid sensor, the connect method will raise an exception.

connect( callback): This method connects the sensor to the given callback. A sensor can only be connected to one callback, so this will destroy any pre-existing connection to another callback. If an event filter has been set, the events passed on to callback will first pass this event filter of the Sensor object. If the connection is properly established, this method returns 1, otherwise 0. Note: The connection can be established also if the callback does not exist or cannot be called for any other reason.

disconnect( ): Disconnects this callback connection of the Sensor object. After a successful call to this method, a callback that has been previously connected through connect will not receive any more events. If a connection existed and is successfully removed, this method returns 1, otherwise 0.

connected( ): Retrieves this Sensor object's connection status. Returns True if the sensor is connected, False otherwise.

set_event_filter( event_filter): Sets an event filter for this Sensor object. After the event filter has been successfully installed, the connected callback of the Sensor object will receive only events that have passed the filter. event_filter must be derived from EventFilter in order to function properly. If a callback connection has already been established before calling this method, the connection will be re-established after the event filter has been installed.

class EventFilter

The EventFilter class provides a generic interface for event filters. The default implementation only passes events on, that is, events are not filtered. Classes deriving from EventFilter can decide if an event should be delivered at all as well as they can alter the data that is passed on to the callback.

callback: This is where the callback of the event filter is stored. In case, the EventFilter object is used together with a Sensor object, the Sensor object will handle correct setting of this variable.

__init__( ): Initialises the event filter object. The callback member is initialised to None.

__del__( ): Destructs the event filter object. This method calls cleanup, which can be overridden by deriving classes to clean up resources.

event( data): This method is the place where event filtering takes place, and hence this method should be overridden by deriving classes. Overridden event methods can deliver their own data to the callback, the data delivered can be data or any other set of data. In case the event is decided to be delivered, overriding instances must call self.callback, which by default takes one argument.

cleanup( ): Cleans up any resources needed by the event filter. The default implementation does not need this feature. This method is called by the destructor __del__.

class OrientationEventFilter

Derived from EventFilter. This event filter is meant to be used together with the acceleration sensors of the device. Note that it is not required to use it with any other sensor type. It generates events when the devices orientation changes. For example, if it is turned from the upright position to lying on the back side. If an OrientationEventFiler is used with a Sensor object, the callback of the Sensor object will not receive the raw acceleration data as an argument, but only one of the orientation constants, representing the new orientation of the device. In case the algorithm needs calibration on the device to be used, you must check the OrientationCalibration variables in the file sensor.py.

__init__( ): Initialises the OrientationEventFilter object.

event( sensor_val): Overridden method. Filters 3-axis acceleration events such that it detects orientation changes. Only upon detection of such an orientation change, the callback is invoked. The argument passed to the callback is a value from the orientation constants of this module.

cleanup( ): Cleans up the timer resource of this filter. This will be called by destructor of the EventFilter class.

class RotEventFilter

Derived from EventFilter.

This event filter generates events when the devices orientation changes. For example, if it is turned from the left side up position to right side up position. This sensor is resident. For example, in Nokia N95.

event( sensor_val): Overridden method. Upon detection of an orientation change, the callback is invoked. The argument passed to the callback is a value from this module's orientation constants.

See About this document... for information on suggesting changes.