mirror of https://github.com/nymea/nymea.git
38 lines
2.5 KiB
Plaintext
38 lines
2.5 KiB
Plaintext
/*!
|
|
\page interfaces.html
|
|
\brief Interfaces define how a DeviceClass behaves
|
|
|
|
\section1 Interfaces for DeviceClasses
|
|
|
|
When creating a DeviceClass, the interfaces field can be used to specify a list of interfaces this DeviceClass implements.
|
|
|
|
When implementing an interface, the DeviceClass must follow the interface specification for the according interface. This means
|
|
the DeviceClass needs to have at least all the \l{StateType}{states}, \l{ActionType}{actions} and \l{EventType}{events} the given interface requires. A DeviceClass may
|
|
add custom states, actions or events, or even implement multiple interfaces.
|
|
|
|
The main purpose of interfaces is to provide for a better user experience. Using interfaces, a plugin developer can suggest the
|
|
ui to be used for this DeviceClass. For example, having a plugin that can control a dimmable light would likely have a state
|
|
named "powered" of type boolean and one named "brightness" of type int, ranging from 0 to 100%. Having just this information,
|
|
the ui would create a generic switch component to flip the bool state and a generic slider component to allow adjusting the
|
|
brightness because it can't know what the actual switch or slider do. For a better user experience though, the plugin developer
|
|
could just add the interface "dimmedlight" to this deviceclass and this way tell the ui that this actually is a dimmed light.
|
|
The ui can use this information to paint a pretty brightness slider, and implicitly flip the power switch off when the brightness
|
|
slider is moved to the lower end.
|
|
|
|
Another purpose of interfaces is to help the ui grouping and managing device classes. For example the \l {gateway} interface does
|
|
not require to implement any properties, however, it tells the ui that this is a gateway and thus not relevant to show to the
|
|
user in the main control entity. Instead, gateways might be listed in the configuration section of the client application.
|
|
|
|
In general it is a good idea to follow as many interfaces as precicely as possible in order to provide for the best user experience.
|
|
|
|
A interface can extend another interface. For example, the \l {light} interface only requires one state called powered of type bool.
|
|
A dimmablelight extends this type and adds a brightness property to it. This means, if a DeviceClass implements \l {dimmablelight}, it
|
|
also needs to cater for the \l {light} interface's states.
|
|
|
|
|
|
\section1 Currently available interfaces
|
|
\include interfacelist.qdoc
|
|
|
|
|
|
*/
|