nymea/doc/tutorial1.qdoc

/*!
    \page tutorial1.html
    \title Tutorial 1 - The "Minimal" plugin
    \brief This tutorial shows you how to open, edit, build and load the first plugin.
    \ingroup tutorials
    \contentspage {Tutorials}

    \section1 Topics
    This first tutorial shows you how to:
    \list
        \li \unicode{0x25B6} Open and edit the project
        \li \unicode{0x25B6} Build and load the first plugin.
    \endlist

    \section1 Open the project
    Assuming you already have downloaded the \l{https://github.com/guh/nymea-plugin-template}{nymea-plugin-template} you can open the \tt {plugin-template \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 the plugin
    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
    libnymea_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 nymea-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 libnymea_devicepluginminimal.so} file is our fresh compiled deviceplugin. 
    
    \section1 Install the plugin
        
    I you have installed nymea using the repository (see \l{Set up the build environment}) you will find the installed plugins here:

    \code
    /usr/lib/nymea/plugins/
    \endcode

    This is the directory where we have to install the \b {\tt libnymea_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 "libnymea_devicepluginminimal.so" "/usr/lib/nymea/plugins/libnymea_devicepluginminimal.so" 
            \endcode
        \li Copy the file manually:
            \code
                $ cd build-minimal-Desktop-Debug/
                $ sudo cp libnymea_devicepluginminimal.so /usr/lib/nymea/plugins/
            \endcode
    \endlist

    Once you have installed the new plugin you can test it.

    \section1 Test the plugin

    If order to test the new plugin we need to restart the nymea daemon. Please make shore there is only one instance of nymea 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 libnymea_devicepluginminimal.so} file you need a clean start of the nymea daemon. 

    \code
    $ nymead -n
    \endcode

    If you want to see the debug output of the \b {\tt libnymea_devicepluginminimal.so} you can start \tt nymead with the parameter \tt -d :

    \code
    $ nymead -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 nymead} 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 nymea client application to examin the new plugin and device. Since the application \b {\tt nymea-cli} (nymea command line interface) was developed for developers, I will show you how this works with the \b {\tt nymea-cli}.

    \note You can open two terminal tabs. In the first one you can start \tt nymead with the \tt -n parameter to see the debug output. In the second one you can start \b {\tt nymea-cli} to interact with the server and test your plugin. You can find the documentation for \b {\tt nymea-cli} \l{https://github.com/guh/nymea/wiki/guh-cli}{here}.    

    
    \section2 nymea-cli

    The nymea command line interface \b {\tt nymea-cli} is an admin tool for testing \l{Plugins}, the \l{JSON-RPC API} and core functionalities of nymea. It communicates with the nymea daemon using the \l{JSON-RPC API} over the \l{nymeaserver::TcpServer}{TcpServer}.

    \code
    $ nymea-cli
    \endcode

    \section3 Add a new device
    
    Here is an example how to \e {Add a new device} with \b {\tt nymea-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 nymea-cli and enter the \b "Devices" menue:
            \image nymea-cli.png "nymea-cli"
        \li Select the \b {"Add a new device"} menue:
            \image nymea-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 nymea-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 nymea-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 nymea-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 nymead} 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 "Buttons" plugin}.
*/