guh - Developer documentation

The plugin JSON File

Each Plugin in guh 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 guh-generateplugininfo precompiler

The guh-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": "Name of the plugin",
    "idName": "PluginName",
    "id": "uuid",
    "vendors": [
        {
            "name": "Name of the plugin",
            "idName": "Name of the logging category",
            "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, idName, id and vendors) describe the properties of the plugin it self.

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

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

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

Note: All parameters must be definend.

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

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

A DeviceClass contains following parameters:

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",
            "idName": "paramName"
            "name": "name of the param (translatable)",
            "type": "DataType",
            "index": "int",
            "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"
        }
    ]
}

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 guhserver::GuhCore. 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": [
        {
            "name": "Name of the state (translatable)",
            "id": "uuid",
            "idName": "stateName",
            "index": "int",
            "type": "DataType",
            "o:ruleRelevant": "bool",
            "o:eventRuleRelevant": "bool",
            "eventTypeName": "Name of the created EventType (translatable)",
            "o:graphRelevant": "bool",
            "o:unit": "The unit of the state value.",
            "defaultValue": "The state will be initialized with this value."
            "o:minValue": "Numeric minimum value for this state.",
            "o:maxValue": "Numeric maximum value for this state.",
            "o:possibleValues": [
                "value"
            ],
            "o:writable": true,
            "o:actionTypeName": "Name of the the created ActionType (translatable)"
        }
    ]
}

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

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

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

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