.. Writing and Using Plugins describes how to implement a plugin for FogLAMP and how to use it
.. https://docs.google.com/document/d/1IKGXLWbyN6a7vx8UO3uDbq5Df0VvE4oCQIULgZVZbjM

.. Links
.. |these INSTALLATION| raw:: html

   <a href="../building_foglamp/04_installation.html">these</a>

.. |Getting Started| raw:: html

   <a href="../building_foglamp/building_foglamp.html">here</a>

.. Links in new tabs

.. |foglamp DHT| raw:: html

   <a href="https://github.com/foglamp/foglamp-south-dht" target="_blank">https://github.com/foglamp/foglamp-south-dht</a>
   <br />



A South Plugin Example In C/C++: the DHT11 Sensor
-------------------------------------------------

Using the same example as before, the DHT11 temperature and humidity sensor, let's look at how to create the plugin in C/C++.

The Software
~~~~~~~~~~~~

For this plugin we use the wiringpi C library to connect to the hardware of the Raspberry Pi

.. code-block:: console
 
  $ sudo apt-get install wiringpi
  Reading package lists... Done
  Building dependency tree
  Reading state information... Done
  The following NEW packages will be installed:
  wiringpi
  ...
  $


The Plugin
~~~~~~~~~~

This is the code for the plugin.cpp file that provides the plugin API:

.. code-block:: C

  /*
   * FogLAMP south plugin.
   *
   * Copyright (c) 2018 OSisoft, LLC
   *
   * Released under the Apache 2.0 Licence
   *
   * Author: Amandeep Singh Arora
   */
  #include <dht11.h>
  #include <plugin_api.h>
  #include <stdio.h>
  #include <stdlib.h>
  #include <strings.h>
  #include <string>
  #include <logger.h>
  #include <plugin_exception.h>
  #include <config_category.h>
  #include <rapidjson/document.h>
  #include <version.h>

  using namespace std;
  #define PLUGIN_NAME "dht11_V2"

  /**
   * Default configuration
   */
  const static char *default_config = QUOTE({
                  "plugin" : { 
                          "description" : "DHT11 C south plugin",
                          "type" : "string",
                          "default" : PLUGIN_NAME,
                          "readonly": "true"
                          },
                  "asset" : {
                          "description" : "Asset name",
                          "type" : "string",
                          "default" : "dht11",
                          "order": "1",
                          "displayName": "Asset Name",
                          "mandatory" : "true"
                          },
                  "pin" : {
                          "description" : "Rpi pin to which DHT11 is attached",
                          "type" : "integer",
                          "default" : "7",
                          "displayName": "Rpi Pin"
                          }
                  });


  /**
   * The DHT11 plugin interface
   */
  extern "C" {

  /**
   * The plugin information structure
   */
  static PLUGIN_INFORMATION info = {
          PLUGIN_NAME,              // Name
          VERSION,                  // Version
          0,                        // Flags
          PLUGIN_TYPE_SOUTH,        // Type
          "1.0.0",                  // Interface version
          default_config            // Default configuration
  };

  /**
   * Return the information about this plugin
   */
  PLUGIN_INFORMATION *plugin_info()
  {
          return &info;
  }

  /**
   * Initialise the plugin, called to get the plugin handle
   */
  PLUGIN_HANDLE plugin_init(ConfigCategory *config)
  {
          unsigned int pin;

          if (config->itemExists("pin"))
          {
                  pin = stoul(config->getValue("pin"), nullptr, 0);
          }

          DHT11 *dht11= new DHT11(pin);

          if (config->itemExists("asset"))
                  dht11->setAssetName(config->getValue("asset"));
          else
                  dht11->setAssetName("dht11");

          Logger::getLogger()->info("m_assetName set to %s", dht11->getAssetName());

          return (PLUGIN_HANDLE)dht11;
  }

  /**
   * Poll for a plugin reading
   */
  Reading plugin_poll(PLUGIN_HANDLE *handle)
  {
          DHT11 *dht11 = (DHT11*)handle;
          return dht11->takeReading();
  }

  /**
   * Reconfigure the plugin
   */
  void plugin_reconfigure(PLUGIN_HANDLE *handle, string& newConfig)
  {
  ConfigCategory	conf("dht", newConfig);
  DHT11 *dht11 = (DHT11*)*handle;

          if (conf.itemExists("asset"))
                  dht11->setAssetName(conf.getValue("asset"));
          if (conf.itemExists("pin"))
          {
                  unsigned int pin = stoul(conf.getValue("pin"), nullptr, 0);
                  dht11->setPin(pin);
          }
  }

  /**
   * Shutdown the plugin
   */
  void plugin_shutdown(PLUGIN_HANDLE *handle)
  {
          DHT11 *dht11 = (DHT11*)handle;
          delete dht11;
  }
  };

The full source code, including the *DHT11* class can be found in GitHub |foglamp DHT|

Building FogLAMP and Adding the Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have not built FogLAMP yet, follow the steps described |Getting Started|. After the build, you can optionally install FogLAMP following |these INSTALLATION| steps.


- Clone the *foglamp-south-dht* repository

.. code-block:: console

  $ git clone https://github.com/foglamp/foglamp-south-dht.git
  ...
  $

- Set the environment variable FOGLAMP_ROOT to the directory in which you built FogLAMP

.. code-block:: console

  $ export FOGLAMP_ROOT=~/foglamp
  $

- Go to the location in which you cloned the foglamp-south-dht repository and create a build directory and run cmake in that directory

.. code-block:: console

  $ cd ~/foglamp-south-dht
  $ mkdir build
  $ cd build
  $ cmake ..
  ...
  $

- Now make the plugin

.. code-block:: console

  $ make
  $

- If you have started FogLAMP from the build directory, copy the plugin into the destination directory

.. code-block:: console

  $ mkdir -p $FOGLAMP_ROOT/plugins/south/dht
  $ cp libdht.so $FOGLAMP_ROOT/plugins/south/dht
  $

- If you have installed FogLAMP by executing ``sudo make install``, copy the plugin into the destination directory

.. code-block:: console

  $ sudo mkdir -p /usr/local/foglamp/plugins/south/dht
  $ sudo cp libdht.so /usr/local/foglamp/plugins/south/dht
  $

.. note:: If you have installed FogLAMP using an alternative *DESTDIR*, remember to add the path to the destination directory to the ``cp`` command.


- Add service

.. code-block:: console

   $ curl -sX POST http://localhost:8081/foglamp/service -d '{"name": "dht", "type": "south", "plugin": "dht", "enabled": true}'

You may now use the C/C++ plugin in exactly the same way as you used a Python plugin earlier.
