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 HTTPS protocol and the JSON standard.
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.
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 |
Messages Reference
Device Registration
Requests the registration of a device on the server.
| Method | POST |
|---|---|
| URL | https://api.mysmartgrid.de:8443/device/<device id> |
| Body | {
key: <string(32) - SHA-1 key used for device authentication>
}
|
| Response | {
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> |
| 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 | 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> |
| Body | {
device: <string(32) - device id>
}
|
| Response | {
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> |
| 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 | {
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> |
| 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 | {
response: <string(2) - "ok">
}
|
| Error Response | {
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 | {
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"
