User Tools

Site Tools


webserviceinterface

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 API version (currently supported: 1.0)
X-Digest The message digest, using the device key
Accept The response data type: application/json


Response Structure

The HTTP status code is used to inform the client of the request execution result. 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.
405 Method Not Allowed Method not supported by resource, for example, using GET on a resource that supports only POST
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:    <string(32)  - the version of a pending firmware upgrade if there is one or 0 if there is none>,
  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>
  }
} 


Firmware Upgrade File Download

Downloads a firmware upgrade file. The server responds with HTTP error 404 if there is no pending upgrade for the device.

Method GET
URL https://api.mysmartgrid.de:8443/firmware/<device id>
Request Body
{
}
Response Body
{
  data:       <string - the Base64-encoded shell script to be executed on the device>
}


Device Event Notification

Notifies the server of the occurrence of a device event. For instance, only brownout events (id 103) are implemented.

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. The header X-Digest is not informed, since authentication is based on the sensor token, informed in header X-Token.

Method GET
URL https://api.mysmartgrid.de:8443/sensor/<sensor id>?<attributes>
Extra Headers
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"
webserviceinterface.1340360538.txt.gz · Last modified: 2012/10/30 10:38 (external edit)