nymea/doc/tutorials/your-first-plugin.qdoc

/*!
    \example simplebutton
    \title 2. Your very first plugin
    \ingroup tutorials
    \brief A simple button example for showing the basic concepts of a \l{DevicePlugin}.

    This is a nice example for showing the very basic concept of the nymea plugin mechanism.

    Lets say we want to create a Button device, called \tt{Simple button}, which has a \tt{press} \l{Action} and
    emits an \l{Event} called \tt{pressed} when someone executes the \tt{press} Action.

    Based on this Event we can create a rule and we have a virtual button which can
    be connected to any Action available in the entire system.

    \section1 Create the plugin structure

    Assuming you have read \l{1. The plugin wizard} {The plugin wizard} tutorial and you have installed
    all \l{Set up the build environment}{build dependencies} we start to create a new plugin project.


    In this image sequence you can see how this example was created.
    \image simplebutton-tutorial.gif


    \section1 Define the plugin properties
    In order to start with the development, you have to take a closer look at the \tt{devicepluginsimplebutton.json} file.
    In this file you can update the definitions of the \l{DevicePlugin}, \l{Vendor} and \l{DeviceClass}.

    The full documentation of this plugin definition file and the properties can be found in \l{The plugin JSON File} documentation.

    \quotefile simplebutton/devicepluginsimplebutton.json

    First you have to update the plugin, vendor and device class id in the id fields. The wizard initializes these uuids with
    the default zero uuid. You can use the \tt {uuidgen} command to create a new uuid and copy paste it into the id section.

    \note You have to rebuild the whole plugin once you update the deviceplugin JSON file.


    \section2 The plugin definition
    As you can see in this example, the plugin name is called \tt{SimpleButton}, and will be displayed as \tt{Simple button} plugin
    in the client applications. The name can also be translated. The name will be used to define the debug category for your plugin.
    In this example the debug categorie will be defined as \tt{dcSimpleButton} and can be used like following:

    \code
        qCDebug(dcSimpleButton()) << "This is a debug information.";
        qCWarning(dcSimpleButton()) << "This is a debug warning.";
        qCCritical(dcSimpleButton()) << "This is a critical debug warning.";
    \endcode

    The resulting debug output will look like following if the category is enabled:

    \code
        $ nymead -n -d SimpleButton

        ...

        I | SimpleButton: This is a debug information.
        W | SimpleButton: This is a debug warning.
        C | SimpleButton: This is a critical debug warning.
    \endcode

    This makes it easy to enable / disable the debug output of your plugin.

    \section2 The device class definition

    The Vendor section has not changed, since this example was developed from the guh Vendor.

    In order to give this simple button the required action and event described in the beginning of this tutorial,
    we have to define the appropriate types:

    \code
                    "actionTypes":[
                        {
                            "id": "64c4ced5-9a1a-4858-81dd-1b5c94dba495",
                            "name": "press",
                            "displayName": "press"
                        }
                    ],
    \endcode

    This is the most simple action you can create. The \tt{name} property definies how the action will be called in the system.
    The \tt{displayName} definies the string how the action will be displayed to the user and in the client applications.

    \code
                    "eventTypes":[
                        {
                            "id": "f9652210-9aed-4f38-8c19-2fd54f703fbe",
                            "name": "pressed",
                            "displayName": "button pressed"
                        }
                    ]
    \endcode

    This is the most simple event you can create. The \tt{name} property definies how the event will be called in the system.
    The \tt{displayName} definies the string how the event will be displayed to the user and in the client applications.

    As you may have noticed, this example represents already an \l{Interfaces for DeviceClasses}{interface}. The \l{simplebutton} interface offers
    a template for general simple buttons which are able to emit a \tt{pressed} event. In order to make use of the interface
    you simply add the interface to the list.

    \code
    ...

    "interfaces": [ "simplebutton" ],

    ...
    \endcode

    The server will verify if the required types for an interface match the template. This will be evaluated once the server loads the plugin.

    Once you updated the JSON file, you have to rebuild the whole plugin in order to trigger a rebuild of the plugin information
    include files.

    \section2 nymea-generateplugininfo

    Before the source code will be compiled, a precompiler called \tt {nymea-generateplugininfo} will be launched. This tool will
    read the plugin JSON file and generate two header files for the plugin in the build directory.

    \section3 plugininfo.h

    As you can see here this file contains all uuid definitions and translation string generated from the plugin JSON file. This file
    will regenerated every time you
    \quotefile simplebutton/plugininfo.h

    \section3 extern-plugininfo.h

    \quotefile simplebutton/extern-plugininfo.h

    \section1 Implement the plugin

    In order to implement this simple action and emit the Event once the button will be pressed, you need to implement following code:

    \quotefromfile simplebutton/devicepluginsimplebutton.cpp
    \skipto DeviceManager::DeviceError DevicePluginSimpleButton::executeAction
    \printuntil }\n

    In this code section you can see the implementation of the \tt executeAction method for this example tutorial. The method
    will be called from DeviceManager once an Action should be executed. First we have to check for which device class this action
    is ment. The we have to check which action of this device class should be executed. In this example we have only one deviceclass and
    one action.

    \code
        emitEvent(Event(simplebuttonPressedEventTypeId, device->id()));
    \endcode

    And finally, once the action \tt press gets called, the event \tt pressed will be emitted in the system.

    This event can be connected within a rule to execute whatever action you want.

    \section1 Test the plugin

    Now it's time to build you first plugin. In order to make sure all changes in you JSON file are up to date press the \tt{Rebuild all} instead
    of only \tt {Build}. This will rerun the nymea-generateplugininfo tool and update the \tt plugininfo.h and \tt extern-plugininfo.h files.

    \note Coming soon!


*/