How to start

First you have to get and build entire Yadoms project from sources. You will develop your plugin in the sources/plugins path. You will also find many examples and resources viewing existing plugins code :

• FakePlugin plugin is provided as example, and demonstrates all functionalities related to plugin.
• EmptyPlugin plugin is a skeleton, and can be used to start development of a new plugin.
• If you are looking for easier to read plugins, take a look at MegatecUps or FreeMobileSMS (but use only a few of all available functions).

First create a folder with your plugin name in sources/plugins.

To make a plugin be recognized by Yadoms, these files are required :

• CMakeLists.txt : used to build your plugin
• package.json : provide informations about your plugin to Yadoms. Also provide the configuration schema of your plugin (if it needs a serial port, custom options...)
• changelog.md : contains plugin versions and changes
• icon.png : the visual identity of your plugin

To understand well how a plugin works, you can active developer mode (in yadoms.ini configuration file), to be able to create instances of development dev-xxx plugins (like dev-fakePlugin).

Plugin main principles

A plugin is mainly composed of an infinite loop (implemented in the doWork method). In this loop, plugin code waits for events. Events can be :

• a command from Yadoms
• a configuration update notification from Yadoms
• a stop request (plugin have to finished as soon as possible)
• user custom events like timers, communication events (ie from a serial port...), etc...

Build your plugin

Yadoms and all of its components are using CMake to generate project files. You have to write the CMakeLists.txt file for your plugin. Yadoms build system will parse all plugin folders for the CMakeLists.txt, and call it to build project files. These file contains the list of source files, libraries dependencies, post-build file copies... Some macros are provided so it is easy to write it (see FakePlugin as example).

Dependencies

If your plugin requires dependencies, please read this section. Note that CMake will only generate project files if required dependencies are found on the system. For example, smsDialer plugin requires the Gammu library. If Gammu is not found on your system, smsDialer will not be built (project files are not generated). The reason is that plugins are optional at full Yadoms project build. So in your CMakeLists.txt, you have to condition the project files generation at dependencies availability (See smsDialer plugin for example).

Example of plugin with dependency check :

    include(findGammu.cmake)
    if(GAMMU_FOUND)
       ... The CMakeList.txt normal body is here (list of source files, include directories...) ...
    else()
       message(WARNING "smsDialer plugin is not available. Gammu is Missing")
    endif()

Declare your plugin

To make your plugin usable by Yadoms, you have to provide some information :

• The plugin description (name(*), description, version, author, credits, etc...)
• The supported platforms ([see here for supported values](Plugin supported platforms))
• The configuration schema
• An icon

The file package.json contains the plugin description and configuration schema (see above). The icon is the icon.png file.

(*) Name of plugin should be composed of 2 parts : The organization name/acronym followed by the gateway/device/service name (ex : FreeMobileSMS, LametricTime, SomfySituo...). Keep only one part if both are equals (ex Rfxcom, ZWave, EnOcean) or generic plugin (WebConnectionQuality, Weather, Sigfox...)

Package.json file

The file package.json contains the plugin description and configuration schema (see FakePlugin as example). Let explain all fields :

    {
      "type": "fakePlugin",                       ==> The main plugin name. Should be the same as the plugin folder name. 
      "version": "@PLUGIN_VERSION@",              ==> Current plugin version, filled in changelog.md (don't change version here)
      "author": "yadoms-team",                    ==> You !
      "url": "https://github.com/Yadoms/yadoms/", ==> The URL where we can find your plugin, if you decide to share it.
      "credits": "",                              ==> Enter here all credits information (dependencies...)
      "supportedPlatforms": "all",                ==> Supported platforms
      "dependencies": {                           ==> [Optional] Dependency list
         "yadoms": {
            "minimumVersion": "2.3.0-beta.1"
         }
      },
      "configurationSchema": {                    ==> The configuration schema.
         ...
      }
    }

The credits field supports mardown.

See this page for the configurationSchema section (same as for widgets).

Changelog.md file

Set here the version number, keep historic (descendant) of your plugin changes and describe the change.

Internationalize your plugin

You can add a sub-directory called "locales" to manage labels translations. In these directory, add a file for each supported language. The file must be called by the language-ISO code (2 chars), for example for french : fr.json. This file has the same structure of package.json file, but with only translate-able values ("name" and "description" fields).