Controller Plugin

Controller Plugin Loading Principle

The Controller Plugin is used to load user-defined functionality into the controller without modifying the main controller program. A plugin is essentially a dynamic library file that conforms to a defined interface; in a Linux controller environment it is typically a .so file.

When the controller starts or refreshes plugins, it scans the plugin directory and reads plugin name, version, dependencies, enable status, and controller version constraints from the .json descriptor in each plugin package. After validation passes, the controller loads the corresponding dynamic library and calls the registration function exported according to the interface specification. In the registration function, the plugin registers its features, commands, callbacks, or extensions with the controller framework, after which the controller can dispatch plugin functionality like internal modules.

A typical loading flow is as follows:

1. The controller reads the plugin package and validates that json, lic, and so files are complete and consistently named.
2. The controller checks the license file, plugin enable status, dependent plugins, and controller version constraints.
3. The controller loads the plugin dynamic library and locates the agreed export function.
4. The controller runs the plugin registration function; the plugin registers its feature interfaces with the controller.
5. After successful registration, plugin functionality runs with the controller and can be invoked by tasks, scripts, or internal controller flows.

Therefore, Controller Plugin development must satisfy the dynamic library interface specification, plugin package structure specification, and target controller runtime environment requirements.

Controller Plugin Structure

A Controller Plugin package mainly contains three files: plugin .so, plugin .lic, and plugin .json.

Taking a plugin package that contains only one Controller Plugin as an example:

controller.zip  
      └──example  
            ├──example.lic
            ├──example.so  
            └──example.json

controller.zip can contain multiple Controller Plugins. For each Controller Plugin, the file names for json, lic, and so must be consistent. The so and json files are generated by the user; the lic file is generated by Rokae.

The so dynamic library is built by the user from the provided API and build environment. The json file is filled in by the user. Field meanings are as follows:

{
    "controller_plugin":{// Describes a Controller Plugin
        "example":{// Plugin name
            "name": "example",// Plugin name, must be consistent
            "depend":["plugin1","plugin2"],// Dependent plugins
            "enable":true,// Whether enabled; disabled plugins are not loaded
            "min_controller_version":"3.0.2",// Minimum controller version required to run this plugin
            "must_controller_version":[],// This plugin runs only on these controller versions; overrides minimum version
            "version": "1.0.0",// User-defined plugin version; recommended to include the API version used
            "author": "rokae",// Plugin author
            "description": "description info"// Plugin description
        }
    }
}

When loading a Controller Plugin, the package format is validated first. Packages that do not conform to the rules above are not loaded.

Build and Runtime Environment

Development Language

Controller Plugins are developed in C++; C++11 is recommended. Development should be based on the Controller Plugin API, headers, and sample project provided by Rokae. The dynamic library must implement the export functions and registration logic required by the interface specification.

Build Environment

Plugin dynamic libraries must be built in an environment compatible with the target controller.

Target Platform	Recommended OS	Compiler	Output
x86_64	Ubuntu 20.04	gcc-5.4/g++-5.4	PluginName.so
aarch64	Ubuntu 20.04	gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu	PluginName.so

Notes when building:

1. The dynamic library name must match the plugin directory name, license file name, and plugin name in json.
2. The build architecture must match the target controller; for example, an aarch64 controller requires the aarch64 cross-compilation toolchain.
3. Third-party dynamic libraries used by the plugin must match the target platform architecture and be deployed correctly with the plugin or controller environment.
4. It is recommended to reflect the plugin API version or compatible controller version in the plugin version number for easier maintenance.
5. If the plugin uses controller-version-specific interfaces, declare version constraints in min_controller_version or must_controller_version.

Runtime Environment

When the controller runs plugins, the following conditions must be met:

1. The plugin package structure meets requirements: plugin directory, .so, .lic, and .json in controller.zip must use consistent naming.
2. The .lic license file is valid and matches the plugin and controller authorization information.
3. The target controller version satisfies the version requirements declared in the plugin json.
4. Other Controller Plugins that this plugin depends on already exist and are declared correctly in the depend field.
5. Runtime libraries required by the plugin dynamic library can be loaded by the controller process.

If plugin loading fails, first check the plugin package structure, dynamic library architecture, controller version, license file, and whether dependencies meet requirements.

Rokae provides a virtual machine development environment for building, debugging, and running the controller. To obtain VM images, plugin API, sample projects, or toolchains, contact Rokae for the corresponding materials and workflow.