This is an old revision of the document!
Web Service Interface
This page is under construction. We intend to specify here the web service interface used by all users and Flukso V2 devices to communicate with the mySmartGrid server.
The mySmartGrid API adopts the RESTful model, and therefore it relies on the HTTP protocol and the JSON standard. Regarding security, all the communication is performed over HTTPS, using a server certificate issued by the mySmartGrid CA. Additionally, both request and response bodies are encrypted using the device individual SHA-1 key, which only the server and the device know.
Despite some similarities, the mySmartGrid API is different from the Flukso.net API in many important aspects. So, if you want to switch from the Flukso.net platform to mySmartGrid, we strongly recomend you to flash the latest mySmartGrid image to your device.
Request Message Structure
URL
https://api.mysmartgrid.de:8443/<object>[/<id>[?<parameters>]] … [<body>]
| Part | Description |
|---|---|
| <object> | The entity being affected by the invocation |
| <id> | The object id |
| <parameters> | The list of parameters of the operation |
| <body> | A JSON object provided by all POST messages |
HTTP Methods
| Name | Purpose |
|---|---|
| GET | object retrieval |
| POST | object update and creation |
| DELETE | object removal |
HTTP Headers
| Name | Description |
|---|---|
| X-Version | The device firmware version |
| X-Digest | The message digest, using the device key |
Response Structure
The HTTP status code is used to inform the client of the request execution status. Further information is returned in the response body. Successful requests return JSON objects, as seen in the following section, and failed requests return the default MochiWeb HTML error page. In all cases, clients should primarily check the HTTP status code in order to properly interpret the response.
HTTP Status Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | The request has been successfully processed. |
| 301 | Moved Permanently | This and all future requests should be directed to the given URI. |
| 400 | Bad request | The request cannot be fulfilled due to bad syntax. |
| 403 | Forbidden | The user is not authorized to access the requested resource. |
| 404 | Not Found | The requested resource does not exist on the server. |
| 500 | Internal Server Error | The request was aborted due to an unspecified error on the server. |
| 501 | Not Implemented | The server does not provide the requested operation. |
Messages Reference
Device Registration
Requests the registration of a device on the server.
| Method | POST |
|---|---|
| URL | https://api.mysmartgrid.de:8443/device/<device id> |
| Request Body | {
key: <string(32) - SHA-1 key used for device authentication>
}
|
| Response Body | {
upgrade: <integer - flag to indicate whether or not there is a pending firmware upgrade>,
timestamp: <unixtime - server current time>
}
|
Device Heartbeat
Sends a life signal to the server, which contains information about the device environment.
| Method | POST |
|---|---|
| URL | https://api.mysmartgrid.de:8443/device/<device id> |
| Request Body | {
memtotal: <integer - total RAM in MB>,
memcached: <integer - total cache memory in MB>,
membuffers: <integer - total buffer memory in MB>,
memfree: <integer - total free memory in MB>,
uptime: <integer - total time the device has been up and running, in seconds>,
reset: <integer - number of times the device has been reset>,
version: <integer - this field has been deprecated, and is currently being ignored by the server>,
firmware: {
version: <string(11) - firmware version using format: 9.9.9-9, for example: 2.3.1-1>,
releasetime: <string(14) - firmware release date and time using format: YYYYmmmdd_HHii, for example: 20120524_1158>,
build: <string(32) - firmware release identifier, for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>,
tag: <string(32) - firmware release tag in Git repository, for example: flukso-2.0.3-rc1-19-gf0ba69e>
}
}
|
| Response Body | The field 'support' is included only if the user requests device remote support on the web application.{
upgrade: <integer - a flag to indicate whether there is a pending upgrade>,
timestamp: <unixtime - server current time>,
support: {
user: <string(60) - username for the reverse SSH connection>,
host: <string(60) - hostname for the reverse SSH connection>,
port: <integer - port where SSH is running on host>,
tunnelport: <integer - port bound to the device localhost:22>,
devicekey: <string(700) - a Base64-encoded DSA key to be used by the device for SSH authentication>,
techkey: <string(700) - the technician DSA key to be added to file the authorized_keys on the device>,
hostkey: <string(700) - the host RSA key to be added to the file known_hosts on the device>
}
}
|
Device Event Notification
Notifies the server of the occurrence of a device event.
| Method | POST |
|---|---|
| URL | https://api.mysmartgrid.de:8443/event/<event id> |
| Request Body | {
device: <string(32) - device id>
}
|
| Response Body | {
timestamp: <unixtime - server current time>
}
|
Sensor Configuration
Registers or updates a device sensor. This message must be preceded by a device registration message.
| Method | POST |
|---|---|
| URL | https://api.mysmartgrid.de:8443/sensor/<sensor id> |
| Request Body | {
config : {
device: <string(32) - device id>,
function: <string(16) - sensor name>,
class: <string(10) - this field has been deprecated, and is currently being ignored by the server>,
voltage: <integer - this field has been deprecated, and is currently being ignored by the server>,
current: <integer - this field has been deprecated, and is currently being ignored by the server>,
phase: <integer - this field has been deprecated, and is currently being ignored by the server>,
constant: <integer - this field has been deprecated, and is currently being ignored by the server>,
type: <string(16) - this field has been deprecated, and is currently being ignored by the server>,
enable: <integer - this field has been deprecated, and is currently being ignored by the server>
}
}
|
| Response Body | {
timestamp: <unixtime - server current time>
}
|
Sensor Measurements Registration
Reports sensor measurements to the server. The measurement values are saved in RRD files in Ws (Wattseconds).
| Method | POST |
|---|---|
| URL | https://api.mysmartgrid.de:8443/sensor/<sensor id> |
| Request Body | {
measurements: [
[ <unixtime - timestamp of the first measurement>,
<integer - consumed power in kW/h (ever increasing value), measured at the first timestamp> ],
...
[ <unixtime - timestamp of the measurement n>,
<integer - consumed power in kW/h (ever increasing value), measured at the timestamp n> ]
]
}
|
| Response Body | {
response: <string(2) - "ok">
}
|
| Error Response Body | {
response: <string(200) - the error message>
}
|
Sensor Measurements Query
Queries measurements performed by a sensor.
| Method | GET |
|---|---|
| URL | https://api.mysmartgrid.de:8443/sensor/<sensor id>?<attributes> |
| Headers | Accept: application/json X-Version: <integer - device firmware version> X-Token: <string(32) - sensor token> |
| Attributes | start = <unixtime - first timestamp of a period of time> end = <unixtime - last timestamp of a period of time> resolution = <the resolution of the measurement results (minute, 15min, hour, day, week)> unit = <the unit in which the measurement results will be shown (watt, kwhperyear, eurperyear)> interval = <an alternative way of representing a period of time that ends right now (minute, 15min, day, week)> |
| Response Body | {
measurements: [
[ <unixtime - timestamp of the first measurement>,
<integer - consumed power measured at the first timestamp> ],
...
[ <unixtime - timestamp of the last measurement>,
<integer - consumed power measured at the last timestamp> ]
]
}
|
In the following, two examples are given of how this operation can be invoked from a Linux shell. The sensor id and token are fictitious and should be replaced by real values.
Query 1: Measurements performed during the past 1 hour, in minute resolution, and in watt.
curl -k -v -X GET -H "X-Version: 1.0" -H "X-Token: dvd1mtm1tktktktktktktktktktktkt1" -H "Accept: application/json" "https://api.mysmartgrid.de:8443/sensor/dvd1mtmtmtmtmtmtmtmtmtmtmtmtmtm1?interval=hour&unit=watt"
Query 2: Measurements performed between 05.10.2011 00:00:00 GMT+2:00 and 05.10.2011 17:00:00 GMT+2:00, in 15-minute resolution, and in euros per year.
curl -k -v -X GET -H "X-Version: 1.0" -H "X-Token: dvd1mtm1tktktktktktktktktktktkt1" -H "Accept: application/json" "https://api.mysmartgrid.de:8443/sensor/dvd1mtmtmtmtmtmtmtmtmtmtmtmtmtm1?start=1317765600&end=1317826800&resolution=15min&unit=eurperyear"
