diff --git a/doc/api.qdoc b/doc/api.qdoc new file mode 100644 index 00000000..5e0b26e5 --- /dev/null +++ b/doc/api.qdoc @@ -0,0 +1,14 @@ +/*! + \page api.html + \title Overview of guh API's + + The guh server provides two different API's: + \list + \li \l{JSON-RPC API}{JSON-RPC} + \li \l{https://github.com/guh/guh/wiki/REST-Api-documentation}{REST} + \endlist + + + +*/ + diff --git a/doc/config.qdocconf b/doc/config.qdocconf index a6a48592..550715d2 100644 --- a/doc/config.qdocconf +++ b/doc/config.qdocconf @@ -1,6 +1,6 @@ include(html-template.qdocconf) -project = guh +project = guh | documentation description = Gear up your Home! dita.metadata.default.author = Simon Stürz diff --git a/doc/getting-started-plugins.qdoc b/doc/getting-started-plugins.qdoc index 3e79f73e..a36b6362 100644 --- a/doc/getting-started-plugins.qdoc +++ b/doc/getting-started-plugins.qdoc @@ -1,15 +1,46 @@ /*! \page getting-started-plugins.html \title Getting Started + \brief Understanding the basic concept of guh plugins + + Plugins in guh are used to exand the functionalitys and capabilitys of the guh server. A plugin is basically a shared library, which will be loaded dynamically from the guh server during the start up process. Each plugin has a \e name, a \e uuid and a list of supported \e vendors which will be visible in the system once the plugin is loaded. Each of thouse \l{Vendor}{Vendors} contains a list of supported \l{DeviceClass}{DeviceClasses}. A \l{DeviceClass} describes how the supported \l{Device} looks like, how it will be created (\l{DeviceClass::CreateMethod}{CreateMethod}), how the setup (\l{DeviceClass::SetupMethod}{SetupMethod}) looks like and what you can do with the \l{Device}. + + \section1 Devices + A device in guh can represent a real device, a gateway or even a service like weather. When you want to represent you own device / service in guh, you should try to abstract that device and think in terms like: + \list + \li \l{ParamType}{ParamTypes} \unicode{0x2192} A \l{Device} can have \l{Param}{Params}, which will be needed to set up the device (like IP addresses or device configurations) and give information for the user like name or location. The \l{ParamType} represents the description of an actual \l{Param}. + \li \l{StateType}{StateTypes} \unicode{0x2192} A \l{Device} can have \l{State}{States}, which basically represent a value of a \l{Device} like \e {current temperature} or \e ON/OFF. The \l{StateType} represents the description of an actual \l{State}. + \li \l{EventType}{EventTypes} \unicode{0x2192} A \l{Device} can emit \l{Event}{Events}, which basically represent a signal. An example of an \l{Event} could be: \e {Button pressed}. An \l{Event} can have \l{Param}{Params} to give the possibility to pass information with the signal. The \l{EventType} represents the description of an actual \l{Event}. + \li \l{ActionType}{ActionTypes} \unicode{0x2192} A \l{Device} can execute \l{Action}{Actions}, which represent basically a method for the \l{Device} which the user can execute. An example of an \l{Action} could be: \e {Set temperature}. An \l{Action} can have \l{Param}{Params} to give the possibility to parameterize the action. The \l{ActionType} represents the description of an actual \l{Action}. + \endlist + + The \l{DeviceClass} represents the description of an actual \l{Device}. + + \section1 Hardware resources + The \e libguh provides a list of \l{Hardware Resources}{HardwareResources}, which can be used in every plugin. When sou start writing a plugin, you need to know which resource you will need. Each resource provides it's own interface for a \l{DevicePlugin}. In the plugin you don't have to take care about the resource. + + + \section1 Getting started with a plugin In order to show how a plugin ist structured here is an example of the most minimalistic device plugin possible for the guh system. - \chapter Basic structure - The name of the plugin should be clear and inform about the content in one word. In this first minimalistic example the \b is \e "minimal". - The basic structure of the minimal plugin looks like this: + For an easier start we provide a set of plugin templates which can be used for your own plugin and to have a basic for the tutorials described in this documentation. You can get the templates with following command: \code + $ git clone https://github.com/guh/plugin-templates.git + \endcode + + This will create the \tt plugin-templates folder containing all templates and examples you will need to write your own plugin. Let's start with the smallest, simplest plugin. + + \section2 Basic structure + + The name of the plugin should be clear and inform about the content in one word. In this first minimalistic example the \b is \e "minimal". + + The basic structure of the \e minimal plugin looks like this: + + \code + $ cd plugin-templates $ ls -l minimal/ devicepluginminimal.cpp @@ -19,7 +50,7 @@ plugins.pri \endcode - \section2 minimal.pro + \section3 minimal.pro The \tt minimal.pro file is the project file of the plugin, which can be openend with the \tt{Qt Creator}. The name of this file should be the same as the folder name of the project. In this example the name would be \e "minimal". \code @@ -46,7 +77,7 @@ - \section2 plugins.pri + \section3 plugins.pri The \tt plugins.pri file contains all relevant definitions and configuration to build a plugin. Each plugin must contain this file and \underline{should not} be changed. In this file the precompiler \b guh-generateplugininfo will be called. \code TEMPLATE = lib @@ -80,7 +111,7 @@ \endcode - \section2 devicepluginminimal.json + \section3 devicepluginminimal.json The properties of a plugin will be definend with in the \tt JSON file containing all needed information for guh to load it. The name convention fot the json file is: \tt {deviceplugin\b{}.json} @@ -121,7 +152,7 @@ In this minimal example of a device plugin we have one \l{Vendor} ("Minimal vendor") with the VendorId \tt {3897e82e-7c48-4591-9a2f-0f56c55a96a4}, which contains one \l{DeviceClass} with the name "Minimal device". The \l{DeviceClass} has one QString \l{Param} called \e name. - \section2 devicepluginminimal.h + \section3 devicepluginminimal.h The main header file of the plugin. The naming convention is: \tt {deviceplugin\b.h} @@ -154,7 +185,7 @@ As you can see this class has two methods which override the corresponding method in the \l{DevicePlugin} class. These two methods are pure virtual, which meas you \underline{must} implement them. - \section2 devicepluginminimal.cpp + \section3 devicepluginminimal.cpp The implementation of the \l{DevicePlugin}. The naming convention is: \tt {deviceplugin\b.cpp} @@ -181,4 +212,6 @@ } \endcode + You can start with \l{Tutorial 1 - The "Minimal" plugin}. + */ diff --git a/doc/guh.qdoc b/doc/guh.qdoc index c70bf5a8..8b9ec4e4 100644 --- a/doc/guh.qdoc +++ b/doc/guh.qdoc @@ -33,14 +33,14 @@ \li \l{https://github.com/guh/guh/wiki/REST-Api-documentation}{REST} \endlist - \section1 How To's - Here you can find some tutorials for developing and working with the guh: + \section1 Write your own plugin + Here you can find some tutorials for developing and working with guh: \list - \li \l{How to write a plugin} + \li \l{Set up the build environment} \li \l{Getting started} \li \l{The plugin JSON File} - \li \l{Tutorial 1}{Tutorial 1 - The "Minimal" plugin} - \li \l{Tutorial 2}{Tutorial 2 - The "NetworkInfo" plugin} + \li \l{Tutorial 1 - The "Minimal" plugin} + \li \l{Tutorial 2 - The "NetworkInfo" plugin} \endlist \section1 Quicklinks diff --git a/doc/html-styles.qdocconf b/doc/html-styles.qdocconf index 14b29ee9..1208496a 100644 --- a/doc/html-styles.qdocconf +++ b/doc/html-styles.qdocconf @@ -7,11 +7,15 @@ HTML.templatedir = . HTML.stylesheets = style.css HTML.scripts = + +extraimages.HTML = images/logo.png \ + images/favicon.ico \ # Include the style sheets and scripts used. HTML.headerstyles = \ - " \n" + " \n" \ + " \n" HTML.headerscripts = diff --git a/doc/html-template.qdocconf b/doc/html-template.qdocconf index efad46e9..59c2fb64 100644 --- a/doc/html-template.qdocconf +++ b/doc/html-template.qdocconf @@ -8,19 +8,23 @@ HTML.postheader = \ "
\n" \ " \n" \ "
\n" \ "\n" \ "
\n" + HTML.footer = \ "
\n" \ "

\n" \ - " © 2013-2015 ARGE guh. All rights reserved. License" \ + " © 2013-2015 guh. All rights reserved. License" \ "

\n" \ "
\n" \ diff --git a/doc/images/favicon.ico b/doc/images/favicon.ico new file mode 100644 index 00000000..5a95c3e8 Binary files /dev/null and b/doc/images/favicon.ico differ diff --git a/doc/images/guh-cli-devices-print.png b/doc/images/guh-cli-devices-print.png new file mode 100644 index 00000000..3002c2aa Binary files /dev/null and b/doc/images/guh-cli-devices-print.png differ diff --git a/doc/images/guh-cli.png b/doc/images/guh-cli.png new file mode 100644 index 00000000..e677dfa7 Binary files /dev/null and b/doc/images/guh-cli.png differ diff --git a/doc/images/guh-cli_devices_add-device.png b/doc/images/guh-cli_devices_add-device.png new file mode 100644 index 00000000..a6953ee3 Binary files /dev/null and b/doc/images/guh-cli_devices_add-device.png differ diff --git a/doc/images/guh-cli_devices_add-device_minimal-1.png b/doc/images/guh-cli_devices_add-device_minimal-1.png new file mode 100644 index 00000000..3a7a3b9a Binary files /dev/null and b/doc/images/guh-cli_devices_add-device_minimal-1.png differ diff --git a/doc/images/guh-cli_devices_add-device_minimal-2.png b/doc/images/guh-cli_devices_add-device_minimal-2.png new file mode 100644 index 00000000..e35d71f1 Binary files /dev/null and b/doc/images/guh-cli_devices_add-device_minimal-2.png differ diff --git a/doc/images/guh-cli_devices_add-device_minimal-3.png b/doc/images/guh-cli_devices_add-device_minimal-3.png new file mode 100644 index 00000000..b59ee41b Binary files /dev/null and b/doc/images/guh-cli_devices_add-device_minimal-3.png differ diff --git a/doc/images/minimal-deviceclass.png b/doc/images/minimal-deviceclass.png new file mode 100644 index 00000000..a5ff9ecb Binary files /dev/null and b/doc/images/minimal-deviceclass.png differ diff --git a/doc/images/minimal-project-open.png b/doc/images/minimal-project-open.png new file mode 100644 index 00000000..6b0c1368 Binary files /dev/null and b/doc/images/minimal-project-open.png differ diff --git a/doc/plugin-json.qdoc b/doc/plugin-json.qdoc index b1a1ae90..d696819e 100644 --- a/doc/plugin-json.qdoc +++ b/doc/plugin-json.qdoc @@ -15,16 +15,16 @@ Each \l{DevicePlugin}{Plugin} in guh will be defined in the corresponding JSON file. You can find information how to read JSON \l{http://json.org/}{here}. This file will be loaded from the \l{DeviceManager} to define the plugin and the corresponding DeviceClasses internal. - \section1 The \e guh-generateplugininfo precompiler + \section1 The \b {\tt guh-generateplugininfo} precompiler The \tt {\b guh-generateplugininfo} precompiler will parse this file and generates a \tt plugininfo.h and a \tt extern-plugininfo.h file containing the definitions of: \list - \li \l{PluginId}: <\e idName>PluginId -> the defined UUID for the \l{DevicePlugin}. - \li \l{VendorId}: <\e idName>VendorId -> the defined UUID for the corresponding \l{Vendor}. - \li \l{DeviceClassId}: <\e idName>DeviceClassId -> the definend UUID for the corresponding \l{DeviceClass}. - \li \l{ActionTypeId}: <\e idName>ActionTypeId -> the defined UUID for the corresponding \l{ActionType}. - \li \l{StateTypeId}: <\e idName>StateTypeId -> the defidefinednend UUID for the corresponding \l{StateType}. - \li \l{EventTypeId}: <\e idName>EventTypeId -> the defined UUID for the corresponding \l{EventType}. + \li \l{PluginId}: <\e idName>PluginId \unicode{0x2192} the defined UUID for the \l{DevicePlugin}. + \li \l{VendorId}: <\e idName>VendorId \unicode{0x2192} the defined UUID for the corresponding \l{Vendor}. + \li \l{DeviceClassId}: <\e idName>DeviceClassId \unicode{0x2192} the definend UUID for the corresponding \l{DeviceClass}. + \li \l{ActionTypeId}: <\e idName>ActionTypeId \unicode{0x2192} the defined UUID for the corresponding \l{ActionType}. + \li \l{StateTypeId}: <\e idName>StateTypeId \unicode{0x2192} the defidefinednend UUID for the corresponding \l{StateType}. + \li \l{EventTypeId}: <\e idName>EventTypeId \unicode{0x2192} the defined UUID for the corresponding \l{EventType}. \li Logging Category \endlist diff --git a/doc/plugins.qdoc b/doc/plugins.qdoc index 1c6f9b9e..f8336424 100644 --- a/doc/plugins.qdoc +++ b/doc/plugins.qdoc @@ -1,14 +1,16 @@ /*! \page plugins.html \title Plugins + + Here you can find the current list of supported plugins. - \section1 RF 433 MHz Plugins + \section2 RF 433 MHz Plugins \annotatedlist rf433 - \section1 Services + \section2 Services \annotatedlist services - \section1 Network Plugins + \section2 Network Plugins \annotatedlist network diff --git a/doc/setup-environment.qdoc b/doc/setup-environment.qdoc new file mode 100644 index 00000000..e1e84069 --- /dev/null +++ b/doc/setup-environment.qdoc @@ -0,0 +1,68 @@ +/*! + \page build-environment.html + \title Set up the build environment + \brief This tutorial shows you how to set up the build environment for developing guh. + + Assuming you are working on an Ubuntu system here are the steps how to set up the build environment. Basically you can choose your prefered SDK but all tutorials are based on the Qt Creator and we recommand to use that one. You can also use the Ubuntu SDK, which is basically a modified Qt Creator. + + \section2 Install Qt + In the first step you need to install the Qt libraries: + + \code + $ sudo apt-get install qtcreator qt5-default qtbase5-dev python dpkg-dev debhelper hardening-wrapper + \endcode + + \section2 Install guh dependencys + + You can find a good instructions how to install the guh repository on your system here: + + \b {\unicode{0x2192}} \l{https://github.com/guh/guh/wiki/Install}{guh install wiki} + + For example, if you are working on Ubuntu 15.04 Vivid, you can create a source list file and add the guh repository like this: + + \code + $ sudo nano /etc/apt/sources.list.d/guh.list + \endcode + + Copy following 3 lines in the \tt /etc/apt/sources.list.d/guh.list file, save and close it + \code + ## guh repo + deb http://repo.guh.guru vivid main + deb-src http://repo.guh.guru vivid main + \endcode + + Now you need to add the public key of the \e guh-repository to your key list with following command: + + \code + $ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key 6B9376B0 + \endcode + + Update your package lists: + + \code + $ sudo apt-get update + \endcode + + Now you are ready to install the guh packages: + + \code + $ sudo apt-get install guh guh-webinterface guh-cli guh-doc libguh1-dev + \endcode + + \list + \li \underline{\e guh} \unicode{0x2192} the \tt guh package is a meta package and will install the \tt guhd, \tt libguh1 and \tt guh-plugins package so you can start the guh daemon. + \li \underline{\e guh-webinterface} \unicode{0x2192} the \tt guh-webinterface package will install the webinterface for guh, which is accessable on \l{http://localhost:3333}. + \li \underline{\e guh-cli} \unicode{0x2192} the \tt guh-cli package will install the command line interface for the guh JSON-RPC API. You can find more infomation \l{https://github.com/guh/guh/wiki/guh-cli}{here}. + \li \underline{\e guh-doc} \unicode{0x2192} the \tt guh-doc package will install the offline documentation on your system (this homepage). You can access the documentation in your brwoser with \l{file:///usr/share/doc/guh/html/index.html}{file:///usr/share/doc/guh/html/index.html}. + \li \underline{\e libguh1-dev} \unicode{0x2192} the \tt libguh1-dev package brings all development files of guh (header files and lib) which will be needed to write a plugin. + \endlist + + Once you have successfully installed everything you are ready for \l{Getting started}. +*/ + + + + + + + diff --git a/doc/tutorial1.qdoc b/doc/tutorial1.qdoc index 3eb9436c..fca7a7f1 100644 --- a/doc/tutorial1.qdoc +++ b/doc/tutorial1.qdoc @@ -1,8 +1,138 @@ /*! \page tutorial1.html - \title Tutorial 1 + \title Tutorial 1 - The "Minimal" plugin + \brief The smallest and simplest plugin possible + \ingroup tutorials + + This first tutorial shows you how to open, edit, build and load the first plugin. + + \section1 Open + Assuming you already have downloaded the \l{https://github.com/guh/plugin-templates}{plugin-templates} you can open the \tt {plugin-templates \unicode{0x2192} minimal \unicode{0x2192} minimal.pro} file with the Qt Creator. + + \image minimal-project-open.png "Qt Creator" + + Qt will create next to the \tt {plugin-templates \unicode{0x2192} minimal \unicode{0x2192}} folder the build directory (shadow build). + + \section1 Build + In order to compile your first plugin you can press the \b "Build" button in the lower left corner of the \e {Qt Creator} window. You can follow the build process in the \e {Compile Output} window (\tt alt + \tt 4). + + The resulting build directory should look like this: + + \code + ls -l build-minimal-Desktop-Debug/ + + devicepluginminimal.o + extern-plugininfo.h + libguh_devicepluginminimal.so + Makefile + moc_devicepluginminimal.cpp + moc_devicepluginminimal.o + plugininfo.h + \endcode + + As you can see there are two new header files: the \tt plugininfo.h and \tt extern-plugininfo.h . Thouse files were generated by the \tt {\b guh-generateplugininfo} and contain the uuid definitions of from the \tt devicepluginminimal.json file. You can find out more about thouse files in \l{The plugin JSON File} documentation. + + The \b {\tt libguh_devicepluginminimal.so} file is our fresh compiled deviceplugin. + + \section1 Install + + I you have installed guh using the repository (see \l{Set up the build environment}) you will find the installed plugins here: + + \code + /usr/lib/guh/plugins/ + \endcode + + This is the directory where we have to install the \b {\tt libguh_devicepluginminimal.so} file. You have two possibilities to install the new plugin. For bouth methods you need \tt root permissions: + + \list 1 + \li Install using \b {\tt make}: + \code + $ cd build-minimal-Desktop-Debug/ + $ sudo make install + install -m 755 -p "libguh_devicepluginminimal.so" "/usr/lib/guh/plugins/libguh_devicepluginminimal.so" + \endcode + \li Copy the file manually: + \code + $ cd build-minimal-Desktop-Debug/ + $ sudo cp libguh_devicepluginminimal.so /usr/lib/guh/plugins/ + \endcode + \endlist + + Once you have installed the new plugin you can test it. + + \section1 Test + + If order to test the new plugin we need to restart the guh daemon. Please make shore there is only one instance of guh running on your system, otherwise one of the daemons will colide with the ports of the other one. Once you have installed the \b {\tt libguh_devicepluginminimal.so} file you need a clean start of the guh daemon. + + \code + $ guhd -n + \endcode + + If you want to see the debug output of the \b {\tt libguh_devicepluginminimal.so} you can start \tt guhd with the parameter \tt -d : + + \code + $ guhd -n -d Minimal + \endcode + + With this command the debug category will be enabled for this plugin. By default the debug categorie of a plugin is disabled, to keep the STDOUT clean and readable. With the \tt -d parameter of \b {\tt guhd} you can specify which categorie you want to see. The categorie name will be defined in the \tt idName parameter of the plugin object in \l{The Plugin JSON file}. + + Now you can use any guh client application to examin the new plugin and device. Since the application \b {\tt guh-cli} (guh command line interface) was developed for developers, I will show you how this works with the \b {\tt guh-cli}. + + \note You can open two terminal tabs. In the first one you can start \tt guhd with the \tt -n parameter to see the debug output. In the second one you can start \b {\tt guh-cli} to interact with the server and test your plugin. You can find the documentation for \b {\tt guh-cli} \l{https://github.com/guh/guh/wiki/guh-cli}{here}. - + \section2 guh-cli + + The guh command line interface \b {\tt guh-cli} is an admin tool for testing \l{Plugins}, the \l{JSON-RPC API} and core functionalities of guh. It communicates with the guh daemon using the \l{JSON-RPC API} over the \l{guhserver::TcpServer}{TcpServer}. + + \code + $ guh-cli + \endcode + + \section3 Add a new device + + Here is an example how to \e {Add a new device} with \b {\tt guh-cli}. This steps should give you a feeling how the setup process works from the client to the method in the \l{DevicePlugin}. + + \list 1 + \li Open guh-cli and enter the \b "Devices" menue: + \image guh-cli.png "guh-cli" + \li Select the \b {"Add a new device"} menue: + \image guh-cli_devices_add-device.png "Add a new device" + \li Select the \b {"Minimal vendor"} from the \l{Vendor}{Vendors} list. Take a look at \l{The Plugin JSON file} \unicode{0x2192} \l{The Vendor definition} to see where this will be definend. + \image guh-cli_devices_add-device_minimal-1.png "Select vendor" + \li Select the \b {"Minimal device"} from the list of supported devices for this \l{Vendor}. Take a look at \l{The Plugin JSON file} \unicode{0x2192} \l{The DeviceClass definition} to see where this will be definend. + \image guh-cli_devices_add-device_minimal-2.png "Select device" + \li Now enter the \e value for the \l{Param} \e "name" of the \l{DeviceClass} \e {"Minimal device"}. Take a look at \l{The Plugin JSON file} \unicode{0x2192} \l{The ParamType definition} to see where this will be definend. This parameter will be used to set up the new \l{Device}. Once you entered the \e name for the new \l {Device} and pressed \tt enter, the \l{DeviceManager} will call the \l{DevicePlugin::setupDevice()} in the \tt devicepluginminimal.cpp. + + \image guh-cli_devices_add-device_minimal-3.png "Set the parameter \"name\"" + + A new \l{Device} with a new \l{DeviceId} will be created and the passed to the \l{DevicePlugin::setupDevice()} in your plugin. + You can see here the implementation of the code: + \code + DeviceManager::DeviceSetupStatus DevicePluginMinimal::setupDevice(Device *device) + { + Q_UNUSED(device) + qCDebug(dcMinimal) << "Hello word! Setting up a new device:" << device->name(); + qCDebug(dcMinimal) << "The new device has the DeviceId" << device->id().toString(); + qCDebug(dcMinimal) << device->params(); + + return DeviceManager::DeviceSetupStatusSuccess; + } + \endcode + + If you started \b {\tt guhd} with the parameters \b {\tt{-n -d Minimal}} you will see following debug output: + + \code + Connection: Tcp server: new client connected: "127.0.0.1" + Minimal: Hello word! Setting up a new device: "Minimal device" + Minimal: The new device has the DeviceId "{b8d1f5a3-e892-4995-94b1-fa9aef662db2}" + Minimal: ParamList (count:1) + 0: Param(Name: "name", Value:QVariant(QString, "Name of minimal device") ) + + DeviceManager: Device setup complete. + \endcode + \endlist + + Now you can take a look at \l{Tutorial 2 - The "NetworkInfo" plugin}. */ diff --git a/doc/tutorial2.qdoc b/doc/tutorial2.qdoc index 623259ec..0e9a23fa 100644 --- a/doc/tutorial2.qdoc +++ b/doc/tutorial2.qdoc @@ -1,6 +1,259 @@ /*! \page tutorial2.html - \title Tutorial 2 + \title Tutorial 2 - The "NetworkInfo" plugin + \brief The first plugin which actualy does something. + \ingroup tutorials + + + In the second tutorial we make our own first plugin with the name \b {"Network Info"}. We will use this name for the naming concentions of the filenames. + + This plugin will use the \l{NetworkManager} hardware resource to fetch the location and WAN ip of your internet connection from \l{http://ip-api.com/json}. It will have an \l Action called \e "update" which will refresh the \l{State}{States} of the \l{Device}. + +In order to get started with our new \b {"Network Info"} plugin we use the minimal plugin as template and start from there. Make a copy of the minimal folder and name the new folder \b networkinfo-diy. In this case \b{networkinfo-diy} because the folder \b networkinfo already exits from the \tt plugin-template repository. + + \section1 Create the basic structure + \code + $ cp -rv minimal/ networkinfo-diy + ‘minimal/’ -> ‘networkinfo-diy’ + ‘minimal/plugins.pri’ -> ‘networkinfo-diy/plugins.pri’ + ‘minimal/minimal.pro’ -> ‘networkinfo-diy/minimal.pro’ + ‘minimal/devicepluginminimal.json’ -> ‘networkinfo-diy/devicepluginminimal.json’ + ‘minimal/devicepluginminimal.h’ -> ‘networkinfo-diy/devicepluginminimal.h’ + ‘minimal/devicepluginminimal.cpp’ -> ‘networkinfo-diy/devicepluginminimal.cpp’ + \endcode + + \note Delete the minimal.pro.user file if there is any. + + Now we can rename the files using the plugin name convention: + \code + $ cd networkinfo-diy/ + $ mv minimal.pro networkinfo.pro + $ mv devicepluginminimal.h devicepluginnetworkinfo.h + $ mv devicepluginminimal.cpp devicepluginnetworkinfo.cpp + $ mv devicepluginminimal.json devicepluginnetworkinfo.json + \endcode + + \section2 Change the \tt networkinfo.pro + Open the \tt networkinfo.pro file with the \e {Qt Creator} and open that file in the editor: + + \code + include(plugins.pri) + + TARGET = $$qtLibraryTarget(guh_devicepluginminimal) + + message("Building $$deviceplugin$${TARGET}.so") + + SOURCES += \ + devicepluginminimal.cpp \ + + HEADERS += \ + devicepluginminimal.h \ + + \endcode + + \list 1 + \li Change the \tt TARGET name form \tt guh_devicepluginminimal \unicode{0x2192} \tt guh_devicepluginnetworkinfo + \li Change the SOURCES file from \tt devicepluginminimal.cpp \unicode{0x2192} \tt devicepluginnetworkinfo.cpp + \li Change the HEADERS file from \tt devicepluginminimal.h \unicode{0x2192} \tt devicepluginnetworkinfo.h + \endlist + + Your file sould look now like this: + \code + include(plugins.pri) + + TARGET = $$qtLibraryTarget(guh_devicepluginnetworkinfo) + + message("Building $$deviceplugin$${TARGET}.so") + + SOURCES += \ + devicepluginnetworkinfo.cpp \ + + HEADERS += \ + devicepluginnetworkinfo.h \ + \endcode + + If you save the file, the header and source file should appear in the project structure of the \e {Qt Creator}. + + \section2 Change the \tt devicepluginnetworkinfo.h + Open the \tt devicepluginnetworkinfo.h file. + + \code + #ifndef DEVICEPLUGINMINIMAL_H + #define DEVICEPLUGINMINIMAL_H + + #include "plugin/deviceplugin.h" + #include "devicemanager.h" + + class DevicePluginMinimal : public DevicePlugin + { + Q_OBJECT + + Q_PLUGIN_METADATA(IID "guru.guh.DevicePlugin" FILE "devicepluginminimal.json") + Q_INTERFACES(DevicePlugin) + + public: + explicit DevicePluginMinimal(); + + DeviceManager::HardwareResources requiredHardware() const override; + DeviceManager::DeviceSetupStatus setupDevice(Device *device) override; + }; + + #endif // DEVICEPLUGINMINIMAL_H + \endcode + + \list 1 + \li Change the \tt {#ifndef}, \tt {#define} and \tt #define name from \tt DEVICEPLUGINMINIMAL_H \unicode{0x2192} \tt DEVICEPLUGINNETWORKINFO_H + \li Change the class name form \tt DevicePluginMinimal \unicode{0x2192} \tt DevicePluginNetworkInfo + \li Change in the \tt Q_PLUGIN_METADATA line the \tt FILE parameter from \tt "devicepluginminimal.json" \unicode{0x2192} \tt "devicepluginnetworkinfo.json" to set \l{The Plugin JSON file}. + \li Change the constructor name from \tt DevicePluginMinimal \unicode{0x2192} \tt DevicePluginNetworkInfo + \endlist + + Your file sould look now like this: + + \code + #ifndef DEVICEPLUGINNETWORKINFO_H + #define DEVICEPLUGINNETWORKINFO_H + + #include "plugin/deviceplugin.h" + #include "devicemanager.h" + + class DevicePluginNetworkInfo : public DevicePlugin + { + Q_OBJECT + + Q_PLUGIN_METADATA(IID "guru.guh.DevicePlugin" FILE "devicepluginnetworkinfo.json") + Q_INTERFACES(DevicePlugin) + + public: + explicit DevicePluginNetworkInfo(); + + DeviceManager::HardwareResources requiredHardware() const override; + DeviceManager::DeviceSetupStatus setupDevice(Device *device) override; + }; + + #endif // DEVICEPLUGINNETWORKINFO_H + \endcode + + \section2 Change the \tt devicepluginnetworkinfo.cpp + + Open the \tt devicepluginnetworkinfo.h file. + + \code + #include "devicepluginminimal.h" + #include "plugininfo.h" + + DevicePluginMinimal::DevicePluginMinimal() + { + } + + DeviceManager::HardwareResources DevicePluginMinimal::requiredHardware() const + { + return DeviceManager::HardwareResourceNone; + } + + DeviceManager::DeviceSetupStatus DevicePluginMinimal::setupDevice(Device *device) + { + Q_UNUSED(device) + qCDebug(dcMinimal) << "Hello word! Setting up a new device:" << device->name(); + qCDebug(dcMinimal) << "The new device has the DeviceId" << device->id().toString(); + qCDebug(dcMinimal) << device->params(); + + return DeviceManager::DeviceSetupStatusSuccess; + } + \endcode + + \list 1 + \li Change the \tt {#include "devicepluginminimal.h"} \unicode{0x2192} \tt {#include "devicepluginnetworkinfo.h"} + \li Change in each method implementation the \tt DevicePluginMinimal \unicode{0x2192} \tt DevicePluginNetworkInfo namespace. + \endlist + + Your file sould look now like this: + + \code + #include "devicepluginnetworkinfo.h" + #include "plugininfo.h" + + DevicePluginNetworkInfo::DevicePluginNetworkInfo() + { + } + + DeviceManager::HardwareResources DevicePluginNetworkInfo::requiredHardware() const + { + return DeviceManager::HardwareResourceNone; + } + + DeviceManager::DeviceSetupStatus DevicePluginNetworkInfo::setupDevice(Device *device) + { + Q_UNUSED(device) + qCDebug(dcMinimal) << "Hello word! Setting up a new device:" << device->name(); + qCDebug(dcMinimal) << "The new device has the DeviceId" << device->id().toString(); + qCDebug(dcMinimal) << device->params(); + + return DeviceManager::DeviceSetupStatusSuccess; + } + \endcode + + The basic structure of our new \l{DevicePlugin} is finished. You may recognize that the \tt {plugininfo.h} file does not exist yet. You have to build the plugin to generate that file. Each time you change \l{The Plugin JSON file} this file will be new generated. Once the build step is finished, you can take a look at that file (curser in line \tt {#include "plugininfo.h"} and press \tt F2) + + You will see in the build output following section: + \code + /usr/bin/guh-generateplugininfo ../networkinfo-diy/devicepluginnetworkinfo.json plugininfo.h + ../networkinfo-diy/devicepluginnetworkinfo.json -> plugininfo.h + --> generate plugininfo.h + PluginId for plugin "Minimal plugin" = 6878754a-f27d-4007-a4e5-b030b55853f5 + define VendorId MinimalVendorId = 3897e82e-7c48-4591-9a2f-0f56c55a96a4 + define DeviceClassId minimalDeviceClassId = 7014e5f1-5b04-407a-a819-bbebd11fa372 + define logging category: "dcMinimal" + --> generated successfully "plugininfo.h" + --> generate extern-plugininfo.h + --> generated successfully "extern-plugininfo.h" + \endcode + + This shows you how the \tt{plugininfo.h} and \tt{extern-plugininfo.h} will be generated. As you can see the UUID definitions and the logging category will be definend for the \b {Minimal} plugin because we have not changed yet \l{The Plugin JSON file}. + + The generated \tt {plugininfo.h} file will look like this: + \code + #ifndef PLUGININFO_H + #define PLUGININFO_H + #include "typeutils.h" + #include + + // Id definitions + PluginId pluginId = PluginId("6878754a-f27d-4007-a4e5-b030b55853f5"); + VendorId minimalVendorId = VendorId("3897e82e-7c48-4591-9a2f-0f56c55a96a4"); + DeviceClassId minimalDeviceClassId = DeviceClassId("7014e5f1-5b04-407a-a819-bbebd11fa372"); + + // Loging category + Q_DECLARE_LOGGING_CATEGORY(dcMinimal) + Q_LOGGING_CATEGORY(dcMinimal, "Minimal") + + #endif // PLUGININFO_H + \endcode + + The generated \tt {extern-plugininfo.h} file will look like this: + \code + #ifndef EXTERNPLUGININFO_H + #define EXTERNPLUGININFO_H + #include "typeutils.h" + #include + + // Id definitions + extern VendorId minimalVendorId; + extern DeviceClassId minimalDeviceClassId; + + // Logging category definition + Q_DECLARE_LOGGING_CATEGORY(dcMinimal) + + #endif // EXTERNPLUGININFO_H + \endcode + + \section2 Change the \tt devicepluginnetworkinfo.json + + + + + + */ diff --git a/doc/tutorials.qdoc b/doc/tutorials.qdoc new file mode 100644 index 00000000..3bb1e009 --- /dev/null +++ b/doc/tutorials.qdoc @@ -0,0 +1,6 @@ +/*! + \page tutorials.html + \title Tutorials + + \annotatedlist tutorials +*/ diff --git a/doc/write-plugins.qdoc b/doc/write-plugins.qdoc index cfcc7ef1..acd2304c 100644 --- a/doc/write-plugins.qdoc +++ b/doc/write-plugins.qdoc @@ -1,37 +1,16 @@ /*! \page write-plugins.html - \title How to write a plugin - \brief This tutorial shows you how to write a plugin for your own device / service / protocol. + \title Write your own plugin - \chapter Create the build environment - Assuming you are working an an Ubuntu system here are the steps how to set up the build environment. - - - \section2 Install Qt - - - \section2 Install guh dependencys - - \code - $ sudo apt-get install guh libguh1-dev - \endcode - - \code - $ git clone https://github.com/guh/plugin-templates.git - \endcode - - \chapter Tutorials \list + \li \l{Set up the build environment} \li \l{Getting started} \li \l{The plugin JSON File} - \li \l{Tutorial 1}{Tutorial 1 - The "Minimal" plugin} + \li \l{Tutorials} + \list + \li \l{Tutorial 1 - The "Minimal" plugin} + \li \l{Tutorial 2 - The "NetworkInfo" plugin} + \endlist \endlist - */ - - - - - - diff --git a/guh.pro b/guh.pro index 878c8fda..901a037f 100644 --- a/guh.pro +++ b/guh.pro @@ -18,7 +18,7 @@ tests.depends = libguh doc.depends = libguh server doc.commands = cd $$top_srcdir/doc; qdoc config.qdocconf; cp images/logo.png html/images/; \ - cp -r $$top_srcdir/doc/html $$top_builddir/ + cp images/favicon.ico html; cp -r $$top_srcdir/doc/html $$top_builddir/ licensecheck.commands = $$top_srcdir/tests/auto/checklicenseheaders.sh $$top_srcdir diff --git a/server/jsonrpc/actionhandler.cpp b/server/jsonrpc/actionhandler.cpp index e0c1ad70..d1b2e341 100644 --- a/server/jsonrpc/actionhandler.cpp +++ b/server/jsonrpc/actionhandler.cpp @@ -19,6 +19,19 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class guhserver::ActionHandler + \brief This subclass of \l{JsonHandler} processes the JSON requests for the \tt Action namespace. + + \ingroup json + \inmodule core + + This \l{JsonHandler} will be created in the \l{JsonRPCServer} and used to handle JSON-RPC requests + for the \tt {Action} namespace of the API. + + \sa JsonHandler, JsonRPCServer +*/ + #include "actionhandler.h" #include "guhcore.h" diff --git a/server/transportinterface.cpp b/server/transportinterface.cpp index 7e223ed1..013d950c 100644 --- a/server/transportinterface.cpp +++ b/server/transportinterface.cpp @@ -35,7 +35,7 @@ */ /*! \fn void guhserver::TransportInterface::clientDisconnected(const QUuid &clientId); - This signal is emitted when a new client with the given \a clientId has been connected. + This signal is emitted when a new client with the given \a clientId has been disconnected. \sa WebSocketServer, TcpServer */