This is an old revision of the document!
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 API relies on protocol HTTPS, and the JSON standard. All date/time values are Unix timestamps.
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 |
Name | Purpose |
---|---|
GET | object retrieval |
POST | object update and creation |
DELETE | object removal |
Name | Description |
---|---|
X-Version | The device firmware version |
X-Digest | The message digest, using the device key |
Requests registration of a device on the server.
Method | POST |
---|---|
URL | https://api.mysmartgrid.de:8443/device/<device id> |
Body | { key: <SHA-1 key (32 bytes long) used for device authentication> } |
Response | { upgrade: <a flag to indicate whether or not there is a pending firmware upgrade>, timestamp: <server current time> } |
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: <total RAM>, memcached: <total cache memory in MB>, membuffers: <total buffer memory in MB>, memfree: <total free memory in MB>, uptime: <total time the device is up and running>, reset: <number of times the device has been reseted>, version: <device version>, firmware: { version: <firmware version, for example: 2.3.1-1 >, releasetime: <firmware release date and time using format: YYYYmmmdd_HHii, for example: 20120524_1158>, build: <firmware release identifier, for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>, tag: <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: <a flag to indicate whether there is a pending upgrade>, timestamp: <server current time>, support: { user: <username for the reverse SSH connection>, host: <hostname for the reverse SSH connection>, port: <port for the reverse SSH connection>, devicekey: <a Base64-encoded DSA key to be used by the device for SSH authentication>, techkey: <the technician DSA key to be added to file the authorized_keys on the device>, hostkey: <the host RSA key to be added to the file known_hosts on the device> } } |
!!Not yet verified or tested!!
Notifies the server of the occurrence of a device event.
Method | POST |
---|---|
URL | https://api.mysmartgrid.de:8443/event/<event id> |
Body | { device: <device id> } |
Response | { timestamp: <server current time> } |
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: <device id>, function: <sensor name>, [ class: <electricity,...>], [ type: <analog,s0,...>], [ function: <name>], [ voltage: 230], [ current: <int]>, [ constant: <int>], [ enable: <0,1>], } } |
Response | { timestamp: <server current time> } |
Reports sensor measurements to the server.
Method | POST |
---|---|
URL | https://api.mysmartgrid.de:8443/sensor/<sensor id> |
Body | { measurements: [[<timestamp1>,<value1>], [<timestamp2>,<value2>], ... ,[<timestamp n>,<value n>]] } |
Response | { response: ok } |
Error Response | { response: <error message> } |
timestamp: unix timestamp (long)
value: consumed power (increasing value) kW/h
values are save in rrd-file as Ws (Wattseconds)
Queries measurements performed by a sensor.
Method | GET |
---|---|
URL | https://api.mysmartgrid.de:8443/sensor/<sensor id>?<attributes> |
Headers | Accept: application/json X-Version: <device firmware version> X-Token: <sensor token> |
Attributes | 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) start first timestamp of a period of time end last timestamp of a period of time interval an alternative way of representing a period of time that ends right now (minute, 15min, day, week) |
Response | { measurements: [[<timestamp1>,<value1>], [<timestamp2>,<value2>], ... ,[<timestamp n>,<value n>]] } |
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"