sensorfw
mainpage.h
Go to the documentation of this file.
1 *plugin.[h|cpp] for plug-in construction.
448 
449 
450 
451 @subsection writingadaptorsub Writing an Adaptor
452 
453 A device adaptors is responsible for reading data from a source (usually a device driver interface)
454 and pushing it into the processing chain in sensor framework.
455 
456 The easiest way to create a new device adaptor is to extend SysfsAdaptor. The base class will then
457 handle most things as long as the adaptor class itself provides the interface specific details.
458 
459 What 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.
463  * Specify metadata
464 
465 @subsubsection pollparagraph Interrupt based or busypoll
466 
467 Files 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.
470 
471 In 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.
474 
475 In 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).
477 
478 @subsubsection bufferparagraph Buffers
479 
480 An adaptor can have any number of output buffers. Usually there is only one, but if an adaptor
481 monitors several filehandles, or a filehandle provides more than one type of output, it might
482 occasionally make sense to provide several output buffers. The buffers are named and are searched
483  by listeners based on the name.
484 
485 @subsubsection readingdataparagraph Reading data from driver
486 
487 SysfsAdaptor 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.
490 
491 Whenever 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.
494 
495 The function should be implemented to read data from fd and propagate it to listeners by writing
496  to buffer.
497 
498 @subsubsection metadataparagraph Metadata
499 
500 Metadata for adaptors should represent the capabilities of the hardware and driver.
501 
502 See section 'Metadata' at the end for generic details.
503 
504 See examples/sampleadaptor/ for adaptor construction.
505 
506 @subsubsection adaptorshardway Implementing A Device Adaptor - the hardway
507 
508 
509 If you wish to go all the way, adaptors are expected to implement the following things:
510 
511 - Provide an output buffer. Create a buffer, introduce it with
512 
513 void addAdaptedSensor(const QString& name, const QString& description, RingBufferBase* buffer);
514 
515 where "name" is the id for the buffer. The name is used by the next node in the filtering chain to
516 locate the buffer. Currently these names are hardcoded in the layers above, so if the created adaptor
517 is a replacement for an existing one, the same buffer name(s) should be used. Adaptors and their
518 buffer names and types are listed below.
519 
520 - Set adaptor description with setDescription() and list possible dataRanges for the adaptor with
521 introduceAvailableDataRange(). DataRange options are defined as (min value, max value, accuracy).
522 
523 If the adaptor supports more than one data range, introduce all ranges and implement setDataRange()
524 to allow the client to switch between ranges. The NodeBase class will take care of queuing the range
525 requests (first come, first served).
526 
527 - Implement startAdaptor() and stopAdaptor(). These are leftovers from something that is not very
528 valid at the moment, but might come handy in the future. These are called on construction and
529 destruction of the adaptor (by sensormanager). One could use these for example to do some
530 preliminary setup for sensor connection. Current adaptors don't do much. Calling startAdaptor()
531 should not make the sensor consume power (unless really
532 necessary, think BT connection)
533 
534 - Implement startSensor() and stopSensor(). These are the functions used to start the sensor
535 dataflow into the named buffer. They should take care of reference counting for themselves, so
536 that the adapted sensor (aka. the buffer) will run as long as there is someone expecting data.
537 The AdaptedSensorEntry class provides help in reference counting. Whenever the sensor is stopped,
538 it should not consume any power. (quite sensor specific what is released here and what is released
539  with stopAdaptor()).
540 
541 - Implement standby() and resume(). These are called when display blanks / unblanks. The expected
542 functionality is to stop on standby, and start again on resume (goal is to save power). The
543 difference to start and stop is that the release of hardware should be invisible to layers above.
544 They can adjust properties and call start/stop, but these will only take effect after the adaptor
545 has resumed.
546 
547 - In case the rate of the sensor can be adjusted, re-implement getPollingInterval() and
548 setPollingInterval(). [need to revise the code here, may have too many hardcodings to original
549 setup to make this work in a reasonable way]
550 
551 
552 
553 @subsection writingfilter Writing a Filter
554 A filter is responsible for processing data.
555 
556 A new filter should be created by inheriting from QObject and Filter.
557 
558 Then what need to be implemented are:
559  - In the header file
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
562 the nam-e in class constructor
563  Implement the filter() function in the source file and do the necessary filtering operation
564 there
565 
566 See examples/samplefilter/ for filter construction.
567 
568 
569 
570 @subsection writingsensorsection Writing a Sensor
571 
572 
573 To create a new sensor, the following four steps should be done
574  - implementation of AbstractSensorChannel
575  - implementation of AbstractSensorChannelAdaptor
576  - implementation of AbstractSensorChannelInterface
577  - implementation of datatypes if sensor introduces new ones
578 
579 AbstractSensorChannel is the end-node in the sensor graph.
580 
581 AbstractSensorChannelAdaptor is the DBus interface of the sensor.
582 
583 AbstractSensorChannelInterface is the client API for managing sensor through DBus and reading
584 datastream from the socket.
585 
586 See examples/samplesensor/ for sensor channel construction.
587 
588 
589 
590 @subsection writingchain Writing a Chain
591 
592 
593 A chain is responsible for adapting filters into the data flow between an adaptor and a sensor.
594 A new chain is created by inheriting from AbstractChain.
595 
596 Then what need to be implemented are:
597  - In the header file
598  - Override the static factoryMethod() function and return a new instance of the chain
599  - In the constructor
600  - Get an instance of SensorManager
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
607  - Setup metadata
608  - Do the cleaning up in the destructor
609  - Override start() function to start chain
610  - Override stop() function to stop chain
611 
612 See examples/samplechain/ for chain construction.
613 
614 
615 @subsection metadatasubsection Metadata
616 
617 
618 Each node (adaptor/chain/sensor, not filters) should define metadata for itself. The following
619 things are included:
620 
621  - Description
622  - Interval range(s)
623  - Data range(s)
624  - Standby override sources (sort of metadata)
625  - Buffer size
626  - Buffer interval
627 
628 @subsection metadatasubsection Description
629 
630 Description should provide a human readable string that describes what is the output from the node.
631 
632 @subsection rangesubsection Interval range(s)
633 
634 Interval ranges define the possible rates at which this node can provide output. They are given
635 with min/max pairs, where any value between min and max is allowed. Resolution parameter is ignored.
636 
637 Base class takes care of queuing and sorting the interval requests. Each node just needs to provide
638 accepted ranges and set/get methods. Interval is specified as milliseconds between samples. The
639 real used value will be the smallest value, ensuring that data is measured as fast as required.
640 This behavior can be modified for a node, in case smallest == fastest does not apply for its sources.
641 
642 For adaptors, the interval should represent the real capabilities of the hardware and driver.
643 
644 Chains and sensors have more possibilities. In simplest case, they just delegate the interval for
645 the source node by using setIntervalSource(). Then any requests are directly moved to the source
646 node.
647 
648 If a node has more than one source whose output affect the rate of the output for the node itself,
649 setInterval() and interval() should be reimplemented to merge the requests into wanted rate.
650 
651 @subsection datarangesubsection Data range(s)
652 
653 Data ranges tell the possible min and max values and accuracy of measurements. Setting them closely
654 resembles interval setting. The largest difference is that datarates are set with
655 first-come-first-serve basis. The first requester of data range gets to keep the setting.
656 
657 Currently there are no examples of sensors that would make use of multiple dataranges. For the sake
658 of information, the rates should be described with introduceAvailableDataRange() or taken from a
659 source with setIntervalSource().
660 
661 @subsection standbysubsection Standby override
662 
663 Default behavior is to turn off all sensors when display goes blank.
664 
665 Client can request a sensor to stay on in such a case by setting the standbyOverride -property to
666 true. In practise, nodes specify which sources should stay on with addStandbyOverrideSource().
667 
668 In adaptors, display blank will result in all filehandles being released. Setting the property to
669 true prevents this from happening.
670 
671 The property should be used with care and only when required in order to minimize power consumption.
672 
673 @subsection buffersubsection Buffer size and interval
674 
675 Buffering means two things:
676  - sensor driver of chip may have internal buffer for storing data. In that case adaptor will
677 implement setBufferSize() virtual function to configure the driver and implement
678 getAvailableBufferSizes() virtual function to list available buffer sizes.
679  - if adaptor doesn't support buffering then sensorfw uses internal buffering to send data in
680 bursts to the clients. These modes are mutually exclusive for single sensor.
681 
682 Buffer interval can be used to configure the time limit for long we will wait for buffer to get
683 full before flushing the content to the user. For driver/chip supported interval handling adaptor
684 will implement setBufferInterval() virtual function to configure the driver and implement
685 getAvailableBufferIntervals() virtual function to list available intervals.
686 
687 By default buffering is disabled for client sessions.
688 
689 @section configurationsection Configuration Files
690 
691 
692 Sensorfw supports multiple configuration files. There are two locations:
693 
694  (1) /etc/sensorfw/sensord.conf
695  (2) /etc/sensorfw/sensord.conf.d/
696 
697 Any option set in (1) will override options set in any of the files in (2). Files in (2) are
698 processed in alpha-numerical order, and later files can override settings from earlier files.
699 Using double-digits as the beginning of the filename for clarity is encouraged.
700 
701 Configuration files contain sections for different HW. These sections should connect plugin
702 metanames (sampleadaptor) with the real plugin that should be used (sampleadaptor-inputdev).
703 The configuration file also contains option 'deviceId', which specifies which section should be
704 used. This will be removed once we have automatic detection of underlying HW in place.
705 
706 The structure of the configuration files is likely to change in the future to contain better
707 separation between different platforms.
708 
709 
710 */
Base-class for client facades of different sensor types.
Datatype for storing sensor data range information.
Definition: datarange.h:46
::LocalSensorManagerInterface SensorManager