1*plugin.[h|cpp] 
for plug-in construction.
 
  451@subsection writingadaptorsub Writing an Adaptor
 
  453A device adaptors is responsible 
for reading data from a source (usually a device driver interface)
 
  454and pushing it into the processing chain in sensor framework.
 
  456The easiest way to create a 
new device adaptor is to extend SysfsAdaptor. The base 
class will then
 
  457handle most things as long as the adaptor class itself provides the interface specific details.
 
  459What needs to be implemented:
 
  460  * Select busypoll or interrupt based approach0
 
  461  * Create and name an outputbuffer(s).
 
  462  * Function for reading and propagating data.
 
  465@subsubsection pollparagraph Interrupt based or busypoll
 
  467Files can be monitored either in SelectMode or IntervalMode. SelectMode uses epoll() to monitor for
 
  468  interrupts, while IntervalMode just busypolls with specified delay. Using SelectMode is encouraged
 
  469  due to power saving reasons as 
long as driver interface provides interrupts.
 
  471In case the driver interface provides possibility to control hardware sampling frequency
 
  472  (implies SelectMode), interval() and setInterval() should be reimplemented to
 
  473  make use of the functionality.
 
  475In case the driver initiates hardware measurement when the interface is read, the IntervalMode
 
  476 handles everything related to interval handling already (except specifying the allowed values).
 
  478@subsubsection bufferparagraph Buffers
 
  480An adaptor can have any number of output buffers. Usually there is only one, but if an adaptor
 
  481monitors several filehandles, or a filehandle provides more than one type of output, it might
 
  482occasionally make sense to provide several output buffers. The buffers are named and are searched
 
  483     by listeners based on the name.
 
  485@subsubsection readingdataparagraph Reading data from driver
 
  487SysfsAdaptor provides method addPath() for registering filehandles for listening. The path can also
 
  488     be set as constructor parameter. There can be any number of paths added, but mode of the
 
  489     adaptor will be the same for all of them, as well as the interval setting.
 
  491Whenever a registered filehandle has new data (signalled either by interrupt or by timeout),
 
  492    processSample(
int pathId, 
int fd) gets called. Data can be read from fd, and pathId is used
 
  493     to separate which file the handle points to.
 
  495The function should be implemented to read data from fd and propagate it to listeners by writing
 
  498@subsubsection metadataparagraph Metadata
 
  500Metadata for adaptors should represent the capabilities of the hardware and driver.
 
  502See section 'Metadata' at the end for generic details.
 
  504See examples/sampleadaptor/ for adaptor construction.
 
  506@subsubsection adaptorshardway Implementing A Device Adaptor - the hardway
 
  509If you wish to go all the way, adaptors are expected to implement the following things:
 
  511- Provide an output buffer. Create a buffer, introduce it with
 
  513void addAdaptedSensor(const QString& name, const QString& description, RingBufferBase* buffer);
 
  515where "name" is the 
id for the buffer. The name is used by the next node in the filtering chain to
 
  516locate the buffer. Currently these names are hardcoded in the layers above, so if the created adaptor
 
  517is a replacement for an existing one, the same buffer name(s) should be used. Adaptors and their
 
  518buffer names and types are listed below.
 
  520- Set adaptor description with setDescription() and list possible dataRanges for the adaptor with
 
  521introduceAvailableDataRange(). 
DataRange options are defined as (min value, max value, accuracy).
 
  523If the adaptor supports more than one data range, introduce all ranges and implement setDataRange()
 
  524to allow the client to switch between ranges. The NodeBase class will take care of queuing the range
 
  525requests (first come, first served).
 
  527- Implement startAdaptor() and stopAdaptor(). These are leftovers from something that is not very
 
  528valid at the moment, but might come handy in the future. These are called on construction and
 
  529destruction of the adaptor (by sensormanager). One could use these for example to do some
 
  530preliminary setup for sensor connection. Current adaptors don't do much. Calling startAdaptor()
 
  531should not make the sensor consume power (unless really
 
  532necessary, think BT connection)
 
  534- Implement startSensor() and stopSensor(). These are the functions used to start the sensor
 
  535dataflow into the named buffer. They should take care of reference counting for themselves, so
 
  536that the adapted sensor (aka. the buffer) will run as 
long as there is someone expecting data.
 
  537The AdaptedSensorEntry class provides help in reference counting. Whenever the sensor is stopped,
 
  538it should not consume any power. (quite sensor specific what is released here and what is released
 
  541- Implement standby() and resume(). These are called when display blanks / unblanks. The expected
 
  542functionality is to stop on standby, and start again on resume (goal is to save power). The
 
  543difference to start and stop is that the release of hardware should be invisible to layers above.
 
  544They can adjust properties and call start/stop, but these will only take effect after the adaptor
 
  547- In case the rate of the sensor can be adjusted, re-implement getPollingInterval() and
 
  548setPollingInterval(). [need to revise the code here, may have too many hardcodings to original
 
  549setup to make this work in a reasonable way]
 
  553@subsection writingfilter Writing a Filter
 
  554A filter is responsible for processing data.
 
  556A new filter should be created by inheriting from QObject and Filter.
 
  558Then what need to be implemented are:
 
  560        - Override the static factoryMethod() function and return a new instance of the filter
 
  561        - Define a private filter() function which can be called anything, as 
long as it matches
 
  562the nam-e in class constructor
 
  563   Implement the filter() function in the source file and do the necessary filtering operation
 
  566See examples/samplefilter/ for filter construction.
 
  570@subsection writingsensorsection Writing a Sensor
 
  573To create a new sensor, the following four steps should be done
 
  574  - implementation of AbstractSensorChannel
 
  575  - implementation of AbstractSensorChannelAdaptor
 
  577  - implementation of datatypes if sensor introduces new ones
 
  579AbstractSensorChannel is the end-node in the sensor graph.
 
  581AbstractSensorChannelAdaptor is the DBus interface of the sensor.
 
  584datastream from the socket.
 
  586See examples/samplesensor/ for sensor channel construction.
 
  590@subsection writingchain Writing a Chain
 
  593A chain is responsible for adapting filters into the data flow between an adaptor and a sensor.
 
  594A new chain is created by inheriting from AbstractChain.
 
  596Then what need to be implemented are:
 
  598        - Override the static factoryMethod() function and return a new instance of the chain
 
  601        - Get a pointer (refcounted) to the adaptor from sensor manager
 
  602        - Create a reader for the adaptor
 
  603        - Create and name output buffer
 
  604        - Create a new bin and add elements into it with names
 
  605        - Make connections between the elements in the Bin
 
  606        - Connect the reader to the adaptor
 
  608  - Do the cleaning up in the destructor
 
  609  - Override start() function to start chain
 
  610  - Override stop() function to stop chain
 
  612See examples/samplechain/ for chain construction.
 
  615@subsection metadatasubsection Metadata
 
  618Each node (adaptor/chain/sensor, not filters) should define metadata for itself. The following
 
  624  - Standby override sources (sort of metadata)
 
  628@subsection metadatasubsection Description
 
  630Description should provide a human readable 
string that describes what is the output from the node.
 
  632@subsection rangesubsection Interval range(s)
 
  634Interval ranges define the possible rates at which this node can provide output. They are given
 
  635with min/max pairs, where any value between min and max is allowed. Resolution parameter is ignored.
 
  637Base class takes care of queuing and sorting the interval requests. Each node just needs to provide
 
  638accepted ranges and set/get methods. Interval is specified as milliseconds between samples. The
 
  639real used value will be the smallest value, ensuring that data is measured as fast as required.
 
  640This behavior can be modified for a node, in case smallest == fastest does not apply for its sources.
 
  642For adaptors, the interval should represent the real capabilities of the hardware and driver.
 
  644Chains and sensors have more possibilities. In simplest case, they just delegate the interval for
 
  645the source node by using setIntervalSource(). Then any requests are directly moved to the source
 
  648If a node has more than one source whose output affect the rate of the output for the node itself,
 
  649setInterval() and interval() should be reimplemented to merge the requests into wanted rate.
 
  651@subsection datarangesubsection Data range(s)
 
  653Data ranges tell the possible min and max values and accuracy of measurements. Setting them closely
 
  654resembles interval setting. The largest difference is that datarates are set with
 
  655first-come-first-serve basis. The first requester of data range gets to keep the setting.
 
  657Currently there are no examples of sensors that would make use of multiple dataranges. For the sake
 
  658of information, the rates should be described with introduceAvailableDataRange() or taken from a
 
  659source with setIntervalSource().
 
  661@subsection standbysubsection Standby override
 
  663Default behavior is to turn off all sensors when display goes blank.
 
  665Client can request a sensor to stay on in such a case by setting the standbyOverride -property to
 
  666true. In practise, nodes specify which sources should stay on with addStandbyOverrideSource().
 
  668In adaptors, display blank will result in all filehandles being released. Setting the property to
 
  669true prevents this from happening.
 
  671The property should be used with care and only when required in order to minimize power consumption.
 
  673@subsection buffersubsection Buffer size and interval
 
  675Buffering means two things:
 
  676  - sensor driver of chip may have internal buffer for storing data. In that case adaptor will
 
  677implement setBufferSize() virtual function to configure the driver and implement
 
  678getAvailableBufferSizes() virtual function to list available buffer sizes.
 
  679  - if adaptor doesn't support buffering then sensorfw uses internal buffering to send data in
 
  680bursts to the clients. These modes are mutually exclusive for single sensor.
 
  682Buffer interval can be used to configure the time limit for 
long we will wait for buffer to get
 
  683full before flushing the content to the user. For driver/chip supported interval handling adaptor
 
  684will implement setBufferInterval() virtual function to configure the driver and implement
 
  685getAvailableBufferIntervals() virtual function to list available intervals.
 
  687By default buffering is disabled for client sessions.
 
  689@section configurationsection Configuration Files
 
  692Sensorfw supports multiple configuration files. There are two locations:
 
  694  (1) /etc/sensorfw/sensord.conf
 
  695  (2) /etc/sensorfw/sensord.conf.d/
 
  697Any option set in (1) will override options set in any of the files in (2). Files in (2) are
 
  698processed in alpha-numerical order, and later files can override settings from earlier files.
 
  699Using 
double-digits as the beginning of the filename for clarity is encouraged.
 
  701Configuration files contain sections for different HW. These sections should connect plugin
 
  702metanames (sampleadaptor) with the real plugin that should be used (sampleadaptor-inputdev).
 
  703The configuration file also contains option 'deviceId', which specifies which section should be
 
  704used. This will be removed once we have automatic detection of underlying HW in place.
 
  706The structure of the configuration files is likely to change in the future to contain better
 
  707separation between different platforms.
 
Base-class for client facades of different sensor types.
Datatype for storing sensor data range information.
::LocalSensorManagerInterface SensorManager