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.
• 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...)
• 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.

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": "0.1",                           ==> Current plugin version
      "releaseType": "beta",                      ==> The current release type. Can be "beta", "testing", "stable". Note that users can filter for updates with this parameter (can choose to use only stable releases for example).
      "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
      "configurationSchema": {                    ==> The configuration schema.
         ...
      }
    }

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

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).