/*!
    \example template
    \title 1. The plugin wizard
    \ingroup tutorials
    \brief Explanation of the Qt Creator plugin wizard template


    This tutorial shows you how to start a new plugin project using the nymea-qtcreator wizard. You can find the source code of the
    qt-creator wizard on our \l{https://github.com/guh/nymea-qtcreator-wizards}{github page}.


    \section1 Create the plugin project

    Once you have installed all packages required for development, you can open the Qt Creator and start a new project.
    If you need help with the overall Qt Creator project creation, you can find more information
    \l{http://doc.qt.io/qtcreator/creator-project-creating.html}{here}.

    \section2 Choose template
        In the template view cou can find now the nymea section. In that section you can find the template for a new plugin.
        \image plugin-template-1.png Create a new plugin


    \section2 Project location
        Choose the project name and the path where the project should be located. As in this example the name is \e{template}
        and will be used within the source code as refference. A good practice is to pick a general describing name like a vendor
        or product/project name.
        \image plugin-template-2.png Project location

    \section2 Plugin details
        In this section the plugin details can be defined.

        In the first part you can find the c++ specific definitions:
        \list
            \li \b{Class name}: Enter the name of the main class for this device plugin.
                The naming should be \tt{DevicePlugin\e{Name}} in camel case.
        \endlist

        In the second part you can find the json specific definitions:
        \list
            \li \b{Vendor name}: Enter the name of the \l{Vendor}.
            \li \b{Device name}: Enter the name for the default device which will be created as template.
                You can change this any time in the json file.
            \li \b{Setup method}: Pick the desired setup method for the default device which will be created as template.
                You can change this any time in the json file. You can find more information in the
                \l{CreateMethods and SetupMethods} section.
            \li \b{Create method}: Pick the desired create method for the default device which will be created as template.
                You can change this any time in the json file.
            \li \b{Icon}: Pick the desired icon for the default device which will be created as template.
                You can change this any time in the json file.
        \endlist

        See also the \l{CreateMethods and SetupMethods} section.

        \image plugin-template-3.png Plugin details

    \section2 Developer information
        Enter the name and email address of the developer for this plugin. These information will be used in the
        copyright sections of the plugin. The copyright information are placed in the \tt{debian/copyright} file and in each
        source code license header.
        \image plugin-template-4.png Developer information

    \section2 Kit selection
        Pick the build kit for this project. The kit must match the version of the \tt{nymead} and \tt{libnymea1} built.

        \note: You have to make sure you are using the \underline{same kit} as the nymea daemon and libraries use. If you have installed the
               \underline{nymea library} and \underline{Qt libraries} from you default system package manager, you should probably go with the
               default kit of your distribution.

        \image plugin-template-5.png Kit selection

    \section2 Project Management
        Here you can select your preferred project management tool. If you choose git,
        the default \tt{.gitignore} file will be added to the project.

        \image plugin-template-6.png Project Management

    \section2 Project tree
        Once you finished the plugin wizard, you can start with the development of you plugin.
        \image plugin-template-7.png Project tree

    \section1 Walk trough

        Starting with the new created project you can find following files in you project:

    \section3 template.pro

        This is the generated project files of your plugin. If you need additional qt modules or external libraries in your project
        you can include them normaly using i.e. \tt{QT += network} or \tt{INCLUDEPATH += /path/to/includes} and \tt{LIBS += -lfoo}
        like in any other Qt project.

        \quotefile template/template.pro
        \quotefromfile template/template.pro

        \list

            \li In the first line you can see the gloabl nymea plugin include, where all the nymea plugin related
                configurations and setting for your plugin project get included.
                \printline include(

            \li The next line defines the library file name of your plugin. If you change the plugin name, this line has to be updated to.
                \printline TARGET


             \li The next section is just for debugging the project configuration and showing you the project name and Qt Version you are building with.
                \printuntil message("Building


             \li The \tt{SOURCES} and \tt{HEADERS} section shows the included source code files for your project.
                \printuntil

        \endlist

    \section3 deviceplugintemplate.json

        Here you can find the device plugin interface describing the vendors, devices and plugin information.
        A detailed description of each section can be found in the \l{The plugin JSON File} section.

        \quotefile template/deviceplugintemplate.json

        \quotefromfile template/deviceplugintemplate.json

        In the first section you can find the plugin specific properties. The id will be set to zero and must be changed with an actual uuid.
        The zero uuid is creaed by the plugin template in order to indicate that this field has to be updated.

        \printuntil "vendors"

        In the vendors section you can see the vendor specific properties. There can be multiple vendors defined in one plugin,
        each with its own device classes. The uuid of the vendor guh is known, and therefore already filled out. You have to update
        the vendor uuid, name and id with your plugin information.

        \printuntil "deviceClasses"

        Here you can see the default created deviceclass, showing you the basic structure of a device class.

        \printuntil }


    \section3 deviceplugintemplate.h

    The main header file shows you the basic structure of your DevicePlugin template. The header file start with the license header
    containing the copyright information passed during the wizard.

    \code
        /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
         *                                                                         *
         *  Copyright (C) 2018 Developer Name <developer.name@example.com>         *
         *                                                                         *
         *  This file is part of nymea.                                            *
         *                                                                         *
         *  This library is free software; you can redistribute it and/or          *
         *  modify it under the terms of the GNU Lesser General Public             *
         *  License as published by the Free Software Foundation; either           *
         *  version 2.1 of the License, or (at your option) any later version.     *
         *                                                                         *
         *  This library is distributed in the hope that it will be useful,        *
         *  but WITHOUT ANY WARRANTY; without even the implied warranty of         *
         *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU      *
         *  Lesser General Public License for more details.                        *
         *                                                                         *
         *  You should have received a copy of the GNU Lesser General Public       *
         *  License along with this library; If not, see                           *
         *  <http://www.gnu.org/licenses/>.                                        *
         *                                                                         *
         * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    \endcode

    The main class has the name \tt{DevicePluginExample}. The device plugin class inherts from the DevicePlugin class and must implement
    the pure virtual methods in order build correctly.

    \quotefromfile template/deviceplugintemplate.h
    \skipto DevicePluginExample
    \printuntil };

    \section3 deviceplugintemplate.cpp

    The implementation of each method can be found in the corresponding \tt{cpp} file.

    As you can see, the plugin includes in the cpp file the \tt{plugininfo.h} file, which will be generated during build time
    from the \tt{nymea-plugininfocompiler} tool. This tool translates the \l{deviceplugintemplate.json} into a c++ header file
    containing all uuid definitions, translations strings and the debug catergory definition.

    \quotefromfile template/deviceplugintemplate.cpp
    \skipto #include
    \printline plugininfo

    The main entry point of the plugin is the \l{DevicePlugin::init()}{init()} method. This method will be called from the DeviceManager once all plugins are
    loaded and the initialization phase starts for you all plugins. Here you can start creating your objects in initialize
    whatever you need. This method can be seen like a constructor.
    \skipto init
    \printuntil }


    The \l{DevicePlugin::startMonitoringAutoDevices()}{startMonitoringAutoDevices} method will be called from the DeviceManager once all devices are set
    up and the plugin can start for searching device which appear automatically if your plugin supports such device types.
    \skipto startMonitoringAutoDevices
    \printuntil }

    The \l{DevicePlugin::postSetupDevice()}{postSetupDevice} method will be called from the DeviceManager once the setup of a device has finished successfully.
    Here is a good point to initialize the states of the device.
    \skipto postSetupDevice
    \printuntil }

    The \l{DevicePlugin::deviceRemoved()}{deviceRemoved} method will be called from the DeviceManager once a device is about to be removed from the system.
    Here is a good place to clean up everything related to the device which will be removed.
    \skipto deviceRemoved
    \printuntil }

    When the user wants to add a new device from this plugin, the \l{DevicePlugin::setupDevice()}{setupDevice()} method will be called.
    Here you can initialize Objects and set up everything you need for your device.
    \skipto setupDevice
    \printuntil }

    When the user wants to execute an Action of a Device from this DevicePlugin, the \l{DevicePlugin::executeAction()}{executeAction} method will be called.
    Here you can perform the actual execution of the custom call for your Device.
    \skipto executeAction
    \printuntil }

*/
