/*!
    \page tutorial1.html
    \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}.

*/