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 API relies on protocol HTTPS, and the JSON standard. All date/time values are Unix timestamps.

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 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>
}


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:   <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>
  }
} 


Device Event Notification

!!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>
}


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:    <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>
}


Sensor Measurements Registration

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)

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: <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"
webserviceinterface.1339511209.txt.gz · Last modified: 2012/10/30 10:35 (external edit)