mirror of https://github.com/nymea/nymea.git
add initial docs
Michael Zanetti
parent
842236ddf1
commit
fdd4bc8718
4
Hive.pro
4
Hive.pro
|
|
@ -4,3 +4,7 @@ SUBDIRS += libhive server plugins
|
|||
|
||||
server.depends = libhive plugins
|
||||
plugins.depends = libhive
|
||||
|
||||
docs.depends = libhive server
|
||||
docs.commands = cd ../doc; qdoc config.qdocconf
|
||||
QMAKE_EXTRA_TARGETS += docs
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
include(html-template.qdocconf)
|
||||
|
||||
project = Hive
|
||||
description = Hive your Home!
|
||||
|
||||
outputdir = html
|
||||
outputformats = HTML
|
||||
|
||||
headerdirs = ..
|
||||
headers.fileextensions = "*.h"
|
||||
|
||||
sourcedirs = ..
|
||||
sources.fileextensions = "*.cpp *.qdoc"
|
||||
|
||||
|
|
@ -0,0 +1,22 @@
|
|||
/*!
|
||||
\page index.html
|
||||
\title Hive
|
||||
|
||||
\section1 Summary
|
||||
The hive backend service consists of three main modules:
|
||||
|
||||
\list
|
||||
\li libhive
|
||||
\list
|
||||
\li \l{Types} used in the hive system
|
||||
\li Defines plugin API and plugin loading mechanism
|
||||
\endlist
|
||||
\li Hive server
|
||||
\list
|
||||
\li Hive core
|
||||
\li \l{JSONRPC Interface}
|
||||
\li Rules engine
|
||||
\endlist
|
||||
\li Device plugins. A collection of officially supported device plugins.
|
||||
\endlist
|
||||
*/
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
# Define the location of the templates to use. Style sheets and scripts are
|
||||
# specified relative to the template directory and will be copied into
|
||||
# subdirectories of the output directory.
|
||||
|
||||
HTML.templatedir = .
|
||||
|
||||
HTML.stylesheets = style.css
|
||||
|
||||
HTML.scripts =
|
||||
|
||||
# Files not referenced in any qdoc file (last four needed by qtdemo)
|
||||
# See also qhp.Qt.extraFiles
|
||||
extraimages.HTML = qt-logo.png \
|
||||
arrow_down.png \
|
||||
breadcrumb.png \
|
||||
bullet_gt.png \
|
||||
bullet_dn.png \
|
||||
bullet_sq.png \
|
||||
bullet_up.png \
|
||||
horBar.png \
|
||||
sprites-combined.png
|
||||
|
||||
# Include the style sheets and scripts used.
|
||||
|
||||
HTML.headerstyles = \
|
||||
" <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
|
||||
|
||||
HTML.headerscripts =
|
||||
|
||||
HTML.endheader = \
|
||||
"</head>\n" \
|
||||
"<body>\n"
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
include(html-styles.qdocconf)
|
||||
|
||||
HTML.postheader = \
|
||||
"<div class=\"header\" id=\"qtdocheader\">\n" \
|
||||
" <div class=\"content\"> \n" \
|
||||
" <a href=\"index.html\" class=\"qtref\"><span>Hive Documentation</span></a>\n" \
|
||||
" </div>\n" \
|
||||
" <div class=\"breadcrumb toolblock\">\n" \
|
||||
" <ul>\n" \
|
||||
" <li class=\"first\"><a href=\"index.html\">Home</a></li>\n" \
|
||||
" <!-- Breadcrumbs go here -->\n"
|
||||
|
||||
HTML.postpostheader = \
|
||||
" </ul>\n" \
|
||||
" </div>\n" \
|
||||
"</div>\n" \
|
||||
"<div class=\"content mainContent\">\n"
|
||||
|
||||
HTML.footer = ""
|
||||
# Files not referenced in any qdoc file.
|
||||
# See also extraimages.HTML
|
||||
|
|
@ -1,3 +1,13 @@
|
|||
/*!
|
||||
\class State
|
||||
\brief The container class for States.
|
||||
\inmodule Types
|
||||
|
||||
\ingroup types
|
||||
|
||||
Lorem ipsum
|
||||
*/
|
||||
|
||||
#include "state.h"
|
||||
|
||||
State::State(const QUuid &stateTypeId, const QUuid &deviceId):
|
||||
|
|
|
|||
|
|
@ -0,0 +1,12 @@
|
|||
/*!
|
||||
\page types.html
|
||||
\title Types
|
||||
\nextpage
|
||||
libhive types:
|
||||
|
||||
\list
|
||||
\li \c State
|
||||
\li \c Trigger
|
||||
\li \c Action
|
||||
\endlist
|
||||
*/
|
||||
|
|
@ -0,0 +1,159 @@
|
|||
/*!
|
||||
\page jsonrpc.html
|
||||
\title JSONRPC Interface
|
||||
\section1 Description
|
||||
|
||||
The JSON RPC interface represents a TCP 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 Hive 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
|
||||
the system. A more limited REST API implementation might be added in the main controller interface.
|
||||
|
||||
The JSON message protocol communicates by exchanging JSON Objects with the following properties:
|
||||
\list
|
||||
\li \c "id": \c integer
|
||||
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 "method": string
|
||||
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.
|
||||
(Example: "JSONRPC.Introspect")
|
||||
\li "params": Object
|
||||
The params contains any JSON object. This parameter is optional and differs according to
|
||||
the requested method.
|
||||
\endlist
|
||||
|
||||
The JSONRPC API is self documenting and can be introspected by calling JSONRPC.Introspect.
|
||||
|
||||
\section1 Communicating with the server
|
||||
The server listens on TCP port 1234 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 Hive server
|
||||
is running:
|
||||
\code
|
||||
$ telnet localhost 1234
|
||||
Trying 127.0.0.1...
|
||||
Connected to localhost.
|
||||
Escape character is '^]'.
|
||||
{
|
||||
"id":0,
|
||||
"status": "connected",
|
||||
"server":"Hive JSONRPC Interface"
|
||||
"version":"0.0.0"
|
||||
}
|
||||
\endcode
|
||||
Now the connection is established and waits for commands.
|
||||
|
||||
|
||||
\section1 Examples
|
||||
|
||||
\section2 Introspect API
|
||||
\section3 Request
|
||||
\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"
|
||||
],
|
||||
"triggers": [
|
||||
"$ref:TriggerType"
|
||||
]
|
||||
},
|
||||
...
|
||||
}
|
||||
},
|
||||
"status": "success"
|
||||
}
|
||||
\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"
|
||||
}
|
||||
],
|
||||
"triggers": [
|
||||
{
|
||||
"id": "{7cae711a-a0af-41b4-b3bf-38d3e23b41ba}",
|
||||
"name": "inRange",
|
||||
"params": [
|
||||
{
|
||||
"name": "inRange",
|
||||
"type": "bool"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
...
|
||||
]
|
||||
}
|
||||
"status": "success"
|
||||
}
|
||||
\endcode
|
||||
|
||||
*/
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
/*!
|
||||
\page server.html
|
||||
\title Hive Server
|
||||
\nextpage
|
||||
The Hive server is the instance that communicates with the hardware and provides a JSONRPC interface
|
||||
for communicating with the UI.
|
||||
|
||||
|
||||
*/
|
||||
|
|
@ -38,6 +38,8 @@ void TcpServer::newClientConnected()
|
|||
connect(newConnection, SIGNAL(readyRead()),this,SLOT(readPackage()));
|
||||
connect(newConnection,SIGNAL(disconnected()),this,SLOT(clientDisconnected()));
|
||||
|
||||
// TODO: properly handle this with jsonrpcserver
|
||||
newConnection->write("{\n \"id\":0,\n \"status\": \"connected\",\n \"server\":\"Hive JSONRPC Interface\"\n \"version\":\"0.0.0\"\n}\n");
|
||||
}
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue