The plugin JSON File

Each Plugin in nymea will be defined in the corresponding JSON file. You can find information how to read JSON here. This file will be loaded from the DeviceManager to define the plugin and the corresponding DeviceClasses internal.

The nymea-generateplugininfo precompiler

The nymea-generateplugininfo precompiler will parse this file and generates a plugininfo.h and a extern-plugininfo.h file containing the definitions of:

• PluginId: <pluginId → the defined UUID for the DevicePlugin.
• VendorId: <name>VendorId → the defined UUID for the corresponding Vendor.
• DeviceClassId: <name>DeviceClassId → the definend UUID for the corresponding DeviceClass.
• ActionTypeId: <name>ActionTypeId → the defined UUID for the corresponding ActionType.
• StateTypeId: <name>StateTypeId → the defidefinednend UUID for the corresponding StateType.
• EventTypeId: <name>EventTypeId → the defined UUID for the corresponding EventType.
• ParamTypeId: <name>ParamTypeId → the defined UUID for the corresponding ParamType.
• Logging Category: dc<Name>

The plugininfo.h has to be included in the main plugin cpp file (deviceplugin<pluginName>.cpp). The extern-plugininfo.h can be included in other classes/files of the plugin to get the extern definitions of the ID's and the logging category.

Basic structure

The name convention fot the plugin json file is:

deviceplugin<pluginName>.json

The basic structure of a plugin looks like this:

{
    "name": "PluginName",
    "displayName": "Name of the plugin",
    "id": "uuid",
    "vendors": [
        {
            "name": "VendorName",
            "displayName": "Name of the vendor",
            "id": "uuid",
            "deviceClasses": [
                ...
            ]
        }

    ]
}

Warning: For each new object which has an "uuid" value, you need to generate a new UUID. The easyest way to do this is using the command uuidgen:

$ sudo apt-get install uuid-runtime

$ uuidgen
cd938452-213d-432f-ae7a-3ef3c474fe99

Writing the plugin JSON file

The Plugin definition

The parameters of the first object (name, displayName, id and vendors) describe the properties of the plugin it self.

{
    "id": "uuid",
    "name": "PluginName",
    "displayName": "Name of the plugin (translatable)",
    "o:paramTypes": [
        ...
    ],
    "vendors": [
        {
            ...
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.

            qCDebug(dcExample()) << "Hello world!";
            qCWarning(dcExample()) << "Warning the world!";

The Vendor definition

A plugin can support more then one Vendor, so the parameter vendors in the plugin definition is a list. Each element of this list represents a Vendor in nymea.

}
    ...
    "vendors": [
        {
            "id": "uuid",
            "name": "vendorName",
            "displayName": "Name of the vendor (translatable)",
            "deviceClasses": [
                ...
            ]
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.

The DeviceClass definition

A Vendor can support more then one DeviceClass, so the parameter deviceClasses in the vendor definition is a list. Each element of this list represents a DeviceClass in nymea.

}
    ...
    "vendors": [
        {
            ..
            "deviceClasses": [
                {
                    "id": "uuid",
                    "name": "deviceClassName",
                    "displayName": "The name of the device class (translatable)",
                    "o:createMethods": [ ],
                    "o:setupMethod": "SetupMethod",
                    "o:deviceIcon": "Icon",
                    "o:interfaces": [ "interfacename" ],
                    "o:basicTags": [ ],
                    "o:pairingInfo": "Information how to pair the device. (translatable)",
                    "o:criticalStateTypeId": "uuid",
                    "o:primaryStateTypeId": "uuid",
                    "o:primaryActionTypeId": "uuid",
                    "o:discoveryParamTypes": [ ],
                    "o:paramTypes": [ ],
                    "o:stateTypes": [ ],
                    "o:actionTypes": [ ],
                    "o:eventTypes": [ ]
                }
            ]
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.

The ParamType definition

A DeviceClass can have a list of ParamTypes which will be filled in during the setup and describe the device. Each device should have a parameter "name" to allow the user to give a device an individual name like: "Desk lamp in the living room". ParamTypes will be used for discoveryParamType in the DeviceClass definition and in the ActionType and EventType definition.

}
    ...
    "paramTypes": [
        {
            "id": "uuid",
            "name": "paramName"
            "displayName": "name of the param (translatable)",
            "type": "DataType",
            "defaultValue": "The default value which will be used if the param is not given.",
            "o:inputType": "InputType",
            "o:unit": "The unit of the parameter",
            "o:minValue": "numeric minimum value for this parameter",
            "o:maxValue": "numeric maximum value for this parameter",
            "o:allowedValues": [
                "value"
            ],
            "o:readOnly": "bool"
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.

The StateType definition

A DeviceClass can have a list of StateTypes which allow you to represent a state of a device. A State can be changed/updated in the plugin code. If you change a state in the plugin using Device::setStateValue() an Event will generate automatically in the nymeaserver::NymeaCore. This Event has the same uuid (EventTypeId) like the State which created the "<stateName> changed" Event. The event will have exactly one Param, which has the same properties like the StateType value and contains the new value.

A StateType has following parameters:

}
    ...
    "stateTypes": [
        {
            "id": "uuid",
            "name": "stateName",
            "displayName": "Name of the state (translatable)",
            "displayNameEvent": "Name of the created EventType (translatable)",
            "type": "DataType",
            "defaultValue": "The state will be initialized with this value."
            "o:cached": "bool",
            "o:ruleRelevant": "bool",
            "o:eventRuleRelevant": "bool",
            "o:graphRelevant": "bool",
            "o:unit": "The unit of the state value.",
            "o:minValue": "Numeric minimum value for this state.",
            "o:maxValue": "Numeric maximum value for this state.",
            "o:possibleValues": [ ],
            "o:writable": true,
            "o:displayNameAction": "Name of the created ActionType (translatable)"
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.

If a StateType has the property writable the DeviceManager will create automatically an ActionType for this state, which will also have exactly one ParamType with the same properties like the StateType. The created ActionType has the same uuid (ActionTypeId) like the StateType uuid and will be named actionTypeName.

This mechanism was created to ensure that the EventType and ActionType which correspond to a certain StateType will always be equal. This makes it possible for clients to know that an Action will set the value of a State, and an Event was generated by the corresponding State.

StateTypeId == EventTypeId == ActionTypeId

The ParamType for the created EventType will have the same id. In the code, the ParamTypeId will be named: <stateName>StateParamTypeId.

Example StateType: Following StateType stands for a volume State named volume. The value of this State has the data type int and the unit %. This StateType is writable, which means there will be an ActionType generated with id 9bc84381-785f-46bf-94c8-6e35116f50d3. The generated ActionType will have one ParamType which has the id = 9bc84381-785f-46bf-94c8-6e35116f50d3, name = volume, type = int, minValue = 0, maxValue =100, unit = Percentage. The ActionType name will be . If the value of the State will be changed, an Event will be generated. The ParamType of the event will be equal to the ParamType of the generated ActionType.

{
    "id": "{9bc84381-785f-46bf-94c8-6e35116f50d3}",
    "name": "volume",
    "displayName": "Volume",
    "unit": "Percentage",
    "type": "int",
    "minValue": 0,
    "maxValue": 100,
    "writable": true,
    "displayNameAction": "Set volume",
    "displayNameEvent": "Volume changed"
}

This StateType definition will create for you an ActionType looking like this:

{
    "id": "{9dfe5d78-4c3f-497c-bab1-bb9fdf7e93a9}",
    "displayName": "Set volume",
    "paramTypes": [
        {
            "id": "{9bc84381-785f-46bf-94c8-6e35116f50d3}",
            "displayName": "Volume",
            "type": "int",
            "maxValue": 100,
            "minValue": 0,
            "unit": "Percentage"
        }
    ]
}

And an EventType looking like this:

{
    "id": "{9dfe5d78-4c3f-497c-bab1-bb9fdf7e93a9}",
    "displayName": "Volume changed",
    "paramTypes": [
        {
            "id": "{9bc84381-785f-46bf-94c8-6e35116f50d3}",
            "displayName": "Volume",
            "type": "int",
            "maxValue": 100,
            "minValue": 0,
            "unit": "Percentage"
        }
    ]
}

The ActionType definition

A DeviceClass can have more then one ActionType, so the parameter actionTypes in the DeviceClass definition is a list. Each element of this list represents an ActionType in nymea.

}
    ...
    "actionTypes": [
        {
            "id": "uuid",
            "name": "actionName",
            "displayName": "Name of the action (translatable)",
            "o:paramTypes": [
                ...
            ]
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.

The EventType definition

A DeviceClass can have more then one EventType, so the parameter eventTypes in the DeviceClass definition is a list. Each element of this list represents an EventType in nymea.

}
    ...
    "eventTypes": [
        {
            "id": "uuid",
            "name": "eventName",
            "displayName": "Name of the event (translatable)",
            "o:ruleRelevant": "bool",
            "o:graphRelevant": "bool",
            "o:paramTypes": [
                ...
            ]
        }
    ]
}

Note: M is a mandatory parameter, O is an optional parameter.