diff --git a/doc/allmodules.qdoc b/doc/allmodules.qdoc index ed9d8f26..0b81f149 100644 --- a/doc/allmodules.qdoc +++ b/doc/allmodules.qdoc @@ -3,8 +3,8 @@ \title All nymea Modules \table 80% - \row \li \l{nymeaserver} \li The nymea server daemon implementation - \row \li \l{libnymea} \li Common data types and plugin interfaces + \row \li \l{nymeaserver} \li The nymea server daemon implementation + \row \li \l{libnymea} \li Common data types and plugin interfaces \endtable \generatelist legalese-command diff --git a/doc/config.qdocconf b/doc/config.qdocconf index 1d57a728..6bee075f 100644 --- a/doc/config.qdocconf +++ b/doc/config.qdocconf @@ -34,6 +34,7 @@ exampledirs = examples/ sourcedirs = .. sources.fileextensions = "*.cpp *.qdoc" -Cpp.ignoredirectives = DECLARE_TYPE \ - DECLARE_OBJECT +Cpp.ignoredirectives = Q_DECLARE_METATYPE \ + Q_ENUM \ + Q_ENUMS \ diff --git a/doc/examples/examples.pro b/doc/examples/examples.pro index 13c36e92..2f92753a 100644 --- a/doc/examples/examples.pro +++ b/doc/examples/examples.pro @@ -1,4 +1,5 @@ -TEMPLATE = subdirs +TEMPLATE = subdirs CONFIG += no_docs_target + SUBDIRS = \ template \ diff --git a/doc/generate-api-qdoc.py b/doc/generate-api-qdoc.py index dda33024..0b7d7e72 100755 --- a/doc/generate-api-qdoc.py +++ b/doc/generate-api-qdoc.py @@ -126,7 +126,7 @@ def extractTypes(types): typesSorted = sorted(typesList) for type in typesSorted: - writeToFile('\section3 %s' % type) + writeToFile('\section2 %s' % type) writeCodeSection(types[type]) if isinstance(types[type], dict): writeToFile(createReferenceLine(types[type])) @@ -139,11 +139,11 @@ def extractMethods(methods): methodsSorted = sorted(methodsList) for method in methodsSorted: - writeToFile('\section3 %s' % method) + writeToFile('\section2 %s' % method) writeToFile('%s' % methods[method]['description']) - writeToFile('\section4 Params') + writeToFile('Params') writeCodeSection(methods[method]['params']) - writeToFile('\section4 Returns') + writeToFile('Returns') writeCodeSection(methods[method]['returns']) writeToFile(createReferenceLine(methods[method])) @@ -155,9 +155,9 @@ def extractNotifications(notifications): notificationsSorted = sorted(notificationsList) for notification in notificationsSorted: - writeToFile('\section3 %s' % notification) + writeToFile('\section2 %s' % notification) writeToFile('%s' % notifications[notification]['description']) - writeToFile('\section4 Params') + writeToFile('Params') writeCodeSection(notifications[notification]['params']) writeToFile(createReferenceLine(notifications[notification])) @@ -186,7 +186,7 @@ def writeDocumentationContent(apiVersion, apiJson): extractMethods(apiJson['methods']) if 'notifications' in apiJson: - writeToFile("\section2 Notifications") + writeToFile("\section1 Notifications") extractNotifications(apiJson['notifications']) writeToFile("\section1 Full introspect") diff --git a/doc/images/plugin-template-1.png b/doc/images/plugin-template-1.png new file mode 100644 index 00000000..0d7d52ba Binary files /dev/null and b/doc/images/plugin-template-1.png differ diff --git a/doc/images/plugin-template-2.png b/doc/images/plugin-template-2.png new file mode 100644 index 00000000..6e789a7b Binary files /dev/null and b/doc/images/plugin-template-2.png differ diff --git a/doc/images/plugin-template-3.png b/doc/images/plugin-template-3.png new file mode 100644 index 00000000..ae30e5fa Binary files /dev/null and b/doc/images/plugin-template-3.png differ diff --git a/doc/images/plugin-template-4.png b/doc/images/plugin-template-4.png new file mode 100644 index 00000000..69018105 Binary files /dev/null and b/doc/images/plugin-template-4.png differ diff --git a/doc/images/plugin-template-5.png b/doc/images/plugin-template-5.png new file mode 100644 index 00000000..9f0df8f0 Binary files /dev/null and b/doc/images/plugin-template-5.png differ diff --git a/doc/images/plugin-template-6.png b/doc/images/plugin-template-6.png new file mode 100644 index 00000000..b32706fb Binary files /dev/null and b/doc/images/plugin-template-6.png differ diff --git a/doc/images/plugin-template-7.png b/doc/images/plugin-template-7.png new file mode 100644 index 00000000..31fea806 Binary files /dev/null and b/doc/images/plugin-template-7.png differ diff --git a/doc/images/plugin-template-8.png b/doc/images/plugin-template-8.png new file mode 100644 index 00000000..96eec8a1 Binary files /dev/null and b/doc/images/plugin-template-8.png differ diff --git a/doc/jsonrpc-api.qdoc b/doc/jsonrpc-api.qdoc index 8f29c675..8299b9e5 100644 --- a/doc/jsonrpc-api.qdoc +++ b/doc/jsonrpc-api.qdoc @@ -1,12 +1,12 @@ /*! -In the following section you can find a detaild description of the current API version 1.4. +In the following section you can find a detaild description of the current API version 1.7. \list \li \l{Types} \li \l{Methods} \li \l{Notifications} \endlist \section1 Types -\section3 Action +\section2 Action \code { "actionTypeId": "Uuid", @@ -17,7 +17,7 @@ In the following section you can find a detaild description of the current API v } \endcode See also: \l{Param} -\section3 ActionType +\section2 ActionType \code { "displayName": "String", @@ -30,7 +30,7 @@ See also: \l{Param} } \endcode See also: \l{ParamType} -\section3 BasicTag +\section2 BasicTag \code [ "BasicTagService", @@ -53,7 +53,7 @@ See also: \l{ParamType} "BasicTagLock" ] \endcode -\section3 BasicType +\section2 BasicType \code [ "Uuid", @@ -68,7 +68,7 @@ See also: \l{ParamType} "Object" ] \endcode -\section3 CalendarItem +\section2 CalendarItem \code { "duration": "Uint", @@ -78,7 +78,7 @@ See also: \l{ParamType} } \endcode See also: \l{RepeatingOption} -\section3 ConfigurationError +\section2 ConfigurationError \code [ "ConfigurationErrorNoError", @@ -91,7 +91,7 @@ See also: \l{RepeatingOption} "ConfigurationErrorInvalidCertificate" ] \endcode -\section3 CreateMethod +\section2 CreateMethod \code [ "CreateMethodUser", @@ -99,7 +99,7 @@ See also: \l{RepeatingOption} "CreateMethodDiscovery" ] \endcode -\section3 Device +\section2 Device \code { "deviceClassId": "Uuid", @@ -119,7 +119,7 @@ See also: \l{RepeatingOption} } \endcode See also: \l{Param} -\section3 DeviceClass +\section2 DeviceClass \code { "actionTypes": [ @@ -159,7 +159,7 @@ See also: \l{Param} } \endcode See also: \l{ActionType}, \l{CreateMethod}, \l{DeviceIcon}, \l{BasicTag}, \l{ParamType}, \l{SetupMethod}, \l{StateType}, \l{EventType}, \l{ParamType} -\section3 DeviceDescriptor +\section2 DeviceDescriptor \code { "description": "String", @@ -168,7 +168,7 @@ See also: \l{ActionType}, \l{CreateMethod}, \l{DeviceIcon}, \l{BasicTag}, \l{Par } \endcode -\section3 DeviceError +\section2 DeviceError \code [ "DeviceErrorNoError", @@ -197,7 +197,7 @@ See also: \l{ActionType}, \l{CreateMethod}, \l{DeviceIcon}, \l{BasicTag}, \l{Par "DeviceErrorParameterNotWritable" ] \endcode -\section3 DeviceIcon +\section2 DeviceIcon \code [ "DeviceIconNone", @@ -238,7 +238,7 @@ See also: \l{ActionType}, \l{CreateMethod}, \l{DeviceIcon}, \l{BasicTag}, \l{Par "DeviceIconRollerShutter" ] \endcode -\section3 Event +\section2 Event \code { "deviceId": "Uuid", @@ -249,7 +249,7 @@ See also: \l{ActionType}, \l{CreateMethod}, \l{DeviceIcon}, \l{BasicTag}, \l{Par } \endcode See also: \l{Param} -\section3 EventDescriptor +\section2 EventDescriptor \code { "o:deviceId": "Uuid", @@ -262,7 +262,7 @@ See also: \l{Param} } \endcode See also: \l{ParamDescriptor} -\section3 EventType +\section2 EventType \code { "displayName": "String", @@ -277,7 +277,7 @@ See also: \l{ParamDescriptor} } \endcode See also: \l{ParamType} -\section3 InputType +\section2 InputType \code [ "InputTypeNone", @@ -292,7 +292,7 @@ See also: \l{ParamType} "InputTypeMacAddress" ] \endcode -\section3 LogEntry +\section2 LogEntry \code { "loggingLevel": "$ref:LoggingLevel", @@ -307,7 +307,7 @@ See also: \l{ParamType} } \endcode See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} -\section3 LoggingError +\section2 LoggingError \code [ "LoggingErrorNoError", @@ -315,7 +315,7 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} "LoggingErrorInvalidFilterParameter" ] \endcode -\section3 LoggingEventType +\section2 LoggingEventType \code [ "LoggingEventTypeTrigger", @@ -325,14 +325,14 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} "LoggingEventTypeExitActionsExecuted" ] \endcode -\section3 LoggingLevel +\section2 LoggingLevel \code [ "LoggingLevelInfo", "LoggingLevelAlert" ] \endcode -\section3 LoggingSource +\section2 LoggingSource \code [ "LoggingSourceSystem", @@ -342,7 +342,7 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} "LoggingSourceRules" ] \endcode -\section3 NetworkDeviceState +\section2 NetworkDeviceState \code [ "NetworkDeviceStateUnknown", @@ -360,7 +360,7 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} "NetworkDeviceStateFailed" ] \endcode -\section3 NetworkManagerError +\section2 NetworkManagerError \code [ "NetworkManagerErrorNoError", @@ -375,7 +375,7 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} "NetworkManagerErrorNetworkManagerNotAvailable" ] \endcode -\section3 NetworkManagerState +\section2 NetworkManagerState \code [ "NetworkManagerStateUnknown", @@ -388,7 +388,7 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} "NetworkManagerStateConnectedGlobal" ] \endcode -\section3 Param +\section2 Param \code { "paramTypeId": "Uuid", @@ -396,16 +396,17 @@ See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} } \endcode See also: \l{BasicType} -\section3 ParamDescriptor +\section2 ParamDescriptor \code { + "o:paramName": "Uuid", + "o:paramTypeId": "Uuid", "operator": "$ref:ValueOperator", - "paramTypeId": "Uuid", "value": "$ref:BasicType" } \endcode -See also: \l{ValueOperator}, \l{BasicType} -\section3 ParamType +See also: \l{BasicType}, \l{ValueOperator} +\section2 ParamType \code { "displayName": "String", @@ -425,7 +426,7 @@ See also: \l{ValueOperator}, \l{BasicType} } \endcode See also: \l{Unit}, \l{InputType}, \l{BasicType} -\section3 Plugin +\section2 Plugin \code { "displayName": "String", @@ -437,14 +438,14 @@ See also: \l{Unit}, \l{InputType}, \l{BasicType} } \endcode See also: \l{ParamType} -\section3 RemovePolicy +\section2 RemovePolicy \code [ "RemovePolicyCascade", "RemovePolicyUpdate" ] \endcode -\section3 RepeatingMode +\section2 RepeatingMode \code [ "RepeatingModeNone", @@ -455,7 +456,7 @@ See also: \l{ParamType} "RepeatingModeYearly" ] \endcode -\section3 RepeatingOption +\section2 RepeatingOption \code { "mode": "$ref:RepeatingMode", @@ -468,7 +469,7 @@ See also: \l{ParamType} } \endcode See also: \l{RepeatingMode} -\section3 Rule +\section2 Rule \code { "actions": [ @@ -490,7 +491,7 @@ See also: \l{RepeatingMode} } \endcode See also: \l{TimeDescriptor}, \l{RuleAction}, \l{StateEvaluator}, \l{RuleAction}, \l{EventDescriptor} -\section3 RuleAction +\section2 RuleAction \code { "o:actionTypeId": "Uuid", @@ -503,7 +504,7 @@ See also: \l{TimeDescriptor}, \l{RuleAction}, \l{StateEvaluator}, \l{RuleAction} } \endcode See also: \l{RuleActionParam} -\section3 RuleActionParam +\section2 RuleActionParam \code { "o:eventParamTypeId": "Uuid", @@ -514,7 +515,7 @@ See also: \l{RuleActionParam} } \endcode See also: \l{BasicType} -\section3 RuleDescription +\section2 RuleDescription \code { "active": "Bool", @@ -525,7 +526,7 @@ See also: \l{BasicType} } \endcode -\section3 RuleError +\section2 RuleError \code [ "RuleErrorNoError", @@ -551,7 +552,7 @@ See also: \l{BasicType} "RuleErrorInterfaceNotFound" ] \endcode -\section3 ServerConfiguration +\section2 ServerConfiguration \code { "address": "String", @@ -562,7 +563,7 @@ See also: \l{BasicType} } \endcode -\section3 SetupMethod +\section2 SetupMethod \code [ "SetupMethodJustAdd", @@ -571,7 +572,7 @@ See also: \l{BasicType} "SetupMethodPushButton" ] \endcode -\section3 State +\section2 State \code { "deviceId": "Uuid", @@ -580,17 +581,19 @@ See also: \l{BasicType} } \endcode -\section3 StateDescriptor +\section2 StateDescriptor \code { - "deviceId": "Uuid", + "o:deviceId": "Uuid", + "o:interface": "String", + "o:interfaceState": "String", + "o:stateTypeId": "Uuid", "operator": "$ref:ValueOperator", - "stateTypeId": "Uuid", "value": "Variant" } \endcode See also: \l{ValueOperator} -\section3 StateEvaluator +\section2 StateEvaluator \code { "o:childEvaluators": [ @@ -601,14 +604,14 @@ See also: \l{ValueOperator} } \endcode See also: \l{StateEvaluator}, \l{StateDescriptor}, \l{StateOperator} -\section3 StateOperator +\section2 StateOperator \code [ "StateOperatorAnd", "StateOperatorOr" ] \endcode -\section3 StateType +\section2 StateType \code { "defaultValue": "Variant", @@ -628,7 +631,22 @@ See also: \l{StateEvaluator}, \l{StateDescriptor}, \l{StateOperator} } \endcode See also: \l{Unit}, \l{BasicType} -\section3 TimeDescriptor +\section2 Tag +\code +{ + "appId": "String", + "o:deviceId": "Uuid", + "o:ruleId": "Uuid", + "o:value": "String", + "tagId": "String" +} +\endcode + +\section2 TagError +\code +"$ref:TagError" +\endcode +\section2 TimeDescriptor \code { "o:calendarItems": [ @@ -640,7 +658,7 @@ See also: \l{Unit}, \l{BasicType} } \endcode See also: \l{TimeEventItem}, \l{CalendarItem} -\section3 TimeEventItem +\section2 TimeEventItem \code { "o:datetime": "Uint", @@ -649,7 +667,7 @@ See also: \l{TimeEventItem}, \l{CalendarItem} } \endcode See also: \l{RepeatingOption} -\section3 TokenInfo +\section2 TokenInfo \code { "creationTime": "Uint", @@ -659,7 +677,7 @@ See also: \l{RepeatingOption} } \endcode -\section3 Unit +\section2 Unit \code [ "UnitNone", @@ -714,7 +732,7 @@ See also: \l{RepeatingOption} "UnitAmpereHour" ] \endcode -\section3 UserError +\section2 UserError \code [ "UserErrorNoError", @@ -726,7 +744,7 @@ See also: \l{RepeatingOption} "UserErrorPermissionDenied" ] \endcode -\section3 ValueOperator +\section2 ValueOperator \code [ "ValueOperatorEquals", @@ -737,7 +755,7 @@ See also: \l{RepeatingOption} "ValueOperatorGreaterOrEqual" ] \endcode -\section3 Vendor +\section2 Vendor \code { "displayName": "String", @@ -746,7 +764,7 @@ See also: \l{RepeatingOption} } \endcode -\section3 WebServerConfiguration +\section2 WebServerConfiguration \code { "address": "String", @@ -757,7 +775,7 @@ See also: \l{RepeatingOption} } \endcode -\section3 WiredNetworkDevice +\section2 WiredNetworkDevice \code { "bitRate": "String", @@ -768,7 +786,7 @@ See also: \l{RepeatingOption} } \endcode See also: \l{NetworkDeviceState} -\section3 WirelessAccessPoint +\section2 WirelessAccessPoint \code { "frequency": "Double", @@ -779,7 +797,7 @@ See also: \l{NetworkDeviceState} } \endcode -\section3 WirelessNetworkDevice +\section2 WirelessNetworkDevice \code { "bitRate": "String", @@ -791,9 +809,9 @@ See also: \l{NetworkDeviceState} \endcode See also: \l{WirelessAccessPoint}, \l{NetworkDeviceState} \section1 Methods -\section3 Actions.ExecuteAction +\section2 Actions.ExecuteAction Execute a single action. -\section4 Params +Params \code { "actionTypeId": "Uuid", @@ -803,22 +821,22 @@ Execute a single action. ] } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError" } \endcode See also: \l{DeviceError}, \l{Param} -\section3 Actions.GetActionType +\section2 Actions.GetActionType Get the ActionType for the given ActionTypeId -\section4 Params +Params \code { "actionTypeId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -834,58 +852,58 @@ Get the ActionType for the given ActionTypeId } \endcode See also: \l{ParamType}, \l{DeviceError} -\section3 Configuration.DeleteTcpServerConfiguration +\section2 Configuration.DeleteTcpServerConfiguration Delete a TCP interface of the server. Note: if you are deleting the configuration for the interface you are currently connected to, the connection will be dropped. -\section4 Params +Params \code { "id": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.DeleteWebServerConfiguration +\section2 Configuration.DeleteWebServerConfiguration Delete a WebServer interface of the server. -\section4 Params +Params \code { "id": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.DeleteWebSocketServerConfiguration +\section2 Configuration.DeleteWebSocketServerConfiguration Delete a WebSocket Server interface of the server. Note: if you are deleting the configuration for the interface you are currently connected to, the connection will be dropped. -\section4 Params +Params \code { "id": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.GetAvailableLanguages +\section2 Configuration.GetAvailableLanguages Returns a list of locale codes available for the server. i.e. en_US, de_AT -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "languages": [ @@ -894,13 +912,13 @@ Returns a list of locale codes available for the server. i.e. en_US, de_AT } \endcode -\section3 Configuration.GetConfigurations +\section2 Configuration.GetConfigurations Get all configuration parameters of the server. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "basicConfiguration": { @@ -926,13 +944,13 @@ Get all configuration parameters of the server. } \endcode See also: \l{ServerConfiguration}, \l{WebServerConfiguration}, \l{ServerConfiguration} -\section3 Configuration.GetTimeZones +\section2 Configuration.GetTimeZones Get the list of available timezones. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "timeZones": [ @@ -941,129 +959,129 @@ Get the list of available timezones. } \endcode -\section3 Configuration.SetCloudEnabled +\section2 Configuration.SetCloudEnabled Sets whether the cloud connection is enabled or disabled in the settings. -\section4 Params +Params \code { "enabled": "Bool" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.SetDebugServerEnabled +\section2 Configuration.SetDebugServerEnabled Enable or disable the debug server. -\section4 Params +Params \code { "enabled": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.SetLanguage +\section2 Configuration.SetLanguage Sets the server language to the given language. See also: "GetAvailableLanguages" -\section4 Params +Params \code { "language": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.SetServerName +\section2 Configuration.SetServerName Set the name of the server. Default is nymea. -\section4 Params +Params \code { "serverName": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.SetTcpServerConfiguration +\section2 Configuration.SetTcpServerConfiguration Configure a TCP interface of the server. If the ID is an existing one, the existing config will be modified, otherwise a new one will be added. Note: if you are changing the configuration for the interface you are currently connected to, the connection will be dropped. -\section4 Params +Params \code { "configuration": "$ref:ServerConfiguration" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError}, \l{ServerConfiguration} -\section3 Configuration.SetTimeZone +\section2 Configuration.SetTimeZone Set the time zone of the server. See also: "GetTimeZones" -\section4 Params +Params \code { "timeZone": "String" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError} -\section3 Configuration.SetWebServerConfiguration +\section2 Configuration.SetWebServerConfiguration Configure a WebServer interface of the server. If the ID is an existing one, the existing config will be modified, otherwise a new one will be added. -\section4 Params +Params \code { "configuration": "$ref:WebServerConfiguration" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError}, \l{WebServerConfiguration} -\section3 Configuration.SetWebSocketServerConfiguration +\section2 Configuration.SetWebSocketServerConfiguration Configure a WebSocket Server interface of the server. If the ID is an existing one, the existing config will be modified, otherwise a new one will be added. Note: if you are changing the configuration for the interface you are currently connected to, the connection will be dropped. -\section4 Params +Params \code { "configuration": "$ref:ServerConfiguration" } \endcode -\section4 Returns +Returns \code { "configurationError": "$ref:ConfigurationError" } \endcode See also: \l{ConfigurationError}, \l{ServerConfiguration} -\section3 Devices.AddConfiguredDevice +\section2 Devices.AddConfiguredDevice Add a configured device with a setupMethod of SetupMethodJustAdd. For devices with a setupMethod different than SetupMethodJustAdd, use PairDevice. Use deviceDescriptorId or deviceParams, depending on the createMethod of the device class. CreateMethodJustAdd takes the parameters you want to have with that device. CreateMethodDiscovery requires the use of a deviceDescriptorId. -\section4 Params +Params \code { "deviceClassId": "Uuid", @@ -1074,7 +1092,7 @@ Add a configured device with a setupMethod of SetupMethodJustAdd. For devices wi ] } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1082,16 +1100,16 @@ Add a configured device with a setupMethod of SetupMethodJustAdd. For devices wi } \endcode See also: \l{DeviceError}, \l{Param} -\section3 Devices.ConfirmPairing +\section2 Devices.ConfirmPairing Confirm an ongoing pairing. In case of SetupMethodEnterPin also provide the pin in the params. -\section4 Params +Params \code { "o:secret": "String", "pairingTransactionId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1099,31 +1117,31 @@ Confirm an ongoing pairing. In case of SetupMethodEnterPin also provide the pin } \endcode See also: \l{DeviceError} -\section3 Devices.EditDevice +\section2 Devices.EditDevice Edit the name of a device. This method does not change the configuration of the device. -\section4 Params +Params \code { "deviceId": "Uuid", "name": "String" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError" } \endcode See also: \l{DeviceError} -\section3 Devices.GetActionTypes +\section2 Devices.GetActionTypes Get action types for a specified deviceClassId. -\section4 Params +Params \code { "deviceClassId": "Uuid" } \endcode -\section4 Returns +Returns \code { "actionTypes": [ @@ -1132,15 +1150,15 @@ Get action types for a specified deviceClassId. } \endcode See also: \l{ActionType} -\section3 Devices.GetConfiguredDevices +\section2 Devices.GetConfiguredDevices Returns a list of configured devices, optionally filtered by deviceId. -\section4 Params +Params \code { "o:deviceId": "Uuid" } \endcode -\section4 Returns +Returns \code { "devices": [ @@ -1149,9 +1167,9 @@ Returns a list of configured devices, optionally filtered by deviceId. } \endcode See also: \l{Device} -\section3 Devices.GetDiscoveredDevices +\section2 Devices.GetDiscoveredDevices Performs a device discovery and returns the results. This function may take a while to return. -\section4 Params +Params \code { "deviceClassId": "Uuid", @@ -1160,7 +1178,7 @@ Performs a device discovery and returns the results. This function may take a wh ] } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1170,15 +1188,15 @@ Performs a device discovery and returns the results. This function may take a wh } \endcode See also: \l{DeviceDescriptor}, \l{DeviceError}, \l{Param} -\section3 Devices.GetEventTypes +\section2 Devices.GetEventTypes Get event types for a specified deviceClassId. -\section4 Params +Params \code { "deviceClassId": "Uuid" } \endcode -\section4 Returns +Returns \code { "eventTypes": [ @@ -1187,15 +1205,15 @@ Get event types for a specified deviceClassId. } \endcode See also: \l{EventType} -\section3 Devices.GetPluginConfiguration +\section2 Devices.GetPluginConfiguration Get a plugin's params. -\section4 Params +Params \code { "pluginId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1205,13 +1223,13 @@ Get a plugin's params. } \endcode See also: \l{Param}, \l{DeviceError} -\section3 Devices.GetPlugins +\section2 Devices.GetPlugins Returns a list of loaded plugins. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "plugins": [ @@ -1220,15 +1238,15 @@ Returns a list of loaded plugins. } \endcode See also: \l{Plugin} -\section3 Devices.GetStateTypes +\section2 Devices.GetStateTypes Get state types for a specified deviceClassId. -\section4 Params +Params \code { "deviceClassId": "Uuid" } \endcode -\section4 Returns +Returns \code { "stateTypes": [ @@ -1237,16 +1255,16 @@ Get state types for a specified deviceClassId. } \endcode See also: \l{StateType} -\section3 Devices.GetStateValue +\section2 Devices.GetStateValue Get the value of the given device and the given stateType -\section4 Params +Params \code { "deviceId": "Uuid", "stateTypeId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1254,15 +1272,15 @@ Get the value of the given device and the given stateType } \endcode See also: \l{DeviceError} -\section3 Devices.GetStateValues +\section2 Devices.GetStateValues Get all the state values of the given device. -\section4 Params +Params \code { "deviceId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1275,15 +1293,15 @@ Get all the state values of the given device. } \endcode See also: \l{DeviceError} -\section3 Devices.GetSupportedDevices +\section2 Devices.GetSupportedDevices Returns a list of supported Device classes, optionally filtered by vendorId. -\section4 Params +Params \code { "o:vendorId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceClasses": [ @@ -1292,13 +1310,13 @@ Returns a list of supported Device classes, optionally filtered by vendorId. } \endcode See also: \l{DeviceClass} -\section3 Devices.GetSupportedVendors +\section2 Devices.GetSupportedVendors Returns a list of supported Vendors. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "vendors": [ @@ -1307,9 +1325,9 @@ Returns a list of supported Vendors. } \endcode See also: \l{Vendor} -\section3 Devices.PairDevice +\section2 Devices.PairDevice Pair a device. Use this for DeviceClasses with a setupMethod different than SetupMethodJustAdd. Use deviceDescriptorId or deviceParams, depending on the createMethod of the device class. CreateMethodJustAdd takes the parameters you want to have with that device. CreateMethodDiscovery requires the use of a deviceDescriptorId. If success is true, the return values will contain a pairingTransactionId, a displayMessage and the setupMethod. Depending on the setupMethod you should either proceed with AddConfiguredDevice or PairDevice. -\section4 Params +Params \code { "deviceClassId": "Uuid", @@ -1320,7 +1338,7 @@ Pair a device. Use this for DeviceClasses with a setupMethod different than Setu ] } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1330,9 +1348,9 @@ Pair a device. Use this for DeviceClasses with a setupMethod different than Setu } \endcode See also: \l{SetupMethod}, \l{DeviceError}, \l{Param} -\section3 Devices.ReconfigureDevice +\section2 Devices.ReconfigureDevice Edit the parameter configuration of the device. The device params will be set to the passed parameters and the setup device will be called. If the device is discoverable, you can perform a GetDiscoveredDevices before calling this method and pass the new DeviceDescriptor (rediscover). Only writable parameters can be changed. By default, every Param is writable. -\section4 Params +Params \code { "deviceId": "Uuid", @@ -1342,16 +1360,16 @@ Edit the parameter configuration of the device. The device params will be set to ] } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError" } \endcode See also: \l{DeviceError}, \l{Param} -\section3 Devices.RemoveConfiguredDevice +\section2 Devices.RemoveConfiguredDevice Remove a device from the system. -\section4 Params +Params \code { "deviceId": "Uuid", @@ -1364,7 +1382,7 @@ Remove a device from the system. ] } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1374,9 +1392,9 @@ Remove a device from the system. } \endcode See also: \l{DeviceError}, \l{RemovePolicy}, \l{RemovePolicy} -\section3 Devices.SetPluginConfiguration +\section2 Devices.SetPluginConfiguration Set a plugin's params. -\section4 Params +Params \code { "configuration": [ @@ -1385,22 +1403,22 @@ Set a plugin's params. "pluginId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError" } \endcode See also: \l{DeviceError}, \l{Param} -\section3 Events.GetEventType +\section2 Events.GetEventType Get the EventType for the given eventTypeId. -\section4 Params +Params \code { "eventTypeId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1408,9 +1426,9 @@ Get the EventType for the given eventTypeId. } \endcode See also: \l{EventType}, \l{DeviceError} -\section3 JSONRPC.Authenticate +\section2 JSONRPC.Authenticate Authenticate a client to the api via user & password challenge. Provide a device name which allows the user to identify the client and revoke the token in case the device is lost or stolen. This will return a new token to be used to authorize a client at the API. -\section4 Params +Params \code { "deviceName": "String", @@ -1418,7 +1436,7 @@ Authenticate a client to the api via user & password challenge. Provide a device "username": "String" } \endcode -\section4 Returns +Returns \code { "o:token": "String", @@ -1426,29 +1444,29 @@ Authenticate a client to the api via user & password challenge. Provide a device } \endcode -\section3 JSONRPC.CreateUser +\section2 JSONRPC.CreateUser Create a new user in the API. Currently this is only allowed to be called once when a new nymea instance is set up. Call Authenticate after this to obtain a device token for this user. -\section4 Params +Params \code { "password": "String", "username": "String" } \endcode -\section4 Returns +Returns \code { "error": "$ref:UserError" } \endcode See also: \l{UserError} -\section3 JSONRPC.Hello +\section2 JSONRPC.Hello Upon first connection, nymea will automatically send a welcome message containing information about the setup. If this message is lost for whatever reason (connections with multiple hops might drop this if nymea sends it too early), the exact same message can be retrieved multiple times by calling this Hello method. Note that the contents might change if the system changed its state in the meantime, e.g. initialSetupRequired might turn false if the initial setup has been performed in the meantime. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "authenticationRequired": "Bool", @@ -1464,13 +1482,13 @@ Upon first connection, nymea will automatically send a welcome message containin } \endcode -\section3 JSONRPC.Introspect +\section2 JSONRPC.Introspect Introspect this API. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "methods": "Object", @@ -1478,58 +1496,58 @@ Introspect this API. } \endcode -\section3 JSONRPC.IsCloudConnected +\section2 JSONRPC.IsCloudConnected Check whether the cloud is currently connected. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "connected": "Bool" } \endcode -\section3 JSONRPC.KeepAlive +\section2 JSONRPC.KeepAlive Keep alive a remote connection. The sessionId is the MQTT topic which has been used to establish the session. It will return false if no ongoing session with the given ID can be found. -\section4 Params +Params \code { "sessionId": "String" } \endcode -\section4 Returns +Returns \code { "success": "Bool" } \endcode -\section3 JSONRPC.RemoveToken +\section2 JSONRPC.RemoveToken Revoke access for a given token. -\section4 Params +Params \code { "tokenId": "Uuid" } \endcode -\section4 Returns +Returns \code { "error": "$ref:UserError" } \endcode See also: \l{UserError} -\section3 JSONRPC.RequestPushButtonAuth +\section2 JSONRPC.RequestPushButtonAuth Authenticate a client to the api via Push Button method. Provide a device name which allows the user to identify the client and revoke the token in case the device is lost or stolen. If push button hardware is available, this will return with success and start listening for push button presses. When the push button is pressed, the PushButtonAuthFinished notification will be sent to the requesting client. The procedure will be cancelled when the connection is interrupted. If another client requests push button authentication while a procedure is still going on, the second call will take over and the first one will be notified by the PushButtonAuthFinished signal about the error. The application should make it clear to the user to not press the button when the procedure fails as this can happen for 2 reasons: a) a second user is trying to auth at the same time and only the currently active user should press the button or b) it might indicate an attacker trying to take over and snooping in for tokens. -\section4 Params +Params \code { "deviceName": "String" } \endcode -\section4 Returns +Returns \code { "success": "Bool", @@ -1537,31 +1555,31 @@ Authenticate a client to the api via Push Button method. Provide a device name w } \endcode -\section3 JSONRPC.SetNotificationStatus +\section2 JSONRPC.SetNotificationStatus Enable/Disable notifications for this connections. -\section4 Params +Params \code { "enabled": "Bool" } \endcode -\section4 Returns +Returns \code { "enabled": "Bool" } \endcode -\section3 JSONRPC.SetupRemoteAccess +\section2 JSONRPC.SetupRemoteAccess Setup the remote connection by providing AWS token information. This requires the cloud to be connected. -\section4 Params +Params \code { "idToken": "String", "userId": "String" } \endcode -\section4 Returns +Returns \code { "message": "String", @@ -1569,13 +1587,13 @@ Setup the remote connection by providing AWS token information. This requires th } \endcode -\section3 JSONRPC.Tokens +\section2 JSONRPC.Tokens Return a list of TokenInfo objects of all the tokens for the current user. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "tokenInfoList": [ @@ -1584,13 +1602,13 @@ Return a list of TokenInfo objects of all the tokens for the current user. } \endcode See also: \l{TokenInfo} -\section3 JSONRPC.Version +\section2 JSONRPC.Version Version of this nymea/JSONRPC interface. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "protocol version": "String", @@ -1598,9 +1616,9 @@ Version of this nymea/JSONRPC interface. } \endcode -\section3 Logging.GetLogEntries +\section2 Logging.GetLogEntries Get the LogEntries matching the given filter. Each list element of a given filter will be connected with OR to each other. Each of the given filters will be connected with AND to each other. -\section4 Params +Params \code { "o:deviceIds": [ @@ -1629,7 +1647,7 @@ Get the LogEntries matching the given filter. Each list element of a given filte ] } \endcode -\section4 Returns +Returns \code { "loggingError": "$ref:LoggingError", @@ -1639,9 +1657,9 @@ Get the LogEntries matching the given filter. Each list element of a given filte } \endcode See also: \l{LogEntry}, \l{LoggingError}, \l{LoggingLevel}, \l{LoggingEventType}, \l{LoggingSource} -\section3 NetworkManager.ConnectWifiNetwork +\section2 NetworkManager.ConnectWifiNetwork Connect to the wifi network with the given ssid and password. -\section4 Params +Params \code { "interface": "String", @@ -1649,65 +1667,65 @@ Connect to the wifi network with the given ssid and password. "ssid": "String" } \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError" } \endcode See also: \l{NetworkManagerError} -\section3 NetworkManager.DisconnectInterface +\section2 NetworkManager.DisconnectInterface Disconnect the given network interface. The interface will remain disconnected until the user connect it again. -\section4 Params +Params \code { "interface": "String" } \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError" } \endcode See also: \l{NetworkManagerError} -\section3 NetworkManager.EnableNetworking +\section2 NetworkManager.EnableNetworking Enable or disable networking in the NetworkManager. -\section4 Params +Params \code { "enable": "Bool" } \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError" } \endcode See also: \l{NetworkManagerError} -\section3 NetworkManager.EnableWirelessNetworking +\section2 NetworkManager.EnableWirelessNetworking Enable or disable wireless networking in the NetworkManager. -\section4 Params +Params \code { "enable": "Bool" } \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError" } \endcode See also: \l{NetworkManagerError} -\section3 NetworkManager.GetNetworkDevices +\section2 NetworkManager.GetNetworkDevices Get the list of current network devices. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError", @@ -1720,13 +1738,13 @@ Get the list of current network devices. } \endcode See also: \l{NetworkManagerError}, \l{WiredNetworkDevice}, \l{WirelessNetworkDevice} -\section3 NetworkManager.GetNetworkStatus +\section2 NetworkManager.GetNetworkStatus Get the current network manager status. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError", @@ -1738,15 +1756,15 @@ Get the current network manager status. } \endcode See also: \l{NetworkManagerError}, \l{NetworkManagerState} -\section3 NetworkManager.GetWirelessAccessPoints +\section2 NetworkManager.GetWirelessAccessPoints Get the current list of wireless network access points for the given interface. The interface has to be a WirelessNetworkDevice. -\section4 Params +Params \code { "interface": "String" } \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError", @@ -1756,24 +1774,24 @@ Get the current list of wireless network access points for the given interface. } \endcode See also: \l{NetworkManagerError}, \l{WirelessAccessPoint} -\section3 NetworkManager.ScanWifiNetworks +\section2 NetworkManager.ScanWifiNetworks Start a wifi scan for searching new networks. -\section4 Params +Params \code { "interface": "String" } \endcode -\section4 Returns +Returns \code { "networkManagerError": "$ref:NetworkManagerError" } \endcode See also: \l{NetworkManagerError} -\section3 Rules.AddRule -Add a rule. You can describe rules by one or many EventDesciptors and a StateEvaluator. Note that only one of either eventDescriptor or eventDescriptorList may be passed at a time. A rule can be created but left disabled, meaning it won't actually be executed until set to enabled. If not given, enabled defaults to true. -\section4 Params +\section2 Rules.AddRule +Add a rule. You can describe rules by one or many EventDesciptors and a StateEvaluator. Note that only one of either eventDescriptor or eventDescriptorList may be passed at a time. A rule can be created but left disabled, meaning it won't actually be executed until set to enabled. If not given, enabled defaults to true. A rule can have a list of actions and exitActions. It must have at least one Action. For state based rules, actions will be executed when the system enters a state matching the stateDescriptor. The exitActions will be executed when the system leaves the described state again. For event based rules, actions will be executed when a matching event happens and if the stateEvaluator matches the system's state. ExitActions for such rules will be executed when a matching event happens and the stateEvaluator is not matching the system's state. A rule marked as executable can be executed via the API using Rules.ExecuteRule, that means, its actions will be executed regardless of the the eventDescriptor and stateEvaluators. +Params \code { "actions": [ @@ -1792,7 +1810,7 @@ Add a rule. You can describe rules by one or many EventDesciptors and a StateEva "o:timeDescriptor": "$ref:TimeDescriptor" } \endcode -\section4 Returns +Returns \code { "o:ruleId": "Uuid", @@ -1800,24 +1818,24 @@ Add a rule. You can describe rules by one or many EventDesciptors and a StateEva } \endcode See also: \l{RuleError}, \l{RuleAction}, \l{TimeDescriptor}, \l{RuleAction}, \l{EventDescriptor}, \l{StateEvaluator} -\section3 Rules.DisableRule +\section2 Rules.DisableRule Disable a rule. The rule won't be triggered by it's events or state changes while it is disabled. If successful, the notification "Rule.RuleConfigurationChanged" will be emitted. -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "ruleError": "$ref:RuleError" } \endcode See also: \l{RuleError} -\section3 Rules.EditRule +\section2 Rules.EditRule Edit the parameters of a rule. The configuration of the rule with the given ruleId will be replaced with the new given configuration. In ordert to enable or disable a Rule, please use the methods "Rules.EnableRule" and "Rules.DisableRule". If successful, the notification "Rule.RuleConfigurationChanged" will be emitted. -\section4 Params +Params \code { "actions": [ @@ -1837,7 +1855,7 @@ Edit the parameters of a rule. The configuration of the rule with the given rule "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "o:rule": "$ref:Rule", @@ -1845,60 +1863,60 @@ Edit the parameters of a rule. The configuration of the rule with the given rule } \endcode See also: \l{RuleError}, \l{Rule}, \l{RuleAction}, \l{TimeDescriptor}, \l{RuleAction}, \l{EventDescriptor}, \l{StateEvaluator} -\section3 Rules.EnableRule +\section2 Rules.EnableRule Enabled a rule that has previously been disabled.If successful, the notification "Rule.RuleConfigurationChanged" will be emitted. -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "ruleError": "$ref:RuleError" } \endcode See also: \l{RuleError} -\section3 Rules.ExecuteActions +\section2 Rules.ExecuteActions Execute the action list of the rule with the given ruleId. -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "ruleError": "$ref:RuleError" } \endcode See also: \l{RuleError} -\section3 Rules.ExecuteExitActions +\section2 Rules.ExecuteExitActions Execute the exit action list of the rule with the given ruleId. -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "ruleError": "$ref:RuleError" } \endcode See also: \l{RuleError} -\section3 Rules.FindRules +\section2 Rules.FindRules Find a list of rules containing any of the given parameters. -\section4 Params +Params \code { "deviceId": "Uuid" } \endcode -\section4 Returns +Returns \code { "ruleIds": [ @@ -1907,15 +1925,15 @@ Find a list of rules containing any of the given parameters. } \endcode -\section3 Rules.GetRuleDetails +\section2 Rules.GetRuleDetails Get details for the rule identified by ruleId -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "o:rule": "$ref:Rule", @@ -1923,13 +1941,13 @@ Get details for the rule identified by ruleId } \endcode See also: \l{RuleError}, \l{Rule} -\section3 Rules.GetRules +\section2 Rules.GetRules Get the descriptions of all configured rules. If you need more information about a specific rule use the method Rules.GetRuleDetails. -\section4 Params +Params \code {} \endcode -\section4 Returns +Returns \code { "ruleDescriptions": [ @@ -1938,30 +1956,30 @@ Get the descriptions of all configured rules. If you need more information about } \endcode See also: \l{RuleDescription} -\section3 Rules.RemoveRule +\section2 Rules.RemoveRule Remove a rule -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode -\section4 Returns +Returns \code { "ruleError": "$ref:RuleError" } \endcode See also: \l{RuleError} -\section3 States.GetStateType +\section2 States.GetStateType Get the StateType for the given stateTypeId. -\section4 Params +Params \code { "stateTypeId": "Uuid" } \endcode -\section4 Returns +Returns \code { "deviceError": "$ref:DeviceError", @@ -1969,10 +1987,61 @@ Get the StateType for the given stateTypeId. } \endcode See also: \l{StateType}, \l{DeviceError} -\section2 Notifications -\section3 Configuration.BasicConfigurationChanged +\section2 Tags.AddTag +Add a Tag. A Tag must have a deviceId OR a ruleId (call this method twice if you want to attach the same tag to a device and a rule), an appId (Use the appId of your app), a tagId (e.g. "favorites") and a value. Upon success, a TagAdded notification will be emitted. Calling this method twice for the same ids (device/rule, appId and tagId) but with a different value will update the tag's value and the TagValueChanged notification will be emitted. +Params +\code +{ + "tag": "$ref:Tag" +} +\endcode +Returns +\code +{ + "tagError": "$ref:TagError" +} +\endcode +See also: \l{TagError}, \l{Tag} +\section2 Tags.GetTags +Get the Tags matching the given filter. Tags can be filtered by a deviceID, a ruleId, an appId, a tagId or a combination of any (however, combining deviceId and ruleId will return an empty result set). +Params +\code +{ + "o:appId": "String", + "o:deviceId": "Uuid", + "o:ruleId": "Uuid", + "o:tagId": "String" +} +\endcode +Returns +\code +{ + "o:tags": [ + "$ref:Tag" + ], + "tagError": "$ref:TagError" +} +\endcode +See also: \l{TagError}, \l{Tag} +\section2 Tags.RemoveTag +Remove a Tag. Tag value is optional and will be disregarded. If the ids match, the tag will be deleted and a TagRemoved notification will be emitted. +Params +\code +{ + "tag": "$ref:Tag" +} +\endcode +Returns +\code +{ + "tagError": "$ref:TagError" +} +\endcode +See also: \l{TagError}, \l{Tag} +\section1 Notifications +\section2 Configuration.BasicConfigurationChanged Emitted whenever the basic configuration of this server changes. -\section4 Params +Params \code { "debugServerEnabled": "Bool", @@ -1983,27 +2052,27 @@ Emitted whenever the basic configuration of this server changes. } \endcode -\section3 Configuration.CloudConfigurationChanged +\section2 Configuration.CloudConfigurationChanged Emitted whenever the cloud configuration is changed. -\section4 Params +Params \code { "enabled": "Bool" } \endcode -\section3 Configuration.LanguageChanged +\section2 Configuration.LanguageChanged Emitted whenever the language of the server changed. The Plugins, Vendors and DeviceClasses have to be reloaded to get the translated data. -\section4 Params +Params \code { "language": "String" } \endcode -\section3 Configuration.TcpServerConfigurationChanged +\section2 Configuration.TcpServerConfigurationChanged Emitted whenever the TCP server configuration changes. -\section4 Params +Params \code { "host": "String", @@ -2011,9 +2080,9 @@ Emitted whenever the TCP server configuration changes. } \endcode -\section3 Configuration.WebServerConfigurationChanged +\section2 Configuration.WebServerConfigurationChanged Emitted whenever the web server configuration changes. -\section4 Params +Params \code { "host": "String", @@ -2021,9 +2090,9 @@ Emitted whenever the web server configuration changes. } \endcode -\section3 Configuration.WebSocketServerConfigurationChanged +\section2 Configuration.WebSocketServerConfigurationChanged Emitted whenever the web socket server configuration changes. -\section4 Params +Params \code { "host": "String", @@ -2031,36 +2100,36 @@ Emitted whenever the web socket server configuration changes. } \endcode -\section3 Devices.DeviceAdded +\section2 Devices.DeviceAdded Emitted whenever a Device was added. -\section4 Params +Params \code { "device": "$ref:Device" } \endcode See also: \l{Device} -\section3 Devices.DeviceChanged +\section2 Devices.DeviceChanged Emitted whenever the params or name of a Device changed (by EditDevice or ReconfigureDevice). -\section4 Params +Params \code { "device": "$ref:Device" } \endcode See also: \l{Device} -\section3 Devices.DeviceRemoved +\section2 Devices.DeviceRemoved Emitted whenever a Device was removed. -\section4 Params +Params \code { "deviceId": "Uuid" } \endcode -\section3 Devices.StateChanged +\section2 Devices.StateChanged Emitted whenever a State of a device changes. -\section4 Params +Params \code { "deviceId": "Uuid", @@ -2069,27 +2138,27 @@ Emitted whenever a State of a device changes. } \endcode -\section3 Events.EventTriggered +\section2 Events.EventTriggered Emitted whenever an Event is triggered. -\section4 Params +Params \code { "event": "$ref:Event" } \endcode See also: \l{Event} -\section3 JSONRPC.CloudConnectedChanged +\section2 JSONRPC.CloudConnectedChanged Emitted whenever the cloud connection status changes. -\section4 Params +Params \code { "connected": "Bool" } \endcode -\section3 JSONRPC.PushButtonAuthFinished +\section2 JSONRPC.PushButtonAuthFinished Emitted when a push button authentication reaches final state. NOTE: This notification is special. It will only be emitted to connections that did actively request a push button authentication, but also it will be emitted regardless of the notification settings. -\section4 Params +Params \code { "o:token": "String", @@ -2098,25 +2167,25 @@ Emitted when a push button authentication reaches final state. NOTE: This notifi } \endcode See also: \l{UserError} -\section3 Logging.LogDatabaseUpdated +\section2 Logging.LogDatabaseUpdated Emitted whenever the database was updated. The database will be updated when a log entry was deleted. A log entry will be deleted when the corresponding device or a rule will be removed, or when the oldest entry of the database was deleted to keep to database in the size limits. -\section4 Params +Params \code {} \endcode -\section3 Logging.LogEntryAdded +\section2 Logging.LogEntryAdded Emitted whenever an entry is appended to the logging system. -\section4 Params +Params \code { "logEntry": "$ref:LogEntry" } \endcode See also: \l{LogEntry} -\section3 NetworkManager.NetworkStatusChanged +\section2 NetworkManager.NetworkStatusChanged Emitted whenever a status of a NetworkManager changes. -\section4 Params +Params \code { "status": { @@ -2127,63 +2196,63 @@ Emitted whenever a status of a NetworkManager changes. } \endcode See also: \l{NetworkManagerState} -\section3 NetworkManager.WiredNetworkDeviceAdded +\section2 NetworkManager.WiredNetworkDeviceAdded Emitted whenever a new WiredNetworkDevice was added. -\section4 Params +Params \code { "wiredNetworkDevice": "$ref:WiredNetworkDevice" } \endcode See also: \l{WiredNetworkDevice} -\section3 NetworkManager.WiredNetworkDeviceChanged +\section2 NetworkManager.WiredNetworkDeviceChanged Emitted whenever the given WiredNetworkDevice has changed. -\section4 Params +Params \code { "wiredNetworkDevice": "$ref:WiredNetworkDevice" } \endcode See also: \l{WiredNetworkDevice} -\section3 NetworkManager.WiredNetworkDeviceRemoved +\section2 NetworkManager.WiredNetworkDeviceRemoved Emitted whenever a WiredNetworkDevice was removed. -\section4 Params +Params \code { "interface": "String" } \endcode -\section3 NetworkManager.WirelessNetworkDeviceAdded +\section2 NetworkManager.WirelessNetworkDeviceAdded Emitted whenever a new WirelessNetworkDevice was added. -\section4 Params +Params \code { "wirelessNetworkDevice": "$ref:WirelessNetworkDevice" } \endcode See also: \l{WirelessNetworkDevice} -\section3 NetworkManager.WirelessNetworkDeviceChanged +\section2 NetworkManager.WirelessNetworkDeviceChanged Emitted whenever the given WirelessNetworkDevice has changed. -\section4 Params +Params \code { "wirelessNetworkDevice": "$ref:WirelessNetworkDevice" } \endcode See also: \l{WirelessNetworkDevice} -\section3 NetworkManager.WirelessNetworkDeviceRemoved +\section2 NetworkManager.WirelessNetworkDeviceRemoved Emitted whenever a WirelessNetworkDevice was removed. -\section4 Params +Params \code { "interface": "String" } \endcode -\section3 Rules.RuleActiveChanged +\section2 Rules.RuleActiveChanged Emitted whenever the active state of a Rule changed. -\section4 Params +Params \code { "active": "Bool", @@ -2191,33 +2260,60 @@ Emitted whenever the active state of a Rule changed. } \endcode -\section3 Rules.RuleAdded +\section2 Rules.RuleAdded Emitted whenever a Rule was added. -\section4 Params +Params \code { "rule": "$ref:Rule" } \endcode See also: \l{Rule} -\section3 Rules.RuleConfigurationChanged +\section2 Rules.RuleConfigurationChanged Emitted whenever the configuration of a Rule changed. -\section4 Params +Params \code { "rule": "$ref:Rule" } \endcode See also: \l{Rule} -\section3 Rules.RuleRemoved +\section2 Rules.RuleRemoved Emitted whenever a Rule was removed. -\section4 Params +Params \code { "ruleId": "Uuid" } \endcode +\section2 Tags.TagAdded +Emitted whenever a tag is added to the system. +Params +\code +{ + "tag": "$ref:Tag" +} +\endcode +See also: \l{Tag} +\section2 Tags.TagRemoved +Emitted whenever a tag is removed from the system. +Params +\code +{ + "tag": "$ref:Tag" +} +\endcode +See also: \l{Tag} +\section2 Tags.TagValueChanged +Emitted whenever a tag's value is changed in the system. +Params +\code +{ + "tag": "$ref:Tag" +} +\endcode +See also: \l{Tag} \section1 Full introspect \code { @@ -2867,7 +2963,7 @@ Emitted whenever a Rule was removed. } }, "Rules.AddRule": { - "description": "Add a rule. You can describe rules by one or many EventDesciptors and a StateEvaluator. Note that only one of either eventDescriptor or eventDescriptorList may be passed at a time. A rule can be created but left disabled, meaning it won't actually be executed until set to enabled. If not given, enabled defaults to true.", + "description": "Add a rule. You can describe rules by one or many EventDesciptors and a StateEvaluator. Note that only one of either eventDescriptor or eventDescriptorList may be passed at a time. A rule can be created but left disabled, meaning it won't actually be executed until set to enabled. If not given, enabled defaults to true. A rule can have a list of actions and exitActions. It must have at least one Action. For state based rules, actions will be executed when the system enters a state matching the stateDescriptor. The exitActions will be executed when the system leaves the described state again. For event based rules, actions will be executed when a matching event happens and if the stateEvaluator matches the system's state. ExitActions for such rules will be executed when a matching event happens and the stateEvaluator is not matching the system's state. A rule marked as executable can be executed via the API using Rules.ExecuteRule, that means, its actions will be executed regardless of the the eventDescriptor and stateEvaluators.", "params": { "actions": [ "$ref:RuleAction" @@ -2997,6 +3093,39 @@ Emitted whenever a Rule was removed. "deviceError": "$ref:DeviceError", "o:stateType": "$ref:StateType" } + }, + "Tags.AddTag": { + "description": "Add a Tag. A Tag must have a deviceId OR a ruleId (call this method twice if you want to attach the same tag to a device and a rule), an appId (Use the appId of your app), a tagId (e.g. \"favorites\") and a value. Upon success, a TagAdded notification will be emitted. Calling this method twice for the same ids (device/rule, appId and tagId) but with a different value will update the tag's value and the TagValueChanged notification will be emitted.", + "params": { + "tag": "$ref:Tag" + }, + "returns": { + "tagError": "$ref:TagError" + } + }, + "Tags.GetTags": { + "description": "Get the Tags matching the given filter. Tags can be filtered by a deviceID, a ruleId, an appId, a tagId or a combination of any (however, combining deviceId and ruleId will return an empty result set).", + "params": { + "o:appId": "String", + "o:deviceId": "Uuid", + "o:ruleId": "Uuid", + "o:tagId": "String" + }, + "returns": { + "o:tags": [ + "$ref:Tag" + ], + "tagError": "$ref:TagError" + } + }, + "Tags.RemoveTag": { + "description": "Remove a Tag. Tag value is optional and will be disregarded. If the ids match, the tag will be deleted and a TagRemoved notification will be emitted.", + "params": { + "tag": "$ref:Tag" + }, + "returns": { + "tagError": "$ref:TagError" + } } }, "notifications": { @@ -3169,6 +3298,24 @@ Emitted whenever a Rule was removed. "params": { "ruleId": "Uuid" } + }, + "Tags.TagAdded": { + "description": "Emitted whenever a tag is added to the system. ", + "params": { + "tag": "$ref:Tag" + } + }, + "Tags.TagRemoved": { + "description": "Emitted whenever a tag is removed from the system. ", + "params": { + "tag": "$ref:Tag" + } + }, + "Tags.TagValueChanged": { + "description": "Emitted whenever a tag's value is changed in the system. ", + "params": { + "tag": "$ref:Tag" + } } }, "types": { @@ -3477,8 +3624,9 @@ Emitted whenever a Rule was removed. "value": "$ref:BasicType" }, "ParamDescriptor": { + "o:paramName": "Uuid", + "o:paramTypeId": "Uuid", "operator": "$ref:ValueOperator", - "paramTypeId": "Uuid", "value": "$ref:BasicType" }, "ParamType": { @@ -3609,9 +3757,11 @@ Emitted whenever a Rule was removed. "value": "Variant" }, "StateDescriptor": { - "deviceId": "Uuid", + "o:deviceId": "Uuid", + "o:interface": "String", + "o:interfaceState": "String", + "o:stateTypeId": "Uuid", "operator": "$ref:ValueOperator", - "stateTypeId": "Uuid", "value": "Variant" }, "StateEvaluator": { @@ -3641,6 +3791,14 @@ Emitted whenever a Rule was removed. "o:unit": "$ref:Unit", "type": "$ref:BasicType" }, + "Tag": { + "appId": "String", + "o:deviceId": "Uuid", + "o:ruleId": "Uuid", + "o:value": "String", + "tagId": "String" + }, + "TagError": "$ref:TagError", "TimeDescriptor": { "o:calendarItems": [ "$ref:CalendarItem" diff --git a/doc/main.css b/doc/main.css index 80e8c075..8c12ac75 100644 --- a/doc/main.css +++ b/doc/main.css @@ -58,7 +58,7 @@ body { } ol, ul { - list-style: none; + list-style: list-style-type:circle; } blockquote, q { @@ -829,22 +829,49 @@ div.header + li { color: #676767; } -.content .sidebar ul { +.content .sidebar ul li { padding-left: 0; + list-style-type: circle; + text-align: left; +} + +/* +.content .sidebar .level2:before { + content: "#"; + background-image: none; + text-align: right; +} +*/ + +.content .sidebar .level1 { + font-size: 1.2rem; + line-height: 1.5; + list-style: "- "; } .content .sidebar .level2 { font-size: 1rem; - margin-left: 1rem; + margin-left: 1.5rem; line-height: 1.5; + list-style-type: circle; } +.content .sidebar .level3 { + font-size: 1rem; + margin-left: 2rem; + line-height: 1.5; + list-style: "→ "; +} + + +/* .content .sidebar .level2:before { content: "-"; background-image: none; text-align: right; } +*/ .content .context { width: 90%; margin: 0 -120px 0 auto; @@ -869,7 +896,7 @@ div.header + li { .content ul li { line-height: 1.5; position: relative; - padding-left: calc(1.5em + 10px); + padding-left: 1; } .content ul li::before { diff --git a/doc/plugin-wizard.qdoc b/doc/plugin-wizard.qdoc index d24d9af8..0cef88f6 100644 --- a/doc/plugin-wizard.qdoc +++ b/doc/plugin-wizard.qdoc @@ -1,6 +1,6 @@ /*! \example template - \title Plugin wizard + \title 1. Plugin wizard \ingroup tutorials \brief Explanation of the Qt Creator plugin wizard template @@ -9,6 +9,88 @@ qt-creator wizard on our \l{https://github.com/guh/nymea-qtcreator-wizards}{github page}. + \section1 Create the plugin project + Once you have installed all packages required for development, you can open the Qt Creator and start a new project. + If you need help with the overall Qt Creator project creation, you can find more information + \l{http://doc.qt.io/qtcreator/creator-project-creating.html}{here}. + + \section2 Choose template + In the template view cou can find now the nymea section. In that section you can find the template for a new plugin. + \image plugin-template-1.png Create a new plugin + + + \section2 Project location + Choose the project name and the path where the project should be located. As in this example the name is \e{template} + and will be used within the source code as refference. A good practice is to pick a general describing name like a vendor + or product/project name. + \image plugin-template-2.png Project location + + \section2 Plugin details + In this section the plugin details can be defined. + + In the first part you can find the c++ specific definitions: + \list + \li \b{Class name}: Enter the name of the main class for this device plugin. + The naming should be \tt{DevicePlugin\e{Name}} in camel case. + \endlist + + In the second part you can find the json specific definitions: + \list + \li \b{Vendor name}: Enter the name of the \l{Vendor}. + \li \b{Device name}: Enter the name for the default device which will be created as template. + You can change this any time in the json file. + \li \b{Setup method}: Pick the desired setup method for the default device which will be created as template. + You can change this any time in the json file. You can find more information in the + \l{CreateMethods and SetupMethods} section. + \li \b{Create method}: Pick the desired create method for the default device which will be created as template. + You can change this any time in the json file. + \li \b{Icon}: Pick the desired icon for the default device which will be created as template. + You can change this any time in the json file. + \endlist + + See also the \l{CreateMethods and SetupMethods} section. + + \image plugin-template-3.png Plugin details + + \section2 Developer information + Enter the name and email address of the developer for this plugin. These information will be used in the + copyright sections of the plugin. The copyright information are placed in the \tt{debian/copyright} file and in each + source code license header. + \image plugin-template-4.png Developer information + + \section2 Kit selection + Pick the build kit for this project. The kit must match the version of the \tt{nymead} and \tt{libnymea1} built. + + \note: You have to make sure you are using the \underline{same kit} as the nymea daemon and libraries use. If you have installed the + \underline{nymea library} and \underline{Qt libraries} from you default system package manager, you should probably go with the + default kit of your distribution. + + \image plugin-template-5.png Kit selection + + \section2 Project Management + Here you can select your prefered project management tool. If you choose git, + the default \tt{.gitignore} file will be added to the project. + + \image plugin-template-6.png Project Management + + \section2 Project tree + Once you finished the plugin wizard, you can start with the development of you plugin. + \image plugin-template-7.png Project tree + + \section1 Walk trough + + Starting with the new created project you can find following files in you project: + + \section2 template.pro + + \quotefile template/template.pro + + \section2 deviceplugintemplate.json + + Here you can find the device plugin interface describibg the vendors, devices and plugin information. + A detailed description of each section can be found in the \l{The plugin JSON File} section. + + \quotefile template/deviceplugintemplate.json */ diff --git a/libnymea-core/hardware/network/avahi/qtavahiservice.h b/libnymea-core/hardware/network/avahi/qtavahiservice.h index fb574f20..6af0634c 100644 --- a/libnymea-core/hardware/network/avahi/qtavahiservice.h +++ b/libnymea-core/hardware/network/avahi/qtavahiservice.h @@ -35,7 +35,6 @@ class QtAvahiServicePrivate; class QtAvahiService : public QObject { Q_OBJECT - Q_ENUMS(QtAvahiServiceState) public: enum QtAvahiServiceState { @@ -45,6 +44,7 @@ public: QtAvahiServiceStateCollision = 3, QtAvahiServiceStateFailure = 4 }; + Q_ENUM(QtAvahiServiceState) explicit QtAvahiService(QObject *parent = nullptr); ~QtAvahiService(); diff --git a/libnymea/devicemanager.cpp b/libnymea/devicemanager.cpp index 6cad4d4a..ceeb9ae5 100644 --- a/libnymea/devicemanager.cpp +++ b/libnymea/devicemanager.cpp @@ -34,6 +34,7 @@ \l{DevicePlugin}{device plugins}. */ + /*! \enum DeviceManager::DeviceError This enum type specifies the errors that can happen when working with \l{Device}{Devices}. @@ -101,6 +102,7 @@ */ // Signals + /*! \fn void DeviceManager::loaded(); The DeviceManager will emit this signal when all \l{Device}{Devices} are loaded. */ diff --git a/libnymea/devicemanager.h b/libnymea/devicemanager.h index bca40f03..eb9de9bd 100644 --- a/libnymea/devicemanager.h +++ b/libnymea/devicemanager.h @@ -50,8 +50,6 @@ class HardwareManager; class LIBNYMEA_EXPORT DeviceManager : public QObject { Q_OBJECT - Q_ENUMS(DeviceError) - Q_ENUMS(DeviceSetupStatus) friend class DevicePlugin; diff --git a/libnymea/nymeasettings.cpp b/libnymea/nymeasettings.cpp index c00bfe5e..3d3fd1fe 100644 --- a/libnymea/nymeasettings.cpp +++ b/libnymea/nymeasettings.cpp @@ -50,6 +50,8 @@ file is read only. \value SettingsRoleDeviceStates This role will create the \b{device-states.conf} file and is used to store the configured \l{Device} \l{State}{States}. + \value SettingsRoleTags + This role will create the \b{tags.conf} file and is used to store the \l{Tag}{Tags}. */ diff --git a/libnymea/plugin/devicedescriptor.cpp b/libnymea/plugin/devicedescriptor.cpp index b12a3936..1a42ffe9 100644 --- a/libnymea/plugin/devicedescriptor.cpp +++ b/libnymea/plugin/devicedescriptor.cpp @@ -114,7 +114,7 @@ DeviceId DeviceDescriptor::parentDeviceId() const return m_parentDeviceId; } -/*! Sets the parent device Id for devices created from this DeviceDescriptor. */ +/*! Sets the parent device Id \a parentDeviceId for devices created from this DeviceDescriptor. */ void DeviceDescriptor::setParentDeviceId(const DeviceId &parentDeviceId) { m_parentDeviceId = parentDeviceId; diff --git a/libnymea/types/paramdescriptor.cpp b/libnymea/types/paramdescriptor.cpp index c394b101..86a569c0 100644 --- a/libnymea/types/paramdescriptor.cpp +++ b/libnymea/types/paramdescriptor.cpp @@ -46,7 +46,7 @@ ParamDescriptor::ParamDescriptor(const ParamTypeId ¶mTypeId, const QVariant { } -/*! Constructs an ParamDescriptor describing an \l{Param} with the given \a paramTypeId and \a value. +/*! Constructs an ParamDescriptor describing an \l{Param} with the given \a paramName and \a value. * The ValueOperator is by default ValueOperatorEquals. */ ParamDescriptor::ParamDescriptor(const QString ¶mName, const QVariant &value): Param(ParamTypeId(), value), diff --git a/nymea.pro b/nymea.pro index 04e367c2..58361002 100644 --- a/nymea.pro +++ b/nymea.pro @@ -13,7 +13,7 @@ doc.depends = FORCE # Note: some how extraimages in qdocconf did not the trick doc.commands += cd $$top_srcdir/libnymea/interfaces; ./generatedoc.sh; doc.commands += cd $$top_srcdir/doc; ./generate-api-qdoc.py; -doc.commands += cd $$top_srcdir/doc; qdoc config.qdocconf; cp -r images/* html/images/; \ +doc.commands += cd $$top_srcdir/doc; qdoc --highlighting config.qdocconf; cp -r images/* html/images/; \ cp -r favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/ licensecheck.commands = $$top_srcdir/tests/auto/checklicenseheaders.sh $$top_srcdir