3.9.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 a device's acceleration sensor.

In case different filters should 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 pass this Sensor object's event filter first. If the connection was 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 Sensor object's callback connection. After a successful call to this method, a callback that has been previously connected via connect will not receive any events anymore. If a connection existed and was 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, this Sensor object's connected callback 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, i.e. 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 event filter's callback 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 may be data or any other set of data. In case the event is decided to be delivered, overriding instances should 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 device's acceleration sensors. Note that it does not make sense to use it with any other sensor type. It generates events when the devices orientation changes, e.g. if it is turned from the upright position to lying on the back side. If an OrientationEventFiler is used with a Sensor object, the Sensor object's callback will not receive the raw acceleration data as an argument, but only one of the orientation constants, representing the device's new orientation. In case the algorithm needs calibration on the device to be used, please 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 this module's orientation constants.

cleanup( ): Cleans up this filter's timer resource. This will be called by EventFilter's destructor.

class RotEventFilter

Derived from EventFilter.

This event filter generates events when the devices orientation changes, e.g. if it is turned from the left side up position to right side up position. This sensor is resident e.g. 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.