• The plugin JSON File
  • 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:

    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.

    idMuuidThe actual uuid (PluginId) of the plugin → DevicePlugin::pluginId()
    nameMstringThis parameter will be used to define the PluginId variable named pluginId in the plugininfo.h, so it can be used in the code. This parameter also defines the logging categorie for this plugin. The logging category will always definend as dc<Name> and can be used as follows ("name":"Example"):
                qCDebug(dcExample()) << "Hello world!";
                qCWarning(dcExample()) << "Warning the world!";

    The logging category allows you to categorise the debug output. It can be configured with the -d argument of nymead (see $ nymead -h).

    displayNameMstringThe visible name of the plugin → DevicePlugin::pluginDisplayName(). This string will be available for translations.
    paramTypesOarrayA list of ParamTypes which define the parameters of this plugin → DevicePlugin::configuration().

    See also: The ParamType definition

    vendorsMarrayThe list of Vendors objects this plugin supports.

    See also: The Vendor definition

    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.

    idMuuidThe actual uuid (VendorId) of the vendor → Vendor::id().
    nameMstringThis parameter will be used to define the VendorId variable named <name>VendorId in the plugininfo.h, so it can be used in the code.
    displayNameMstringThe visible name of the vendor → Vendor::displayName(). This string will be available for translations.
    deviceClassesMarrayA list of DeviceClasses objects.

    See also: The DeviceClass definition

    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.

    idMuuidThe actual uuid (DeviceClassId) of the DeviceClassDeviceClass::id().
    nameMstringThis parameter will be used to define the DeviceClassId variable named <name>DeviceClassId in the plugininfo.h, so it can be used in the code.
    displayNameMstringThe visible name of the DeviceClassDeviceClass::displayName(). This string will be available for translations.
    interfacesOarrayA string list of interfaces this plugin implements. Interfaces show you how types of this DeviceClass must look like.
    basicTagsOarrayA string list of BasicTags for this device → DeviceClass::basicTags(). A DeviceClass can have multiple BasicTags which describe the basic category of the DeviceClass. A DeviceClass should be eighter a Service or a Device, never both. See enum DeviceClass::BasicTag for more information. The expected value for the basicTags parameters matches the enum name like this:

    DeviceClass::BasicTagService"basicTags": [ "Service" ]

    DeviceClass::BasicTagLighting"basicTags": [ "Lighting" ]

    ...

    deviceIconOstringDefines the icon for this DeviceClass. See enum DeviceClass::DeviceIcon for more information. The expected value for the deviceIcon parameters matches the enum name like this:

    DeviceClass::DeviceIconBed"deviceIcon": "Bed"

    DeviceClass::DeviceIconPower"deviceIcon": "Power"

    ...

    createMethodsOarrayA string list of possible CreateMethods for this device → DeviceClass::createMethods(). If no createMethods are definend, DeviceClass::CreateMethodUser will be used as default. Some devices can be created in different ways. Possible strings are:

    See also: CreateMethods and SetupMethods

    setupMethodOstringDefinens the SetupMethod of this device → DeviceClass::setupMethod(). Possible strings are:

    See also: CreateMethods and SetupMethods

    pairingInfoOstringThe pairingInfo will inform the user how to pair the device → DeviceClass::setupMethod(). This parameter will only be used for DisplayPin and EnterPin and PushButton. Example: "Please press the button on the device before continue."
    criticalStateTypeIdOstringDeprecated: please use interfaces instead.
    primaryStateTypeIdOstringDeprecated: please use interfaces instead.
    primaryActionTypeIdOstringDeprecated: please use interfaces instead.
    discoveryParamTypesOarrayA list of ParamTypes which will be needed for discovering a device → DeviceClass::discoveryParamTypes(). This parameter will only be used for devices with the CreateMethodDiscovery.

    See also: The ParamType definition

    paramTypesOarrayA list of ParamTypes which define the parameters of a device → DeviceClass::paramTypes().

    See also: The ParamType definition"

    stateTypesOarrayA list of StateTypes of the device → DeviceClass::stateTypes().

    See also: The StateType definition

    actionTypesOarrayA list of ActionTypes of the device → DeviceClass::actionTypes().

    See also: The ActionType definition

    eventTypesOarrayA list of EventTypes of the device → DeviceClass::eventTypes()

    See also: The EventType definition

    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.

    idMuuidThe actual uuid (ParamTypeId) of the ParamTypeParamType::id().
    nameMstringThis parameter will be used to define the ParamTypeId variable named deviceClassName<name>ParamTypeId in the plugininfo.h, so it can be used in the code.
    displayNameMstringThe visible name of the ParamTypeParamType::displayName(). This string will be available for translations.
    typeMstringThe data type of this parameter → ParamType::type().
    defaultValueOvariantSets the default value of the ParamType. If a parameter will not be set by the user, the parameter will be set to this value → ParamType::defaultValue().
    inputTypeOstringA parameter for clients to know which kind of InputType this. See enum Types::InputType for more information. The expected value for the inputType parameter matches the enum name like this:

    Types::InputTypeTextArea"inputType": "TextArea"

    Types::InputTypePassword"inputType": "Password"

    ...

    unitOstringWith this parameter you can specify the Unit of the parameter i.e. °C → DegreeCelsius. See enum Types::Unit for more information. The expected value for the unit parameter matches the enum name like this:

    Types::UnitDegreeCelsius"unit": "DegreeCelsius"

    Types::UnitMetersPerHour"unit": "MetersPerHour"

    ...

    minValueOnumberSets the minimum limit for this ParamType. Can only be set for int and double values. If the user tries to set the value smaller than the minValue, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation.
    maxValueOnumberSets the maximum limit for this ParamType. Can only be set for int and double values. If the user tries to set the value greater than the maxValue, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation.
    allowedValuesOarrayGives you the possibility to define a list of allowed values. If the user tries to set the value which is not in the allowedValues list, the DeviceManager will catch the invalid parameter and report the error code. You don't have to check this value in the plugin implementation. This is typically used for strings i.e. ["North", "East", "South", "West"].
    readOnlyOboolBool value to make this ParamType realOnly. When you want to edit the params of a device you only can edit the parameters which are "readOnly": false. If not specified, the parameter is writeable by default.

    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.

    idMuuidThe actual uuid (StateTypeId) of the StateTypeStateType::id().
    nameMstringThis parameter will be used to define the StateTypeId variable named deviceClassName<name>StateTypeId in the plugininfo.h, so it can be used in the code.
    displayNameMstringThe visible name of the StateTypeStateType::displayName(). This string will be available for translations.
    displayNameEventMstringWill be used for the name of the created EventType for this StateType. This string will be available for translations.
    displayNameActionOstringWill be used for the name of the created ActionType for this StateType if "writable : true" is definend. This string will be available for translations.
    typeMstringThe data type of this state → StateType::type().
    defaultValueOvariantThe state will be initialized with this value.

    See also: cached

    cachedOboolIndicates if a state value should be cached over reboot of the server. The value will be initialized with the last known value. By default all states get chached. If you want to disable that behaviour you can set this property to false. In that case the value will be initialized with the default value of the State.
    ruleRelevantOboolSince not all States make sense for the user in a rule, with this flag can be specified if this state should be visible in the rule engine for the user or not. This flag has no effect to the ruleengine mechanism and is only ment to filter out not interesting States. By default, every state is rule relevant.
    eventRuleRelevantOboolDeprecated: please use interfaces instead.
    graphRelevantOboolDeprecated: please use interfaces instead.
    unitOstringWith this parameter you can specify the Unit of the parameter i.e. °C → DegreeCelsius. See enum Types::Unit for more information. The expected value for the unit parameter matches the enum name like this:

    Types::UnitDegreeCelsius"unit": "DegreeCelsius"

    Types::UnitMetersPerHour"unit": "MetersPerHour"

    ...

    possibleValuesOarrayGives you the possibility to define a list of possible values which this state can have. This allowes a user to create a rule based on a state and define only values which are possible. This is typically used for strings i.e. ["Loading", "Installing", "Removing"].
    writableOboolIf you define the "writable : true" value an ActionType will be created to set the State value. The created ActionType has the same uuid (ActionTypeId) like the StateType uuid and will be named "<displayNameAction>". The ParamType of the created ActionType will have the same values in the allowedValues list as the StateType in the possibleValues list. Also the minValue / maxValue will be taken over from the StateType.

    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.

    idMuuidThe actual uuid (ActionTypeId) of the ActionTypeActionType::id().
    nameMstringThis parameter will be used to define the ActionTypeId variable named deviceClassName<name>ActionTypeId in the plugininfo.h, so it can be used in the code.
    displayNameMstringThe visible name of the ActionTypeActionType::displayName(). This string will be available for translations.
    paramTypesOarrayA list of ParamTypes which define the parameters of this action → ActionType::paramTypes().

    See also: The ParamType definition"

    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.

    idMuuidThe actual uuid (EventTypeId) of the EventTypeEventType::id().
    nameMstringThis parameter will be used to define the EventTypeId variable named deviceClassName<name>EventTypeId in the plugininfo.h, so it can be used in the code.
    displayNameMstringThe visible name of the EventTypeEventType::displayName(). This string will be available for translations.
    paramTypesOarrayA list of ParamTypes which define the parameters of this event → EventType::paramTypes().

    See also: The ParamType definition"

    ruleRelevantOboolSince not all Events make sense for the user in a rule, with this flag can be specidied if this event should be visible in the rule engine for the user or not. This flag has no effect to the ruleengine mechanism and is only ment to filter out not interesting Events. By default, every event is rule relevant.
    graphRelevantOboolDeprecated: please use interfaces instead.