mirror of https://github.com/nymea/nymea.git
219 lines
11 KiB
Plaintext
219 lines
11 KiB
Plaintext
/*!
|
|
\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-generateplugininfo} 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 }
|
|
|
|
*/
|