MySmartGrid Developer Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

===== Web Service Interface (Version 2.1) =====

This page specifies the web service interface used by all users and software clients (including Flukso V2 devices) to communicate with the mySmartGrid server.

The mySmartGrid API adopts the RESTful model, and therefore relies on the HTTP protocol and the JSON standard. 
All the communication is performed over HTTPS, using a server certificate issued by the mySmartGrid CA.

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 [[http://openwrt.mysmartgrid.de/flm02/atheros|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 Common Headers ===
^ Name            ^  Description                                                                   ^
| X-Version       | The minimum version supported by this API (currently, 1.0)                     |
| Accept          | The response data type: application/json                                       |
| User-Agent      | The name of the client software, performing the request, for example: Flukso 2 |
 \\ 


==== 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 by the server. |
| 301             | Moved Permanently     | This and all future requests should be directed to the given URL. |
| 400             | Bad request           | The request cannot be fulfilled due to bad syntax. Please check the message structure. |
| 401             | Unauthorized          | The user is not authorized to access the requested resource,  because it has not been successfully authenticated. Please check the object id, device key, and token. |
| 403             | Forbidden             | The user is not authorized to access the requested resource, even if authenticated. Please check the URL and object id. |
| 404             | Not Found             | The requested resource does not exist on the server. Please check the object id used. |
| 405             | Method Not Allowed    | Method not supported by resource, for example, using GET on a resource that supports only POST. |
| 406             | Not acceptable        | The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. Please check the message structure, and use the headers as described in this page. |
| 470             | Invalid Timestamp     | The request cannot be fulfilled because it contains invalid timestamps. Please check your message data and be sure your system clock is up-to-date. |
| 471             | Invalid Unit          | The request cannot be fulfilled because it contains an invalid unit. Please have a look at the list of supported units below.|
| 472             | Invalid Measurement   | The request cannot be fulfilled because it contains invalid measurement values. Please check the message structure. |
| 473             | Invalid Object Type   | The request cannot be fulfilled because it contains invalid object type. Please check the message structure. |
| 474             | Invalid Object Id     | The request cannot be fulfilled because it contains invalid object id. Please check the message structure. |
| 475             | Invalid Key   | The request cannot be fulfilled because it contains invalid key. Please check the message structure. |
| 476             | Invalid Time Period   | The request cannot be fulfilled because it contains invalid time period. Please check the message structure. |
| 477             | Invalid Event         | The request cannot be fulfilled because it contains invalid an invalid event id. Please check the message structure. |
| 478             | Unupgradable Firmware | The current device firmware can not be upgraded via the API. Please, flash the [[http://openwrt.mysmartgrid.de/flm02/atheros|latest mySmartGrid image]] to your device manually. |
| 479             | Invalid Sensor External Id | The request cannot be fulfilled because it contains invalid sensor external id. Please check the message structure. If the problem persists, the id might be taken. In this case, please inform a new one. |
| 480             | Invalid Characters  | The request cannot be fulfilled because it contains a string with non-printable characters. |
| 481             | Invalid Network Configuration | The request cannot be fulfilled because it contains invalid network configuration properties. Please check the message structure. |
| 500             | Internal Server Error | The request was aborted due to an unspecified error on the server. This incident has been reported to the mySmartGrid team. |
| 501             | Not Implemented       | The server does not provide the requested operation. Please check the X-Version header and the URL structure.  |
 \\ 


==== Measurement Units ====

The table below shows the list of measurement units supported by the API. Use their ids to inform the unit arguments of some requests.

^ Name                     ^  Symbol        ^  Id            ^
| Watt                     | W              | Watt           |
| Kilowatt-hour            | kWh            | kWh            |
| Kilowatt-hour per year   | kWh / year     | kWhPerYear     |
| Watt-hour                | Wh             | Wh             |
| Degree Celsius           | °C             | degC           |
| Hectopascal              | hPa            | hPa            |
| Relative Humidity        | %r.h.          | rh             |
| Internal Control Unit    | _hsbs          | _hsbs          |
\\


==== Messages Reference ====

=== Device Registration ===

Requests the registration of a device on the server.

^ Method        | POST                                                    |
^ URL           | %%https://api.mysmartgrid.de:8443%%/device/<device id>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Request Body |
  {
    key:         <string(32) - SHA-1 key used for device authentication>,
    description: <string(60) - the description of the device (optional)>,
    memtotal:    <integer - total RAM in MB (optional)>,
    memcached:   <integer - total cache memory in MB (optional)>,
    membuffers:  <integer - total buffer memory in MB (optional)>,
    memfree:     <integer - total free memory in MB (optional)>,
    uptime:      <integer - total time the device has been up and running, in seconds>,
    reset:       <integer - number of times the device has been reset (optional)>,
    version:     <integer - deprecated field, currently being ignored by the server>,
    firmware:    (optional) { 
      version:     <string(11) - firmware version, using the
                                 format: 9.9.9-9, for example: 2.3.1-1>,
      releasetime: <string(14) - firmware release date and time, using the
                                 format: YYYYmmmdd_HHii, for example: 20120524_1158>,
      build:       <string(40) - firmware release identifier,
                                 for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>,
      tag:         <string(32) - firmware release tag in Git repository,
                                 for example: flukso-2.0.3-rc1-19-gf0ba69e>
    },
    type: <the device type (flukso2, vzlogger, libklio, raspberrypi)
          (mandadory if firmware is informed)>
  }
|
^ Response Body | 
  {
    upgrade:   <integer  - flag to indicate whether or not there is a pending firmware upgrade>, 
    timestamp: <unixtime - server current time>
  }
| 
\\ 

=== Device Removal ===

Removes a device and all its related data from the server.

^ Method       | DELETE                                                    |
^ URL          | %%https://api.mysmartgrid.de:8443%%/device/<device id>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Response Body | 
  {
    response: <string(2) - "ok">
  }
|
^ Error Response Body |
  {
    response: <string(200) - the error message>
  }
|
\\ 

=== 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>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Request Body | The field 'config' is included only if the Flukso changed its configuration due to the information from the last heartbeat.
  {
    description: <string(60) - the description of the device (optional)>,
    memtotal:    <integer - total RAM in MB (optional)>,
    memcached:   <integer - total cache memory in MB (optional)>,
    membuffers:  <integer - total buffer memory in MB (optional)>,
    memfree:     <integer - total free memory in MB (optional)>,
    uptime:      <integer - total time the device has been up and running, in seconds>,
    reset:       <integer - number of times the device has been reset (optional)>,
    version:     <integer - deprecated field, currently being ignored by the server>,
    firmware:   (optional) { 
      version:     <string(11) - firmware version, using the
                                 format: 9.9.9-9, for example: 2.3.1-1>,
      releasetime: <string(14) - firmware release date and time, using the
                                 format: YYYYmmmdd_HHii, for example: 20120524_1158>,
      build:       <string(40) - firmware release identifier,
                                 for example: f0ba69e4fea1d0c411a068e5a19d0734511805bd>,
      tag:         <string(32) - firmware release tag in Git repository,
                                 for example: flukso-2.0.3-rc1-19-gf0ba69e>
    },
    config:     (optional) {
      network:    (optional) {
        lan:        (optional) {
          enabled:  <integer>,
          protocol: <string(6)  - either static or dhcp>,
          ip:       <string(15) - iff protocol is static>,
          netmask:  <string(15) - iff protocol is static>,
          gateway:  <string(15) - iff protocol is static>
        },
        wifi:       (optional) {
          enabled:  <integer>,
          essid:    <string(60)>,
          enc:      <string(5)  - one of open,wep,wpa,wpa2>,
          psk:      <string(60) - iff enc is wep, wpa or wpa2>,
          protocol: <string(6)  - either static or dhcp>,
          ip:       <string(15) - iff protocol is static>,
          netmask:  <string(15) - iff protocol is static>,
          gateway:  <string(15) - iff protocol is static>
        }
      }
    },
    type: <the device type (flukso2, vzlogger, libklio, raspberrypi)
          (mandadory if firmware is informed)>,
  }
|
^ Response Body | The field 'support' is included only if the user requests device remote support on the web application. The block 'config' is only included if the configuration on the server differs from the configuration of the device.
  {
    upgrade:   <integer     - flag to indicate whether or not there is a pending firmware 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 authorized_keys on the device>,
      hostkey:    <string(700) - the host RSA key to be added to the file
                                 known_hosts on the device>
    },
    config:     (optional) {
      network:    (optional) {
        lan:        (optional) {
          enabled:  <integer>,
          protocol: <string(6)  - either static or dhcp>,
          ip:       <string(15) - iff protocol is static>,
          netmask:  <string(15) - iff protocol is static>,
          gateway:  <string(15) - iff protocol is static>
        },
        wifi:       (optional) {
          essid:    <string(60)>,
          enc:      <string(5)  - one of open,wpa,wpa2>,
          psk:      <string(60) - iff enc is wpa or wpa2>,
          protocol: <string(6)  - either static or dhcp>,
          ip:       <string(15) - iff protocol is static>,
          netmask:  <string(15) - iff protocol is static>,
          gateway:  <string(15) - iff protocol is static>
        }
      },
      sensors: [
        <string(64) - id>,
        ...
        <string(64) - id>
      ]
    }
  } 
|
\\ 

=== Device Query ===

Queries the device properties and its list of sensors. Either header X-Token or X-Digest should be informed for authentication.

^ Method        | GET                                                     |
^ URL           | %%https://api.mysmartgrid.de:8443%%/device/<device id>  |
^ Extra Headers |
    X-Token:     <string(32) - access token, configured by the user on the web site>
    X-Digest:    <string(32) - the message digest, using the device key>
|
^ Response Body | 
  {
    description:  <string(60) - the device description>,
    type:         <the device type (flukso2, vzlogger, libklio, raspberrypi)>,
    sensors: [
      { meter:    <string(32) - sensor id>,
        function: <string(16) - sensor name> },
      ...
      { meter:    <string(32) - sensor id>,
        function: <string(16) - sensor name> }
    ]
  }
|
\\ 

=== 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> |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ 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.

^ Method       | POST                                                    |
^ URL          | %%https://api.mysmartgrid.de:8443%%/event/<event id>    |
^ Extra Headers |
    X-Digest:  <string(32) - the message digest, using the device key>
|
^ Request Body |
  {
    device:    <string(32) - device id>
  }
|
^ Response Body | 
  {
    timestamp: <unixtime   - server current time>
  }
|

The list of possible events is shown bellow.

^ Code            ^  Name                   ^ Description                                 ^
| 104             | Brownout                | The device has detected a brownout event. |
| 105             | Firmware Upgraded       | The device has successfully performed a firmware upgrade. |
| 106             | Failed Firmware Upgrade | The device has failed to performed a firmware upgrade. |
 \\ 

=== 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>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Request Body |
  {
    config : {
       device:      <string(32) - device id>,
       externalid:  <string(64) - sensor id given by the client>,
       function:    <string(16) - sensor name>,
       unit:        <string(16) - sensor unit>,
       class:       <string(10) - sensor class (either analog or pulse)>,
       voltage:     <integer    - sensor voltage in Volts (only if class is analog)>,
       current:     <integer    - sensor current in Amperes (only if class is analog)>,
       constant:    <integer    - sensor constant in pulses/kWh (only if class is pulse)>,
       description: <string(64) - a user defined description of the sensor>
    }
  }
|
^ Response Body | 
  {
    timestamp: <unixtime - server current time>
  }
|
\\ 

=== Sensor Configuration Query ===

Queries the current configuration of a sensor. This message must be preceded by a device registration message.

^ Method       | GET                                                     |
^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Response Body |
  {
    config : {
       device:      <string(32) - device id>,
       externalid:  <string(64) - sensor id given by the client>,
       function:    <string(16) - sensor name>,
       unit:        <string(16) - sensor unit>,
       class:       <string(10) - sensor class (one of analog, pulse)>,
       voltage:     <integer    - sensor voltage (iff class is analog and type is electricity)>,
       current:     <integer    - sensor current (iff class is analog and type is electricity)>,
       constant:    <integer    - sensor constant (iff class is pulse)>,
       type:        <string(16) - sensor type (one of electricity, water, gas)>,
       description: <string(64) - a user defined description of the sensor>
    }
  }
|
\\ 

=== Sensor Measurements Registration ===

Reports sensor measurements to the server. The measurement values are saved in RRD files in Wh (Watt-hour).

^ Method       | POST                                                    |
^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Request Body |
  {
    measurements: [
      [ <unixtime - timestamp of the first measurement>,
        <integer  - consumed energy in Wh (ever increasing value),
                    measured at the first timestamp> ],
      ...
      [ <unixtime - timestamp of the measurement n>,
        <integer  - consumed energy in Wh (ever increasing value),
                    measured at the timestamp n >]
    ]
  }
|
^ Response Body | 
  {
    response: <string(2) - "ok">
  }
|
^ Error Response Body |
  {
    response: <string(200) - the error message>
  }
|
\\ 

=== Sensor Removal ===

Removes a sensor and all its related data from the server.

^ Method       | DELETE                                                  |
^ URL          | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>  |
^ Extra Headers |
    X-Digest: <string(32) - the message digest, using the device key>
|
^ Response Body | 
  {
    response: <string(2) - "ok">
  }
|
^ Error Response Body |
  {
    response: <string(200) - the error message>
  }
|
\\ 

=== Sensor Measurements Query ===

Queries measurements performed by a sensor. Either header X-Digest or header X-Token must be informed for authentication.

^ Method        | GET                                                                  |
^ URL           | %%https://api.mysmartgrid.de:8443%%/sensor/<sensor id>?<attributes>  |
^ Extra Headers |
    X-Token:  <string(32) - access token, configured by the user on the web site>
    X-Digest: <string(32) - the message digest, using the device key>
|
^ 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>
  interval   = <an alternative way of representing a period of time that ends right now
               (15min, hour, 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, using curl. The sensor id and token are from a demo device 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: d3a16238d92456bb0f6727743275dce0" \
  -H "Accept: application/json" \
  "https://api.mysmartgrid.de:8443/sensor/5715a57b0c8ec958727ab3bb206d8b6e?\
  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: d3a16238d92456bb0f6727743275dce0" \
  -H "Accept: application/json" \
  "https://api.mysmartgrid.de:8443/sensor/5715a57b0c8ec958727ab3bb206d8b6e?\
  start=1317765600&end=1317826800&resolution=15min&unit=eurperyear"

Notes:

The argument "-k" allows curl to overlook server certificate validation and work in an insecure mode. If you want to be sure you are connecting the right server, you need the mySmartGrid CA certificate installed in your system.

Please take the following steps to install the certificate in a Debian/Ubuntu distribution.
  - Download the [[https://www.mysmartgrid.de/files/msg-ca/msg_CA.crt|mySmartGrid CA certificate file]].
  - Move the file to /usr/local/share/ca-certificates. You may change the file name, but the extension must remain crt.
  - Run the command "sudo update-ca-certificates". You should see a message like: "1 added, 0 removed; done".

After that, if you omit the argument "-k", the server certificate will be validated, and the command output should contain the following section.

    Server certificate:
        subject: C=DE; O=Fraunhofer-Gesellschaft; OU=ITWM; CN=api.mysmartgrid.de
        start date: 2013-05-13 09:13:45 GMT
        expire date: 2023-05-11 09:13:45 GMT
        common name: api.mysmartgrid.de (matched)
        issuer: C=DE; O=Fraunhofer-Gesellschaft; OU=ITWM; CN=mySmartGrid CA
        SSL certificate verify ok.

The message "SSL certificate verify ok" means that you are connecting to the right server. Otherwise, you would see messages like "SSL certificate problem", "host name does not match", or "expired certificate".

If you are unable or unwilling to install the CA certificate in your system, inform the location of the CA file by adding "--cacert /path/to/msg_CA.crt" to the command.
MySmartGrid Developer Wiki

User Tools

Site Tools

Page Tools
