• IntegrationPlugin
  • IntegrationPlugin Class

    This is the base class interface for integration plugins. More...

    Header: #include <IntegrationPlugin>
    Inherits:

    Properties

    Public Functions

    IntegrationPlugin(QObject * parent = nullptr)
    virtual ~IntegrationPlugin()
    virtual void browseThing(BrowseResult * result)
    virtual void browserItem(BrowserItemResult * result)
    QVariant configValue(const ParamTypeId & paramTypeId) const
    ParamList configuration() const
    ParamTypes configurationDescription() const
    virtual void confirmPairing(ThingPairingInfo * info, const QString & username, const QString & secret)
    virtual void discoverThings(ThingDiscoveryInfo * info)
    virtual void executeAction(ThingActionInfo * info)
    virtual void executeBrowserItem(BrowserActionInfo * info)
    virtual void executeBrowserItemAction(BrowserItemActionInfo * info)
    virtual void init()
    bool isBuiltIn() const
    QString pluginDisplayName() const
    PluginId pluginId() const
    QString pluginName() const
    virtual void postSetupThing(Thing * thing)
    Thing::ThingError setConfigValue(const ParamTypeId & paramTypeId, const QVariant & value)
    Thing::ThingError setConfiguration(const ParamList & configuration)
    virtual void setupThing(ThingSetupInfo * info)
    virtual void startMonitoringAutoThings()
    virtual void startPairing(ThingPairingInfo * info)
    ThingClasses supportedThings() const
    Vendors supportedVendors() const
    virtual void thingRemoved(Thing * thing)

    Signals

    void autoThingDisappeared(const ThingId & id)
    void autoThingsAppeared(const ThingDescriptors & thingDescriptors)
    void configValueChanged(const ParamTypeId & paramTypeId, const QVariant & value)
    void emitEvent(const Event & event)

    Protected Functions

    HardwareManager * hardwareManager() const
    Things myThings() const
    QSettings * pluginStorage() const

    Detailed Description

    This is the base class interface for integration plugins.

    Integration plugins extend nymea to allow integrating a device or online service, commonly referred to as thing in IoT.

    This is the base class to be subclassed when starting a new integration plugin.

    Property Documentation

    displayName : const QString

    Access functions:

    QString pluginDisplayName() const

    id : const QUuid

    Access functions:

    PluginId pluginId() const

    name : const QString

    Access functions:

    QString pluginName() const

    paramTypes : const ParamTypes

    Access functions:

    ParamTypes configurationDescription() const

    Member Function Documentation

    IntegrationPlugin::IntegrationPlugin(QObject * parent = nullptr)

    IntegrationPlugin constructor. IntegrationPlugins will be instantiated by the system. This should never be called manually by a plugin implementation.

    [virtual] IntegrationPlugin::~IntegrationPlugin()

    [signal] void IntegrationPlugin::autoThingDisappeared(const ThingId & id)

    A plugin should emit this signal when a thing with the given id is to be removed from the system. When emitting this signal, nymea will remove the Thing from the system and with it all the associated rules and child. Because of this, this signal should only be emitted when it's certain that the given device or online service will never return to be available any more. This can only be used for things that have been added using IntegrationPlugin::autoThingsAppeared.

    [signal] void IntegrationPlugin::autoThingsAppeared(const ThingDescriptors & thingDescriptors)

    A plugin emits this signal when new Things appears. For instance, a plugin connected to a bridge might detect that new devices have been connected to the bridge. Emitting this signal will cause those devices to be added as Thing to the nymea system and setupThing will be called for them.

    [virtual] void IntegrationPlugin::browseThing(BrowseResult * result)

    A plugin must implement this if its things support browsing ("browsable" being true in the metadata JSON). When the system calls this method, the result must be filled with entries from the browser using BrowseResult::addItems. The info object will contain information about which thing and which item/node should be browsed. If the itemId is empty it means that the root node of the file system should be returned otherwise all the children of the given item/node should be returned.

    Each item in the result set shall be uniquely identifiable using its id property. The system might call this method again, with an itemId returned in a previous query, provided that item's BrowserItem::browsable property is true. In this case all children of the given item shall be returned. All browser BrowserItem::displayName properties shall be localized using the given locale in the info object.

    If a returned item's BrowserItem::executable property is set to true, the system might call ThingPlugin::executeBrowserAction for this itemId.

    An item might have additional actions which must be defined in the plugin metadata JSON as "browserItemActionTypes". Such actions might be context actions to items in a browser. For instance, a file browser might add copy/cut/paste actions to an item. The system might call ThingPlugin::executeBrowserItemAction on such items.

    When done, the browse result must be completed by calling BrowserResult::finish with Thing::ThingErrorNoError in case of success or an appropriate Thing::ThingError otherwise. An optional display message can be passed which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    [virtual] void IntegrationPlugin::browserItem(BrowserItemResult * result)

    A plugin must implement this if its things support browsing ("browsable" being true in the metadata JSON). When the system calls this method, the result must be filled with a single item identified by the BrowserItemResult::itemId using BrowseResult::addItem. The result object will contain information about which thing and which item/node should be browsed. If the itemId is empty it means that the root node of the file system should be returned.

    Each item in the result set shall be uniquely identifiable using its id property. The system might call this method again, with an itemId returned in a previous query, provided that item's BrowserItem::browsable property is true. In this case all children of the given item shall be returned. All browser BrowserItem::displayName properties shall be localized using the given locale in the info object.

    When done, the browse result must be completed by calling BrowserItemResult::finish with Thing::ThingErrorNoError in case of success or an appropriate Thing::ThingError otherwise. An optional display message can be passed which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    QVariant IntegrationPlugin::configValue(const ParamTypeId & paramTypeId) const

    Use this to retrieve the values for your parameters. Values might not be set at the time when your plugin is loaded, but will be set soon after. Listen to configurationValueChanged() to know when something changes. When implementing a new plugin, specify in configurationDescription() what you want to see here. Returns the config value of a Param with the given paramTypeId of this IntegrationPlugin.

    See also setConfigValue().

    [signal] void IntegrationPlugin::configValueChanged(const ParamTypeId & paramTypeId, const QVariant & value)

    This signal is emitted when the Param with a certain paramTypeId of a Thing configuration changed the value.

    ParamList IntegrationPlugin::configuration() const

    Returns a map containing the plugin configuration. When implementing a new plugin, override this and fill in the empty configuration if your plugin requires any.

    See also setConfiguration().

    [virtual] void IntegrationPlugin::confirmPairing(ThingPairingInfo * info, const QString & username, const QString & secret)

    Confirms the pairing of the given info. username and secret are filled in depending on the setup method of the thing class. username will be used for SetupMethodUserAndPassword. secret will be used for SetupMethodUserAndPassword, SetupMethodDisplayPin and SetupMethodOAuth. Once the pairing is completed, the plugin implementation should call the info's finish() method reporting about the status of the pairing operation. The optional displayMessage needs to be wrapped in QT_TR_NOOP in order to be translatable to the client's locale.

    [virtual] void IntegrationPlugin::discoverThings(ThingDiscoveryInfo * info)

    A plugin must reimplement this if it supports a ThingClass with createMethod CreateMethodDiscovery. When the nymea system needs to discover available things, this will be called on the plugin. The plugin implementation is set to discover devices or online service endpoints for the ThingClassId given in the info object. When things are discovered, they should be added to the info object by calling ThingDiscoveryInfo::addThingDescriptor. Once the discovery is complete, a plugin must finish it by calling ThingDiscoveryInfo::finish using Thing::ThingErrorNoError in case of success, or a matching error code otherwise. An optional display message can be passed which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    A discovery might be cancelled by nymea. In which case the ThingDiscoveryInfo::aborted signal will be emitted. The info object must not be accessed after ThingDiscoveryInfo::destroyed is emitted.

    [signal] void IntegrationPlugin::emitEvent(const Event & event)

    To produce a new event in the system, a plugin should create a new Event and emit this signal it with that event. Usually events are emitted in response to incoming data or other other events happening on the actua device or online service.

    [virtual] void IntegrationPlugin::executeAction(ThingActionInfo * info)

    This will be called to execute actions on the thing. The given info object contains information about the target Thing and the Action to be executed.

    When the execution is completed, a plugin must finish it by calling ThingActionInfo::finish on the info object. In case of success, Thing::ThingErrorNoError must be used, or an appropriate Thing::ThingError in case of failure. An optional display message can be passed which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    An action execution might be cancelled by nymea. In which case the ThingActionInfo::aborted signal will be emitted. The info object must not be accessed after ThingActionInfo::destroyed is emitted.

    [virtual] void IntegrationPlugin::executeBrowserItem(BrowserActionInfo * info)

    This will be called to execute browser items on the thing. For instance, a file browser might execute a file here. The given info object contains information about the target Thing and the BrowserAction to be executed.

    When the execution is completed, a plugin must finish it by calling BrowserActionInfo::finish on the info object. In case of success, {Thing::ThingErrorNoError} must be used, or an appropriate Thing::ThingError in case of failure. An optional display message can be passed which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    An action execution might be cancelled by nymea. In which case the {BrowserActionInfo::aborted} signal will be emitted. The info object must not be accessed after BrowsereActionInfo::destroyed is emitted.

    [virtual] void IntegrationPlugin::executeBrowserItemAction(BrowserItemActionInfo * info)

    This will be called to execute browser item actions on the thing. For instance a file browser might have "browserItemActionTypes" defined in the JSON in order to support context options like copy/cut/paste. The given info object contains information about the target Thing and the BrowserItemAction to be executed.

    When the execution is completed, a plugin must finish it by calling BrowserItemActionInfo::finish on the info object. In case of success, Thing::ThingErrorNoError must be used, or an appropriate Thing::ThingError in case of failure. An optional display message can be passed which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    An action execution might be cancelled by nymea. In which case the {BrowserItemActionInfo::aborted} signal will be emitted. The info object must not be accessed after BrowserItemActionInfo::destroyed is emitted.

    [protected] HardwareManager * IntegrationPlugin::hardwareManager() const

    Returns the pointer to the main HardwareManager of this server.

    [virtual] void IntegrationPlugin::init()

    This will be called after constructing the IntegrationPlugin. Override this to do any initialisation work you need to do. While some initialization can also be done in the constructor, some resources like the hardwareManager might not be available at that point yet. When init() is called, it is guaranteed that the system is fully started up and ready for operation.

    bool IntegrationPlugin::isBuiltIn() const

    [protected] Things IntegrationPlugin::myThings() const

    Returns a list of all configured things belonging to this plugin.

    [protected] QSettings * IntegrationPlugin::pluginStorage() const

    Returns a pointer to a QSettings object which is reserved for this plugin. The plugin can store arbitrary data in this.

    [virtual] void IntegrationPlugin::postSetupThing(Thing * thing)

    This will be called when a new thing was added successfully and the thing setup is finished. A plugin can optionally trigger additional code to operate on the thing by reimplementing this method.

    Thing::ThingError IntegrationPlugin::setConfigValue(const ParamTypeId & paramTypeId, const QVariant & value)

    Can be called in the IntegrationPlugin to set a plugin's Param with the given paramTypeId and value.

    See also configValue().

    Thing::ThingError IntegrationPlugin::setConfiguration(const ParamList & configuration)

    Will be called by the systtem to set a plugin's configuration.

    See also configuration().

    [virtual] void IntegrationPlugin::setupThing(ThingSetupInfo * info)

    This will be called when a new thing is created. The plugin can do a setup of the thing by reimplementing this method. The passed info object will contain the information about the new Thing. When the setup is completed, a plugin must finish it by calling ThingSetupInfo::finish on the info object. In case of success, {Thing::ThingErrorNoError} must be used, or an appropriate Thing::ThingError in case of failure. An optional display message can be passed optionally which might be shown to the user, indicating more details about the error. The displayMessage must be made translatable by wrapping it in a QT_TR_NOOP() statement.

    A setup might be cancelled by nymea. In which case the {ThingSetupInfo::aborted} signal will be emitted. The info object must not be accessed after ThingSetupInfo::destroyed is emitted.

    [virtual] void IntegrationPlugin::startMonitoringAutoThings()

    Override this if your plugin supports things with ThingClass::CreationMethodAuto. This will be called at startup, after the configured things have been loaded. This is the earliest time you should start emitting autoThingsAppeared(). If you are monitoring some hardware/service for things to appear, start monitoring now. If you are building the things based on a static list, you may emit autoThingsAppeard() in here.

    [virtual] void IntegrationPlugin::startPairing(ThingPairingInfo * info)

    This method will be called to initiate a pairing. The plugin can do a initialisation for an upcoming pairing process. Depending on the setupMethod of a thing class, different actions may be required here. SetupMethodDisplayPin should trigger the thing to display a pin that will be entered in the client. SetupMethodOAuth should generate the OAuthUrl which will be opened on the client to allow the user logging in and obtain the OAuth code. SetupMethodEnterPin, SetupMethodPushButton and SetupMethodUserAndPassword will typically not require to do anything here. It is not required to reimplement this method for those setup methods, however, a plugin reimplementing it must call finish() on the ThingPairingInfo object and can provide an optional displayMessage which might be presented to the user. Those strings need to be wrapped in QT_TR_NOOP() in order to be translatable for the client's locale.

    ThingClasses IntegrationPlugin::supportedThings() const

    Return a list of ThingClasses describing all the Things supported by this plugin. If a ThingClass has an invalid parameter it will be ignored.

    Vendors IntegrationPlugin::supportedVendors() const

    Returns the list of Vendors supported by this plugin.

    [virtual] void IntegrationPlugin::thingRemoved(Thing * thing)

    This will be called when a thing removed. The plugin has the chance to do some cleanup. The thing is still valid during this call, but already removed from the system. The thing will be deleted as soon as this method returns.