ETM-Schurig/powersync-core
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update API documentation and remove deprecated doc files

Browse Source
This commit is contained in:
Simon Stürz 2018-04-04 16:58:40 +02:00 committed by Michael Zanetti
parent 03ba42bd4e
commit 6608748f83
8 changed files with 200 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/allmodules.qdoc
View File

@ -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

16
doc/api.qdoc
View File

@ -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
*/

39
doc/create-setupmethods.qdoc
View File

@ -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

2
doc/html-template.qdocconf
View File

@ -18,7 +18,7 @@ HTML.postheader = \
" <div>\n" \
" <ul class=\"nymea-navbar-nav\">\n" \
" <li><a href=\"interfaces.html\">Interfaces</a></li>\n" \
" <li><a href=\"api.html\">API</a></li>\n" \
" <li><a href=\"jsonrpc.html\">API</a></li>\n" \
" <li><a href=\"write-plugins.html\">Write Plugins</a></li>\n" \
" </ul>\n" \
" </div>\n" \

13
doc/interfaces.qdoc
View File

@ -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
*/

231
doc/jsonrpc.qdoc
View File

@ -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

21
doc/plugins.qdoc
View File

@ -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
*/

2
nymea.pro
View File

@ -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(============================================)