160 lines
5.1 KiB
Plaintext
160 lines
5.1 KiB
Plaintext
/*!
|
|
\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
|
|
|
|
*/
|