mirror of https://github.com/nymea/nymea.git
459 lines
30 KiB
Plaintext
459 lines
30 KiB
Plaintext
/*!
|
|
\page plugin-json.html
|
|
\title The plugin JSON File
|
|
\brief Description of the plugin JSON file structure.
|
|
|
|
Each \l{DevicePlugin}{Plugin} in guh will be defined in the corresponding JSON file. You can find information how to read JSON \l{http://json.org/}{here}. This file will be loaded from the \l{DeviceManager} to define the plugin and the corresponding DeviceClasses internal.
|
|
|
|
|
|
\section1 The \b {\tt guh-generateplugininfo} precompiler
|
|
|
|
The \tt {\b guh-generateplugininfo} precompiler will parse this file and generates a \tt plugininfo.h and a \tt extern-plugininfo.h file containing the definitions of:
|
|
\list
|
|
\li \l{PluginId}: <\e pluginId \unicode{0x2192} the defined UUID for the \l{DevicePlugin}.
|
|
\li \l{VendorId}: <\e idName>VendorId \unicode{0x2192} the defined UUID for the corresponding \l{Vendor}.
|
|
\li \l{DeviceClassId}: <\e idName>DeviceClassId \unicode{0x2192} the definend UUID for the corresponding \l{DeviceClass}.
|
|
\li \l{ActionTypeId}: <\e idName>ActionTypeId \unicode{0x2192} the defined UUID for the corresponding \l{ActionType}.
|
|
\li \l{StateTypeId}: <\e idName>StateTypeId \unicode{0x2192} the defidefinednend UUID for the corresponding \l{StateType}.
|
|
\li \l{EventTypeId}: <\e idName>EventTypeId \unicode{0x2192} the defined UUID for the corresponding \l{EventType}.
|
|
\li \l{ParamTypeId}: <\e idName>ParamTypeId \unicode{0x2192} the defined UUID for the corresponding \l{ParamType}.
|
|
\li Logging Category: \e dc<idName>
|
|
\endlist
|
|
|
|
The \tt plugininfo.h has to be included in the main plugin \tt cpp file (\tt{deviceplugin<\b pluginName>.cpp}). The \tt 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.
|
|
|
|
\section1 Basic structure
|
|
|
|
The name convention fot the plugin json file is:
|
|
|
|
\tt{deviceplugin\b{<pluginName>}.json}
|
|
|
|
The basic structure of a plugin looks like this:
|
|
|
|
\code
|
|
{
|
|
"name": "Name of the plugin",
|
|
"idName": "PluginName",
|
|
"id": "uuid",
|
|
"vendors": [
|
|
{
|
|
"name": "Name of the plugin",
|
|
"idName": "Name of the logging category",
|
|
"id": "uuid",
|
|
"deviceClasses": [
|
|
...
|
|
]
|
|
}
|
|
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\warning For each new object which has an \e "uuid" value, you need to generate a new UUID. The easyest way to do this is using the command \tt uuidgen:
|
|
|
|
\code
|
|
$ sudo apt-get install uuid-runtime
|
|
\endcode
|
|
|
|
\code
|
|
$ uuidgen
|
|
cd938452-213d-432f-ae7a-3ef3c474fe99
|
|
\endcode
|
|
|
|
|
|
\section1 Writing the plugin JSON file
|
|
|
|
\section2 The Plugin definition
|
|
The parameters of the first object (\e name, \e idName, \e id and \e vendors) describe the properties of the plugin it self.
|
|
|
|
\code
|
|
{
|
|
"name": "Name of the plugin (translatable)",
|
|
"idName": "PluginName",
|
|
"id": "uuid",
|
|
"o:paramTypes": [
|
|
...
|
|
],
|
|
"vendors": [
|
|
{
|
|
...
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\list
|
|
\li - \underline{\e name:} The visible name of the plugin \unicode{0x2192} \l{DevicePlugin::pluginName()}
|
|
\li - \underline{\e idName:} This parameter will be used to define the PluginId variable named <idName>PluginId in the plugininfo.h, so it can be used in the code. This parameter also defines the logging categorie for this plugin. The loging category will always definend as \tt dc<idName> and can be used as follows (\tt {"idName":"Example"}):
|
|
|
|
\code
|
|
qCdebug(dcExample) << "Hello world!";
|
|
qCWarning(dcExample) << "Warning the world!";
|
|
\endcode
|
|
|
|
Please start allways with a capital letter i.e. \tt {"idName": "Example"}. The logging category allowes you to categorise the debug output. It can be configured with the \tt -d argument of guhd (see \tt {$ man guhd}).
|
|
\li - \underline{\e id:} The actual uuid (\l{PluginId}) of the plugin \unicode{0x2192} \l{DevicePlugin::pluginId()}
|
|
\li - \underline{\e paramTypes:} Optionl: A list of \l{ParamType}{ParamTypes} which define the paramters of this plugin \unicode{0x2192} \l{DevicePlugin::configuration()} (see section "\l{The ParamType definition}").
|
|
\li - \underline{\e vendors:} The list of \l{Vendor}{Vendors} objects (see section "\l{The Vendor definition}");
|
|
\endlist
|
|
|
|
|
|
\section2 The Vendor definition
|
|
A plugin can support more then one \l{Vendor}, so the parameter \e vendors in the plugin definition is a list. Each element of this list represents a \l{Vendor} in guh.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"vendors": [
|
|
{
|
|
"name": "Name of the vendor (translatable)",
|
|
"idName": "vendorName",
|
|
"id": "uuid",
|
|
"deviceClasses": [
|
|
...
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note All parameters \underline{must} be definend.
|
|
|
|
\list
|
|
\li - \underline{\e name:} The visible name of the vendor \unicode{0x2192} \l{Vendor::name()}.
|
|
\li - \underline{\e idName:} This parameter will be used to define the VendorId variable named <idName>VendorId in the plugininfo.h, so it can be used in the code.
|
|
\li - \underline{\e id:} The actual uuid (\l{VendorId}) of the plugin \unicode{0x2192} \l{Vendor::id()}.
|
|
\li - \underline{\e deviceClasses:} A list of \l{DeviceClass}{DeviceClasses} objects (see section "\l{The DeviceClass definition}").
|
|
\endlist
|
|
|
|
\section2 The DeviceClass definition
|
|
A \l{Vendor} can support more then one \l{DeviceClass}, so the parameter \e deviceClasses in the vendor definition is a list. Each element of this list represents a \l{DeviceClass} in guh.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"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": [
|
|
]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
A \l{DeviceClass} contains following parameters:
|
|
\list
|
|
\li - \underline{\e name:} The visible name of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::name()}.
|
|
\li - \underline{\e idName:} This parameter will be used to define the DeviceClassId variable named <idName>DeviceClassId in the plugininfo.h, so it can be used in the code.
|
|
\li - \underline{\e id:} The actual uuid (\l{DeviceClassId}) of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::id()}.
|
|
\li - \underline{\e interfaces: } A list of \l{Interfaces for DeviceClasses}{interfaces} this plugin implements.
|
|
\li - \underline{\e basicTags:} A list of \l{DeviceClass::BasicTag}{BasicTags} for this device \unicode{0x2192} \l{DeviceClass::basicTags()}. A \l{DeviceClass} can have multiple \l{DeviceClass::BasicTag}{BasicTags} which describe the basic category of the DeviceClass. A \l{DeviceClass} should be eighter a Service or a Device, never both. See enum \l{DeviceClass::BasicTag} for more information. The expected value for the \e basicTags parameters matches the enum name like this:
|
|
|
|
\tt {DeviceClass::BasicTagService} \unicode{0x2192} \tt {"basicTags": [ "Service" ]}
|
|
|
|
\tt {DeviceClass::BasicTagLighting} \unicode{0x2192} \tt {"basicTags": [ "Lighting" ]}
|
|
|
|
\tt ...
|
|
|
|
\li - \underline{\e deviceIcon:} Defines the icon for this \l{DeviceClass}. See enum \l{DeviceClass::DeviceIcon} for more information. The expected value for the \e deviceIcon parameters matches the enum name like this:
|
|
|
|
\tt {DeviceClass::DeviceIconBed} \unicode{0x2192} \tt {"deviceIcon": "Bed" }
|
|
|
|
\tt {DeviceClass::DeviceIconPower} \unicode{0x2192} \tt {"deviceIcon": "Power" }
|
|
|
|
\tt ...
|
|
|
|
\li - \underline{\e createMethods:} A list of possible \l{DeviceClass::CreateMethod}{CreateMethods} for this device \unicode{0x2192} \l{DeviceClass::createMethods()}. Some devices can be created in different ways. Possible values are:
|
|
\list
|
|
\li \e user \unicode{0x2192} \l{DeviceClass::CreateMethodUser}
|
|
\li \e discovery \unicode{0x2192} \l{DeviceClass::CreateMethodDiscovery}
|
|
\li \e auto \unicode{0x2192} \l{DeviceClass::CreateMethodAuto}
|
|
\endlist
|
|
\li - \underline{\e setupMethod:} Optional: Definens the \l{DeviceClass::SetupMethod}{SetupMethod} of this device \unicode{0x2192} \l{DeviceClass::setupMethod()}. Possible values are:
|
|
\list
|
|
\li \e justAdd \unicode{0x2192} \l{DeviceClass::SetupMethodJustAdd} (default)
|
|
\li \e displayPin \unicode{0x2192} \l{DeviceClass::SetupMethodDisplayPin}
|
|
\li \e enterPin \unicode{0x2192} \l{DeviceClass::SetupMethodEnterPin}
|
|
\li \e pushButton \unicode{0x2192} \l{DeviceClass::SetupMethodPushButton}
|
|
\endlist
|
|
\note For more information please take a look at \l{CreateMethods and SetupMethods} documentation.
|
|
\li - \underline{\e pairingInfo:} Optional: The \l{DeviceClass::pairingInfo()}{pairingInfo} will inform the user how to pair the device \unicode{0x2192} \l{DeviceClass::setupMethod()}. This parameter will only be used for \l{DeviceClass::SetupMethodDisplayPin}{DisplayPin} and \l{DeviceClass::SetupMethodEnterPin}{EnterPin} and \l{DeviceClass::SetupMethodPushButton}{PushButton}. Example: "Please press the button on the device before continue."
|
|
\li - \underline{\e criticalStateTypeId:} Optional: Define which \l{StateType} is critical for this \l{Device}. The given \l{StateTypeId} has to be a \tt{bool} \l{State} which enables / disables the whole \l{Device} i.e. \e{"connected"}, \e{"available"} or \e{"reachable"}. This allowes a client application to disable the device until this \l{State} becomes true.
|
|
\li - \underline{\e primaryStateTypeId:} Optional: Define which \l{StateType} is the primary \l{State} for this \l{Device}. This allowes a client developer to place the primary \l{State} value in the device overview.
|
|
\li - \underline{\e primaryActionTypeId:} Optional: Define which \l{ActionType} is the primary \l{Action} for this \l{Device}. This allowes a client developer to place the primary \l{Action} element in the device overview.
|
|
\li - \underline{\e discoveryParamTypes:} Optional: A list of \l{ParamType}{ParamTypes} which will be needed for discovering a device \unicode{0x2192} \l{DeviceClass::discoveryParamTypes()}. This parameter will only be used for devices with the \l{DeviceClass::CreateMethodDiscovery}{CreateMethodDiscovery} (see section "\l{The ParamType definition}").
|
|
\li - \underline{\e paramTypes:} A list of \l{ParamType}{ParamTypes} which define the paramters of a device \unicode{0x2192} \l{DeviceClass::paramTypes()} (see section "\l{The ParamType definition}").
|
|
\li - \underline{\e stateTypes:} Optional: A list of \l{StateType}{StateTypes} of the device \unicode{0x2192} \l{DeviceClass::stateTypes()} (see section "\l{The StateType definition}").
|
|
\li - \underline{\e actionTypes:} Optional: A list of \l{ActionType}{ActionTypes} of the device \unicode{0x2192} \l{DeviceClass::actionTypes()} (see section "\l{The ActionType definition}").
|
|
\li - \underline{\e eventTypes:} Optional: A list of \l{EventType}{EventTypes} of the device \unicode{0x2192} \l{DeviceClass::eventTypes()} (see section "\l{The EventType definition}").
|
|
\endlist
|
|
|
|
|
|
\section2 The ParamType definition
|
|
A \l{DeviceClass} can have a list of \l{ParamType}{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". \l{ParamType}{ParamTypes} will be used for \e discoveryParamType in the \l{DeviceClass} definition and in the \l{ActionType} and \l{EventType} definition.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\list
|
|
\li - \underline{\e id:} The actual uuid (\l{ParamTypeId}) of the \l{ParamType} \unicode{0x2192} \l{ParamType::id()}.
|
|
\li - \underline{\e idName:} This parameter will be used to define the ParamTypeId variable named <idName>ParamTypeId in the plugininfo.h, so it can be used in the code.
|
|
\li - \underline{\e name:} The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::name()}.
|
|
\li - \underline{\e type:} The data type of this paramter \unicode{0x2192} \l{ParamType::type()}.
|
|
\li - \underline{\e index:} The order index of the \l{ParamType} \unicode{0x2192} \l{ParamType::index()}. This index will be used for sorting the \l{Param}{Params} of a \l{Device}/\l{Action}/\l{Event} to make sure the types looks the same on all clients. Please make sure all \l{ParamType}{ParamTypes} together will create a list from \tt 0 to \tt x.
|
|
\li - \underline{\e inputType:} Optional: A paramter for clients to know which kind of \l{Types::InputType}{InputType} this. See enum \l{Types::InputType} for more information. The expected value for the \e inputType parameter matches the enum name like this:
|
|
|
|
\tt {Types::InputTypeTextArea} \unicode{0x2192} \tt {"inputType": "TextArea"}
|
|
|
|
\tt {Types::InputTypePassword} \unicode{0x2192} \tt {"inputType": "Password"}
|
|
|
|
\tt ...
|
|
|
|
|
|
\li - \underline{\e defaultValue:} Sets the default value of the \l{ParamType}. If a parameter will not be set by the user, the parameter will be set to this value \unicode{0x2192} \l{ParamType::defaultValue()}.
|
|
\li - \underline{\e unit:} Optional: With this parameter you can specify the \l{Types::Unit}{Unit} of the parameter i.e. \unicode{0x00B0}C \unicode{0x2192} DegreeCelsius. See enum \l{Types::Unit} for more information. The expected value for the \e unit parameter matches the enum name like this:
|
|
|
|
\tt {Types::UnitDegreeCelsius} \unicode{0x2192} \tt {"unit": "DegreeCelsius"}
|
|
|
|
\tt {Types::UnitMetersPerHour} \unicode{0x2192} \tt {"unit": "MetersPerHour"}
|
|
|
|
\tt ...
|
|
|
|
\li - \underline{\e minValue:} Optional: Sets the minimum limit for this \l{ParamType}. Can only be set for \e int and \e double values. If the user tries to set the value smaller than the \e 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.
|
|
\li - \underline{\e maxValue:} Optional: Sets the maximum limit for this \l{ParamType}. Can only be set for \e int and \e double values. If the user tries to set the value greater than the \e 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.
|
|
\li - \underline{\e allowedValues:} Optional: Gives you the possibility to define a list of allowed values. If the user tries to set the value which is not in the \e 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"].
|
|
\li - \underline{\e readOnly:} Optional: Bool value to make this \l{ParamType} realOnly. When you want to edit the params of a device you only can edit the parameters which are \tt {"readOnly": false}. If not specified, the parameter is writeable by default.
|
|
\endlist
|
|
|
|
|
|
|
|
\section2 The StateType definition
|
|
A \l{DeviceClass} can have a list of \l{StateType}{StateTypes} which allow you to represent a state of a device. A \l{State} can be changed/updated in the plugin code. If you change a state in the plugin using \l{Device::setStateValue()} an \l{Event} will generate automatically in the \l{guhserver::GuhCore}. This \l{Event} has the same uuid (\l{EventTypeId}) like the \l{State} which created the "<stateName> changed" \l{Event}. The event will have exactly one \l{Param}, which has the same properties like the \l{StateType} value and contains the new value.
|
|
|
|
A \l{StateType} has following parameters:
|
|
|
|
\code
|
|
}
|
|
...
|
|
"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)"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\list
|
|
\li - \underline{\e name:} The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::name()}.
|
|
\li - \underline{\e idName:} This parameter will be used to define the StateTypeId variable named <idName>StateTypeId in the plugininfo.h, so it can be used in the code.
|
|
\li - \underline{\e id:} The actual uuid (\l{StateTypeId}) of the \l{StateType} \unicode{0x2192} \l{StateType::id()}.
|
|
\li - \underline{\e index:} The order index of the \l{StateType} \unicode{0x2192} \l{StateType::index()}. This index will be used for sorting the \l{State}{States} of a \l{Device} to make sure the types looks the same on all clients. Please make sure all \l{StateType}{StateTypes} together will create a list from \tt 0 to \tt x.
|
|
\li - \underline{\e type:} The data type of this state \unicode{0x2192} \l{StateType::type()}.
|
|
\li - \underline{\e ruleRelevant:} Optional: Since not all \l{State}{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 \l{State}{States}. By default, every state is rule relevant.
|
|
\li - \underline{\e graphRelevant:} Optional: This flag indicates that this \l{State} is interesting to be shown in a graph/chart. By default every state is \underline not \tt {graphRelevant}. The corresponding EventType will not be graphRelevant, because the graph will be generated from the \l{State} logs.
|
|
\li - \underline{\e eventRuleRelevant:} Optional: The same thing as \e {ruleRelevat}, but this flag is for the \l{EventType}, which will be generated for this \l{StateType}.
|
|
\li - \underline{\e eventTypeName:} Will be used for the name of the created \l EventType for this \l StateType. It is good practice to name the event \tt{"<stateName> changed"}.
|
|
\li - \underline{\e unit:} Optional: With this parameter you can specify the unit of the state value i.e. \unicode{0x00B0}C \unicode{0x2192} DegreeCelsius (\l{Types::Unit}).
|
|
\li - \underline{\e defaultValue:} The state will be initialized with this value.
|
|
\li - \underline{\e possibleValues:} Optional: Gives 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"].
|
|
\li - \underline{\e writable:} Optional: If you define the "\e writable : true" value an \l{ActionType} will be created to set the \l{State} value. The created \l{ActionType} has the same uuid (\l{ActionTypeId}) like the \l{StateType} uuid and will be named "set <stateName>". The \l{ParamType} of the created \l{ActionType} will have the same values in the \e allowedValues list as the \l{StateType} in the \e possibleValues list. Also the \e minValue / \e maxValue will be taken over from the \l{StateType}.
|
|
\li - \underline{\e actionTypeName:} Optional: Will be used for the name of the created \l ActionType for this \l StateType if "\e writable : true" is definend. It is good practice to name the ActionType \tt{"Set <stateName>"}.
|
|
|
|
|
|
If a \l{StateType} has the property \e writable the \l{DeviceManager} will create automatically an \l{ActionType} for this state, which will also have exactly one \l{ParamType} with the same properties like the \l{StateType}. The created \l{ActionType} has the same uuid (\l{ActionTypeId}) like the \l{StateType} uuid and will be named \tt actionTypeName.
|
|
|
|
This mechanism was created to ensure that the \l{EventType} and \l{ActionType} which correspond to a certain \l{StateType} will always be equal. This makes it possible for clients to know that an \l{Action} will set the \a value of a \l{State}, and an \l{Event} was generated by the corresponding \l{State}.
|
|
|
|
\tt {\l{StateTypeId} == \l{EventTypeId} == \l{ActionTypeId}}
|
|
|
|
The \l{ParamType} for the created \l{EventType} will have the same id. In the code, the \l{ParamTypeId} will be named: \tt{<stateIdName>StateParamTypeId}.
|
|
|
|
Example \l{StateType}: Following \l{StateType} stands for a volume \l{State} named \e volume. The value of this \l{State} has the data type \tt int and the unit \tt \%. This \l{StateType} is writable, which means there will be an \l{ActionType} generated with \e id \tt 9bc84381-785f-46bf-94c8-6e35116f50d3. The generated \l{ActionType} will have one \e ParamType which has the \e id = \tt 9bc84381-785f-46bf-94c8-6e35116f50d3, \e name = \tt volume, \e type = \tt int, \e minValue = \tt 0, \e maxValue =\tt 100, \e unit = \tt Percentage. The \l{ActionType} name will be . If the value of the \l{State} will be changed, an \l{Event} will be generated. The \l{ParamType} of the event will be equal to the \l{ParamType} of the generated \l{ActionType}.
|
|
|
|
\code
|
|
{
|
|
"id": "{9bc84381-785f-46bf-94c8-6e35116f50d3}",
|
|
"idName": "volume",
|
|
"name": "volume",
|
|
"unit": "Percentage",
|
|
"index": "0",
|
|
"type": "int",
|
|
"minValue": 0,
|
|
"maxValue": 100,
|
|
"writable": true,
|
|
"actionTypeName": "Set volume",
|
|
"eventTypeName": "volume changed"
|
|
}
|
|
\endcode
|
|
|
|
This \l{StateType} definition will create for you an \l{ActionType} looking like this:
|
|
\code
|
|
{
|
|
"id": "{9dfe5d78-4c3f-497c-bab1-bb9fdf7e93a9}",
|
|
"name": "Set volume",
|
|
"paramTypes": [
|
|
{
|
|
"id": "{9bc84381-785f-46bf-94c8-6e35116f50d3}",
|
|
"idName": "volumeStateParamTypeId",
|
|
"name": "volume",
|
|
"type": "int",
|
|
"index": 0,
|
|
"maxValue": 100,
|
|
"minValue": 0,
|
|
"unit": "Percentage"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
And an \l{EventType} looking like this:
|
|
\code
|
|
{
|
|
"id": "{9dfe5d78-4c3f-497c-bab1-bb9fdf7e93a9}",
|
|
"name": "volume changed",
|
|
"index": 0,
|
|
"paramTypes": [
|
|
{
|
|
"id": "{9bc84381-785f-46bf-94c8-6e35116f50d3}",
|
|
"idName": "volumeStateParamTypeId",
|
|
"name": "volume",
|
|
"type": "int",
|
|
"index": 0,
|
|
"maxValue": 100,
|
|
"minValue": 0,
|
|
"unit": "Percentage"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
\endlist
|
|
|
|
\section2 The ActionType definition
|
|
A \l{DeviceClass} can have more then one \l{ActionType}, so the parameter \e actionTypes in the \l{DeviceClass} definition is a list. Each element of this list represents an \l{ActionType} in guh.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"actionTypes": [
|
|
{
|
|
"name": "Name of the action (translatable)",
|
|
"idName": "actionName",
|
|
"id": "uuid",
|
|
"index": "int",
|
|
"o:paramTypes": [
|
|
...
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\list
|
|
\li - \underline{\e name:} The visible name of the \l{ActionType} \unicode{0x2192} \l{ActionType::name()}.
|
|
\li - \underline{\e idName:} This parameter will be used to define the ActionTypeId variable named <idName>ActionTypeId in the plugininfo.h, so it can be used in the code.
|
|
\li - \underline{\e id:} The actual uuid (\l{ActionTypeId}) of the \l{ActionType} \unicode{0x2192} \l{ActionType::id()}.
|
|
\li - \underline{\e index:} The order index of the \l{ActionType} \unicode{0x2192} \l{ActionType::index()}. This index will be used for sorting the \l{Action}{Actions} of a \l{Device} to make sure the \l{Device} looks the same on all clients. Please make sure all \l{ActionType}{ActionTypes} together will create a list from \tt 0 to \tt x.
|
|
\li - \underline{\e paramTypes:} Optional: A list of \l{ParamType}{ParamTypes} (see section "\l{The ParamType definition}") for this \l{ActionType}. This parameter is optional. You can also create an \l{ActionType} which has no \l{ParamType}{ParamTypes}.
|
|
\endlist
|
|
|
|
\section2 The EventType definition
|
|
A \l{DeviceClass} can have more then one \l{EventType}, so the parameter \e eventTypes in the \l{DeviceClass} definition is a list. Each element of this list represents an \l{EventType} in guh.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"eventTypes": [
|
|
{
|
|
"name": "Name of the event (translatable)",
|
|
"idName": "eventName",
|
|
"id": "uuid",
|
|
"index": "int",
|
|
"o:ruleRelevant": "bool",
|
|
"o:graphRelevant": "bool",
|
|
"o:paramTypes": [
|
|
...
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\list
|
|
\li - \underline{\e name:} The visible name of the \l{EventType} \unicode{0x2192} \l{EventType::name()}.
|
|
\li - \underline{\e idName:} This parameter will be used to define the EventTypeId variable named <idName>EventTypeId in the plugininfo.h, so it can be used in the code.
|
|
\li - \underline{\e id:} The actual uuid (\l{EventTypeId}) of the \l{EventType} \unicode{0x2192} \l{EventType::id()}.
|
|
\li - \underline{\e index:} The order index of the \l{EventType} \unicode{0x2192} \l{EventType::index()}. This index will be used for sorting the \l{Event}{Events} of a \l{Device} to make sure the \l{Device} looks the same on all clients. Please make sure all \l{EventType}{EventTypes} together will create a list from \tt 0 to \tt x.
|
|
\li - \underline{\e ruleRelevant:} Optional: Since not all \l{Event}{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 \l{Event}{Events}. By default, every event is rule relevant.
|
|
\li - \underline{\e graphRelevant:} Optional: This flag indicates that this \l{Event} is interesting to be shown in a graph/chart. By default all \l{Event} are \underline not \tt {graphRelevant}.
|
|
\li - \underline{\e paramTypes:} Optional: A list of \l{ParamType}{ParamTypes} (see section "\l{The ParamType definition}") for this \l{EventType}. This parameter is optional. You can also create an \l{EventType} which has no \l{ParamType}{ParamTypes}.
|
|
\endlist
|
|
|
|
*/
|