Creating the Plugin Package

Follow this format when creating the plugin package and configuration file so the package can be imported into Rokae+.

Package Structure

The HMI imports a plugin package (zip) that contains data packages:

• client.zip: client plugins
• controller.zip: controller plugins

The plugin package may include both, or only one of them. Client and controller plugins have no mandatory dependency on each other.

To deliver more than one plugin, use either approach:

1. Separate packages: Build a separate plugin package (and its data packages) for each plugin, and import them individually.
2. Combined package: Place multiple plugin directories side by side in the same client.zip or controller.zip, and import once.

The following sections describe both layouts.

1. One Plugin

Single-architecture package with both client and controller:

Package.zip                # plugin package
├── client.zip             # client data package
│   └── MyPlugin/
│       ├── MyPlugin.dll   # Windows: .dll suffix; Linux: .so suffix
│       ├── xplugin.dll    # framework library; Windows: .dll; Linux: .so
│       └── MyPlugin.json  # configuration file
└── controller.zip         # controller data package
    └── MyPlugin/
        ├── MyPlugin.lic   # license file
        ├── MyPlugin.so    # controller binary (.so)
        └── MyPlugin.json  # configuration file

2. Multiple Plugins in One Data Package (Combined)

Place multiple plugin directories side by side in the same client.zip or controller.zip. Each directory holds one plugin and uses the same layout as a single-plugin package. One import installs all plugins in the package.

Example with both MyPlugin and OtherPlugin on client and controller:

Package.zip
├── client.zip
│   ├── MyPlugin/
│   │   ├── MyPlugin.dll      # Windows: .dll suffix; Linux: .so suffix
│   │   ├── xplugin.dll       # framework library; Windows: .dll; Linux: .so
│   │   └── MyPlugin.json     # configuration file
│   └── OtherPlugin/
│       ├── OtherPlugin.dll   # Windows: .dll suffix; Linux: .so suffix
│       ├── xplugin.dll       # framework library; Windows: .dll; Linux: .so
│       └── OtherPlugin.json  # configuration file
└── controller.zip
    ├── MyPlugin/
    │   ├── MyPlugin.lic      # license file
    │   ├── MyPlugin.so       # controller binary (.so)
    │   └── MyPlugin.json     # configuration file
    └── OtherPlugin/
        ├── OtherPlugin.lic   # license file
        ├── OtherPlugin.so    # controller binary (.so)
        └── OtherPlugin.json  # configuration file

If MyPlugin depends on OtherPlugin, declare it in depend (client dependency) or ctrlDepend (controller dependency) in MyPlugin.json, for example "depend": ["OtherPlugin"].

Configuration File

Place MyPlugin.json in the plugin directory. Client configuration example (see the table for field descriptions):

{
    "client_plugin": {
        "name": "MyPlugin",
        "depend": [],
        "ctrlDepend": [],
        "enable": false,
        "version": "3.0.1",
        "min_hmi_version": "3.0.1",
        "custom_hmi_version": [],
        "author": "rokae",
        "description": "description"
    }
}

Optional fields (marked ✗ in the table) may be omitted from the JSON file.

Field	Required	Description
name	✓	Plugin name; naming rules are in Plugin Name Consistency below
depend	✗	Names of other client plugins this plugin depends on; use [] when none
ctrlDepend	✗	Names of controller plugins this plugin depends on
enable	✓	Whether the plugin is enabled by default after import; false in this example
version	✓	Plugin version
min_hmi_version	✗	Minimum supported HMI (xCore) version
custom_hmi_version	✗	Custom compatible version list
author	✗	Author
description	✗	Description

The controller configuration file is also MyPlugin.json in the plugin directory. Field definitions follow the controller plugin specification; file-name and directory-name rules are in Plugin Name Consistency below.

Plugin Name Consistency

The plugin name in each of the following places must be the same string. Examples use MyPlugin; in a combined package, OtherPlugin follows the same rules with OtherPlugin throughout.

1. Project registration
   PLUGIN_NAME in the Qt project and the KEY of XPLUGIN_REGISTER must be MyPlugin.

2. Data-package directory and files
   Paths and base file names for this plugin inside the plugin package must be MyPlugin:

Package.zip
├── client.zip
│   └── MyPlugin/              # deploy directory name = MyPlugin
│       ├── MyPlugin.dll       # user plugin binary base name = MyPlugin (MyPlugin.so on Linux)
│       ├── xplugin.dll
│       └── MyPlugin.json      # configuration file name = MyPlugin
└── controller.zip
    └── MyPlugin/              # deploy directory name = MyPlugin
        ├── MyPlugin.lic       # license file base name = MyPlugin
        ├── MyPlugin.so        # controller binary base name = MyPlugin
        └── MyPlugin.json      # configuration file name = MyPlugin

3. name in the configuration file
   The name field in MyPlugin.json must be "MyPlugin".

4. Dependency declarations (if any)
   Names listed in depend / ctrlDepend must match the dependent plugin’s name in all items above (for example "OtherPlugin" when depending on OtherPlugin).

Quick Generation with Scripts

Scripts provided with this documentation pack prepared client / controller directories into an importable plugin package.

Get the Scripts

Place the following files in the same working directory as the client and controller directories:

File	Description
PluginPackage.bat	Windows packaging script
PluginPackage.sh	Linux packaging script

Prepare the Directory

Use the following layout (client-only or controller-only is allowed). Multiple plugin directories may be placed under client / controller:

Working directory/
├── client/                   # optional
│   ├── MyPlugin/
│   │   ├── MyPlugin.dll      # Windows: .dll suffix; Linux: .so suffix
│   │   ├── xplugin.dll       # framework library; Windows: .dll; Linux: .so
│   │   └── MyPlugin.json     # configuration file
│   └── OtherPlugin/          # optional
│       ├── OtherPlugin.dll   # Windows: .dll suffix; Linux: .so suffix
│       ├── xplugin.dll       # framework library; Windows: .dll; Linux: .so
│       └── OtherPlugin.json  # configuration file
├── controller/               # optional
│   └── MyPlugin/
│       ├── MyPlugin.lic      # license file
│       ├── MyPlugin.so       # controller binary (.so)
│       └── MyPlugin.json     # configuration file
└── PluginPackage.bat         # or PluginPackage.sh

Generation Steps (Windows)

1. Confirm that the working directory contains PluginPackage.bat, and client and/or controller.
2. Double-click PluginPackage.bat.
3. When the console reports completion, a plugin package zip is created in the same directory (default file name is the current folder name; rename if required).
4. Import the zip in plugin management.

Output

Package.zip
├── client.zip      # packed from client/
└── controller.zip  # packed from controller/

• If only client is present, the plugin package contains only client.zip.
• If only controller is present, the plugin package contains only controller.zip.

FAQ

Issue	Action
client / controller not found	Place the script in the same directory as those folders
Multi-architecture not as expected	Architecture directory names must be aarch64 / amd64 / win (controller has no win)

Multi-Architecture Package

Rokae+ supports storing per-architecture data within one plugin package. Under client.zip / controller.zip, create architecture subdirectories first, then place the same plugin directory layout as for a single architecture.

• Client (client.zip): aarch64, amd64, win
• Controller (controller.zip): aarch64, amd64

Package.zip
├── client.zip
│   ├── aarch64
│   │   └── MyPlugin/
│   │       ├── MyPlugin.so
│   │       ├── xplugin.so
│   │       └── MyPlugin.json
│   ├── amd64
│   │   └── MyPlugin/
│   │       ├── MyPlugin.so
│   │       ├── xplugin.so
│   │       └── MyPlugin.json
│   └── win
│       └── MyPlugin/
│           ├── MyPlugin.dll
│           ├── xplugin.dll
│           └── MyPlugin.json
└── controller.zip
    ├── aarch64
    │   └── MyPlugin/
    │       ├── MyPlugin.lic
    │       ├── MyPlugin.so
    │       └── MyPlugin.json
    └── amd64
        └── MyPlugin/
            ├── MyPlugin.lic
            ├── MyPlugin.so
            └── MyPlugin.json

tip

Multi-architecture packages are supported since plugin 1.0.2.6, with xCore v3.2.2 or later.

Next Step

Import the plugin package in the HMI and enable it according to Installation and Usage.