mirror of https://github.com/nymea/nymea.git
684 lines
29 KiB
Plaintext
684 lines
29 KiB
Plaintext
/*!
|
|
\page plugin-json.html
|
|
\title The plugin JSON File
|
|
\brief Description of the plugin JSON file structure.
|
|
|
|
Each \l{DevicePlugin}{Plugin} in nymea 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 nymea-plugininfocompiler precompiler
|
|
|
|
The \tt {\b nymea-plugininfocompiler} 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 name>VendorId \unicode{0x2192} the defined UUID for the corresponding \l{Vendor}.
|
|
\li \l{DeviceClassId}: <\e name>DeviceClassId \unicode{0x2192} the definend UUID for the corresponding \l{DeviceClass}.
|
|
\li \l{ActionTypeId}: <\e name>ActionTypeId \unicode{0x2192} the defined UUID for the corresponding \l{ActionType}.
|
|
\li \l{StateTypeId}: <\e name>StateTypeId \unicode{0x2192} the defidefinednend UUID for the corresponding \l{StateType}.
|
|
\li \l{EventTypeId}: <\e name>EventTypeId \unicode{0x2192} the defined UUID for the corresponding \l{EventType}.
|
|
\li \l{ParamTypeId}: <\e name>ParamTypeId \unicode{0x2192} the defined UUID for the corresponding \l{ParamType}.
|
|
\li Logging Category: \e dc<Name>
|
|
\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": "PluginName",
|
|
"displayName": "Name of the plugin",
|
|
"id": "uuid",
|
|
"vendors": [
|
|
{
|
|
"name": "VendorName",
|
|
"displayName": "Name of the vendor",
|
|
"id": "uuid",
|
|
"thingClasses": [
|
|
...
|
|
]
|
|
}
|
|
|
|
]
|
|
}
|
|
\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 displayName, \e id and \e vendors) describe the properties of the plugin it self.
|
|
|
|
\code
|
|
{
|
|
"id": "uuid",
|
|
"name": "PluginName",
|
|
"displayName": "Name of the plugin (translatable)",
|
|
"o:paramTypes": [
|
|
...
|
|
],
|
|
"vendors": [
|
|
{
|
|
...
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{PluginId}) of the plugin \unicode{0x2192} \l{DevicePlugin::pluginId()}
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the PluginId variable named \tt{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 \tt dc<Name>
|
|
and can be used as follows (\tt {"name":"Example"}):
|
|
\code
|
|
qCDebug(dcExample()) << "Hello world!";
|
|
qCWarning(dcExample()) << "Warning the world!";
|
|
\endcode
|
|
|
|
The logging category allows you to categorise the debug output. It can be configured with the \tt -d argument of nymead (see \tt {$ nymead -h}).
|
|
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the plugin \unicode{0x2192} \l{DevicePlugin::pluginDisplayName()}. This string will be available for translations.
|
|
|
|
\row
|
|
\li \tt paramTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{ParamType}{ParamTypes} which define the parameters of this plugin \unicode{0x2192} \l{DevicePlugin::configuration()}.
|
|
|
|
\b{See also:} \l{The ParamType definition}
|
|
|
|
\row
|
|
\li \tt vendors
|
|
\li \b M
|
|
\li array
|
|
\li The list of \l{Vendor}{Vendors} objects this plugin supports.
|
|
|
|
\b{See also:} \l{The Vendor definition}
|
|
|
|
\endtable
|
|
|
|
|
|
\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 nymea.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"vendors": [
|
|
{
|
|
"id": "uuid",
|
|
"name": "vendorName",
|
|
"displayName": "Name of the vendor (translatable)",
|
|
"thingClasses": [
|
|
...
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{VendorId}) of the vendor \unicode{0x2192} \l{Vendor::id()}.
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the VendorId variable named \tt{<name>VendorId} in the plugininfo.h, so it can be used in the code.
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the vendor \unicode{0x2192} \l{Vendor::displayName()}. This string will be available for translations.
|
|
\row
|
|
\li \tt thingClasses
|
|
\li \b M
|
|
\li array
|
|
\li A list of \l{DeviceClass}{DeviceClasses} objects.
|
|
|
|
\b{See also:} \l{The DeviceClass definition}
|
|
|
|
\endtable
|
|
|
|
\section2 The DeviceClass definition
|
|
A \l{Vendor} can support more then one \l{DeviceClass}, so the parameter \e thingClasses in the vendor definition is a list.
|
|
Each element of this list represents a \l{DeviceClass} in nymea.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"vendors": [
|
|
{
|
|
..
|
|
"thingClasses": [
|
|
{
|
|
"id": "uuid",
|
|
"name": "thingClassName",
|
|
"displayName": "The name of the device class (translatable)",
|
|
"o:createMethods": [ ],
|
|
"o:setupMethod": "SetupMethod",
|
|
"o:interfaces": [ "interfacename" ],
|
|
"o:pairingInfo": "Information how to pair the device. (translatable)",
|
|
"o:discoveryParamTypes": [ ],
|
|
"o:paramTypes": [ ],
|
|
"o:stateTypes": [ ],
|
|
"o:actionTypes": [ ],
|
|
"o:eventTypes": [ ]
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{DeviceClassId}) of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::id()}.
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the DeviceClassId variable named \tt{<name>DeviceClassId} in the plugininfo.h, so it can be used in the code.
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the \l{DeviceClass} \unicode{0x2192} \l{DeviceClass::displayName()}. This string will be available for translations.
|
|
\row
|
|
\li \tt interfaces
|
|
\li \b O
|
|
\li array
|
|
\li A string list of \l{Interfaces for DeviceClasses}{interfaces} this plugin implements. Interfaces define states, events and actions to
|
|
provide more defined ways of creating device class. A plugin developer should always try to follow interface definitions if possible.
|
|
\row
|
|
\row
|
|
\li \tt createMethods
|
|
\li \b O
|
|
\li array
|
|
\li A string list of possible \l{DeviceClass::CreateMethod}{CreateMethods} for this device \unicode{0x2192} \l{DeviceClass::createMethods()}.
|
|
If no createMethods are definend, \l{DeviceClass::CreateMethodUser} will be used as default.
|
|
Some devices can be created in different ways. Possible strings are:
|
|
\list
|
|
\li \tt User \unicode{0x2192} \l{DeviceClass::CreateMethodUser}
|
|
\li \tt Discovery \unicode{0x2192} \l{DeviceClass::CreateMethodDiscovery}
|
|
\li \tt Auto \unicode{0x2192} \l{DeviceClass::CreateMethodAuto}
|
|
\endlist
|
|
|
|
\b{See also:} \l{CreateMethods and SetupMethods}
|
|
\row
|
|
\li \tt setupMethod
|
|
\li \b O
|
|
\li string
|
|
\li Definens the \l{DeviceClass::SetupMethod}{SetupMethod} of this device \unicode{0x2192} \l{DeviceClass::setupMethod()}. Possible strings are:
|
|
\list
|
|
\li \tt JustAdd \unicode{0x2192} \l{DeviceClass::SetupMethodJustAdd} (default)
|
|
\li \tt DisplayPin \unicode{0x2192} \l{DeviceClass::SetupMethodDisplayPin}
|
|
\li \tt EnterPin \unicode{0x2192} \l{DeviceClass::SetupMethodEnterPin}
|
|
\li \tt PushButton \unicode{0x2192} \l{DeviceClass::SetupMethodPushButton}
|
|
\endlist
|
|
|
|
\b{See also:} \l{CreateMethods and SetupMethods}
|
|
\row
|
|
\li \tt pairingInfo
|
|
\li \b O
|
|
\li string
|
|
\li 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."
|
|
\row
|
|
\li \tt discoveryParamTypes
|
|
\li \b O
|
|
\li array
|
|
\li 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}.
|
|
|
|
\b{See also:} \l{The ParamType definition}
|
|
\row
|
|
\li \tt paramTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{ParamType}{ParamTypes} which define the parameters of a device \unicode{0x2192} \l{DeviceClass::paramTypes()}.
|
|
|
|
\b{See also:} \l{The ParamType definition}"
|
|
\row
|
|
\li \tt stateTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{StateType}{StateTypes} of the device \unicode{0x2192} \l{DeviceClass::stateTypes()}.
|
|
|
|
\b{See also:} \l{The StateType definition}
|
|
|
|
\row
|
|
\li \tt actionTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{ActionType}{ActionTypes} of the device \unicode{0x2192} \l{DeviceClass::actionTypes()}.
|
|
|
|
\b{See also:} \l{The ActionType definition}
|
|
|
|
\row
|
|
\li \tt eventTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{EventType}{EventTypes} of the device \unicode{0x2192} \l{DeviceClass::eventTypes()}
|
|
|
|
\b{See also:} \l{The EventType definition}
|
|
|
|
\endtable
|
|
|
|
|
|
\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",
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{ParamTypeId}) of the \l{ParamType} \unicode{0x2192} \l{ParamType::id()}.
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the ParamTypeId variable named \tt{thingClassName<name>ParamTypeId} in the plugininfo.h, so it can be used in the code.
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the \l{ParamType} \unicode{0x2192} \l{ParamType::displayName()}. This string will be available for translations.
|
|
\row
|
|
\li \tt type
|
|
\li \b M
|
|
\li string
|
|
\li The data type of this parameter \unicode{0x2192} \l{ParamType::type()}.
|
|
\row
|
|
\li \tt defaultValue
|
|
\li \b O
|
|
\li variant
|
|
\li 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()}.
|
|
\row
|
|
\li \tt inputType
|
|
\li \b O
|
|
\li string
|
|
\li A parameter 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 ...
|
|
\row
|
|
\li \tt unit
|
|
\li \b O
|
|
\li string
|
|
\li 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 ...
|
|
\row
|
|
\li \tt minValue
|
|
\li \b O
|
|
\li number
|
|
\li 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.
|
|
\row
|
|
\li \tt maxValue
|
|
\li \b O
|
|
\li number
|
|
\li 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.
|
|
\row
|
|
\li \tt allowedValues
|
|
\li \b O
|
|
\li array
|
|
\li 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"].
|
|
\row
|
|
\li \tt readOnly
|
|
\li \b O
|
|
\li bool
|
|
\li 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.
|
|
\endtable
|
|
|
|
\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{nymeaserver::NymeaCore}. 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": [
|
|
{
|
|
"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: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)"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{StateTypeId}) of the \l{StateType} \unicode{0x2192} \l{StateType::id()}.
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the StateTypeId variable named \tt{thingClassName<name>StateTypeId} in the plugininfo.h, so it can be used in the code.
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the \l{StateType} \unicode{0x2192} \l{StateType::displayName()}. This string will be available for translations.
|
|
\row
|
|
\li \tt displayNameEvent
|
|
\li \b M
|
|
\li string
|
|
\li Will be used for the name of the created \l EventType for this \l {StateType}. This string will be available for translations.
|
|
\row
|
|
\li \tt displayNameAction
|
|
\li \b O
|
|
\li string
|
|
\li Will be used for the name of the created \l ActionType for this \l StateType if "\tt {writable : true}" is definend. This string will be available for translations.
|
|
\row
|
|
\li \tt type
|
|
\li \b M
|
|
\li string
|
|
\li The data type of this state \unicode{0x2192} \l{StateType::type()}.
|
|
\row
|
|
\li \tt defaultValue
|
|
\li \b O
|
|
\li variant
|
|
\li The state will be initialized with this value.
|
|
|
|
\b{See also:} \tt cached
|
|
\row
|
|
\li \tt cached
|
|
\li \b O
|
|
\li bool
|
|
\li Indicates 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 \tt{false}. In that case the
|
|
value will be initialized with the default value of the State.
|
|
\row
|
|
\li \tt unit
|
|
\li \b O
|
|
\li string
|
|
\li 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 ...
|
|
\row
|
|
\li \tt possibleValues
|
|
\li \b O
|
|
\li array
|
|
\li Gives you the possibility to define a list of possible values which this state can have. This allows 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. \tt {["Loading", "Installing", "Removing"]}.
|
|
\row
|
|
\li \tt writable
|
|
\li \b O
|
|
\li bool
|
|
\li 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 "<displayNameAction>". 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}.
|
|
|
|
\endtable
|
|
|
|
|
|
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{<stateName>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}",
|
|
"name": "volume",
|
|
"displayName": "Volume",
|
|
"unit": "Percentage",
|
|
"type": "int",
|
|
"minValue": 0,
|
|
"maxValue": 100,
|
|
"writable": true,
|
|
"displayNameAction": "Set volume",
|
|
"displayNameEvent": "Volume changed"
|
|
}
|
|
\endcode
|
|
|
|
This \l{StateType} definition will create for you an \l{ActionType} looking like this:
|
|
\code
|
|
{
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
And an \l{EventType} looking like this:
|
|
\code
|
|
{
|
|
"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"
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\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 nymea.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"actionTypes": [
|
|
{
|
|
"id": "uuid",
|
|
"name": "actionName",
|
|
"displayName": "Name of the action (translatable)",
|
|
"o:paramTypes": [
|
|
...
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{ActionTypeId}) of the \l{ActionType} \unicode{0x2192} \l{ActionType::id()}.
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the ActionTypeId variable named \tt{thingClassName<name>ActionTypeId} in the plugininfo.h, so it can be used in the code.
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the \l{ActionType} \unicode{0x2192} \l{ActionType::displayName()}. This string will be available for translations.
|
|
\row
|
|
\li \tt paramTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{ParamType}{ParamTypes} which define the parameters of this action \unicode{0x2192} \l{ActionType::paramTypes()}.
|
|
|
|
\b{See also:} \l{The ParamType definition}"
|
|
|
|
\endtable
|
|
|
|
\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 nymea.
|
|
|
|
\code
|
|
}
|
|
...
|
|
"eventTypes": [
|
|
{
|
|
"id": "uuid",
|
|
"name": "eventName",
|
|
"displayName": "Name of the event (translatable)",
|
|
"o:paramTypes": [
|
|
...
|
|
]
|
|
}
|
|
]
|
|
}
|
|
\endcode
|
|
|
|
\note \b M is a mandatory parameter, \b O is an optional parameter.
|
|
|
|
\table
|
|
\row
|
|
\li \tt id
|
|
\li \b M
|
|
\li uuid
|
|
\li The actual uuid (\l{EventTypeId}) of the \l{EventType} \unicode{0x2192} \l{EventType::id()}.
|
|
\row
|
|
\li \tt name
|
|
\li \b M
|
|
\li string
|
|
\li This parameter will be used to define the EventTypeId variable named \tt{thingClassName<name>EventTypeId} in the plugininfo.h, so it can be used in the code.
|
|
\row
|
|
\li \tt displayName
|
|
\li \b M
|
|
\li string
|
|
\li The visible name of the \l{EventType} \unicode{0x2192} \l{EventType::displayName()}. This string will be available for translations.
|
|
\row
|
|
\li \tt paramTypes
|
|
\li \b O
|
|
\li array
|
|
\li A list of \l{ParamType}{ParamTypes} which define the parameters of this event \unicode{0x2192} \l{EventType::paramTypes()}.
|
|
|
|
\b{See also:} \l{The ParamType definition}"
|
|
\endtable
|
|
|
|
*/
|