From 1f583003523727565979c992713fe4df744d7028 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20St=C3=BCrz?= Date: Tue, 27 Feb 2018 21:03:31 +0100 Subject: [PATCH] Add API documentation --- doc/coap.qdoc | 2 +- doc/generate-api-qdoc.py | 245 ++ doc/jsonrpc-api.qdoc | 3766 +++++++++++++++++ doc/jsonrpc.qdoc | 193 +- doc/libnymea.qdoc | 2 +- doc/main.css | 8 +- doc/nymea.qdoc | 13 +- .../hardware/network/avahi/qtavahiservice.cpp | 4 +- libnymea/coap/coap.cpp | 6 +- libnymea/coap/coapobserveresource.cpp | 2 +- libnymea/coap/coapoption.cpp | 14 +- libnymea/coap/coapoption.h | 2 +- libnymea/coap/coappdu.cpp | 2 +- libnymea/coap/coapreply.cpp | 2 +- libnymea/coap/coaprequest.cpp | 2 +- libnymea/coap/corelink.cpp | 2 +- libnymea/coap/corelinkparser.cpp | 2 +- libnymea/devicemanager.cpp | 29 +- libnymea/devicemanager.h | 2 + libnymea/hardware/radio433/radio433.cpp | 8 + libnymea/hardwaremanager.cpp | 39 + libnymea/hardwareresource.cpp | 43 + libnymea/network/avahi/avahiserviceentry.cpp | 2 + .../network/avahi/qtavahiservicebrowser.cpp | 63 + libnymea/network/networkaccessmanager.cpp | 142 +- .../network/upnp/upnpdevicedescriptor.cpp | 8 +- libnymea/network/upnp/upnpdiscovery.cpp | 89 +- libnymea/network/upnp/upnpdiscoveryreply.cpp | 67 + libnymea/nymeasettings.cpp | 3 + libnymea/plugin/deviceplugin.cpp | 5 +- libnymea/plugintimer.cpp | 164 + libnymea/types/deviceclass.cpp | 6 + libnymea/types/eventdescriptor.cpp | 10 + libnymea/types/eventtype.cpp | 2 +- libnymea/types/paramtype.cpp | 9 +- libnymea/types/ruleaction.cpp | 11 +- libnymea/types/ruleactionparam.cpp | 1 + libnymea/types/statetype.cpp | 10 +- libnymea/types/vendor.cpp | 2 +- nymea.pro | 1 + 40 files changed, 4776 insertions(+), 207 deletions(-) create mode 100755 doc/generate-api-qdoc.py create mode 100644 doc/jsonrpc-api.qdoc diff --git a/doc/coap.qdoc b/doc/coap.qdoc index 6b92092c..001f8046 100644 --- a/doc/coap.qdoc +++ b/doc/coap.qdoc @@ -4,7 +4,7 @@ In order to interact with a CoAP (Constrained Application Protocol) server nymea provides following classes: - \annotatedlist coap + \annotatedlist coap-group */ diff --git a/doc/generate-api-qdoc.py b/doc/generate-api-qdoc.py new file mode 100755 index 00000000..8c164325 --- /dev/null +++ b/doc/generate-api-qdoc.py @@ -0,0 +1,245 @@ +#!/usr/bin/env python + +# -*- coding: UTF-8 -*- + +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # +# # +# Copyright (C) 2018 Simon Stuerz # +# # +# This file is part of guh. # +# # +# guh is free software: you can redistribute it and/or modify # +# it under the terms of the GNU General Public License as published by # +# the Free Software Foundation, version 2 of the License. # +# # +# guh is distributed in the hope that it will be useful, # +# but WITHOUT ANY WARRANTY; without even the implied warranty of # +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # +# GNU General Public License for more details. # +# # +# You should have received a copy of the GNU General Public License # +# along with guh. If not, see . # +# # +# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # + +import argparse +import traceback +import json +import os +import subprocess + +__version__='1.0.0' + + +#-------------------------------------------------------------------------- +def printInfo(info): + print(info) + + +#-------------------------------------------------------------------------- +def printWarning(warning): + print('Warning: ' + warning) + + +#-------------------------------------------------------------------------- +def printError(error): + print('Error: ' + error) + + +#-------------------------------------------------------------------------- +def writeToFile(line): + outputFile.write('%s\n' % line) + + +#-------------------------------------------------------------------------- +def writeCodeSection(jsonData): + writeToFile('\code') + writeToFile(json.dumps(jsonData, sort_keys=True, indent=4)) + writeToFile('\endcode') + + +#-------------------------------------------------------------------------- +def getJsonString(object, key): + for objectKey, value in object.items(): + if objectKey is key: + return value + + return None + + +#-------------------------------------------------------------------------- +def extractReferences(object): + referenceList = [] + for key, value in object.iteritems(): + keyString = ('%s' % key) + if keyString.startswith('$ref:'): + referenceList.append(keyString) + + valueString = ('%s' % value) + if valueString.startswith('$ref:'): + referenceList.append(valueString) + + elif isinstance(value, dict): + referenceList.extend(extractReferences(value)) + + elif isinstance(value, list): + for item in value: + itemString = ('%s' % item) + if itemString.startswith('$ref:'): + referenceList.append(itemString) + + elif isinstance(item, dict): + referenceList.extend(extractReferences(item)) + + return referenceList + + +#-------------------------------------------------------------------------- +def createReferenceLine(object): + # Get list of all references + referenceList = [] + fullReferenceList = extractReferences(object) + for reference in fullReferenceList: + if reference not in referenceList: + referenceList.append(reference.replace('$ref:', '')) + + if not referenceList: + return "" + + # Write references from content + referencesString = "See also: " + referenceCount = len(referenceList) + for i in range(len(referenceList)): + if i is referenceCount - 1: + referencesString += '\l{%s}' % referenceList[i] + else: + referencesString += '\l{%s}, ' % referenceList[i] + + return referencesString + + +#-------------------------------------------------------------------------- +def extractTypes(types): + typesList = [] + for type in types: + typesList.append(type) + + typesSorted = sorted(typesList) + for type in typesSorted: + writeToFile('\section3 %s' % type) + writeCodeSection(types[type]) + if isinstance(types[type], dict): + writeToFile(createReferenceLine(types[type])) + +#-------------------------------------------------------------------------- +def extractMethods(methods): + methodsList = [] + for method in methods: + methodsList.append(method) + + methodsSorted = sorted(methodsList) + for method in methodsSorted: + writeToFile('\section3 %s' % method) + writeToFile('%s' % methods[method]['description']) + writeToFile('\section4 Params') + writeCodeSection(methods[method]['params']) + writeToFile('\section4 Returns') + writeCodeSection(methods[method]['returns']) + writeToFile(createReferenceLine(methods[method])) + +#-------------------------------------------------------------------------- +def extractNotifications(notifications): + notificationsList = [] + for notification in notifications: + notificationsList.append(notification) + + notificationsSorted = sorted(notificationsList) + for notification in notificationsSorted: + writeToFile('\section3 %s' % notification) + writeToFile('%s' % notifications[notification]['description']) + writeToFile('\section4 Params') + writeCodeSection(notifications[notification]['params']) + writeToFile(createReferenceLine(notifications[notification])) + + +#-------------------------------------------------------------------------- +def writeDocumentationContent(apiVersion, apiJson): + printInfo('--> Write API documentation content') + printInfo('--> API version: \"%s\"' % (version)) + + writeToFile('In following section you can find a detaild description of the current API version %s.' % apiVersion) + + writeToFile('\list') + writeToFile('\li \l{Types}') + writeToFile('\li \l{Methods}') + writeToFile('\li \l{Notifications}') + writeToFile('\endlist') + + + if 'types' in apiJson: + writeToFile('\section1 Types') + extractTypes(apiJson['types']) + + if 'methods' in apiJson: + writeToFile('\section1 Methods') + extractMethods(apiJson['methods']) + + if 'notifications' in apiJson: + writeToFile("\section2 Notifications") + extractNotifications(apiJson['notifications']) + + writeToFile("\section1 Full introspect") + writeCodeSection(apiJson) + + +########################################################################### +# Main +########################################################################### + +if __name__ == '__main__': + parser = argparse.ArgumentParser(description='This tool generates a qdoc file out of the api.json file for the online documentation.') + parser.add_argument('-v', '--version', action='version', version=__version__) + parser.add_argument('-j', '--jsonfile', help='The API JSON input file name with the JSON RPC api definition', metavar='jsonfile', default='../tests/auto/api.json') + parser.add_argument('-o', '--output', help='The qdoc outputFile with the generated documentation script', metavar='output', default='./jsonrpc-api.qdoc') + args = parser.parse_args() + + # Print build information for debugging + printInfo('Json file: %s' % (args.jsonfile)) + printInfo('Output: %s' % (args.output)) + + # Open API file for reading + try: + inputFile = open(args.jsonfile, 'r') + except: + printError('Could not open input file \"%s\"' % (args.jsonfile)) + exit -1 + + # Open qdoc file for writing + try: + outputFile = open(args.output, 'w') + except: + printError('Could not open output file \"%s\"' % (args.output)) + exit -1 + + # Read version line and create json content of the rest + inputFileContent = inputFile.read().splitlines(True) + inputFile.close() + + # Parse verion and json data + version = inputFileContent[0].strip() + jsonRawContent = '' + for line in inputFileContent[1:]: + jsonRawContent += line + + # Parse json content + try: + apiJson = json.loads(jsonRawContent) + except ValueError as error: + printError(' --> Could not load json content') + printError(' %s' % (error)) + exit -1 + + # Sort alphabetically + apiJsonSortedRaw = json.dumps(apiJson, sort_keys=True, indent=4) + apiJsonSorted = json.loads(apiJsonSortedRaw) + writeDocumentationContent(version, apiJsonSorted) diff --git a/doc/jsonrpc-api.qdoc b/doc/jsonrpc-api.qdoc new file mode 100644 index 00000000..8c5579ed --- /dev/null +++ b/doc/jsonrpc-api.qdoc @@ -0,0 +1,3766 @@ +In following section you can find a detaild description of the current API version 1.2. +\list +\li \l{Types} +\li \l{Methods} +\li \l{Notifications} +\endlist +\section1 Types +\section3 Action +\code +{ + "actionTypeId": "Uuid", + "deviceId": "Uuid", + "o:params": [ + "$ref:Param" + ] +} +\endcode +See also: \l{Param} +\section3 ActionType +\code +{ + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "paramTypes": [ + "$ref:ParamType" + ] +} +\endcode +See also: \l{ParamType} +\section3 BasicTag +\code +[ + "BasicTagService", + "BasicTagDevice", + "BasicTagSensor", + "BasicTagActuator", + "BasicTagLighting", + "BasicTagEnergy", + "BasicTagMultimedia", + "BasicTagWeather", + "BasicTagGateway", + "BasicTagHeating", + "BasicTagCooling", + "BasicTagNotification", + "BasicTagSecurity", + "BasicTagTime", + "BasicTagShading", + "BasicTagAppliance", + "BasicTagCamera", + "BasicTagLock" +] +\endcode +\section3 BasicType +\code +[ + "Uuid", + "String", + "Int", + "Uint", + "Double", + "Bool", + "Variant", + "Color", + "Time", + "Object" +] +\endcode +\section3 CalendarItem +\code +{ + "duration": "Uint", + "o:datetime": "Uint", + "o:repeating": "$ref:RepeatingOption", + "o:startTime": "Time" +} +\endcode +See also: \l{RepeatingOption} +\section3 ConfigurationError +\code +[ + "ConfigurationErrorNoError", + "ConfigurationErrorInvalidTimeZone", + "ConfigurationErrorInvalidStationName", + "ConfigurationErrorInvalidId", + "ConfigurationErrorInvalidPort", + "ConfigurationErrorInvalidHostAddress", + "ConfigurationErrorBluetoothHardwareNotAvailable", + "ConfigurationErrorInvalidCertificate" +] +\endcode +\section3 CreateMethod +\code +[ + "CreateMethodUser", + "CreateMethodAuto", + "CreateMethodDiscovery" +] +\endcode +\section3 Device +\code +{ + "deviceClassId": "Uuid", + "id": "Uuid", + "name": "String", + "o:parentId": "Uuid", + "params": [ + "$ref:Param" + ], + "setupComplete": "Bool", + "states": [ + { + "stateTypeId": "Uuid", + "value": "Variant" + } + ] +} +\endcode +See also: \l{Param} +\section3 DeviceClass +\code +{ + "actionTypes": [ + "$ref:ActionType" + ], + "basicTags": [ + "$ref:BasicTag" + ], + "createMethods": [ + "$ref:CreateMethod" + ], + "deviceIcon": "$ref:DeviceIcon", + "discoveryParamTypes": [ + "$ref:ParamType" + ], + "displayName": "String", + "eventTypes": [ + "$ref:EventType" + ], + "id": "Uuid", + "interfaces": [ + "String" + ], + "name": "String", + "o:criticalStateTypeId": "Uuid", + "o:primaryActionTypeId": "Uuid", + "o:primaryStateTypeId": "Uuid", + "paramTypes": [ + "$ref:ParamType" + ], + "pluginId": "Uuid", + "setupMethod": "$ref:SetupMethod", + "stateTypes": [ + "$ref:StateType" + ], + "vendorId": "Uuid" +} +\endcode +See also: \l{ActionType}, \l{CreateMethod}, \l{DeviceIcon}, \l{BasicTag}, \l{ParamType}, \l{SetupMethod}, \l{StateType}, \l{EventType}, \l{ParamType} +\section3 DeviceDescriptor +\code +{ + "description": "String", + "id": "Uuid", + "title": "String" +} +\endcode + +\section3 DeviceError +\code +[ + "DeviceErrorNoError", + "DeviceErrorPluginNotFound", + "DeviceErrorVendorNotFound", + "DeviceErrorDeviceNotFound", + "DeviceErrorDeviceClassNotFound", + "DeviceErrorActionTypeNotFound", + "DeviceErrorStateTypeNotFound", + "DeviceErrorEventTypeNotFound", + "DeviceErrorDeviceDescriptorNotFound", + "DeviceErrorMissingParameter", + "DeviceErrorInvalidParameter", + "DeviceErrorSetupFailed", + "DeviceErrorDuplicateUuid", + "DeviceErrorCreationMethodNotSupported", + "DeviceErrorSetupMethodNotSupported", + "DeviceErrorHardwareNotAvailable", + "DeviceErrorHardwareFailure", + "DeviceErrorAuthentificationFailure", + "DeviceErrorAsync", + "DeviceErrorDeviceInUse", + "DeviceErrorDeviceInRule", + "DeviceErrorDeviceIsChild", + "DeviceErrorPairingTransactionIdNotFound", + "DeviceErrorParameterNotWritable" +] +\endcode +\section3 DeviceIcon +\code +[ + "DeviceIconNone", + "DeviceIconBed", + "DeviceIconBlinds", + "DeviceIconCeilingLamp", + "DeviceIconCouch", + "DeviceIconDeskLamp", + "DeviceIconDesk", + "DeviceIconHifi", + "DeviceIconPower", + "DeviceIconEnergy", + "DeviceIconRadio", + "DeviceIconSmartPhone", + "DeviceIconSocket", + "DeviceIconStandardLamp", + "DeviceIconSun", + "DeviceIconTablet", + "DeviceIconThermometer", + "DeviceIconTune", + "DeviceIconTv", + "DeviceIconBattery", + "DeviceIconDishwasher", + "DeviceIconWashingMachine", + "DeviceIconLaundryDryer", + "DeviceIconIrHeater", + "DeviceIconRadiator", + "DeviceIconSwitch", + "DeviceIconMotionDetectors", + "DeviceIconWeather", + "DeviceIconTime", + "DeviceIconLightBulb", + "DeviceIconGateway", + "DeviceIconMail", + "DeviceIconNetwork", + "DeviceIconCloud", + "DeviceIconGarage", + "DeviceIconRollerShutter" +] +\endcode +\section3 Event +\code +{ + "deviceId": "Uuid", + "eventTypeId": "Uuid", + "o:params": [ + "$ref:Param" + ] +} +\endcode +See also: \l{Param} +\section3 EventDescriptor +\code +{ + "o:deviceId": "Uuid", + "o:eventTypeId": "Uuid", + "o:interface": "String", + "o:interfaceEvent": "String", + "o:paramDescriptors": [ + "$ref:ParamDescriptor" + ] +} +\endcode +See also: \l{ParamDescriptor} +\section3 EventType +\code +{ + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "o:graphRelevant": "Bool", + "o:ruleRelevant": "Bool", + "paramTypes": [ + "$ref:ParamType" + ] +} +\endcode +See also: \l{ParamType} +\section3 InputType +\code +[ + "InputTypeNone", + "InputTypeTextLine", + "InputTypeTextArea", + "InputTypePassword", + "InputTypeSearch", + "InputTypeMail", + "InputTypeIPv4Address", + "InputTypeIPv6Address", + "InputTypeUrl", + "InputTypeMacAddress" +] +\endcode +\section3 LogEntry +\code +{ + "loggingLevel": "$ref:LoggingLevel", + "o:active": "Bool", + "o:deviceId": "Uuid", + "o:errorCode": "String", + "o:eventType": "$ref:LoggingEventType", + "o:typeId": "Uuid", + "o:value": "String", + "source": "$ref:LoggingSource", + "timestamp": "Int" +} +\endcode +See also: \l{LoggingSource}, \l{LoggingEventType}, \l{LoggingLevel} +\section3 LoggingError +\code +[ + "LoggingErrorNoError", + "LoggingErrorLogEntryNotFound", + "LoggingErrorInvalidFilterParameter" +] +\endcode +\section3 LoggingEventType +\code +[ + "LoggingEventTypeTrigger", + "LoggingEventTypeActiveChange", + "LoggingEventTypeEnabledChange", + "LoggingEventTypeActionsExecuted", + "LoggingEventTypeExitActionsExecuted" +] +\endcode +\section3 LoggingLevel +\code +[ + "LoggingLevelInfo", + "LoggingLevelAlert" +] +\endcode +\section3 LoggingSource +\code +[ + "LoggingSourceSystem", + "LoggingSourceEvents", + "LoggingSourceActions", + "LoggingSourceStates", + "LoggingSourceRules" +] +\endcode +\section3 NetworkDeviceState +\code +[ + "NetworkDeviceStateUnknown", + "NetworkDeviceStateUnmanaged", + "NetworkDeviceStateUnavailable", + "NetworkDeviceStateDisconnected", + "NetworkDeviceStatePrepare", + "NetworkDeviceStateConfig", + "NetworkDeviceStateNeedAuth", + "NetworkDeviceStateIpConfig", + "NetworkDeviceStateIpCheck", + "NetworkDeviceStateSecondaries", + "NetworkDeviceStateActivated", + "NetworkDeviceStateDeactivating", + "NetworkDeviceStateFailed" +] +\endcode +\section3 NetworkManagerError +\code +[ + "NetworkManagerErrorNoError", + "NetworkManagerErrorUnknownError", + "NetworkManagerErrorWirelessNotAvailable", + "NetworkManagerErrorAccessPointNotFound", + "NetworkManagerErrorNetworkInterfaceNotFound", + "NetworkManagerErrorInvalidNetworkDeviceType", + "NetworkManagerErrorWirelessNetworkingDisabled", + "NetworkManagerErrorWirelessConnectionFailed", + "NetworkManagerErrorNetworkingDisabled", + "NetworkManagerErrorNetworkManagerNotAvailable" +] +\endcode +\section3 NetworkManagerState +\code +[ + "NetworkManagerStateUnknown", + "NetworkManagerStateAsleep", + "NetworkManagerStateDisconnected", + "NetworkManagerStateDisconnecting", + "NetworkManagerStateConnecting", + "NetworkManagerStateConnectedLocal", + "NetworkManagerStateConnectedSite", + "NetworkManagerStateConnectedGlobal" +] +\endcode +\section3 Param +\code +{ + "paramTypeId": "Uuid", + "value": "$ref:BasicType" +} +\endcode +See also: \l{BasicType} +\section3 ParamDescriptor +\code +{ + "operator": "$ref:ValueOperator", + "paramTypeId": "Uuid", + "value": "$ref:BasicType" +} +\endcode +See also: \l{ValueOperator}, \l{BasicType} +\section3 ParamType +\code +{ + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "o:allowedValues": [ + "Variant" + ], + "o:defaultValue": "Variant", + "o:inputType": "$ref:InputType", + "o:maxValue": "Variant", + "o:minValue": "Variant", + "o:readOnly": "Bool", + "o:unit": "$ref:Unit", + "type": "$ref:BasicType" +} +\endcode +See also: \l{Unit}, \l{InputType}, \l{BasicType} +\section3 Plugin +\code +{ + "displayName": "String", + "id": "Uuid", + "name": "String", + "paramTypes": [ + "$ref:ParamType" + ] +} +\endcode +See also: \l{ParamType} +\section3 RemovePolicy +\code +[ + "RemovePolicyCascade", + "RemovePolicyUpdate" +] +\endcode +\section3 RepeatingMode +\code +[ + "RepeatingModeNone", + "RepeatingModeHourly", + "RepeatingModeDaily", + "RepeatingModeWeekly", + "RepeatingModeMonthly", + "RepeatingModeYearly" +] +\endcode +\section3 RepeatingOption +\code +{ + "mode": "$ref:RepeatingMode", + "o:monthDays": [ + "Int" + ], + "o:weekDays": [ + "Int" + ] +} +\endcode +See also: \l{RepeatingMode} +\section3 Rule +\code +{ + "actions": [ + "$ref:RuleAction" + ], + "active": "Bool", + "enabled": "Bool", + "eventDescriptors": [ + "$ref:EventDescriptor" + ], + "executable": "Bool", + "exitActions": [ + "$ref:RuleAction" + ], + "id": "Uuid", + "name": "String", + "stateEvaluator": "$ref:StateEvaluator", + "timeDescriptor": "$ref:TimeDescriptor" +} +\endcode +See also: \l{TimeDescriptor}, \l{RuleAction}, \l{StateEvaluator}, \l{RuleAction}, \l{EventDescriptor} +\section3 RuleAction +\code +{ + "o:actionTypeId": "Uuid", + "o:deviceId": "Uuid", + "o:interface": "String", + "o:interfaceAction": "String", + "o:ruleActionParams": [ + "$ref:RuleActionParam" + ] +} +\endcode +See also: \l{RuleActionParam} +\section3 RuleActionParam +\code +{ + "o:eventParamTypeId": "Uuid", + "o:eventTypeId": "Uuid", + "o:paramName": "String", + "o:paramTypeId": "Uuid", + "o:value": "$ref:BasicType" +} +\endcode +See also: \l{BasicType} +\section3 RuleDescription +\code +{ + "active": "Bool", + "enabled": "Bool", + "executable": "Bool", + "id": "Uuid", + "name": "String" +} +\endcode + +\section3 RuleError +\code +[ + "RuleErrorNoError", + "RuleErrorInvalidRuleId", + "RuleErrorRuleNotFound", + "RuleErrorDeviceNotFound", + "RuleErrorEventTypeNotFound", + "RuleErrorStateTypeNotFound", + "RuleErrorActionTypeNotFound", + "RuleErrorInvalidParameter", + "RuleErrorInvalidRuleFormat", + "RuleErrorMissingParameter", + "RuleErrorInvalidRuleActionParameter", + "RuleErrorInvalidStateEvaluatorValue", + "RuleErrorTypesNotMatching", + "RuleErrorNotExecutable", + "RuleErrorInvalidTimeDescriptor", + "RuleErrorInvalidRepeatingOption", + "RuleErrorInvalidCalendarItem", + "RuleErrorInvalidTimeEventItem", + "RuleErrorContainsEventBasesAction", + "RuleErrorNoExitActions", + "RuleErrorInterfaceNotFound" +] +\endcode +\section3 ServerConfiguration +\code +{ + "address": "String", + "authenticationEnabled": "Bool", + "id": "String", + "port": "Uint", + "sslEnabled": "Bool" +} +\endcode + +\section3 SetupMethod +\code +[ + "SetupMethodJustAdd", + "SetupMethodDisplayPin", + "SetupMethodEnterPin", + "SetupMethodPushButton" +] +\endcode +\section3 State +\code +{ + "deviceId": "Uuid", + "stateTypeId": "Uuid", + "value": "Variant" +} +\endcode + +\section3 StateDescriptor +\code +{ + "deviceId": "Uuid", + "operator": "$ref:ValueOperator", + "stateTypeId": "Uuid", + "value": "Variant" +} +\endcode +See also: \l{ValueOperator} +\section3 StateEvaluator +\code +{ + "o:childEvaluators": [ + "$ref:StateEvaluator" + ], + "o:operator": "$ref:StateOperator", + "o:stateDescriptor": "$ref:StateDescriptor" +} +\endcode +See also: \l{StateEvaluator}, \l{StateDescriptor}, \l{StateOperator} +\section3 StateOperator +\code +[ + "StateOperatorAnd", + "StateOperatorOr" +] +\endcode +\section3 StateType +\code +{ + "defaultValue": "Variant", + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "o:graphRelevant": "Bool", + "o:maxValue": "Variant", + "o:minValue": "Variant", + "o:possibleValues": [ + "Variant" + ], + "o:ruleRelevant": "Bool", + "o:unit": "$ref:Unit", + "type": "$ref:BasicType" +} +\endcode +See also: \l{Unit}, \l{BasicType} +\section3 TimeDescriptor +\code +{ + "o:calendarItems": [ + "$ref:CalendarItem" + ], + "o:timeEventItems": [ + "$ref:TimeEventItem" + ] +} +\endcode +See also: \l{TimeEventItem}, \l{CalendarItem} +\section3 TimeEventItem +\code +{ + "o:datetime": "Uint", + "o:repeating": "$ref:RepeatingOption", + "o:time": "Time" +} +\endcode +See also: \l{RepeatingOption} +\section3 TokenInfo +\code +{ + "creationTime": "Uint", + "deviceName": "String", + "id": "Uuid", + "userName": "String" +} +\endcode + +\section3 Unit +\code +[ + "UnitNone", + "UnitSeconds", + "UnitMinutes", + "UnitHours", + "UnitUnixTime", + "UnitMeterPerSecond", + "UnitKiloMeterPerHour", + "UnitDegree", + "UnitRadiant", + "UnitDegreeCelsius", + "UnitDegreeKelvin", + "UnitMired", + "UnitMilliBar", + "UnitBar", + "UnitPascal", + "UnitHectoPascal", + "UnitAtmosphere", + "UnitLumen", + "UnitLux", + "UnitCandela", + "UnitMilliMeter", + "UnitCentiMeter", + "UnitMeter", + "UnitKiloMeter", + "UnitGram", + "UnitKiloGram", + "UnitDezibel", + "UnitBpm", + "UnitKiloByte", + "UnitMegaByte", + "UnitGigaByte", + "UnitTeraByte", + "UnitMilliWatt", + "UnitWatt", + "UnitKiloWatt", + "UnitKiloWattHour", + "UnitEuroPerMegaWattHour", + "UnitEuroCentPerKiloWattHour", + "UnitPercentage", + "UnitPartsPerMillion", + "UnitEuro", + "UnitDollar", + "UnitHerz", + "UnitAmpere", + "UnitMilliAmpere", + "UnitVolt", + "UnitMilliVolt", + "UnitVoltAmpere", + "UnitVoltAmpereReactive", + "UnitAmpereHour" +] +\endcode +\section3 UserError +\code +[ + "UserErrorNoError", + "UserErrorBackendError", + "UserErrorInvalidUserId", + "UserErrorDuplicateUserId", + "UserErrorBadPassword", + "UserErrorTokenNotFound", + "UserErrorPermissionDenied" +] +\endcode +\section3 ValueOperator +\code +[ + "ValueOperatorEquals", + "ValueOperatorNotEquals", + "ValueOperatorLess", + "ValueOperatorGreater", + "ValueOperatorLessOrEqual", + "ValueOperatorGreaterOrEqual" +] +\endcode +\section3 Vendor +\code +{ + "displayName": "String", + "id": "Uuid", + "name": "String" +} +\endcode + +\section3 WebServerConfiguration +\code +{ + "address": "String", + "authenticationEnabled": "Bool", + "id": "String", + "port": "Uint", + "sslEnabled": "Bool" +} +\endcode + +\section3 WiredNetworkDevice +\code +{ + "bitRate": "String", + "interface": "String", + "macAddress": "String", + "pluggedIn": "Bool", + "state": "$ref:NetworkDeviceState" +} +\endcode +See also: \l{NetworkDeviceState} +\section3 WirelessAccessPoint +\code +{ + "frequency": "Double", + "macAddress": "String", + "protected": "Bool", + "signalStrength": "Int", + "ssid": "String" +} +\endcode + +\section3 WirelessNetworkDevice +\code +{ + "bitRate": "String", + "interface": "String", + "macAddress": "String", + "o:currentAccessPoint": "$ref:WirelessAccessPoint", + "state": "$ref:NetworkDeviceState" +} +\endcode +See also: \l{WirelessAccessPoint}, \l{NetworkDeviceState} +\section1 Methods +\section3 Actions.ExecuteAction +Execute a single action. +\section4 Params +\code +{ + "actionTypeId": "Uuid", + "deviceId": "Uuid", + "o:params": [ + "$ref:Param" + ] +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError" +} +\endcode +See also: \l{DeviceError}, \l{Param} +\section3 Actions.GetActionType +Get the ActionType for the given ActionTypeId +\section4 Params +\code +{ + "actionTypeId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:actionType": { + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "paramTypes": [ + "$ref:ParamType" + ] + } +} +\endcode +See also: \l{ParamType}, \l{DeviceError} +\section3 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 +\code +{ + "id": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 Configuration.DeleteWebServerConfiguration +Delete a WebServer interface of the server. +\section4 Params +\code +{ + "id": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 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 +\code +{ + "id": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 Configuration.GetAvailableLanguages +Returns a list of locale codes available for the server. i.e. en_US, de_AT +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "languages": [ + "String" + ] +} +\endcode + +\section3 Configuration.GetConfigurations +Get all configuration parameters of the server. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "basicConfiguration": { + "debugServerEnabled": "Bool", + "language": "String", + "serverName": "String", + "serverTime": "Uint", + "serverUuid": "Uuid", + "timeZone": "String" + }, + "cloud": { + "enabled": "Bool" + }, + "tcpServerConfigurations": [ + "$ref:ServerConfiguration" + ], + "webServerConfigurations": [ + "$ref:WebServerConfiguration" + ], + "webSocketServerConfigurations": [ + "$ref:ServerConfiguration" + ] +} +\endcode +See also: \l{ServerConfiguration}, \l{WebServerConfiguration}, \l{ServerConfiguration} +\section3 Configuration.GetTimeZones +Get the list of available timezones. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "timeZones": [ + "String" + ] +} +\endcode + +\section3 Configuration.SetCloudEnabled +Sets whether the cloud connection is enabled or disabled in the settings. +\section4 Params +\code +{ + "enabled": "Bool" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 Configuration.SetDebugServerEnabled +Enable or disable the debug server. +\section4 Params +\code +{ + "enabled": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 Configuration.SetLanguage +Sets the server language to the given language. See also: "GetAvailableLanguages" +\section4 Params +\code +{ + "language": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 Configuration.SetServerName +Set the name of the server. Default is guhIO. +\section4 Params +\code +{ + "serverName": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 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 +\code +{ + "configuration": "$ref:ServerConfiguration" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError}, \l{ServerConfiguration} +\section3 Configuration.SetTimeZone +Set the time zone of the server. See also: "GetTimeZones" +\section4 Params +\code +{ + "timeZone": "String" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError} +\section3 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 +\code +{ + "configuration": "$ref:WebServerConfiguration" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError}, \l{WebServerConfiguration} +\section3 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 +\code +{ + "configuration": "$ref:ServerConfiguration" +} +\endcode +\section4 Returns +\code +{ + "configurationError": "$ref:ConfigurationError" +} +\endcode +See also: \l{ConfigurationError}, \l{ServerConfiguration} +\section3 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 +\code +{ + "deviceClassId": "Uuid", + "name": "String", + "o:deviceDescriptorId": "Uuid", + "o:deviceParams": [ + "$ref:Param" + ] +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:deviceId": "Uuid" +} +\endcode +See also: \l{DeviceError}, \l{Param} +\section3 Devices.ConfirmPairing +Confirm an ongoing pairing. In case of SetupMethodEnterPin also provide the pin in the params. +\section4 Params +\code +{ + "o:secret": "String", + "pairingTransactionId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:deviceId": "Uuid" +} +\endcode +See also: \l{DeviceError} +\section3 Devices.EditDevice +Edit the name of a device. This method does not change the configuration of the device. +\section4 Params +\code +{ + "deviceId": "Uuid", + "name": "String" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError" +} +\endcode +See also: \l{DeviceError} +\section3 Devices.GetActionTypes +Get action types for a specified deviceClassId. +\section4 Params +\code +{ + "deviceClassId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "actionTypes": [ + "$ref:ActionType" + ] +} +\endcode +See also: \l{ActionType} +\section3 Devices.GetConfiguredDevices +Returns a list of configured devices, optionally filtered by deviceId. +\section4 Params +\code +{ + "o:deviceId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "devices": [ + "$ref:Device" + ] +} +\endcode +See also: \l{Device} +\section3 Devices.GetDiscoveredDevices +Performs a device discovery and returns the results. This function may take a while to return. +\section4 Params +\code +{ + "deviceClassId": "Uuid", + "o:discoveryParams": [ + "$ref:Param" + ] +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:deviceDescriptors": [ + "$ref:DeviceDescriptor" + ] +} +\endcode +See also: \l{DeviceDescriptor}, \l{DeviceError}, \l{Param} +\section3 Devices.GetEventTypes +Get event types for a specified deviceClassId. +\section4 Params +\code +{ + "deviceClassId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "eventTypes": [ + "$ref:EventType" + ] +} +\endcode +See also: \l{EventType} +\section3 Devices.GetPluginConfiguration +Get a plugin's params. +\section4 Params +\code +{ + "pluginId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:configuration": [ + "$ref:Param" + ] +} +\endcode +See also: \l{Param}, \l{DeviceError} +\section3 Devices.GetPlugins +Returns a list of loaded plugins. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "plugins": [ + "$ref:Plugin" + ] +} +\endcode +See also: \l{Plugin} +\section3 Devices.GetStateTypes +Get state types for a specified deviceClassId. +\section4 Params +\code +{ + "deviceClassId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "stateTypes": [ + "$ref:StateType" + ] +} +\endcode +See also: \l{StateType} +\section3 Devices.GetStateValue +Get the value of the given device and the given stateType +\section4 Params +\code +{ + "deviceId": "Uuid", + "stateTypeId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:value": "Variant" +} +\endcode +See also: \l{DeviceError} +\section3 Devices.GetStateValues +Get all the state values of the given device. +\section4 Params +\code +{ + "deviceId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:values": [ + { + "stateTypeId": "Uuid", + "value": "Variant" + } + ] +} +\endcode +See also: \l{DeviceError} +\section3 Devices.GetSupportedDevices +Returns a list of supported Device classes, optionally filtered by vendorId. +\section4 Params +\code +{ + "o:vendorId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceClasses": [ + "$ref:DeviceClass" + ] +} +\endcode +See also: \l{DeviceClass} +\section3 Devices.GetSupportedVendors +Returns a list of supported Vendors. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "vendors": [ + "$ref:Vendor" + ] +} +\endcode +See also: \l{Vendor} +\section3 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 +\code +{ + "deviceClassId": "Uuid", + "name": "String", + "o:deviceDescriptorId": "Uuid", + "o:deviceParams": [ + "$ref:Param" + ] +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:displayMessage": "String", + "o:pairingTransactionId": "Uuid", + "o:setupMethod": "$ref:SetupMethod" +} +\endcode +See also: \l{SetupMethod}, \l{DeviceError}, \l{Param} +\section3 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 +\code +{ + "deviceId": "Uuid", + "o:deviceDescriptorId": "Uuid", + "o:deviceParams": [ + "$ref:Param" + ] +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError" +} +\endcode +See also: \l{DeviceError}, \l{Param} +\section3 Devices.RemoveConfiguredDevice +Remove a device from the system. +\section4 Params +\code +{ + "deviceId": "Uuid", + "o:removePolicy": "$ref:RemovePolicy", + "o:removePolicyList": [ + { + "policy": "$ref:RemovePolicy", + "ruleId": "Uuid" + } + ] +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:ruleIds": [ + "Uuid" + ] +} +\endcode +See also: \l{DeviceError}, \l{RemovePolicy}, \l{RemovePolicy} +\section3 Devices.SetPluginConfiguration +Set a plugin's params. +\section4 Params +\code +{ + "configuration": [ + "$ref:Param" + ], + "pluginId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError" +} +\endcode +See also: \l{DeviceError}, \l{Param} +\section3 Events.GetEventType +Get the EventType for the given eventTypeId. +\section4 Params +\code +{ + "eventTypeId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:eventType": "$ref:EventType" +} +\endcode +See also: \l{EventType}, \l{DeviceError} +\section3 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 +\code +{ + "deviceName": "String", + "password": "String", + "username": "String" +} +\endcode +\section4 Returns +\code +{ + "o:token": "String", + "success": "Bool" +} +\endcode + +\section3 JSONRPC.CreateUser +Create a new user in the API. Currently this is only allowed to be called once when a new guh instance is set up. Call Authenticate after this to obtain a device token for this user. +\section4 Params +\code +{ + "password": "String", + "username": "String" +} +\endcode +\section4 Returns +\code +{ + "error": "$ref:UserError" +} +\endcode +See also: \l{UserError} +\section3 JSONRPC.Hello +Upon first connection, guh 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 guh 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 +\code +{} +\endcode +\section4 Returns +\code +{ + "authenticationRequired": "Bool", + "id": "Int", + "initialSetupRequired": "Bool", + "language": "String", + "name": "String", + "protocol version": "String", + "pushButtonAuthAvailable": "Bool", + "server": "String", + "uuid": "Uuid", + "version": "String" +} +\endcode + +\section3 JSONRPC.Introspect +Introspect this API. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "methods": "Object", + "types": "Object" +} +\endcode + +\section3 JSONRPC.IsCloudConnected +Check whether the cloud is currently connected. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "connected": "Bool" +} +\endcode + +\section3 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 +\code +{ + "sessionId": "String" +} +\endcode +\section4 Returns +\code +{ + "success": "Bool" +} +\endcode + +\section3 JSONRPC.RemoveToken +Revoke access for a given token. +\section4 Params +\code +{ + "tokenId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "error": "$ref:UserError" +} +\endcode +See also: \l{UserError} +\section3 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 +\code +{ + "deviceName": "String" +} +\endcode +\section4 Returns +\code +{ + "success": "Bool", + "transactionId": "Int" +} +\endcode + +\section3 JSONRPC.SetNotificationStatus +Enable/Disable notifications for this connections. +\section4 Params +\code +{ + "enabled": "Bool" +} +\endcode +\section4 Returns +\code +{ + "enabled": "Bool" +} +\endcode + +\section3 JSONRPC.SetupRemoteAccess +Setup the remote connection by providing AWS token information. This requires the cloud to be connected. +\section4 Params +\code +{ + "idToken": "String", + "userId": "String" +} +\endcode +\section4 Returns +\code +{ + "message": "String", + "status": "Int" +} +\endcode + +\section3 JSONRPC.Tokens +Return a list of TokenInfo objects of all the tokens for the current user. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "tokenInfoList": [ + "$ref:TokenInfo" + ] +} +\endcode +See also: \l{TokenInfo} +\section3 JSONRPC.Version +Version of this Guh/JSONRPC interface. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "protocol version": "String", + "version": "String" +} +\endcode + +\section3 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 +\code +{ + "o:deviceIds": [ + "Uuid" + ], + "o:eventTypes": [ + "$ref:LoggingEventType" + ], + "o:loggingLevels": [ + "$ref:LoggingLevel" + ], + "o:loggingSources": [ + "$ref:LoggingSource" + ], + "o:timeFilters": [ + { + "o:endDate": "Int", + "o:startDate": "Int" + } + ], + "o:typeIds": [ + "Uuid" + ], + "o:values": [ + "Variant" + ] +} +\endcode +\section4 Returns +\code +{ + "loggingError": "$ref:LoggingError", + "o:logEntries": [ + "$ref:LogEntry" + ] +} +\endcode +See also: \l{LogEntry}, \l{LoggingError}, \l{LoggingLevel}, \l{LoggingEventType}, \l{LoggingSource} +\section3 NetworkManager.ConnectWifiNetwork +Connect to the wifi network with the given ssid and password. +\section4 Params +\code +{ + "interface": "String", + "o:password": "String", + "ssid": "String" +} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError" +} +\endcode +See also: \l{NetworkManagerError} +\section3 NetworkManager.DisconnectInterface +Disconnect the given network interface. The interface will remain disconnected until the user connect it again. +\section4 Params +\code +{ + "interface": "String" +} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError" +} +\endcode +See also: \l{NetworkManagerError} +\section3 NetworkManager.EnableNetworking +Enable or disable networking in the NetworkManager. +\section4 Params +\code +{ + "enable": "Bool" +} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError" +} +\endcode +See also: \l{NetworkManagerError} +\section3 NetworkManager.EnableWirelessNetworking +Enable or disable wireless networking in the NetworkManager. +\section4 Params +\code +{ + "enable": "Bool" +} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError" +} +\endcode +See also: \l{NetworkManagerError} +\section3 NetworkManager.GetNetworkDevices +Get the list of current network devices. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError", + "wiredNetworkDevices": [ + "$ref:WiredNetworkDevice" + ], + "wirelessNetworkDevices": [ + "$ref:WirelessNetworkDevice" + ] +} +\endcode +See also: \l{NetworkManagerError}, \l{WiredNetworkDevice}, \l{WirelessNetworkDevice} +\section3 NetworkManager.GetNetworkStatus +Get the current network manager status. +\section4 Params +\code +{} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError", + "o:status": { + "networkingEnabled": "Bool", + "state": "$ref:NetworkManagerState", + "wirelessNetworkingEnabled": "Bool" + } +} +\endcode +See also: \l{NetworkManagerError}, \l{NetworkManagerState} +\section3 NetworkManager.GetWirelessAccessPoints +Get the current list of wireless network access points for the given interface. The interface has to be a WirelessNetworkDevice. +\section4 Params +\code +{ + "interface": "String" +} +\endcode +\section4 Returns +\code +{ + "networkManagerError": "$ref:NetworkManagerError", + "o:wirelessAccessPoints": [ + "$ref:WirelessAccessPoint" + ] +} +\endcode +See also: \l{NetworkManagerError}, \l{WirelessAccessPoint} +\section3 NetworkManager.ScanWifiNetworks +Start a wifi scan for searching new networks. +\section4 Params +\code +{ + "interface": "String" +} +\endcode +\section4 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 +\code +{ + "actions": [ + "$ref:RuleAction" + ], + "name": "String", + "o:enabled": "Bool", + "o:eventDescriptors": [ + "$ref:EventDescriptor" + ], + "o:executable": "Bool", + "o:exitActions": [ + "$ref:RuleAction" + ], + "o:stateEvaluator": "$ref:StateEvaluator", + "o:timeDescriptor": "$ref:TimeDescriptor" +} +\endcode +\section4 Returns +\code +{ + "o:ruleId": "Uuid", + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError}, \l{RuleAction}, \l{TimeDescriptor}, \l{RuleAction}, \l{EventDescriptor}, \l{StateEvaluator} +\section3 Rules.DisableRule +Disable a rule. The rule won't be triggered by it's events or state changes while it is disabled. If successfull, the notification "Rule.RuleConfigurationChanged" will be emitted. +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError} +\section3 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 successfull, the notification "Rule.RuleConfigurationChanged" will be emitted. +\section4 Params +\code +{ + "actions": [ + "$ref:RuleAction" + ], + "name": "String", + "o:enabled": "Bool", + "o:eventDescriptors": [ + "$ref:EventDescriptor" + ], + "o:executable": "Bool", + "o:exitActions": [ + "$ref:RuleAction" + ], + "o:stateEvaluator": "$ref:StateEvaluator", + "o:timeDescriptor": "$ref:TimeDescriptor", + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "o:rule": "$ref:Rule", + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError}, \l{Rule}, \l{RuleAction}, \l{TimeDescriptor}, \l{RuleAction}, \l{EventDescriptor}, \l{StateEvaluator} +\section3 Rules.EnableRule +Enabled a rule that has previously been disabled.If successfull, the notification "Rule.RuleConfigurationChanged" will be emitted. +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError} +\section3 Rules.ExecuteActions +Execute the action list of the rule with the given ruleId. +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError} +\section3 Rules.ExecuteExitActions +Execute the exit action list of the rule with the given ruleId. +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError} +\section3 Rules.FindRules +Find a list of rules containing any of the given parameters. +\section4 Params +\code +{ + "deviceId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "ruleIds": [ + "Uuid" + ] +} +\endcode + +\section3 Rules.GetRuleDetails +Get details for the rule identified by ruleId +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "o:rule": "$ref:Rule", + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError}, \l{Rule} +\section3 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 +\code +{} +\endcode +\section4 Returns +\code +{ + "ruleDescriptions": [ + "$ref:RuleDescription" + ] +} +\endcode +See also: \l{RuleDescription} +\section3 Rules.RemoveRule +Remove a rule +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "ruleError": "$ref:RuleError" +} +\endcode +See also: \l{RuleError} +\section3 States.GetStateType +Get the StateType for the given stateTypeId. +\section4 Params +\code +{ + "stateTypeId": "Uuid" +} +\endcode +\section4 Returns +\code +{ + "deviceError": "$ref:DeviceError", + "o:stateType": "$ref:StateType" +} +\endcode +See also: \l{StateType}, \l{DeviceError} +\section2 Notifications +\section3 Configuration.BasicConfigurationChanged +Emitted whenever the basic configuration of this server changes. +\section4 Params +\code +{ + "debugServerEnabled": "Bool", + "serverName": "String", + "serverTime": "Uint", + "serverUuid": "Uuid", + "timeZone": "String" +} +\endcode + +\section3 Configuration.CloudConfigurationChanged +Emitted whenever the cloud configuration is changed. +\section4 Params +\code +{ + "enabled": "Bool" +} +\endcode + +\section3 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 +\code +{ + "language": "String" +} +\endcode + +\section3 Configuration.TcpServerConfigurationChanged +Emitted whenever the TCP server configuration changes. +\section4 Params +\code +{ + "host": "String", + "port": "Uint" +} +\endcode + +\section3 Configuration.WebServerConfigurationChanged +Emitted whenever the web server configuration changes. +\section4 Params +\code +{ + "host": "String", + "port": "Uint" +} +\endcode + +\section3 Configuration.WebSocketServerConfigurationChanged +Emitted whenever the web socket server configuration changes. +\section4 Params +\code +{ + "host": "String", + "port": "Uint" +} +\endcode + +\section3 Devices.DeviceAdded +Emitted whenever a Device was added. +\section4 Params +\code +{ + "device": "$ref:Device" +} +\endcode +See also: \l{Device} +\section3 Devices.DeviceChanged +Emitted whenever the params or name of a Device changed (by EditDevice or ReconfigureDevice). +\section4 Params +\code +{ + "device": "$ref:Device" +} +\endcode +See also: \l{Device} +\section3 Devices.DeviceRemoved +Emitted whenever a Device was removed. +\section4 Params +\code +{ + "deviceId": "Uuid" +} +\endcode + +\section3 Devices.StateChanged +Emitted whenever a State of a device changes. +\section4 Params +\code +{ + "deviceId": "Uuid", + "stateTypeId": "Uuid", + "value": "Variant" +} +\endcode + +\section3 Events.EventTriggered +Emitted whenever an Event is triggered. +\section4 Params +\code +{ + "event": "$ref:Event" +} +\endcode +See also: \l{Event} +\section3 JSONRPC.CloudConnectedChanged +Emitted whenever the cloud connection status changes. +\section4 Params +\code +{ + "connected": "Bool" +} +\endcode + +\section3 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 +\code +{ + "o:token": "String", + "status": "$ref:UserError", + "transactionId": "Int" +} +\endcode +See also: \l{UserError} +\section3 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 +\code +{} +\endcode + +\section3 Logging.LogEntryAdded +Emitted whenever an entry is appended to the logging system. +\section4 Params +\code +{ + "logEntry": "$ref:LogEntry" +} +\endcode +See also: \l{LogEntry} +\section3 NetworkManager.NetworkStatusChanged +Emitted whenever a status of a NetworkManager changes. +\section4 Params +\code +{ + "status": { + "networkingEnabled": "Bool", + "state": "$ref:NetworkManagerState", + "wirelessNetworkingEnabled": "Bool" + } +} +\endcode +See also: \l{NetworkManagerState} +\section3 NetworkManager.WiredNetworkDeviceAdded +Emitted whenever a new WiredNetworkDevice was added. +\section4 Params +\code +{ + "wiredNetworkDevice": "$ref:WiredNetworkDevice" +} +\endcode +See also: \l{WiredNetworkDevice} +\section3 NetworkManager.WiredNetworkDeviceChanged +Emitted whenever the given WiredNetworkDevice has changed. +\section4 Params +\code +{ + "wiredNetworkDevice": "$ref:WiredNetworkDevice" +} +\endcode +See also: \l{WiredNetworkDevice} +\section3 NetworkManager.WiredNetworkDeviceRemoved +Emitted whenever a WiredNetworkDevice was removed. +\section4 Params +\code +{ + "interface": "String" +} +\endcode + +\section3 NetworkManager.WirelessNetworkDeviceAdded +Emitted whenever a new WirelessNetworkDevice was added. +\section4 Params +\code +{ + "wirelessNetworkDevice": "$ref:WirelessNetworkDevice" +} +\endcode +See also: \l{WirelessNetworkDevice} +\section3 NetworkManager.WirelessNetworkDeviceChanged +Emitted whenever the given WirelessNetworkDevice has changed. +\section4 Params +\code +{ + "wirelessNetworkDevice": "$ref:WirelessNetworkDevice" +} +\endcode +See also: \l{WirelessNetworkDevice} +\section3 NetworkManager.WirelessNetworkDeviceRemoved +Emitted whenever a WirelessNetworkDevice was removed. +\section4 Params +\code +{ + "interface": "String" +} +\endcode + +\section3 Rules.RuleActiveChanged +Emitted whenever the active state of a Rule changed. +\section4 Params +\code +{ + "active": "Bool", + "ruleId": "Uuid" +} +\endcode + +\section3 Rules.RuleAdded +Emitted whenever a Rule was added. +\section4 Params +\code +{ + "rule": "$ref:Rule" +} +\endcode +See also: \l{Rule} +\section3 Rules.RuleConfigurationChanged +Emitted whenever the configuration of a Rule changed. +\section4 Params +\code +{ + "rule": "$ref:Rule" +} +\endcode +See also: \l{Rule} +\section3 Rules.RuleRemoved +Emitted whenever a Rule was removed. +\section4 Params +\code +{ + "ruleId": "Uuid" +} +\endcode + +\section1 Full introspect +\code +{ + "methods": { + "Actions.ExecuteAction": { + "description": "Execute a single action.", + "params": { + "actionTypeId": "Uuid", + "deviceId": "Uuid", + "o:params": [ + "$ref:Param" + ] + }, + "returns": { + "deviceError": "$ref:DeviceError" + } + }, + "Actions.GetActionType": { + "description": "Get the ActionType for the given ActionTypeId", + "params": { + "actionTypeId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:actionType": { + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "paramTypes": [ + "$ref:ParamType" + ] + } + } + }, + "Configuration.DeleteTcpServerConfiguration": { + "description": "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.", + "params": { + "id": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.DeleteWebServerConfiguration": { + "description": "Delete a WebServer interface of the server.", + "params": { + "id": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.DeleteWebSocketServerConfiguration": { + "description": "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.", + "params": { + "id": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.GetAvailableLanguages": { + "description": "Returns a list of locale codes available for the server. i.e. en_US, de_AT", + "params": {}, + "returns": { + "languages": [ + "String" + ] + } + }, + "Configuration.GetConfigurations": { + "description": "Get all configuration parameters of the server.", + "params": {}, + "returns": { + "basicConfiguration": { + "debugServerEnabled": "Bool", + "language": "String", + "serverName": "String", + "serverTime": "Uint", + "serverUuid": "Uuid", + "timeZone": "String" + }, + "cloud": { + "enabled": "Bool" + }, + "tcpServerConfigurations": [ + "$ref:ServerConfiguration" + ], + "webServerConfigurations": [ + "$ref:WebServerConfiguration" + ], + "webSocketServerConfigurations": [ + "$ref:ServerConfiguration" + ] + } + }, + "Configuration.GetTimeZones": { + "description": "Get the list of available timezones.", + "params": {}, + "returns": { + "timeZones": [ + "String" + ] + } + }, + "Configuration.SetCloudEnabled": { + "description": "Sets whether the cloud connection is enabled or disabled in the settings.", + "params": { + "enabled": "Bool" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetDebugServerEnabled": { + "description": "Enable or disable the debug server.", + "params": { + "enabled": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetLanguage": { + "description": "Sets the server language to the given language. See also: \"GetAvailableLanguages\"", + "params": { + "language": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetServerName": { + "description": "Set the name of the server. Default is guhIO.", + "params": { + "serverName": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetTcpServerConfiguration": { + "description": "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.", + "params": { + "configuration": "$ref:ServerConfiguration" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetTimeZone": { + "description": "Set the time zone of the server. See also: \"GetTimeZones\"", + "params": { + "timeZone": "String" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetWebServerConfiguration": { + "description": "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.", + "params": { + "configuration": "$ref:WebServerConfiguration" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Configuration.SetWebSocketServerConfiguration": { + "description": "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.", + "params": { + "configuration": "$ref:ServerConfiguration" + }, + "returns": { + "configurationError": "$ref:ConfigurationError" + } + }, + "Devices.AddConfiguredDevice": { + "description": "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.", + "params": { + "deviceClassId": "Uuid", + "name": "String", + "o:deviceDescriptorId": "Uuid", + "o:deviceParams": [ + "$ref:Param" + ] + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:deviceId": "Uuid" + } + }, + "Devices.ConfirmPairing": { + "description": "Confirm an ongoing pairing. In case of SetupMethodEnterPin also provide the pin in the params.", + "params": { + "o:secret": "String", + "pairingTransactionId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:deviceId": "Uuid" + } + }, + "Devices.EditDevice": { + "description": "Edit the name of a device. This method does not change the configuration of the device.", + "params": { + "deviceId": "Uuid", + "name": "String" + }, + "returns": { + "deviceError": "$ref:DeviceError" + } + }, + "Devices.GetActionTypes": { + "description": "Get action types for a specified deviceClassId.", + "params": { + "deviceClassId": "Uuid" + }, + "returns": { + "actionTypes": [ + "$ref:ActionType" + ] + } + }, + "Devices.GetConfiguredDevices": { + "description": "Returns a list of configured devices, optionally filtered by deviceId.", + "params": { + "o:deviceId": "Uuid" + }, + "returns": { + "devices": [ + "$ref:Device" + ] + } + }, + "Devices.GetDiscoveredDevices": { + "description": "Performs a device discovery and returns the results. This function may take a while to return.", + "params": { + "deviceClassId": "Uuid", + "o:discoveryParams": [ + "$ref:Param" + ] + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:deviceDescriptors": [ + "$ref:DeviceDescriptor" + ] + } + }, + "Devices.GetEventTypes": { + "description": "Get event types for a specified deviceClassId.", + "params": { + "deviceClassId": "Uuid" + }, + "returns": { + "eventTypes": [ + "$ref:EventType" + ] + } + }, + "Devices.GetPluginConfiguration": { + "description": "Get a plugin's params.", + "params": { + "pluginId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:configuration": [ + "$ref:Param" + ] + } + }, + "Devices.GetPlugins": { + "description": "Returns a list of loaded plugins.", + "params": {}, + "returns": { + "plugins": [ + "$ref:Plugin" + ] + } + }, + "Devices.GetStateTypes": { + "description": "Get state types for a specified deviceClassId.", + "params": { + "deviceClassId": "Uuid" + }, + "returns": { + "stateTypes": [ + "$ref:StateType" + ] + } + }, + "Devices.GetStateValue": { + "description": "Get the value of the given device and the given stateType", + "params": { + "deviceId": "Uuid", + "stateTypeId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:value": "Variant" + } + }, + "Devices.GetStateValues": { + "description": "Get all the state values of the given device.", + "params": { + "deviceId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:values": [ + { + "stateTypeId": "Uuid", + "value": "Variant" + } + ] + } + }, + "Devices.GetSupportedDevices": { + "description": "Returns a list of supported Device classes, optionally filtered by vendorId.", + "params": { + "o:vendorId": "Uuid" + }, + "returns": { + "deviceClasses": [ + "$ref:DeviceClass" + ] + } + }, + "Devices.GetSupportedVendors": { + "description": "Returns a list of supported Vendors.", + "params": {}, + "returns": { + "vendors": [ + "$ref:Vendor" + ] + } + }, + "Devices.PairDevice": { + "description": "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.", + "params": { + "deviceClassId": "Uuid", + "name": "String", + "o:deviceDescriptorId": "Uuid", + "o:deviceParams": [ + "$ref:Param" + ] + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:displayMessage": "String", + "o:pairingTransactionId": "Uuid", + "o:setupMethod": "$ref:SetupMethod" + } + }, + "Devices.ReconfigureDevice": { + "description": "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.", + "params": { + "deviceId": "Uuid", + "o:deviceDescriptorId": "Uuid", + "o:deviceParams": [ + "$ref:Param" + ] + }, + "returns": { + "deviceError": "$ref:DeviceError" + } + }, + "Devices.RemoveConfiguredDevice": { + "description": "Remove a device from the system.", + "params": { + "deviceId": "Uuid", + "o:removePolicy": "$ref:RemovePolicy", + "o:removePolicyList": [ + { + "policy": "$ref:RemovePolicy", + "ruleId": "Uuid" + } + ] + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:ruleIds": [ + "Uuid" + ] + } + }, + "Devices.SetPluginConfiguration": { + "description": "Set a plugin's params.", + "params": { + "configuration": [ + "$ref:Param" + ], + "pluginId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError" + } + }, + "Events.GetEventType": { + "description": "Get the EventType for the given eventTypeId.", + "params": { + "eventTypeId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:eventType": "$ref:EventType" + } + }, + "JSONRPC.Authenticate": { + "description": "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.", + "params": { + "deviceName": "String", + "password": "String", + "username": "String" + }, + "returns": { + "o:token": "String", + "success": "Bool" + } + }, + "JSONRPC.CreateUser": { + "description": "Create a new user in the API. Currently this is only allowed to be called once when a new guh instance is set up. Call Authenticate after this to obtain a device token for this user.", + "params": { + "password": "String", + "username": "String" + }, + "returns": { + "error": "$ref:UserError" + } + }, + "JSONRPC.Hello": { + "description": "Upon first connection, guh 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 guh 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.", + "params": {}, + "returns": { + "authenticationRequired": "Bool", + "id": "Int", + "initialSetupRequired": "Bool", + "language": "String", + "name": "String", + "protocol version": "String", + "pushButtonAuthAvailable": "Bool", + "server": "String", + "uuid": "Uuid", + "version": "String" + } + }, + "JSONRPC.Introspect": { + "description": "Introspect this API.", + "params": {}, + "returns": { + "methods": "Object", + "types": "Object" + } + }, + "JSONRPC.IsCloudConnected": { + "description": "Check whether the cloud is currently connected.", + "params": {}, + "returns": { + "connected": "Bool" + } + }, + "JSONRPC.KeepAlive": { + "description": "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.", + "params": { + "sessionId": "String" + }, + "returns": { + "success": "Bool" + } + }, + "JSONRPC.RemoveToken": { + "description": "Revoke access for a given token.", + "params": { + "tokenId": "Uuid" + }, + "returns": { + "error": "$ref:UserError" + } + }, + "JSONRPC.RequestPushButtonAuth": { + "description": "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.", + "params": { + "deviceName": "String" + }, + "returns": { + "success": "Bool", + "transactionId": "Int" + } + }, + "JSONRPC.SetNotificationStatus": { + "description": "Enable/Disable notifications for this connections.", + "params": { + "enabled": "Bool" + }, + "returns": { + "enabled": "Bool" + } + }, + "JSONRPC.SetupRemoteAccess": { + "description": "Setup the remote connection by providing AWS token information. This requires the cloud to be connected.", + "params": { + "idToken": "String", + "userId": "String" + }, + "returns": { + "message": "String", + "status": "Int" + } + }, + "JSONRPC.Tokens": { + "description": "Return a list of TokenInfo objects of all the tokens for the current user.", + "params": {}, + "returns": { + "tokenInfoList": [ + "$ref:TokenInfo" + ] + } + }, + "JSONRPC.Version": { + "description": "Version of this Guh/JSONRPC interface.", + "params": {}, + "returns": { + "protocol version": "String", + "version": "String" + } + }, + "Logging.GetLogEntries": { + "description": "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.", + "params": { + "o:deviceIds": [ + "Uuid" + ], + "o:eventTypes": [ + "$ref:LoggingEventType" + ], + "o:loggingLevels": [ + "$ref:LoggingLevel" + ], + "o:loggingSources": [ + "$ref:LoggingSource" + ], + "o:timeFilters": [ + { + "o:endDate": "Int", + "o:startDate": "Int" + } + ], + "o:typeIds": [ + "Uuid" + ], + "o:values": [ + "Variant" + ] + }, + "returns": { + "loggingError": "$ref:LoggingError", + "o:logEntries": [ + "$ref:LogEntry" + ] + } + }, + "NetworkManager.ConnectWifiNetwork": { + "description": "Connect to the wifi network with the given ssid and password.", + "params": { + "interface": "String", + "o:password": "String", + "ssid": "String" + }, + "returns": { + "networkManagerError": "$ref:NetworkManagerError" + } + }, + "NetworkManager.DisconnectInterface": { + "description": "Disconnect the given network interface. The interface will remain disconnected until the user connect it again.", + "params": { + "interface": "String" + }, + "returns": { + "networkManagerError": "$ref:NetworkManagerError" + } + }, + "NetworkManager.EnableNetworking": { + "description": "Enable or disable networking in the NetworkManager.", + "params": { + "enable": "Bool" + }, + "returns": { + "networkManagerError": "$ref:NetworkManagerError" + } + }, + "NetworkManager.EnableWirelessNetworking": { + "description": "Enable or disable wireless networking in the NetworkManager.", + "params": { + "enable": "Bool" + }, + "returns": { + "networkManagerError": "$ref:NetworkManagerError" + } + }, + "NetworkManager.GetNetworkDevices": { + "description": "Get the list of current network devices.", + "params": {}, + "returns": { + "networkManagerError": "$ref:NetworkManagerError", + "wiredNetworkDevices": [ + "$ref:WiredNetworkDevice" + ], + "wirelessNetworkDevices": [ + "$ref:WirelessNetworkDevice" + ] + } + }, + "NetworkManager.GetNetworkStatus": { + "description": "Get the current network manager status.", + "params": {}, + "returns": { + "networkManagerError": "$ref:NetworkManagerError", + "o:status": { + "networkingEnabled": "Bool", + "state": "$ref:NetworkManagerState", + "wirelessNetworkingEnabled": "Bool" + } + } + }, + "NetworkManager.GetWirelessAccessPoints": { + "description": "Get the current list of wireless network access points for the given interface. The interface has to be a WirelessNetworkDevice.", + "params": { + "interface": "String" + }, + "returns": { + "networkManagerError": "$ref:NetworkManagerError", + "o:wirelessAccessPoints": [ + "$ref:WirelessAccessPoint" + ] + } + }, + "NetworkManager.ScanWifiNetworks": { + "description": "Start a wifi scan for searching new networks.", + "params": { + "interface": "String" + }, + "returns": { + "networkManagerError": "$ref:NetworkManagerError" + } + }, + "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.", + "params": { + "actions": [ + "$ref:RuleAction" + ], + "name": "String", + "o:enabled": "Bool", + "o:eventDescriptors": [ + "$ref:EventDescriptor" + ], + "o:executable": "Bool", + "o:exitActions": [ + "$ref:RuleAction" + ], + "o:stateEvaluator": "$ref:StateEvaluator", + "o:timeDescriptor": "$ref:TimeDescriptor" + }, + "returns": { + "o:ruleId": "Uuid", + "ruleError": "$ref:RuleError" + } + }, + "Rules.DisableRule": { + "description": "Disable a rule. The rule won't be triggered by it's events or state changes while it is disabled. If successfull, the notification \"Rule.RuleConfigurationChanged\" will be emitted.", + "params": { + "ruleId": "Uuid" + }, + "returns": { + "ruleError": "$ref:RuleError" + } + }, + "Rules.EditRule": { + "description": "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 successfull, the notification \"Rule.RuleConfigurationChanged\" will be emitted.", + "params": { + "actions": [ + "$ref:RuleAction" + ], + "name": "String", + "o:enabled": "Bool", + "o:eventDescriptors": [ + "$ref:EventDescriptor" + ], + "o:executable": "Bool", + "o:exitActions": [ + "$ref:RuleAction" + ], + "o:stateEvaluator": "$ref:StateEvaluator", + "o:timeDescriptor": "$ref:TimeDescriptor", + "ruleId": "Uuid" + }, + "returns": { + "o:rule": "$ref:Rule", + "ruleError": "$ref:RuleError" + } + }, + "Rules.EnableRule": { + "description": "Enabled a rule that has previously been disabled.If successfull, the notification \"Rule.RuleConfigurationChanged\" will be emitted.", + "params": { + "ruleId": "Uuid" + }, + "returns": { + "ruleError": "$ref:RuleError" + } + }, + "Rules.ExecuteActions": { + "description": "Execute the action list of the rule with the given ruleId.", + "params": { + "ruleId": "Uuid" + }, + "returns": { + "ruleError": "$ref:RuleError" + } + }, + "Rules.ExecuteExitActions": { + "description": "Execute the exit action list of the rule with the given ruleId.", + "params": { + "ruleId": "Uuid" + }, + "returns": { + "ruleError": "$ref:RuleError" + } + }, + "Rules.FindRules": { + "description": "Find a list of rules containing any of the given parameters.", + "params": { + "deviceId": "Uuid" + }, + "returns": { + "ruleIds": [ + "Uuid" + ] + } + }, + "Rules.GetRuleDetails": { + "description": "Get details for the rule identified by ruleId", + "params": { + "ruleId": "Uuid" + }, + "returns": { + "o:rule": "$ref:Rule", + "ruleError": "$ref:RuleError" + } + }, + "Rules.GetRules": { + "description": "Get the descriptions of all configured rules. If you need more information about a specific rule use the method Rules.GetRuleDetails.", + "params": {}, + "returns": { + "ruleDescriptions": [ + "$ref:RuleDescription" + ] + } + }, + "Rules.RemoveRule": { + "description": "Remove a rule", + "params": { + "ruleId": "Uuid" + }, + "returns": { + "ruleError": "$ref:RuleError" + } + }, + "States.GetStateType": { + "description": "Get the StateType for the given stateTypeId.", + "params": { + "stateTypeId": "Uuid" + }, + "returns": { + "deviceError": "$ref:DeviceError", + "o:stateType": "$ref:StateType" + } + } + }, + "notifications": { + "Configuration.BasicConfigurationChanged": { + "description": "Emitted whenever the basic configuration of this server changes.", + "params": { + "debugServerEnabled": "Bool", + "serverName": "String", + "serverTime": "Uint", + "serverUuid": "Uuid", + "timeZone": "String" + } + }, + "Configuration.CloudConfigurationChanged": { + "description": "Emitted whenever the cloud configuration is changed.", + "params": { + "enabled": "Bool" + } + }, + "Configuration.LanguageChanged": { + "description": "Emitted whenever the language of the server changed. The Plugins, Vendors and DeviceClasses have to be reloaded to get the translated data.", + "params": { + "language": "String" + } + }, + "Configuration.TcpServerConfigurationChanged": { + "description": "Emitted whenever the TCP server configuration changes.", + "params": { + "host": "String", + "port": "Uint" + } + }, + "Configuration.WebServerConfigurationChanged": { + "description": "Emitted whenever the web server configuration changes.", + "params": { + "host": "String", + "port": "Uint" + } + }, + "Configuration.WebSocketServerConfigurationChanged": { + "description": "Emitted whenever the web socket server configuration changes.", + "params": { + "host": "String", + "port": "Uint" + } + }, + "Devices.DeviceAdded": { + "description": "Emitted whenever a Device was added.", + "params": { + "device": "$ref:Device" + } + }, + "Devices.DeviceChanged": { + "description": "Emitted whenever the params or name of a Device changed (by EditDevice or ReconfigureDevice).", + "params": { + "device": "$ref:Device" + } + }, + "Devices.DeviceRemoved": { + "description": "Emitted whenever a Device was removed.", + "params": { + "deviceId": "Uuid" + } + }, + "Devices.StateChanged": { + "description": "Emitted whenever a State of a device changes.", + "params": { + "deviceId": "Uuid", + "stateTypeId": "Uuid", + "value": "Variant" + } + }, + "Events.EventTriggered": { + "description": "Emitted whenever an Event is triggered.", + "params": { + "event": "$ref:Event" + } + }, + "JSONRPC.CloudConnectedChanged": { + "description": "Emitted whenever the cloud connection status changes.", + "params": { + "connected": "Bool" + } + }, + "JSONRPC.PushButtonAuthFinished": { + "description": "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. ", + "params": { + "o:token": "String", + "status": "$ref:UserError", + "transactionId": "Int" + } + }, + "Logging.LogDatabaseUpdated": { + "description": "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.", + "params": {} + }, + "Logging.LogEntryAdded": { + "description": "Emitted whenever an entry is appended to the logging system. ", + "params": { + "logEntry": "$ref:LogEntry" + } + }, + "NetworkManager.NetworkStatusChanged": { + "description": "Emitted whenever a status of a NetworkManager changes.", + "params": { + "status": { + "networkingEnabled": "Bool", + "state": "$ref:NetworkManagerState", + "wirelessNetworkingEnabled": "Bool" + } + } + }, + "NetworkManager.WiredNetworkDeviceAdded": { + "description": "Emitted whenever a new WiredNetworkDevice was added.", + "params": { + "wiredNetworkDevice": "$ref:WiredNetworkDevice" + } + }, + "NetworkManager.WiredNetworkDeviceChanged": { + "description": "Emitted whenever the given WiredNetworkDevice has changed.", + "params": { + "wiredNetworkDevice": "$ref:WiredNetworkDevice" + } + }, + "NetworkManager.WiredNetworkDeviceRemoved": { + "description": "Emitted whenever a WiredNetworkDevice was removed.", + "params": { + "interface": "String" + } + }, + "NetworkManager.WirelessNetworkDeviceAdded": { + "description": "Emitted whenever a new WirelessNetworkDevice was added.", + "params": { + "wirelessNetworkDevice": "$ref:WirelessNetworkDevice" + } + }, + "NetworkManager.WirelessNetworkDeviceChanged": { + "description": "Emitted whenever the given WirelessNetworkDevice has changed.", + "params": { + "wirelessNetworkDevice": "$ref:WirelessNetworkDevice" + } + }, + "NetworkManager.WirelessNetworkDeviceRemoved": { + "description": "Emitted whenever a WirelessNetworkDevice was removed.", + "params": { + "interface": "String" + } + }, + "Rules.RuleActiveChanged": { + "description": "Emitted whenever the active state of a Rule changed.", + "params": { + "active": "Bool", + "ruleId": "Uuid" + } + }, + "Rules.RuleAdded": { + "description": "Emitted whenever a Rule was added.", + "params": { + "rule": "$ref:Rule" + } + }, + "Rules.RuleConfigurationChanged": { + "description": "Emitted whenever the configuration of a Rule changed.", + "params": { + "rule": "$ref:Rule" + } + }, + "Rules.RuleRemoved": { + "description": "Emitted whenever a Rule was removed.", + "params": { + "ruleId": "Uuid" + } + } + }, + "types": { + "Action": { + "actionTypeId": "Uuid", + "deviceId": "Uuid", + "o:params": [ + "$ref:Param" + ] + }, + "ActionType": { + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "paramTypes": [ + "$ref:ParamType" + ] + }, + "BasicTag": [ + "BasicTagService", + "BasicTagDevice", + "BasicTagSensor", + "BasicTagActuator", + "BasicTagLighting", + "BasicTagEnergy", + "BasicTagMultimedia", + "BasicTagWeather", + "BasicTagGateway", + "BasicTagHeating", + "BasicTagCooling", + "BasicTagNotification", + "BasicTagSecurity", + "BasicTagTime", + "BasicTagShading", + "BasicTagAppliance", + "BasicTagCamera", + "BasicTagLock" + ], + "BasicType": [ + "Uuid", + "String", + "Int", + "Uint", + "Double", + "Bool", + "Variant", + "Color", + "Time", + "Object" + ], + "CalendarItem": { + "duration": "Uint", + "o:datetime": "Uint", + "o:repeating": "$ref:RepeatingOption", + "o:startTime": "Time" + }, + "ConfigurationError": [ + "ConfigurationErrorNoError", + "ConfigurationErrorInvalidTimeZone", + "ConfigurationErrorInvalidStationName", + "ConfigurationErrorInvalidId", + "ConfigurationErrorInvalidPort", + "ConfigurationErrorInvalidHostAddress", + "ConfigurationErrorBluetoothHardwareNotAvailable", + "ConfigurationErrorInvalidCertificate" + ], + "CreateMethod": [ + "CreateMethodUser", + "CreateMethodAuto", + "CreateMethodDiscovery" + ], + "Device": { + "deviceClassId": "Uuid", + "id": "Uuid", + "name": "String", + "o:parentId": "Uuid", + "params": [ + "$ref:Param" + ], + "setupComplete": "Bool", + "states": [ + { + "stateTypeId": "Uuid", + "value": "Variant" + } + ] + }, + "DeviceClass": { + "actionTypes": [ + "$ref:ActionType" + ], + "basicTags": [ + "$ref:BasicTag" + ], + "createMethods": [ + "$ref:CreateMethod" + ], + "deviceIcon": "$ref:DeviceIcon", + "discoveryParamTypes": [ + "$ref:ParamType" + ], + "displayName": "String", + "eventTypes": [ + "$ref:EventType" + ], + "id": "Uuid", + "interfaces": [ + "String" + ], + "name": "String", + "o:criticalStateTypeId": "Uuid", + "o:primaryActionTypeId": "Uuid", + "o:primaryStateTypeId": "Uuid", + "paramTypes": [ + "$ref:ParamType" + ], + "pluginId": "Uuid", + "setupMethod": "$ref:SetupMethod", + "stateTypes": [ + "$ref:StateType" + ], + "vendorId": "Uuid" + }, + "DeviceDescriptor": { + "description": "String", + "id": "Uuid", + "title": "String" + }, + "DeviceError": [ + "DeviceErrorNoError", + "DeviceErrorPluginNotFound", + "DeviceErrorVendorNotFound", + "DeviceErrorDeviceNotFound", + "DeviceErrorDeviceClassNotFound", + "DeviceErrorActionTypeNotFound", + "DeviceErrorStateTypeNotFound", + "DeviceErrorEventTypeNotFound", + "DeviceErrorDeviceDescriptorNotFound", + "DeviceErrorMissingParameter", + "DeviceErrorInvalidParameter", + "DeviceErrorSetupFailed", + "DeviceErrorDuplicateUuid", + "DeviceErrorCreationMethodNotSupported", + "DeviceErrorSetupMethodNotSupported", + "DeviceErrorHardwareNotAvailable", + "DeviceErrorHardwareFailure", + "DeviceErrorAuthentificationFailure", + "DeviceErrorAsync", + "DeviceErrorDeviceInUse", + "DeviceErrorDeviceInRule", + "DeviceErrorDeviceIsChild", + "DeviceErrorPairingTransactionIdNotFound", + "DeviceErrorParameterNotWritable" + ], + "DeviceIcon": [ + "DeviceIconNone", + "DeviceIconBed", + "DeviceIconBlinds", + "DeviceIconCeilingLamp", + "DeviceIconCouch", + "DeviceIconDeskLamp", + "DeviceIconDesk", + "DeviceIconHifi", + "DeviceIconPower", + "DeviceIconEnergy", + "DeviceIconRadio", + "DeviceIconSmartPhone", + "DeviceIconSocket", + "DeviceIconStandardLamp", + "DeviceIconSun", + "DeviceIconTablet", + "DeviceIconThermometer", + "DeviceIconTune", + "DeviceIconTv", + "DeviceIconBattery", + "DeviceIconDishwasher", + "DeviceIconWashingMachine", + "DeviceIconLaundryDryer", + "DeviceIconIrHeater", + "DeviceIconRadiator", + "DeviceIconSwitch", + "DeviceIconMotionDetectors", + "DeviceIconWeather", + "DeviceIconTime", + "DeviceIconLightBulb", + "DeviceIconGateway", + "DeviceIconMail", + "DeviceIconNetwork", + "DeviceIconCloud", + "DeviceIconGarage", + "DeviceIconRollerShutter" + ], + "Event": { + "deviceId": "Uuid", + "eventTypeId": "Uuid", + "o:params": [ + "$ref:Param" + ] + }, + "EventDescriptor": { + "o:deviceId": "Uuid", + "o:eventTypeId": "Uuid", + "o:interface": "String", + "o:interfaceEvent": "String", + "o:paramDescriptors": [ + "$ref:ParamDescriptor" + ] + }, + "EventType": { + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "o:graphRelevant": "Bool", + "o:ruleRelevant": "Bool", + "paramTypes": [ + "$ref:ParamType" + ] + }, + "InputType": [ + "InputTypeNone", + "InputTypeTextLine", + "InputTypeTextArea", + "InputTypePassword", + "InputTypeSearch", + "InputTypeMail", + "InputTypeIPv4Address", + "InputTypeIPv6Address", + "InputTypeUrl", + "InputTypeMacAddress" + ], + "LogEntry": { + "loggingLevel": "$ref:LoggingLevel", + "o:active": "Bool", + "o:deviceId": "Uuid", + "o:errorCode": "String", + "o:eventType": "$ref:LoggingEventType", + "o:typeId": "Uuid", + "o:value": "String", + "source": "$ref:LoggingSource", + "timestamp": "Int" + }, + "LoggingError": [ + "LoggingErrorNoError", + "LoggingErrorLogEntryNotFound", + "LoggingErrorInvalidFilterParameter" + ], + "LoggingEventType": [ + "LoggingEventTypeTrigger", + "LoggingEventTypeActiveChange", + "LoggingEventTypeEnabledChange", + "LoggingEventTypeActionsExecuted", + "LoggingEventTypeExitActionsExecuted" + ], + "LoggingLevel": [ + "LoggingLevelInfo", + "LoggingLevelAlert" + ], + "LoggingSource": [ + "LoggingSourceSystem", + "LoggingSourceEvents", + "LoggingSourceActions", + "LoggingSourceStates", + "LoggingSourceRules" + ], + "NetworkDeviceState": [ + "NetworkDeviceStateUnknown", + "NetworkDeviceStateUnmanaged", + "NetworkDeviceStateUnavailable", + "NetworkDeviceStateDisconnected", + "NetworkDeviceStatePrepare", + "NetworkDeviceStateConfig", + "NetworkDeviceStateNeedAuth", + "NetworkDeviceStateIpConfig", + "NetworkDeviceStateIpCheck", + "NetworkDeviceStateSecondaries", + "NetworkDeviceStateActivated", + "NetworkDeviceStateDeactivating", + "NetworkDeviceStateFailed" + ], + "NetworkManagerError": [ + "NetworkManagerErrorNoError", + "NetworkManagerErrorUnknownError", + "NetworkManagerErrorWirelessNotAvailable", + "NetworkManagerErrorAccessPointNotFound", + "NetworkManagerErrorNetworkInterfaceNotFound", + "NetworkManagerErrorInvalidNetworkDeviceType", + "NetworkManagerErrorWirelessNetworkingDisabled", + "NetworkManagerErrorWirelessConnectionFailed", + "NetworkManagerErrorNetworkingDisabled", + "NetworkManagerErrorNetworkManagerNotAvailable" + ], + "NetworkManagerState": [ + "NetworkManagerStateUnknown", + "NetworkManagerStateAsleep", + "NetworkManagerStateDisconnected", + "NetworkManagerStateDisconnecting", + "NetworkManagerStateConnecting", + "NetworkManagerStateConnectedLocal", + "NetworkManagerStateConnectedSite", + "NetworkManagerStateConnectedGlobal" + ], + "Param": { + "paramTypeId": "Uuid", + "value": "$ref:BasicType" + }, + "ParamDescriptor": { + "operator": "$ref:ValueOperator", + "paramTypeId": "Uuid", + "value": "$ref:BasicType" + }, + "ParamType": { + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "o:allowedValues": [ + "Variant" + ], + "o:defaultValue": "Variant", + "o:inputType": "$ref:InputType", + "o:maxValue": "Variant", + "o:minValue": "Variant", + "o:readOnly": "Bool", + "o:unit": "$ref:Unit", + "type": "$ref:BasicType" + }, + "Plugin": { + "displayName": "String", + "id": "Uuid", + "name": "String", + "paramTypes": [ + "$ref:ParamType" + ] + }, + "RemovePolicy": [ + "RemovePolicyCascade", + "RemovePolicyUpdate" + ], + "RepeatingMode": [ + "RepeatingModeNone", + "RepeatingModeHourly", + "RepeatingModeDaily", + "RepeatingModeWeekly", + "RepeatingModeMonthly", + "RepeatingModeYearly" + ], + "RepeatingOption": { + "mode": "$ref:RepeatingMode", + "o:monthDays": [ + "Int" + ], + "o:weekDays": [ + "Int" + ] + }, + "Rule": { + "actions": [ + "$ref:RuleAction" + ], + "active": "Bool", + "enabled": "Bool", + "eventDescriptors": [ + "$ref:EventDescriptor" + ], + "executable": "Bool", + "exitActions": [ + "$ref:RuleAction" + ], + "id": "Uuid", + "name": "String", + "stateEvaluator": "$ref:StateEvaluator", + "timeDescriptor": "$ref:TimeDescriptor" + }, + "RuleAction": { + "o:actionTypeId": "Uuid", + "o:deviceId": "Uuid", + "o:interface": "String", + "o:interfaceAction": "String", + "o:ruleActionParams": [ + "$ref:RuleActionParam" + ] + }, + "RuleActionParam": { + "o:eventParamTypeId": "Uuid", + "o:eventTypeId": "Uuid", + "o:paramName": "String", + "o:paramTypeId": "Uuid", + "o:value": "$ref:BasicType" + }, + "RuleDescription": { + "active": "Bool", + "enabled": "Bool", + "executable": "Bool", + "id": "Uuid", + "name": "String" + }, + "RuleError": [ + "RuleErrorNoError", + "RuleErrorInvalidRuleId", + "RuleErrorRuleNotFound", + "RuleErrorDeviceNotFound", + "RuleErrorEventTypeNotFound", + "RuleErrorStateTypeNotFound", + "RuleErrorActionTypeNotFound", + "RuleErrorInvalidParameter", + "RuleErrorInvalidRuleFormat", + "RuleErrorMissingParameter", + "RuleErrorInvalidRuleActionParameter", + "RuleErrorInvalidStateEvaluatorValue", + "RuleErrorTypesNotMatching", + "RuleErrorNotExecutable", + "RuleErrorInvalidTimeDescriptor", + "RuleErrorInvalidRepeatingOption", + "RuleErrorInvalidCalendarItem", + "RuleErrorInvalidTimeEventItem", + "RuleErrorContainsEventBasesAction", + "RuleErrorNoExitActions", + "RuleErrorInterfaceNotFound" + ], + "ServerConfiguration": { + "address": "String", + "authenticationEnabled": "Bool", + "id": "String", + "port": "Uint", + "sslEnabled": "Bool" + }, + "SetupMethod": [ + "SetupMethodJustAdd", + "SetupMethodDisplayPin", + "SetupMethodEnterPin", + "SetupMethodPushButton" + ], + "State": { + "deviceId": "Uuid", + "stateTypeId": "Uuid", + "value": "Variant" + }, + "StateDescriptor": { + "deviceId": "Uuid", + "operator": "$ref:ValueOperator", + "stateTypeId": "Uuid", + "value": "Variant" + }, + "StateEvaluator": { + "o:childEvaluators": [ + "$ref:StateEvaluator" + ], + "o:operator": "$ref:StateOperator", + "o:stateDescriptor": "$ref:StateDescriptor" + }, + "StateOperator": [ + "StateOperatorAnd", + "StateOperatorOr" + ], + "StateType": { + "defaultValue": "Variant", + "displayName": "String", + "id": "Uuid", + "index": "Int", + "name": "String", + "o:graphRelevant": "Bool", + "o:maxValue": "Variant", + "o:minValue": "Variant", + "o:possibleValues": [ + "Variant" + ], + "o:ruleRelevant": "Bool", + "o:unit": "$ref:Unit", + "type": "$ref:BasicType" + }, + "TimeDescriptor": { + "o:calendarItems": [ + "$ref:CalendarItem" + ], + "o:timeEventItems": [ + "$ref:TimeEventItem" + ] + }, + "TimeEventItem": { + "o:datetime": "Uint", + "o:repeating": "$ref:RepeatingOption", + "o:time": "Time" + }, + "TokenInfo": { + "creationTime": "Uint", + "deviceName": "String", + "id": "Uuid", + "userName": "String" + }, + "Unit": [ + "UnitNone", + "UnitSeconds", + "UnitMinutes", + "UnitHours", + "UnitUnixTime", + "UnitMeterPerSecond", + "UnitKiloMeterPerHour", + "UnitDegree", + "UnitRadiant", + "UnitDegreeCelsius", + "UnitDegreeKelvin", + "UnitMired", + "UnitMilliBar", + "UnitBar", + "UnitPascal", + "UnitHectoPascal", + "UnitAtmosphere", + "UnitLumen", + "UnitLux", + "UnitCandela", + "UnitMilliMeter", + "UnitCentiMeter", + "UnitMeter", + "UnitKiloMeter", + "UnitGram", + "UnitKiloGram", + "UnitDezibel", + "UnitBpm", + "UnitKiloByte", + "UnitMegaByte", + "UnitGigaByte", + "UnitTeraByte", + "UnitMilliWatt", + "UnitWatt", + "UnitKiloWatt", + "UnitKiloWattHour", + "UnitEuroPerMegaWattHour", + "UnitEuroCentPerKiloWattHour", + "UnitPercentage", + "UnitPartsPerMillion", + "UnitEuro", + "UnitDollar", + "UnitHerz", + "UnitAmpere", + "UnitMilliAmpere", + "UnitVolt", + "UnitMilliVolt", + "UnitVoltAmpere", + "UnitVoltAmpereReactive", + "UnitAmpereHour" + ], + "UserError": [ + "UserErrorNoError", + "UserErrorBackendError", + "UserErrorInvalidUserId", + "UserErrorDuplicateUserId", + "UserErrorBadPassword", + "UserErrorTokenNotFound", + "UserErrorPermissionDenied" + ], + "ValueOperator": [ + "ValueOperatorEquals", + "ValueOperatorNotEquals", + "ValueOperatorLess", + "ValueOperatorGreater", + "ValueOperatorLessOrEqual", + "ValueOperatorGreaterOrEqual" + ], + "Vendor": { + "displayName": "String", + "id": "Uuid", + "name": "String" + }, + "WebServerConfiguration": { + "address": "String", + "authenticationEnabled": "Bool", + "id": "String", + "port": "Uint", + "sslEnabled": "Bool" + }, + "WiredNetworkDevice": { + "bitRate": "String", + "interface": "String", + "macAddress": "String", + "pluggedIn": "Bool", + "state": "$ref:NetworkDeviceState" + }, + "WirelessAccessPoint": { + "frequency": "Double", + "macAddress": "String", + "protected": "Bool", + "signalStrength": "Int", + "ssid": "String" + }, + "WirelessNetworkDevice": { + "bitRate": "String", + "interface": "String", + "macAddress": "String", + "o:currentAccessPoint": "$ref:WirelessAccessPoint", + "state": "$ref:NetworkDeviceState" + } + } +} +\endcode diff --git a/doc/jsonrpc.qdoc b/doc/jsonrpc.qdoc index 6feca43a..e04c9897 100644 --- a/doc/jsonrpc.qdoc +++ b/doc/jsonrpc.qdoc @@ -3,15 +3,15 @@ \title JSON-RPC API \ingroup jsonrpc - \brief The JSON RPC interface represents a TCP socket connection using plaintext string communication. + \brief The JSON RPC interface represents a socket connection using plaintext string communication. - \section1 Description + \chapter Description - The JSON RPC interface represents a TCP socket connection using plaintext string communication. + The JSON RPC interface represents a socket connection using plaintext string communication. Messages are exchanged using the JSON format. Please note that this is not a REST API as the transport channel is not based on HTTP. It is an internal RPC mechanism to allow communication - between the nymea Server and the main controller interface. This communication socket is not meant - to be exported to the outside of the of the systen as it allows arbitrary commands to manipulate + between the guh Server and the main controller interface. This communication socket is not meant + to be exported to the outside of the of the system as it allows arbitrary commands to manipulate the system. The JSON message protocol communicates by exchanging JSON Objects with the following properties: @@ -29,141 +29,68 @@ the requested method. \endlist - The JSONRPC API is self documenting and can be introspected by calling \c"JSONRPC.Introspect". + \chapter Handshake - Parameters are optional if the type is the type is prefixed with "o:" for optional. - - \section1 Communicating with the server - The server listens by default on TCP port 2222 for incoming TCP connections. It will respond to incoming connections with a some information about the server. Telnet can be used to issue commands for testing. - - An example how to communicate with the API using telnet on the same host where the nymea server - is running: - \code - $ telnet localhost 2222 - \endcode - \code - Trying 127.0.0.1... - Connected to localhost. - Escape character is '^]'. - { - "id": 0, - "protocol version": 28, - "server": "nymea JSONRPC interface", - "version": "0.6.0" - } - \endcode - Now the connection is established and waits for commands. - - \section1 Classes - - \annotatedlist json - - - \section1 Examples - - \section2 Introspect API - \section3 Request + Once connected to the socket, the server will send immediatly a handshake message. The handshake message + is a JSON object and contains all relevant information about the server and the API in order to start + communicationg with the server. + + Here is an example of the handshare: + \code { - "id": 1, - "method":"JSONRPC.Introspect" - } - \endcode - \section3 Response - \code - { - "id": 1, - "params": { - "methods": { - ... - "Devices.GetSupportedDevices": { - "description": "Returns a list of supported Device classes.", - "params": { - }, - "returns": { - "deviceClasses": [ - "$ref:DeviceClass" - ] - } - }, - ... - }, - "types": { - ... - "DeviceClass": { - "actions": [ - "$ref:ActionType" - ], - "id": "uuid", - "name": "string", - "params": [ - "$ref:ParamType" - ], - "states": [ - "$ref:StateType" - ], - "events": [ - "$ref:EventType" - ] - }, - ... - } - }, - "status": "success" + "id": 0, + "name": "guh", + "protocol version": "1.2", + "authenticationRequired": false, + "initialSetupRequired": false, + "pushButtonAuthAvailable": false, + "server": "guhIO", + "language": "de_DE", + "uuid": "{42842b0f-a7bb-4a94-b624-a55f31c5603e}", + "version": "0.8.3" } \endcode - \section2 Getting a list of supported devices - \section3 Request - \code - { - "id":1, - "method":"Devices.GetSupportedDevices" - } - \endcode - \section3 Response: - \code { - "id": 1, - "params": { - "deviceClasses": [ - { - "actions": [ - ], - "id": "{bd216356-f1ec-4324-9785-6982d2174e17}", - "name": "WiFi Device", - "params": [ - { - "name": "mac", - "type": "string" - } - ], - "states": [ - { - "id": "{cb43e1b5-4f61-4538-bfa2-c33055c542cf}", - "name": "inRange", - "type": "bool" - } - ], - "events": [ - { - "id": "{7cae711a-a0af-41b4-b3bf-38d3e23b41ba}", - "name": "inRange", - "params": [ - { - "name": "inRange", - "type": "bool" - } - ] - } - ] - } - ... - ] - } - "status": "success" - } - \endcode + \list + \li \code "id": int \endcode + The id in the handshake has always the value 0. This is the first message during connection. + \li \code "name": string \endcode + This field represents the name of the server you are connected to. This name is user defined an can be changed. + (Example: \c"JSONRPC.Introspect") + \li \code "protocol version": string \endcode + The field represents the API version of the server you are connected to. This should be used for API compatibility checks + \li \code "authenticationRequired": bool \endcode + If this property is true, a client must perform the authentication process before beeing able to interact with the API. See section \l{Authentication} for more information. + \li \code "initialSetupRequired": bool \endcode + This property indicates if the server was set up already. A server is set up if a user has been created. If the \tt authenticationRequired property is \tt{false}, this field can be ignored. + \li \code "pushButtonAuthAvailable": bool \endcode + This property indicates if the server has a running push-button agent and therefore the push-button authentication available. If the \tt authenticationRequired property is \tt{false}, this field can be ignored. + \li \code "server": string \endcode + This property holds the name of the server. This name can not be changed. + \li \code "language": string \endcode + This property holds the language of the server. The language can be changed in the settings. + \li \code "uuid": string \endcode + This property holds the UUID of the server and can be used as a unique identifier. + \li \code "version": string \endcode + This property holds the build version of the server. + \endlist + + + \chapter Authentication + + The API has an authentication mechanism, which makes sure that no unauthorized network participent can perform actions or get information from the server. For using the authentication the \tt authenticationRequired property in the \l{Handshake}{handshake} must be \tt{true}. + + \section2 Create a user + + + + \section2 Authenticate + + + \chapter API + \include jsonrpc-api.qdoc \section1 Newest JSON-RPC API diff --git a/doc/libnymea.qdoc b/doc/libnymea.qdoc index 7fb3ace8..31743a9c 100644 --- a/doc/libnymea.qdoc +++ b/doc/libnymea.qdoc @@ -12,7 +12,7 @@ \annotatedlist hardware \chapter CoAP - \annotatedlist coap + \annotatedlist coap-group */ diff --git a/doc/main.css b/doc/main.css index cddfaec5..01019e56 100644 --- a/doc/main.css +++ b/doc/main.css @@ -290,12 +290,12 @@ strong { :not(pre) > code, :not(pre) > kbd, :not(pre) > samp { - font-size: 0.875rem; + font-size: 1.1rem; font-family: Consolas, monaco, monospace; - color: #d63843; + color: #3d8077; white-space: nowrap; padding: 2px 6px; - background: #efefef; + /* background: #efefef; */ } em { @@ -969,7 +969,7 @@ h2:after, h3.fn:after { margin: 0 auto 0 0; left: 0; right: 0; - width: 20%; + width: 100%; background: #d3d5d6; } diff --git a/doc/nymea.qdoc b/doc/nymea.qdoc index 55472c6c..4139689e 100644 --- a/doc/nymea.qdoc +++ b/doc/nymea.qdoc @@ -1,6 +1,8 @@ /*! \page index.html - + + Welcome to the guh developer documentation. Here you can find information related to the development for guh. + \section1 Overview The nymea daemon consists of three main modules: @@ -21,15 +23,8 @@ \li \l{Type Utils}{Global types of nymea (Type Utils)} \li \l{CoAP}{The CoAP API} \endlist - \li \l{Plugins}{The nymea plugins} \endlist - \section1 API's - The nymea daemon provides two API's: - \list - \li \l{JSON-RPC API}{JSON-RPC} - \li \l{https://github.com/guh/nymea/wiki/REST-API}{REST} - \endlist \section1 Write your own plugin Here you can find some tutorials for developing and working with nymea: @@ -43,6 +38,8 @@ \section1 Client developers \list + \li \l{JSON-RPC API}{The API description} + \li \l{Interfaces for DeviceClasses} \li \l{Paramtypes and the coresponding UI elements} \endlist diff --git a/libnymea-core/hardware/network/avahi/qtavahiservice.cpp b/libnymea-core/hardware/network/avahi/qtavahiservice.cpp index 3745bc21..2114aa67 100644 --- a/libnymea-core/hardware/network/avahi/qtavahiservice.cpp +++ b/libnymea-core/hardware/network/avahi/qtavahiservice.cpp @@ -24,7 +24,7 @@ \class QtAvahiService \brief Allows to publish an avahi service to the network. - \inmodule libnymea + \inmodule core */ /*! \enum QtAvahiService::QtAvahiServiceState @@ -44,7 +44,7 @@ */ -/*! \fn void QtAvahiService::serviceStateChanged(const QtAvahiServiceState &state); +/*! \fn void QtAvahiService::serviceStateChanged(const QtAvahiServiceState &state) This signal will be emitted when the \a state of this \l{QtAvahiService} has changed. */ diff --git a/libnymea/coap/coap.cpp b/libnymea/coap/coap.cpp index d878ce23..6be0f488 100644 --- a/libnymea/coap/coap.cpp +++ b/libnymea/coap/coap.cpp @@ -22,7 +22,7 @@ \class Coap \brief The client connection class to a CoAP server. - \ingroup coap + \ingroup coap-group \inmodule libnymea The Coap class provides a signal solt based communication with a \l{https://tools.ietf.org/html/rfc7252}{CoAP (Constrained Application Protocol)} @@ -67,7 +67,7 @@ /*! \fn void Coap::notificationReceived(const CoapObserveResource &resource, const int ¬ificationNumber, const QByteArray &payload); This signal is emitted when a value of an observed \a resource changed. The \a notificationNumber specifies the the count of the notification - to keep the correct order. The value can be parsed from the \a payload. + to keep the correct order. The value can be parsed from the \a payload parameter. */ #include "coap.h" @@ -76,7 +76,7 @@ Q_LOGGING_CATEGORY(dcCoap, "Coap") -/*! Constructs a coap access manager with the given \a parent and \a port. */ +/*! Constructs a Coap access manager with the given \a parent and \a port. */ Coap::Coap(QObject *parent, const quint16 &port) : QObject(parent), m_reply(0) diff --git a/libnymea/coap/coapobserveresource.cpp b/libnymea/coap/coapobserveresource.cpp index c0dde8d2..b1c08a14 100644 --- a/libnymea/coap/coapobserveresource.cpp +++ b/libnymea/coap/coapobserveresource.cpp @@ -27,7 +27,7 @@ The CoapObserveResource class holds information about an observed resource. - \sa Coap::notificationReceived() + \sa Coap */ diff --git a/libnymea/coap/coapoption.cpp b/libnymea/coap/coapoption.cpp index baabadf7..698fbcd8 100644 --- a/libnymea/coap/coapoption.cpp +++ b/libnymea/coap/coapoption.cpp @@ -60,28 +60,18 @@ */ -/*! \fn CoapOption::CoapOption(); - Constructs a \l{CoapOption}. -*/ - -/*! \fn CoapOption::CoapOption(const Option &option, const QByteArray &data); - Constructs a \l{CoapOption} with the given \a option and option \a data. -*/ - -/*! \fn void CoapOption::setOption(const Option &option); - Sets the \l{CoapOption::Option} of this CoapOption to the given \a option. -*/ - #include "coapoption.h" #include +/*! Constructs a CoapOption. */ CoapOption::CoapOption() { } +/*! Sets the \a option of this CoapOption to the given parameter. */ void CoapOption::setOption(const CoapOption::Option &option) { m_option = option; diff --git a/libnymea/coap/coapoption.h b/libnymea/coap/coapoption.h index e04f54b2..1629b8fe 100644 --- a/libnymea/coap/coapoption.h +++ b/libnymea/coap/coapoption.h @@ -57,7 +57,7 @@ public: CoapOption(); - void setOption(const Option &option); + void setOption(const CoapOption::Option &option); Option option() const; void setData(const QByteArray &data); diff --git a/libnymea/coap/coappdu.cpp b/libnymea/coap/coappdu.cpp index 67ba9115..2045ba6d 100644 --- a/libnymea/coap/coappdu.cpp +++ b/libnymea/coap/coappdu.cpp @@ -22,7 +22,7 @@ \class CoapPdu \brief Represents a CoAP protocol data unit (PDU). - \ingroup coap + \ingroup coap-group \inmodule libnymea */ diff --git a/libnymea/coap/coapreply.cpp b/libnymea/coap/coapreply.cpp index 94e1afc5..994d6ed4 100644 --- a/libnymea/coap/coapreply.cpp +++ b/libnymea/coap/coapreply.cpp @@ -22,7 +22,7 @@ \class CoapReply \brief Represents a reply of a CoAP request. - \ingroup coap + \ingroup coap-group \inmodule libnymea The CoapReply class contains the data and headers for a request sent with \l{Coap} client. diff --git a/libnymea/coap/coaprequest.cpp b/libnymea/coap/coaprequest.cpp index cf9e3edc..2077332c 100644 --- a/libnymea/coap/coaprequest.cpp +++ b/libnymea/coap/coaprequest.cpp @@ -22,7 +22,7 @@ \class CoapRequest \brief Represents a request to a CoAP server. - \ingroup coap + \ingroup coap-group \inmodule libnymea */ diff --git a/libnymea/coap/corelink.cpp b/libnymea/coap/corelink.cpp index 9446f982..26f9c87e 100644 --- a/libnymea/coap/corelink.cpp +++ b/libnymea/coap/corelink.cpp @@ -22,7 +22,7 @@ \class CoreLink \brief Represents a link of a CoRE link format. - \ingroup coap + \ingroup coap-group \inmodule libnymea This class represents a Constrained RESTful Environments (CoRE) Link format according to the diff --git a/libnymea/coap/corelinkparser.cpp b/libnymea/coap/corelinkparser.cpp index 13a1154f..da4518b3 100644 --- a/libnymea/coap/corelinkparser.cpp +++ b/libnymea/coap/corelinkparser.cpp @@ -22,7 +22,7 @@ \class CoreLinkParser \brief Provides an easy way to parse a CoRE link list. - \ingroup coap + \ingroup coap-group \inmodule libnymea \section2 Example diff --git a/libnymea/devicemanager.cpp b/libnymea/devicemanager.cpp index 0625e67f..e19ae4aa 100644 --- a/libnymea/devicemanager.cpp +++ b/libnymea/devicemanager.cpp @@ -100,10 +100,19 @@ The status of the \l{Device} setup will be emitted asynchronous. */ +// Signals /*! \fn void DeviceManager::loaded(); The DeviceManager will emit this signal when all \l{Device}{Devices} are loaded. */ +/*! \fn void DeviceManager::languageUpdated(); + The DeviceManager will emit this signal when all system language has been updated. +*/ + +/*! \fn void DeviceManager::pluginConfigChanged(const PluginId &id, const ParamList &config); + The DeviceManager will emit this signal when the \a config \l{ParamList}{Params} of the \l{DevicePlugin}{plugin} with the given \a id has changed. +*/ + /*! \fn void DeviceManager::deviceSetupFinished(Device *device, DeviceError status); This signal is emitted when the setup of a \a device is finished. The \a status parameter describes the \l{DeviceManager::DeviceError}{DeviceError} that occurred. @@ -114,6 +123,11 @@ \l{StateType} and the \a value parameter holds the new value. */ +/*! \fn void DeviceManager::deviceDisappeared(const DeviceId &deviceId); + This signal is emitted when the automatically created \l{Device} with the given \a deviceId dissapeard. This signal will + create the Devices.DeviceRemoved notification. +*/ + /*! \fn void DeviceManager::deviceRemoved(const DeviceId &deviceId); This signal is emitted when the \l{Device} with the given \a deviceId was removed from the system. This signal will create the Devices.DeviceRemoved notification. @@ -259,8 +273,8 @@ QList DeviceManager::pluginsMetadata() return pluginList; } -/*! Register a DevicePlugin class. This can be used to create devices internally from the nymea system without having to create a full plugin. - The DeviceManager takes ownership of the object and will clean it up when exiting. Do not delete the object yourself. */ +/*! Register a DevicePlugin class. This can be used to create devices internally from the guh system without having to create a full plugin. + The \a metaData contains the static plugin configurations. The DeviceManager takes ownership of the object \a plugin and will clean it up when exiting. Do not delete the object yourself. */ void DeviceManager::registerStaticPlugin(DevicePlugin *plugin, const QJsonObject &metaData) { if (!verifyPluginMetadata(metaData)) { @@ -310,6 +324,10 @@ void DeviceManager::setLocale(const QLocale &locale) emit languageUpdated(); } +/*! Returns the pointer to the \l{HardwareManager} of the system. + + \sa HardwareManager +*/ HardwareManager *DeviceManager::hardwareManager() const { return m_hardwareManager; @@ -364,13 +382,13 @@ QList DeviceManager::supportedVendors() const return m_supportedVendors.values(); } -/*! Returns the list of all supported interfaces */ +/*! Returns the list of all supported \l{Interfaces for DeviceClasses}{interfaces}. */ Interfaces DeviceManager::supportedInterfaces() const { return m_supportedInterfaces.values(); } -/*! Returns the interface with the given name. If the interface can't be found it will return an invalid interface. */ +/*! Returns the interface with the given \a name. If the interface can't be found it will return an invalid interface. */ Interface DeviceManager::findInterface(const QString &name) { return m_supportedInterfaces.value(name); @@ -803,6 +821,7 @@ QList DeviceManager::findConfiguredDevices(const DeviceClassId &device return ret; } +/*! Returns all \l{Device}{Devices} with the given \a interface. See also \l{Interfaces for DeviceClasses}{interfaces}. */ QList DeviceManager::findConfiguredDevices(const QString &interface) const { QList ret; @@ -815,7 +834,7 @@ QList DeviceManager::findConfiguredDevices(const QString &interface) c return ret; } -/*! Returns all child \l{Device}{Devices} of the given \a device. */ +/*! Returns all child \l{Device}{Devices} of the \l{Device} with the given \a id. */ QList DeviceManager::findChildDevices(const DeviceId &id) const { QList ret; diff --git a/libnymea/devicemanager.h b/libnymea/devicemanager.h index 19c7491a..bca40f03 100644 --- a/libnymea/devicemanager.h +++ b/libnymea/devicemanager.h @@ -51,6 +51,7 @@ class LIBNYMEA_EXPORT DeviceManager : public QObject { Q_OBJECT Q_ENUMS(DeviceError) + Q_ENUMS(DeviceSetupStatus) friend class DevicePlugin; @@ -204,5 +205,6 @@ private: }; Q_DECLARE_METATYPE(DeviceManager::DeviceError) +Q_DECLARE_METATYPE(DeviceManager::DeviceSetupStatus) #endif // DEVICEMANAGER_H diff --git a/libnymea/hardware/radio433/radio433.cpp b/libnymea/hardware/radio433/radio433.cpp index 5f6c4084..bd1d955d 100644 --- a/libnymea/hardware/radio433/radio433.cpp +++ b/libnymea/hardware/radio433/radio433.cpp @@ -46,6 +46,14 @@ */ +/*! \fn Radio433::~Radio433(); + The virtual destructor of the Radio433. +*/ + +/*! \fn bool Radio433::sendData(int delay, QList rawData, int repetitions); + Returns true if the given \a rawData can be sent to a RF 433MHz device with the given \a delay. The amount of packages to send can be configured with the paramter \a repetitions. +*/ + #include "radio433.h" #include "loggingcategories.h" diff --git a/libnymea/hardwaremanager.cpp b/libnymea/hardwaremanager.cpp index 9a0b6a6a..d2957aec 100644 --- a/libnymea/hardwaremanager.cpp +++ b/libnymea/hardwaremanager.cpp @@ -20,14 +20,53 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class HardwareManager + \brief The main entry point when interacting with \l{HardwareResource}{hardware resources} + + \inmodule libguh + + \sa HardwareResource +*/ + +/*! \fn HardwareManager::~HardwareManager(); + The virtual destructor of the HardwareManager. +*/ + +/*! \fn Radio433 * HardwareManager::radio433(); + Returns the Radio433 \l{HardwareResource}. +*/ + +/*! \fn PluginTimerManager * HardwareManager::pluginTimerManager(); + Returns the PluginTimerManager \l{HardwareResource}. +*/ + +/*! \fn NetworkAccessManager * HardwareManager::networkManager(); + Returns the NetworkAccessManager \l{HardwareResource}. +*/ + +/*! \fn UpnpDiscovery * HardwareManager::upnpDiscovery(); + Returns the UpnpDiscovery \l{HardwareResource}. +*/ + +/*! \fn QtAvahiServiceBrowser * HardwareManager::avahiBrowser(); + Returns the QtAvahiServiceBrowser \l{HardwareResource}. +*/ + +/*! \fn BluetoothLowEnergyManager * HardwareManager::bluetoothLowEnergyManager(); + Returns the BluetoothLowEnergyManager \l{HardwareResource}. +*/ + #include "hardwaremanager.h" +/*! Constructs a new HardwareManager with the given \a parent.*/ HardwareManager::HardwareManager(QObject *parent) : QObject(parent) { } +/*! Sets the given \a resource to \a enabled. This allowes to enable/disable individual \l{HardwareResource}{HardwareResources}. */ void HardwareManager::setResourceEnabled(HardwareResource *resource, bool enabled) { resource->setEnabled(enabled); diff --git a/libnymea/hardwareresource.cpp b/libnymea/hardwareresource.cpp index ac3d9034..e4464daf 100644 --- a/libnymea/hardwareresource.cpp +++ b/libnymea/hardwareresource.cpp @@ -20,10 +20,52 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class HardwareResource + \brief The base class for hardware resources. + + \inmodule libguh + + \sa HardwareResource +*/ + +/*! \fn HardwareResource::~HardwareResource(); + The virtual destructor of the HardwareResource. +*/ + +/*! \fn bool HardwareResource::available() const; + Returns true if the hardware resource is available. + + \sa availableChanged() +*/ + +/*! \fn bool HardwareResource::enabled() const; + Returns true if the hardware resource is enabled. + + \sa enabledChanged() +*/ + + +/*! \fn bool HardwareResource::setEnabled(bool enabled); + Sets the hardware resource to \a enabled. + + \sa enabledChanged() +*/ + +// Signals +/*! \fn bool HardwareResource::enabledChanged(bool enabled); + This signal will be emited if the hardware resource was \a enabled or disabled. +*/ + +/*! \fn bool HardwareResource::availableChanged(bool available); + This signal will be emited if the hardware resource \a available changed. +*/ + #include "hardwareresource.h" #include "hardwaremanager.h" #include "loggingcategories.h" +/*! Constructs a new HardwareResource with the given \a name and \a parent. */ HardwareResource::HardwareResource(const QString &name, QObject *parent) : NymeaDBusService("/io/guh/nymead/HardwareManager/" + name, parent), m_name(name) @@ -31,6 +73,7 @@ HardwareResource::HardwareResource(const QString &name, QObject *parent) : } +/*! Returns the name of this resource. */ QString HardwareResource::name() const { return m_name; diff --git a/libnymea/network/avahi/avahiserviceentry.cpp b/libnymea/network/avahi/avahiserviceentry.cpp index df5f471a..a5c55be3 100644 --- a/libnymea/network/avahi/avahiserviceentry.cpp +++ b/libnymea/network/avahi/avahiserviceentry.cpp @@ -27,6 +27,8 @@ \ingroup types \inmodule libnymea + You can find an example \l{QtAvahiServiceBrowser}{here}. + */ #include "avahiserviceentry.h" diff --git a/libnymea/network/avahi/qtavahiservicebrowser.cpp b/libnymea/network/avahi/qtavahiservicebrowser.cpp index bef63381..ad20d68f 100644 --- a/libnymea/network/avahi/qtavahiservicebrowser.cpp +++ b/libnymea/network/avahi/qtavahiservicebrowser.cpp @@ -26,8 +26,71 @@ \ingroup hardware \inmodule libnymea + + The QtAvahiServiceBrowser allows to discover the avahi network and get services. + + + \chapter Example + + In order to search for available avahi services in the current network you use this hardware resource like this: + + \tt devicepluginexample.h + + \code + #include "network/avahi/avahiserviceentry.h" + + class DevicePluginExample : public DevicePlugin + { + ... + + public: + void init() override; + + private slots: + void onServiceEntryAdded(const AvahiServiceEntry &serviceEntry); + void onServiceEntryRemoved(const AvahiServiceEntry &serviceEntry); + + ... + + }; + \endcode + + \tt devicepluginexample.cpp + + \code + + void DevicePluginExample::init() { + connect(hardwareManager()->avahiBrowser(), &QtAvahiServiceBrowser::serviceEntryAdded, this, &DevicePluginExample::onServiceEntryAdded); + connect(hardwareManager()->avahiBrowser(), &QtAvahiServiceBrowser::serviceEntryRemoved, this, &DevicePluginExample::onServiceEntryRemoved); + } + + void DevicePluginExample::onServiceEntryAdded(const AvahiServiceEntry &serviceEntry) { + qCDebug(dcExample()) << "New service added to network:" << serviceEntry; + + ... + } + + void DevicePluginExample::onServiceEntryRemoved(const AvahiServiceEntry &serviceEntry) { + qCDebug(dcExample()) << "Service removed from network:" << serviceEntry; + + ... + } + + \endcode + + \sa AvahiServiceEntry + */ +/*! \fn QtAvahiServiceBrowser::~QtAvahiServiceBrowser(); + Destroys this QtAvahiServiceBrowser; +*/ + +/*! \fn QList QtAvahiServiceBrowser::serviceEntries() const; + Returns the list of available service entries in the network of this browser. +*/ + +// Signals /*! \fn void QtAvahiServiceBrowser::serviceEntryAdded(const AvahiServiceEntry &entry); This signal will be emitted when a new \a entry was added to the current entry list. */ diff --git a/libnymea/network/networkaccessmanager.cpp b/libnymea/network/networkaccessmanager.cpp index 6c3c91ba..2ee7be74 100644 --- a/libnymea/network/networkaccessmanager.cpp +++ b/libnymea/network/networkaccessmanager.cpp @@ -21,17 +21,147 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*! - \class NetworkAccessManager - \brief Allows to send network requests and receive replies. + \class NetworkAccessManager + \brief Allows to send network requests and receive replies. - \ingroup hardware - \inmodule libnymea + \ingroup hardware + \inmodule libnymea - The network manager class is a reimplementation of the \l{http://doc-snapshot.qt-project.org/qt5-5.4/qnetworkaccessmanager.html}{QNetworkAccessManager} - and allows plugins to send network requests and receive replies. + The network manager class is a reimplementation of the \l{http://doc.qt.io/qt-5/qnetworkaccessmanager.html}{QNetworkAccessManager} + and allows plugins to send network requests and receive replies. + \chapter Example + + In order to make a GET request in your plugin, you can take a look at following example: + + \tt devicepluginexample.h + + \code + #include "network/networkaccessmanager.h" + + class DevicePluginExample : public DevicePlugin + { + ... + + private: + void getServerData(); + + private slots: + void onGetRequestFinished(); + + ... + + }; + + \endcode + + \tt devicepluginexample.cpp + + \code + void DevicePluginExample::getServerData() { + QNetworkReply *reply = hardwareManager()->networkManager()->get(QNetworkRequest(QUrl("http://example.com"))); + connect(reply, &QNetworkReply::finished, this, &DevicePluginExample::onGetRequestFinished); + } + + void DevicePluginExample::onGetRequestFinished() { + QNetworkReply *reply = static_cast(sender()); + int httpStatus = reply->attribute(QNetworkRequest::HttpStatusCodeAttribute).toInt(); + + if (httpStatus != 200 || reply->error() != QNetworkReply::NoError) { + qCWarning(dcExample()) << "Get data reply error: " << httpStatus << reply->errorString(); + reply->deleteLater(); + return; + } + + QByteArray data = reply->readAll(); + reply->deleteLater(); + + ... + + } + \endcode + + \sa HardwareResource, HardwareManager::networkManager() */ +/*! \fn NetworkAccessManager::~NetworkAccessManager(); + Destroys this NetworkAccessManager. +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::get(const QNetworkRequest &request); + Posts a \a request to obtain the contents of the target request and returns a new QNetworkReply object opened for reading which emits the readyRead() signal whenever new data arrives. + The contents as well as associated headers will be downloaded. + + \sa post(), put(), deleteResource(), sendCustomRequest() +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::deleteResource(const QNetworkRequest &request); + Sends a \a request to delete the resource identified by the URL of request. + + \note This feature is currently available for HTTP only, performing an HTTP DELETE request. + \sa post(), put(), deleteResource(), sendCustomRequest() +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::head(const QNetworkRequest &request); + Posts a \a request to obtain the network headers for request and returns a new QNetworkReply object which will contain such headers. + + The function is named after the HTTP request associated (HEAD). + \sa post(), put(), deleteResource(), sendCustomRequest() +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::post(const QNetworkRequest &request, QIODevice *data); + Sends an HTTP POST \a request to the destination specified by request and returns a new QNetworkReply object opened for reading that will contain the reply sent by the server. The contents of the \a data device will be uploaded to the server. + Data must be open for reading and must remain valid until the finished() signal is emitted for this reply. + + \note Sending a POST request on protocols other than HTTP and HTTPS is undefined and will probably fail. + + \sa get(), put(), deleteResource(), sendCustomRequest() +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::post(const QNetworkRequest &request, const QByteArray &data); + This is an overloaded function. + Sends the contents of the \a data byte array to the destination specified by \a request. +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::post(const QNetworkRequest &request, QHttpMultiPart *multiPart); + This is an overloaded function. + Sends the contents of the \a multiPart message to the destination specified by \a request. + This can be used for sending MIME multipart messages over HTTP. +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::put(const QNetworkRequest &request, QIODevice *data); + Uploads the contents of \a data to the destination \a request and returnes a new QNetworkReply object that will be open for reply. + data must be opened for reading when this function is called and must remain valid until the finished() signal is emitted for this reply. + Whether anything will be available for reading from the returned object is protocol dependent. For HTTP, the server may send a small HTML page indicating the upload was successful (or not). + Other protocols will probably have content in their replies. + + \note For HTTP, this request will send a PUT request, which most servers do not allow. Form upload mechanisms, including that of uploading files through HTML forms, use the POST mechanism. + + \sa get(), post(), deleteResource(), sendCustomRequest() +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::put(const QNetworkRequest &request, const QByteArray &data); + This is an overloaded function. + Sends the contents of the \a data byte array to the destination specified by \a request. +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::put(const QNetworkRequest &request, QHttpMultiPart *multiPart); + This is an overloaded function. + Sends the contents of the \a multiPart message to the destination specified by \a request. + This can be used for sending MIME multipart messages over HTTP. +*/ + +/*! \fn QNetworkReply *NetworkAccessManager::sendCustomRequest(const QNetworkRequest &request, const QByteArray &verb, QIODevice *data = nullptr); + Sends a custom \a request to the server identified by the URL of request. + It is the user's responsibility to send a \a verb to the server that is valid according to the HTTP specification. + This method provides means to send verbs other than the common ones provided via get() or post() etc., for instance sending an HTTP OPTIONS command. + If \a data is not empty, the contents of the data device will be uploaded to the server; in that case, data must be open for reading and must remain valid until the finished() signal is emitted for this reply. + + \sa get(), post(), put(), deleteResource() +*/ + + + #include "networkaccessmanager.h" #include "loggingcategories.h" diff --git a/libnymea/network/upnp/upnpdevicedescriptor.cpp b/libnymea/network/upnp/upnpdevicedescriptor.cpp index fff2dbc3..c948fb60 100644 --- a/libnymea/network/upnp/upnpdevicedescriptor.cpp +++ b/libnymea/network/upnp/upnpdevicedescriptor.cpp @@ -27,8 +27,14 @@ \ingroup types \inmodule libnymea + The upnp device descriptor holds the discovered information of a UPnP device. These information are + the result of a \l{UpnpDiscovery::discoverDevices()}{discoverDevices()} request and can accessed in from the + \l{UpnpDiscoveryReply::deviceDescriptors()}{deviceDescriptors()} once the UpnpDiscoveryReply + is \l{UpnpDiscoveryReply::finished()}{finished}. - \sa UpnpDevice + You can find an example \l{UpnpDiscovery}{here}. + + \sa UpnpDevice, UpnpDiscovery, UpnpDiscoveryReply */ #include "upnpdevicedescriptor.h" diff --git a/libnymea/network/upnp/upnpdiscovery.cpp b/libnymea/network/upnp/upnpdiscovery.cpp index 22cd2573..36b301db 100644 --- a/libnymea/network/upnp/upnpdiscovery.cpp +++ b/libnymea/network/upnp/upnpdiscovery.cpp @@ -21,25 +21,88 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /*! - \class UpnpDiscovery - \brief Allows to detect UPnP devices in the network. + \class UpnpDiscovery + \brief Allows to discover UPnP devices in the network. - \ingroup hardware - \inmodule libnymea + \ingroup hardware + \inmodule libnymea - This resource allows plugins to discover UPnP devices in the network and receive notification messages. The resource - will bind a UDP socket to the multicast 239.255.255.250 on port 1900. + This resource allows plugins to discover UPnP devices in the network and receive notification messages. The resource + will bind a UDP socket to the multicast 239.255.255.250 on port 1900. - The communication was implementet using following documentation: \l{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf} + The communication was implementet using following documentation: \l{http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.1.pdf} - \sa UpnpDevice, UpnpDeviceDescriptor + \chapter Example + + In order to perform an UPnP discovery in your plugin, you can take a look at following example: + + \tt devicepluginexample.h + + \code + class DevicePluginExample : public DevicePlugin + { + ... + + private: + void discoverUpnpDevices(); + + private slots: + void onUpnpDiscoveryFinished(); + + ... + + }; + + \endcode + + \tt devicepluginexample.cpp + + \code + #include "network/upnp/upnpdiscovery.h" + #include "network/upnp/upnpdiscoveryreply.h" + + void DevicePluginExample::discoverUpnpDevices() { + UpnpDiscoveryReply *reply = hardwareManager()->upnpDiscovery()->discoverDevices(); + connect(reply, &UpnpDiscoveryReply::finished, this, &DevicePluginExample::onUpnpDiscoveryFinished); + } + + void DevicePluginExample::onUpnpDiscoveryFinished() { + UpnpDiscoveryReply *reply = static_cast(sender()); + + if (reply->error() != UpnpDiscoveryReply::UpnpDiscoveryReplyErrorNoError) { + qCWarning(dcExample()) << "UPnP discovery error" << reply->error(); + } + + // Note: you have to delete the reply using deleteLater() + reply->deleteLater(); + + foreach (const UpnpDeviceDescriptor &upnpDevice, reply->deviceDescriptors()) { + qCDebug(dcExample()) << upnpDevice.friendlyName() << upnpDevice.hostAddress().toString(); + } + + ... + + } + \endcode + + \sa UpnpDevice, UpnpDeviceDescriptor */ -/*! - \fn UpnpDiscovery::upnpNotify(const QByteArray ¬ifyMessage) - This signal will be emitted when a UPnP NOTIFY message \a notifyMessage will be recognized. - \sa DevicePlugin::upnpNotifyReceived() - */ +/*! \fn UpnpDiscovery::~UpnpDiscovery(); + Destroys this UpnpDiscovery. +*/ + +/*! \fn UpnpDiscoveryReply *UpnpDiscovery::discoverDevices(const QString &searchTarget = "ssdp:all", const QString &userAgent = QString(), const int &timeout = 5000); + Start a UPnP discovery request for devices listening on the given \a searchTarget and \a userAgent. The discovery duration can be specified with \a timeout parameter. +*/ + +/*! \fn void UpnpDiscovery::sendToMulticast(const QByteArray &data); + Sends \a data to the UpnP multicast group. This method can be used in order to send raw data to the group. +*/ + +/*! \fn UpnpDiscovery::upnpNotify(const QByteArray ¬ifyMessage) + This signal will be emitted when a UPnP NOTIFY message \a notifyMessage will be recognized. +*/ #include "upnpdiscovery.h" diff --git a/libnymea/network/upnp/upnpdiscoveryreply.cpp b/libnymea/network/upnp/upnpdiscoveryreply.cpp index 75f10457..c541aa62 100644 --- a/libnymea/network/upnp/upnpdiscoveryreply.cpp +++ b/libnymea/network/upnp/upnpdiscoveryreply.cpp @@ -20,8 +20,75 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class UpnpDiscoveryReply + \brief Allows to handle UPnP discovery request in the network. + + \ingroup hardware + \inmodule libguh + + \sa UpnpDevice, UpnpDiscovery +*/ + +/*! \enum UpnpDiscoveryReply::UpnpDiscoveryReplyError + + \value UpnpDiscoveryReplyErrorNoError + The reply finished successfully. + \value UpnpDiscoveryReplyErrorNotAvailable + The UpnpDiscovery HardwareResource is not available. + \value UpnpDiscoveryReplyErrorNotEnabled + The UpnpDiscovery HardwareResource is not enabled. + \value UpnpDiscoveryReplyErrorResourceBusy + The UpnpDiscovery HardwareResource is currently busy. +*/ + +// Public +/*! \fn UpnpDiscoveryReply::~UpnpDiscoveryReply(); + The virtual destructor of the UpnpDiscoveryReply. +*/ + +/*! \fn int UpnpDiscoveryReply::searchTarget() const; + Returns the search target which was used for this UpnpDiscovery request. + + \sa UpnpDiscovery::discoverDevices() +*/ + +/*! \fn int UpnpDiscoveryReply::userAgent() const; + Returns the user agent which was used for this UpnpDiscovery request. + + \sa UpnpDiscovery::discoverDevices() +*/ + +/*! \fn UpnpDiscoveryReplyError UpnpDiscoveryReply::error() const; + Returns the current error of this UpnpDiscoveryReply. + + \sa UpnpDiscoveryReplyError +*/ + +/*! \fn bool UpnpDiscoveryReply::isFinished() const; + Returns true if this UpnpDiscoveryReply is finished. + + \sa UpnpDiscoveryReplyError +*/ + +/*! \fn QList UpnpDiscoveryReply::deviceDescriptors() const; + Returns the list of found \l{UpnpDeviceDescriptor}{UpnpDeviceDescriptors}. This list will be empty if an error occured. + + \sa finished() +*/ + +// Signals +/*! \fn void UpnpDiscoveryReply::finished(); + This signal will be emitted once the UpnpDiscoveryReply is finished. +*/ + +/*! \fn void UpnpDiscoveryReply::errorOccured(const UpnpDiscoveryReplyError &error); + This signal will be emitted once an UpnpDiscoveryReply \a error occured. +*/ + #include "upnpdiscoveryreply.h" +/*! Construct a new UpnpDiscoveryReply with the given \a parent. */ UpnpDiscoveryReply::UpnpDiscoveryReply(QObject *parent) : QObject(parent) { diff --git a/libnymea/nymeasettings.cpp b/libnymea/nymeasettings.cpp index f840320c..c483c833 100644 --- a/libnymea/nymeasettings.cpp +++ b/libnymea/nymeasettings.cpp @@ -48,6 +48,9 @@ \value SettingsRoleGlobal This role will create the \b{nymead.conf} file and is used to store the global settings of the nymea system. This settings 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}. + */ #include "nymeasettings.h" diff --git a/libnymea/plugin/deviceplugin.cpp b/libnymea/plugin/deviceplugin.cpp index 87501b5d..05483782 100644 --- a/libnymea/plugin/deviceplugin.cpp +++ b/libnymea/plugin/deviceplugin.cpp @@ -28,9 +28,9 @@ \ingroup devices \inmodule libnymea - */ + /*! \fn void DevicePlugin::devicesDiscovered(const DeviceClassId &deviceClassId, const QList &devices); This signal is emitted when the discovery of a \a deviceClassId of this DevicePlugin is finished. The \a devices parameter describes the @@ -71,7 +71,7 @@ /*! \fn void DevicePlugin::autoDeviceDisappeared(const DeviceId &id) - Emit this signal when a device which was created by \l{DevicePlugin::autoDevicesAppeared} has been removed from the system. + Emit this signal when a device with the given \a id and which was created by \l{DevicePlugin::autoDevicesAppeared} has been removed from the system. Be careful with this, as this will completely remove the device from the system and with it all the associated rules. Only emit this if you are sure that a device will never come back. This signal should not be emitted for child auto devices when the parent who created them is removed. The system will automatically remove all child devices in such a case. @@ -462,6 +462,7 @@ QList DevicePlugin::myDevices() const return ret; } +/*! Returns the pointer to the main \l{HardwareManager} of this server. */ HardwareManager *DevicePlugin::hardwareManager() const { return m_deviceManager->hardwareManager(); diff --git a/libnymea/plugintimer.cpp b/libnymea/plugintimer.cpp index c0a1ce55..25780534 100644 --- a/libnymea/plugintimer.cpp +++ b/libnymea/plugintimer.cpp @@ -20,15 +20,179 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/*! + \class PluginTimer + \brief The plugin timer class for plugins. + + \ingroup hardware + \inmodule libguh + + The plugin timer allowes to trigger repeating actions in a device plugin. This timer does not represent a precise timer + should be used for not time critical things. The PluginTimerManager will schedule the requested timer as needed and + trigger the timeout() method. + + + \chapter Example + + In order to do something repeatedly in a \l{DevicePlugin} you can register a new PluginTimer like this: + + \tt devicepluginexample.h + + \code + #include "plugintimer.h" + + class DevicePluginExample : public DevicePlugin + { + ... + public: + void init() override; + + private: + PluginTimer *m_pluginTimer = nullptr; + + private slots: + void onPluginTimerTimeout(); + + ... + + }; + \endcode + + \tt devicepluginexample.cpp + + \code + + void DevicePluginExample::init() { + m_pluginTimer = hardwareManager()->pluginTimerManager()->registerTimer(10); + connect(m_pluginTimer, &PluginTimer::timeout, this, &DevicePluginExample::onPluginTimerTimeout); + } + + DevicePluginExample::~DevicePluginExample() + { + hardwareManager()->pluginTimerManager()->unregisterTimer(m_pluginTimer); + } + + \endcode + + \sa PluginTimerManager +*/ + +// Public +/*! \fn PluginTimer::~PluginTimer(); + The virtual destructor of the PluginTimer. You should always use the PluginTimerManager for destroying a PluginTimer object. +*/ + +/*! \fn int PluginTimer::interval() const; + This property holds the timeout interval in seconds. +*/ + +/*! \fn int PluginTimer::currentTick() const; + Returns the current timer tick of this PluginTimer in seconds. +*/ + +/*! \fn bool PluginTimer::running() const; + Returns true, if this PluginTimer is currently running. + + \sa start(), stop(), pause(), resume(), reset() +*/ + +// Signals +/*! \fn void PluginTimer::timeout(); + This signal will be emited if the timer timeouted. +*/ + +/*! \fn void PluginTimer::currentTickChanged(const int ¤tTick); + This signal will be emited whenever the \a currentTick of this PluginTimer changed. + + \sa currentTick() +*/ + +/*! \fn void PluginTimer::runningChanged(const bool &running); + This signal will be emited whenever the \a running status of this PluginTimer changed. + + \sa running() +*/ + +/*! \fn void PluginTimer::pausedChanged(const bool &paused); + This signal will be emited whenever the \a paused status of this PluginTimer changed. + + \sa running() +*/ + +// Public slots +/*! \fn void PluginTimer::reset(); + This method resets the timer to 0. This method does not change the current running state or the configured interval. +*/ + +/*! \fn void PluginTimer::start(); + Starts the timer. + + \sa running(), runningChanged() +*/ + +/*! \fn void PluginTimer::stop(); + Stops the timer. + + \sa running(), runningChanged() +*/ + +/*! \fn void PluginTimer::pause(); + Pauses the timer. + + \sa running() +*/ + +/*! \fn void PluginTimer::resume(); + Resumes the timer. If the timer was not on paused, this method has no effect. + + \sa pause() +*/ + + + +/*! + \class PluginTimerManager + \brief The plugin timer manager for guh. + + \ingroup hardware + \inmodule libguh + + The plugin timer manager allows to register and unregister generic timers for device plugins. In order to save + resources the PluginTimerManager is responsible to schedule the timers appropriate and stop them if the HardwareResource + gets disabled. + + You can find an example \l{PluginTimer}{here}. + + \sa PluginTimer, HardwareResource +*/ + +/*! \fn PluginTimerManager::~PluginTimerManager(); + The virtual destructor of the PluginTimerManager. +*/ + +/*! \fn PluginTimer *PluginTimerManager::registerTimer(int seconds = 60); + Registers a new PluginTimer with an interval of the given \a seconds parameter. Returns a new PluginTimer object. + + \sa unregisterTimer() +*/ + +/*! \fn void unregisterTimer(PluginTimer *timer = nullptr); + Unregisters the given \a timer. The PluginTimerManager will delete the object once the unregister process is complete. + + \sa registerTimer() +*/ + #include "plugintimer.h" #include "loggingcategories.h" +/*! Constructs a \l{PluginTimerManager} with the given \a parent. */ PluginTimerManager::PluginTimerManager(QObject *parent) : HardwareResource("PluginTimerManager", parent) { } +/*! Constructs a PluginTimer with the given \a parent. */ PluginTimer::PluginTimer(QObject *parent) : QObject(parent) { diff --git a/libnymea/types/deviceclass.cpp b/libnymea/types/deviceclass.cpp index 743f8f24..cb16fe76 100644 --- a/libnymea/types/deviceclass.cpp +++ b/libnymea/types/deviceclass.cpp @@ -449,11 +449,17 @@ void DeviceClass::setPairingInfo(const QString &pairingInfo) m_pairingInfo = pairingInfo; } + +/*! Returns the \l{Interfaces for DeviceClasses}{interfaces} of this \l{DeviceClass}.*/ QStringList DeviceClass::interfaces() const { return m_interfaces; } +/*! Set the \a interfaces of this \l{DeviceClass}. + + \note You can find information about interfaces \l{Interfaces for DeviceClasses}{here}. +*/ void DeviceClass::setInterfaces(const QStringList &interfaces) { m_interfaces = interfaces; diff --git a/libnymea/types/eventdescriptor.cpp b/libnymea/types/eventdescriptor.cpp index ba0f5993..64f78768 100644 --- a/libnymea/types/eventdescriptor.cpp +++ b/libnymea/types/eventdescriptor.cpp @@ -39,6 +39,14 @@ \sa Event, EventType, nymeaserver::Rule */ +/*! \enum EventDescriptor::Type + + \value TypeDevice + The EventDescriptor describes a device Event. + \value TypeInterface + The EventDescriptor describes an interface based Event. +*/ + #include "eventdescriptor.h" /*! Constructs an EventDescriptor describing an \l{Event} with the given \a eventTypeId, \a deviceId and the given \a paramDescriptors. */ @@ -49,6 +57,7 @@ EventDescriptor::EventDescriptor(const EventTypeId &eventTypeId, const DeviceId { } +/*! Constructs an EventDescriptor describing an \l{Event} with the given \a interface, \a interfaceEvent and the given \a paramDescriptors. */ EventDescriptor::EventDescriptor(const QString &interface, const QString &interfaceEvent, const QList ¶mDescriptors): m_interface(interface), m_interfaceEvent(interfaceEvent), @@ -57,6 +66,7 @@ EventDescriptor::EventDescriptor(const QString &interface, const QString &interf } +/*! Returns true \l{EventDescriptor::Type}{Type} of this descriptor. */ EventDescriptor::Type EventDescriptor::type() const { return (!m_deviceId.isNull() && !m_eventTypeId.isNull()) ? TypeDevice : TypeInterface; diff --git a/libnymea/types/eventtype.cpp b/libnymea/types/eventtype.cpp index 8f24832c..6de343be 100644 --- a/libnymea/types/eventtype.cpp +++ b/libnymea/types/eventtype.cpp @@ -67,7 +67,7 @@ QString EventType::displayName() const return m_displayName; } -/*! Set the displayName for this EventType to \a name, e.g. "Temperature changed". */ +/*! Set the displayName for this EventType to \a displayName, e.g. "Temperature changed". */ void EventType::setDisplayName(const QString &displayName) { m_displayName = displayName; diff --git a/libnymea/types/paramtype.cpp b/libnymea/types/paramtype.cpp index 33e722e3..079eed18 100644 --- a/libnymea/types/paramtype.cpp +++ b/libnymea/types/paramtype.cpp @@ -31,6 +31,12 @@ \sa Device, Param, ParamDescriptor */ +/*! \fn ParamType::ParamType(); + Constructs a new ParamType which is initially not valid. + + \sa isValid() +*/ + #include "paramtype.h" @@ -72,7 +78,7 @@ QString ParamType::displayName() const return m_displayName; } -/*! Sets the displayName of this ParamType, to be shown to the user, translated. */ +/*! Sets the \a displayName of this ParamType, to be shown to the user, translated. */ void ParamType::setDisplayName(const QString &displayName) { m_displayName = displayName; @@ -199,6 +205,7 @@ void ParamType::setReadOnly(const bool &readOnly) m_readOnly = readOnly; } +/*! Returns true if this ParamType is valid. A ParamType is valid, if the the id, the name and the data type is set. */ bool ParamType::isValid() const { return !m_id.isNull() && !m_name.isEmpty() && m_type != QVariant::Invalid; diff --git a/libnymea/types/ruleaction.cpp b/libnymea/types/ruleaction.cpp index 601d9f6e..560f3deb 100644 --- a/libnymea/types/ruleaction.cpp +++ b/libnymea/types/ruleaction.cpp @@ -35,9 +35,18 @@ \sa nymeaserver::Rule, RuleActionParam, */ +/*! \enum RuleAction::Type + + \value TypeDevice + The RuleAction describes a device Action. + \value TypeInterface + The RuleAction describes an interface based Action. +*/ + + #include "ruleaction.h" -/*! Constructs a RuleAction with the given by \a actionTypeId and \a deviceId. */ +/*! Constructs a RuleAction with the given by \a actionTypeId, \a deviceId and \a params. */ RuleAction::RuleAction(const ActionTypeId &actionTypeId, const DeviceId &deviceId, const RuleActionParamList ¶ms): m_id(ActionId::createActionId()), m_actionTypeId(actionTypeId), diff --git a/libnymea/types/ruleactionparam.cpp b/libnymea/types/ruleactionparam.cpp index d3a3909a..878d19fa 100644 --- a/libnymea/types/ruleactionparam.cpp +++ b/libnymea/types/ruleactionparam.cpp @@ -74,6 +74,7 @@ ParamTypeId RuleActionParam::paramTypeId() const return m_paramTypeId; } +/*! Returns the name of this RuleActionParam. */ QString RuleActionParam::paramName() const { return m_paramName; diff --git a/libnymea/types/statetype.cpp b/libnymea/types/statetype.cpp index bfa65455..eddcbab7 100644 --- a/libnymea/types/statetype.cpp +++ b/libnymea/types/statetype.cpp @@ -36,7 +36,7 @@ /*! Constructs a StateType with the given \a id. * When creating a \l{DevicePlugin} generate a new uuid for each StateType you define and - * hardcode it into the plugin. */ + * hardcode it into the plugin json file. */ StateType::StateType(const StateTypeId &id): m_id(id) { @@ -49,13 +49,13 @@ StateTypeId StateType::id() const return m_id; } -/*! Returns the name of the StateType. This is used internally, e.g. to match interfaces. */ +/*! Returns the name of the StateType. This is used internally, e.g. to match \l{Interfaces for DeviceClasses}{interfaces}. */ QString StateType::name() const { return m_name; } -/*! Set the name of the StateType to \a name. This is used internally, e.g. to match interfaces. */ +/*! Set the name of the StateType to \a name. This is used internally, e.g. to match \l{Interfaces for DeviceClasses}{interfaces}. */ void StateType::setName(const QString &name) { m_name = name; @@ -67,7 +67,7 @@ QString StateType::displayName() const return m_displayName; } -/*! Set the displayName of the StateType to \a name. This is visible to the user (e.g. "Color temperature"). */ +/*! Set the displayName of the StateType to \a displayName. This is visible to the user (e.g. "Color temperature"). */ void StateType::setDisplayName(const QString &displayName) { m_displayName = displayName; @@ -190,7 +190,7 @@ bool StateType::cached() const return m_cached; } -/*! Sets whether this StateType should be cached or not. */ +/*! Sets whether this StateType should be \a cached or not. If a state value gets cached, the state will be initialized with the cached value on start.*/ void StateType::setCached(bool cached) { m_cached = cached; diff --git a/libnymea/types/vendor.cpp b/libnymea/types/vendor.cpp index 87147dcd..f56b5ba0 100644 --- a/libnymea/types/vendor.cpp +++ b/libnymea/types/vendor.cpp @@ -69,7 +69,7 @@ QString Vendor::displayName() const return m_displayName; } -/*! Sets the name of this Vendor, to be shown to the user, translated. */ +/*! Sets the \a displayName of this Vendor, to be shown to the user, translated. */ void Vendor::setDisplayName(const QString &displayName) { m_displayName = displayName; diff --git a/nymea.pro b/nymea.pro index 295145f6..bb5a9d1c 100644 --- a/nymea.pro +++ b/nymea.pro @@ -12,6 +12,7 @@ tests.depends = libnymea libnymea-core 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/; \ cp -r favicons/* html/; cp -r $$top_srcdir/doc/html $$top_builddir/