From 47c0f46c7b9aaa408dd8857084bca3bf9ea03d02 Mon Sep 17 00:00:00 2001 From: Michael Zanetti Date: Thu, 25 Jul 2019 10:44:33 +0200 Subject: [PATCH] Some updates to the "Write plugins" documentation. --- doc/getting-started-plugins.qdoc | 16 ++++++++++------ doc/setup-environment.qdoc | 29 +++++++++++++++++++---------- doc/write-plugins.qdoc | 5 +++-- 3 files changed, 32 insertions(+), 18 deletions(-) diff --git a/doc/getting-started-plugins.qdoc b/doc/getting-started-plugins.qdoc index 1223a1a8..2ec82596 100644 --- a/doc/getting-started-plugins.qdoc +++ b/doc/getting-started-plugins.qdoc @@ -3,21 +3,25 @@ \title Getting Started \brief Understanding the basic concept of nymea plugins - Plugins in nymea are used to expand the functionalitys and capabilitys of the nymea server. A plugin is basically a shared library, - which will be loaded dynamically from the nymea 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 + Plugins in nymea are used to expand the functionality and capabilities of the nymea server. A plugin is basically a shared library, + which will be loaded dynamically by the nymea 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 those \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 nymea can represent a real device, a gateway or even a service like weather. When you want to represent you own device / service in nymea, - you should try to abstract that device and think in terms like: + A device in nymea can represent a real device, a gateway or a online service (for example a weather service API). When you want to add support for + your own device / service in nymea, 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 identification) and give information needed for setup and load a device. The \l{ParamType} represents - the description of an actual \l{Param}. + the description of an actual \l{Param}. Params will be set when a device is configured initially and can only be changed by + a complete reconfiguration of the given device. + \li \l{ParamType}{SettingsTypes} \unicode{0x2192} A \l{Device} can have settings. They are like params, with the exception that the + user (and also the plugin developer) can change them at runtime. Settings should be used to change the behabior of a device at runtime. + An example would the the refresh interval when polling a web server. \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. diff --git a/doc/setup-environment.qdoc b/doc/setup-environment.qdoc index 54c9fbea..9625604c 100644 --- a/doc/setup-environment.qdoc +++ b/doc/setup-environment.qdoc @@ -3,23 +3,32 @@ \title Set up the build environment \brief This tutorial shows you how to set up the build environment for developing with nymea. - Assuming you are working on an Ubuntu system here are the steps how to set up the build environment. Basically you - can choose your preferred SDK but all tutorials are based on the Qt Creator and we recommend to use that one. + This documentation assumes you are working on a Debian or Ubuntu system. The recommended IDE to use is QtCreator. + Other Linux distributions should work too, however at this point, nymea only ships packages for Debian and Ubuntu so + libnymea needs to be build from code if you prefer to use a different linux distribution. - \note Please take care that you are using the Qt version from the system for building. The nymea server will always be - built with the official Qt version for the appropriate system version. The plugin \underline{must} have the same - version like the nymea server. - \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 + $ sudo apt-get install qtcreator qt5-default qtbase5-dev python dpkg-dev debhelper \endcode - \section2 Install nymea dependencys + \section2 Install nymea dependencies - You can find a good instructions how to install the nymea repository on your system here: + For that we add the nymea repository by first importing the signing key for the repository. + + \code + sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key A1A19ED6 + \endcode + + Now add the repository to the system. + + \code + sudo apt-add-repositry "deb http://repository.nymea.io `lsb_release -cs` main" + \endcode + + More detailed instructions on how to install the nymea repository can be found here: \b {\unicode{0x2192}} \l{https://nymea.io/en/wiki/nymea/master/install}{nymea install wiki} @@ -32,7 +41,7 @@ Now you are ready to install the nymea packages: \code - $ sudo apt-get install nymea nymea-cli nymea-doc libnymea1-dev nymea-qtcreator-wizards + $ sudo apt-get install nymea nymea-doc libnymea1-dev nymea-dev-tools nymea-qtcreator-wizards \endcode Once you have successfully installed everything you are ready for \l{Getting started}. diff --git a/doc/write-plugins.qdoc b/doc/write-plugins.qdoc index 648af40d..b22420e3 100644 --- a/doc/write-plugins.qdoc +++ b/doc/write-plugins.qdoc @@ -10,11 +10,12 @@ about the client management and any other functionality which should make the development straight forward and you can concentrate on your plugin and the content is should cover. - If you are a beginner, and want to start from scratch with the plugin development check out the \l{Plugin tutorials} and - start with the very first tutotial. + If you are a beginner and want to start from scratch with the plugin development, check out the \l{Plugin tutorials}. If you need to interact with a HardwareResource, you can check out the \l{Hardware Resources} documentation. + Additional help can be found at the \l {https://forum.nymea.io} {nymea forum}. + \section1 Overview \list