diff --git a/doc/allmodules.qdoc b/doc/allmodules.qdoc index 34ad63e3..ed9d8f26 100644 --- a/doc/allmodules.qdoc +++ b/doc/allmodules.qdoc @@ -5,7 +5,6 @@ \table 80% \row \li \l{nymeaserver} \li The nymea server daemon implementation \row \li \l{libnymea} \li Common data types and plugin interfaces - \row \li \l{Plugins} \li The device plugins of the nymea server \endtable \generatelist legalese-command diff --git a/doc/api.qdoc b/doc/api.qdoc deleted file mode 100644 index 68761dfb..00000000 --- a/doc/api.qdoc +++ /dev/null @@ -1,16 +0,0 @@ -/*! - \page api.html - \title Overview of nymea API's - - The nymea server provides two different API's: - \list - \li \l{JSON-RPC API}{JSON-RPC} - \li \l{https://github.com/guh/nymea/wiki/REST-API}{REST} - \endlist - - The \l{https://github.com/guh/nymea/wiki/REST-API}{REST API} is accessable on the \l{nymeaserver::WebServer}{WebServer}. The JSON-RPC API can be accessed from the \l {nymeaserver::TcpServer}{TcpServer} and the \l {nymeaserver::WebSocketServer}{WebSocketServer} interface. The command line interface \b {\tt nymea-cli} communicates with the \l {nymeaserver::TcpServer}{TcpServer} and \l {JSON-RPC API}. The \b {\tt nymea-webinterface} uses the \l{nymeaserver::WebServer}{WebServer} with the \l{https://github.com/guh/nymea/wiki/REST-API}{REST-API} and catches notifications from the \l {nymeaserver::WebSocketServer}{WebSocketServer}. - - \image api-overview.png - -*/ - diff --git a/doc/create-setupmethods.qdoc b/doc/create-setupmethods.qdoc index a73ad7e3..121f7a27 100644 --- a/doc/create-setupmethods.qdoc +++ b/doc/create-setupmethods.qdoc @@ -3,35 +3,38 @@ \title CreateMethods and SetupMethods \brief This page describes how the setup and creation of a device is working in a plugin. - This page describes how the setup and creation of a device is working in a plugin. Since the device manager handles all the plugins and devices there are certain steps during the device setup which have to be considered. + This page describes how the setup and creation of a device is working in a plugin. Since the device manager + handles all the plugins and devices there are certain steps during the device setup which have to be considered. - The \l{DeviceClass::CreateMethods}{CreateMethod} describes how the device will be created (by the user, by discovery or automatically). - The \l{DeviceClass::SetupMethod}{SetupMethod} describes how the device will be set up. A \l{Device} can have multiple \l{DeviceClass::CreateMethods}{CreateMethods}, but only one \l{DeviceClass::SetupMethod}{SetupMethod}. + The \l{DeviceClass::CreateMethods}{CreateMethod} describes how the device will be created + (by the user, by discovery or automatically). + The \l{DeviceClass::SetupMethod}{SetupMethod} describes how the device will be set up. A \l{Device} can have + multiple \l{DeviceClass::CreateMethods}{CreateMethods}, but only one \l{DeviceClass::SetupMethod}{SetupMethod}. \list \li \l{DeviceClass::CreateMethods}{CreateMethods} \list - \li \e user \unicode{0x2192} \l{DeviceClass::CreateMethodUser} - \li \e discovery \unicode{0x2192} \l{DeviceClass::CreateMethodDiscovery} - \li \e auto \unicode{0x2192} \l{DeviceClass::CreateMethodAuto} + \li \tt User \unicode{0x2192} \l{DeviceClass::CreateMethodUser} + \li \tt Discovery \unicode{0x2192} \l{DeviceClass::CreateMethodDiscovery} + \li \tt Auto \unicode{0x2192} \l{DeviceClass::CreateMethodAuto} \endlist \li \l{DeviceClass::SetupMethod}{SetupMethods} \list - \li \e justAdd \unicode{0x2192} \l{DeviceClass::SetupMethodJustAdd} - \li \e displayPin \unicode{0x2192} \l{DeviceClass::SetupMethodDisplayPin} - \li \e enterPin \unicode{0x2192} \l{DeviceClass::SetupMethodEnterPin} - \li \e pushButton \unicode{0x2192} \l{DeviceClass::SetupMethodPushButton} + \li \tt JustAdd \unicode{0x2192} \l{DeviceClass::SetupMethodJustAdd} + \li \tt DisplayPin \unicode{0x2192} \l{DeviceClass::SetupMethodDisplayPin} + \li \tt EnterPin \unicode{0x2192} \l{DeviceClass::SetupMethodEnterPin} + \li \tt PushButton \unicode{0x2192} \l{DeviceClass::SetupMethodPushButton} \endlist \endlist - \section1 CreateMethod \b "user" - SetupMethod \b "justAdd - synchronous" + \section1 CreateMethod \b "User" - SetupMethod \b "JustAdd - synchronous" This is the simplest setup what a device can have. \list - \li CreateMethod \b "user": the user has to fill out the \l{Param}{Params} of the device by hand - \li SetupMethod \b "justAdd": there is nothing special to do during the setup with the device. + \li CreateMethod \b "User": the user has to fill out the \l{Param}{Params} of the device by hand + \li SetupMethod \b "JustAdd": there is nothing special to do during the setup with the device. \endlist Once the is adding the device the \l{DeviceManager} is calling following methods in the device plugin: @@ -47,7 +50,7 @@ \endlist \endlist - \section1 CreateMethod \b "user" - SetupMethod \b "justAdd" - asynchronous + \section1 CreateMethod \b "User" - SetupMethod \b "JustAdd" - asynchronous \image setup-async-resized.png @@ -80,7 +83,7 @@ \endlist - \section1 CreateMethod \b "discovery" - SetupMethod \b "justAdd" + \section1 CreateMethod \b "Discovery" - SetupMethod \b "JustAdd" \image setup-discovery-resized.png @@ -99,7 +102,7 @@ \endlist \endlist - \section1 CreateMethod \b "discovery" - SetupMethod \b "pushButton" + \section1 CreateMethod \b "Discovery" - SetupMethod \b "PushButton" \image setup-discovery-pairing-resized.png @@ -124,7 +127,7 @@ \endlist \endlist - \section1 CreateMethod \b "discovery" - SetupMethod \b "enterPin" + \section1 CreateMethod \b "Discovery" - SetupMethod \b "EnterPin" \image setup-discovery-pairing-resized.png @@ -150,7 +153,7 @@ \endlist - \section1 CreateMethod \b "discovery" - SetupMethod \b "displayPin" + \section1 CreateMethod \b "Discovery" - SetupMethod \b "DisplayPin" \image setup-discovery-display-pin-resized.png diff --git a/doc/html-template.qdocconf b/doc/html-template.qdocconf index cd9ec648..2e49a903 100644 --- a/doc/html-template.qdocconf +++ b/doc/html-template.qdocconf @@ -18,7 +18,7 @@ HTML.postheader = \ "
\n" \ " \n" \ "
\n" \ diff --git a/doc/interfaces.qdoc b/doc/interfaces.qdoc index 90f53990..b783e104 100644 --- a/doc/interfaces.qdoc +++ b/doc/interfaces.qdoc @@ -7,8 +7,8 @@ When creating a DeviceClass, the interfaces field can be used to specify a list of interfaces this DeviceClass implements. When implementing an interface, the DeviceClass must follow the interface specification for the according interface. This means - the DeviceClass needs to have at least all the \l{StateType}{states}, \l{ActionType}{actions} and \l{EventType}{events} the given interface requires. A DeviceClass may - add custom states, actions or events, or even implement multiple interfaces. + the DeviceClass needs to have at least all the \l{StateType}{states}, \l{ActionType}{actions} and \l{EventType}{events} the + given interface requires. A DeviceClass may add custom states, actions or events, or even implement multiple interfaces. The main purpose of interfaces is to provide for a better user experience. Using interfaces, a plugin developer can suggest the ui to be used for this DeviceClass. For example, having a plugin that can control a dimmable light would likely have a state @@ -26,12 +26,13 @@ In general it is a good idea to follow as many interfaces as precicely as possible in order to provide for the best user experience. A interface can extend another interface. For example, the \l {light} interface only requires one state called powered of type bool. - A dimmablelight extends this type and adds a brightness property to it. This means, if a DeviceClass implements \l {dimmablelight}, it - also needs to cater for the \l {light} interface's states. + A dimmablelight extends this type and adds a brightness property to it. This means, if a DeviceClass implements \l {dimmablelight}, + it also needs to cater for the \l {light} interface's states. - \section1 Currently available interfaces + \section1 Available interfaces + This following list shows you the current available interfaces. + \include interfacelist.qdoc - */ diff --git a/doc/jsonrpc.qdoc b/doc/jsonrpc.qdoc index 6939c321..93bff9c1 100644 --- a/doc/jsonrpc.qdoc +++ b/doc/jsonrpc.qdoc @@ -20,38 +20,98 @@ The request message is a JSON objects and contains following properties: - \list - \li \code "id": integer \endcode - The id should be a unique identifier for the message. Any server response will contain the - same id allowing to match responses to requests/commands. This parameter is mandatory. - \li \code "method": string \endcode - The method field holds the method to be executed. Methods are grouped into namespaces. The - method string consists of two parts, the namespace and the method name, separated by a dot. - This parameter is mandatory. (i.e: \l{JSONRPC.Introspect}) - \li \code "token": string \endcode - The token property contains the authentication token received from the \l{Authentication}{authentication} process. - This parameter is optional and only required if the authentication is enabled. - \li \code "params": object \endcode - The params contains any JSON object. This parameter is optional and differs according to - the requested method. - \endlist + \code + { + "id": integer, + "method": "Namespace.Method", + "o:token": "string", + "o:params" { } + } + \endcode + + \note \b M = mandatory, \b O = optional + + \table + \row + \li \tt id + \li \b M + \li integer + \li The id should be a unique identifier for the message. Any server response will contain the + same id allowing to match responses to requests/commands. + \row + \li \tt method + \li \b M + \li string + \li The method field holds the method to be executed. Methods are grouped into namespaces. The + method string consists of two parts, the namespace and the method name, separated by a dot + (i.e: \l{JSONRPC.Introspect}). + + \b{See also:} \l{Methods} + + \row + \li \tt token + \li \b O + \li string + \li The token property contains the authentication token received from the \l{Authentication}{authentication} + process. This parameter is optional and only required if the authentication is enabled. + + \b{See also:} \l{Authentication} + + \row + \li \tt params + \li \b O + \li object + \li The params contains any JSON object. This parameter is optional and differs according to + the requested method. + + \endtable + \section2 Response message The response message is a JSON objects and contains following properties: - \list - \li \code "id": integer \endcode - The id matching to the requested id. - \li \code "status": string \endcode - The status property contains either \tt {"success"}, \tt {"error"} or \tt {"unauthorized"} and is mandatory. - \li \code "params": object \endcode - The params contains the response JSON object. This parameter is optional and differs according to - the requested method (see \c Returns section of each method). - \li \code "error": string \endcode - The error property will only be added if a protocol related error happen and the \tt {"status"} property is \tt {"error"} or \tt {"unauthorized"}. - The value contains a description of the error. - \endlist + \code + { + "id": integer, + "status": "string", + "o:params" { }, + "o:error": "string" + } + \endcode + + \note \b M = mandatory, \b O = optional + + \table + \row + \li \tt id + \li \b M + \li integer + \li The id matching to the requested \tt {id}. + \row + \li \tt status + \li \b M + \li string + \li The status property can be: + \list + \li \tt {"success"} + \li \tt {"error"} + \li \tt {"unauthorized"} + \endlist + \row + \li \tt params + \li \b O + \li object + \li The params contains any JSON object. This parameter is optional and differs according to + the requested method. + \row + \li \tt error + \li \b O + \li string + \li The error property will only be added if a protocol related error happen and the \tt {"status"} property is \tt {error} or \tt {unauthorized}. + The value contains a description of the API error. + \endtable + If there is an error on the JSON RPC transport layer, the server will respond with an error message. This error is related to the protocol layer of the communication. @@ -82,31 +142,58 @@ } \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 - using \l{Configuration.SetServerName}. - \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 being 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 using \l{Configuration.SetLanguage}. - \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 + \table + \row + \li \tt id + \li integer + \li The id in the handshake has always the value 0. This is the first message during connection. + \row + \li \tt name + \li string + \li This field represents the name of the server you are connected to. This name is user defined an can be changed + using \l{Configuration.SetServerName}. + \row + \li \tt {protocol version} + \li string + \li The field represents the API version of the server you are connected to (\tt{Major.Minor}). This should be used for API + compatibility checks. A major version bump indicates a breaking API change, a minor version bump is means something was added and + does not break the API compatibility. + \row + \li \tt authenticationRequired + \li bool + \li If this property is true, a client must perform the authentication process before being able to interact with the API. + \b{See also:} \l{Authentication} + \row + \li \tt initialSetupRequired + \li bool + \li 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. + \row + \li \tt pushButtonAuthAvailable + \li bool + \li 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. + + \b{See also:} \l{Push-button authentication} + \row + \li \tt server + \li string + \li This property holds the name of the server. This name can not be changed. + \row + \li \tt language + \li string + \li This property holds the language of the server. The language can be changed in the settings using \l{Configuration.SetLanguage}. + \row + \li \tt uuid + \li string + \li This property holds the UUID of the server and can be used as a unique identifier. + \row + \li \tt version + \li string + \li This property holds the build version of the server. + + \endtable \section1 Sending a request @@ -148,16 +235,38 @@ A notification message has following properties: - \list - \li \code "id": integer \endcode - The id should be a unique identifier for the message. The notification id will be increased for each notification sent to your connection. - \li \code "notification": string \endcode - The notification field holds the name of this notification. Notifications are grouped into namespaces like the methods. - The notification string consists of two parts, the namespace and the notification name, separated by a dot. - This property can be used to check if a received message is a response to a request or a notification. - \li \code "params": object \endcode - The params contains any JSON object. This parameter is optional and differs according to each \l{Notifications}{notification}. - \endlist + \code + { + "id": integer, + "notification": "Namespace.Notification", + "o: params": { } + + } + \endcode + + \note \b M = mandatory, \b O = optional + + \table + \row + \li \tt id + \li \b M + \li integer + \li The id should be a unique identifier for the message. The notification id will be increased for each notification sent to your connection. + \row + \li \tt notification + \li \b M + \li string + \li The notification field holds the name of this notification. Notifications are grouped into namespaces like the methods. + The notification string consists of two parts, the namespace and the notification name, separated by a dot. + This property can be used to check if a received message is a response to a request or a notification. + + \b{See also:} \l{Methods} + \row + \li \tt params + \li \b O + \li object + \li The params contains any JSON object. This parameter is optional and differs according to each \l{Notifications}{notification}. + \endtable \chapter Authentication diff --git a/doc/plugins.qdoc b/doc/plugins.qdoc deleted file mode 100644 index 1cb06b2c..00000000 --- a/doc/plugins.qdoc +++ /dev/null @@ -1,21 +0,0 @@ -/*! - \page plugins.html - \title Plugins - - Here you can find the current list of supported plugins sorted by the corresponding package. - - \section2 The default \tt{nymea-plugins} package: - \annotatedlist nymea-plugins - - \section2 The \tt{nymea-plugins-merkur} package: - \annotatedlist nymea-plugins-merkur - - \section2 The \tt{nymea-plugins-maker} package: - \annotatedlist nymea-plugins-maker - - \section2 The \tt{nymea-tests} package plugins: - \annotatedlist nymea-tests - -*/ - - diff --git a/nymea.pro b/nymea.pro index b67def56..34ac69f3 100644 --- a/nymea.pro +++ b/nymea.pro @@ -42,7 +42,7 @@ INSTALLS += translations QMAKE_EXTRA_TARGETS += licensecheck doc test lupdate lrelease # Show doc files in project tree -OTHER_FILES += doc/*.qdoc +OTHER_FILES += doc/* # Inform about nymea build message(============================================)