Jetlun REST Web Service Interface

Callbacks

Callbacks service allows you to register a URL that JedX will POST whenever a device status changes in your system. For example, when a occupancy sensor status changed to occupied, JedX will create an callback object. This object contains all the relevant information, including the data associated with that status. JedX then sends an HTTP POST request with the callback object to any URLs in your account's callback settings.

The following Jetlun products support callbacks:

  • Occupancy Sensor
  • Temperature Sensor
  • IR Sensor
  • Relay Module
  • Light Dimmer
  • Appliance Module
  • Appliance Module Plus
  • Thermostat
  • Lux Sensor
  • Reed Switch
  • Analog Sensor

Configuring your callback settings

First, you need to add associated Energy Manager's MAC address and serial number in Energy Managers app section. Then you can config callback URL in the app settings section. You can enter any URL you'd like to have receive the callbacks.

Receiving a callback

Callback data is sent as JSON in the request's body. The full callback details are included and can be used directly. If security is a concern, we advise you to guard against replay-attacks by recording which callback you receive by ID in callback json body.

Example for callback json body:

for Occupancy Sensor:
{
    "device_type": "Occupancy",
    "operation_status": {
        "occupancy": "occupied"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for TH Sensor:
{
    "device_type": "Temperature Humidity Sensor",
    "operation_status": {
        "temp": "22.5",
        "humidity": "55.6"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Appliance Module:
{
    "device_type": "Appliance Module",
    "operation_status": {
        "io": "On"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Appliance Module Plus:
{
    "device_type": "Appliance Module Plus",
    "operation_status": {
        "relay1": "On",
        "relay2": "Off"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Thermostat:
{
    "device_type": "Thermostat",
    "operation_status": {
        "mode": "Cool",
        "cooling point": "21.2",
        "heating point": "18.9",
        "fan": "On"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Infrared Sensor:
{
    "device_type": "Infrared Sensor",
    "operation_status": {
        "code": "2",
        "io": "On"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Light Dimmer:
{
    "device_type": "Light Dimmer",
    "operation_status": {
        "dimming": "22"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Zigbee Lux Sensor:
{
    "device_type": "Zigbee Lux",
    "operation_status": {
        "lux": "82.5"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

for Zigbee Reed Switch:
{
    "device_type": "Zigbee Reed Switch",
    "operation_status": {
        "temp"=>"30.30", 
        "relay2"=>"On", 
        "relay1"=>"On", 
        "relay_operation"=>"normal"
    },
    "id": "5268ee3ddac1777XX00000XX",
    "sn": "c8d2c1000000XXXX0000000000000000",
    "mac": "C8D2C100XXXX",
    "network_status": "online",
    "timestamp": "20131024175338"
}

operation_status is the device's operation status, sn is the device's EUI, mac is the associate Energy Manager's mac address, timestamp is device status change time, use the associate Energy Manager's local timezone.

Responding to a callback

To acknowledge that you received the callback without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3xx codes, will indicate to myJetlun that you did not receive the callback. When a callback is not received for whatever reason, myJetlun will continue trying to send the callback once an minute for up to 3 times.

Example for receiving myJetlun API callback

Configuring your server to receive a myJetlun API callback is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Rails or Sinatra, you would add a new route with the desired URL. Remember, with callbacks, your server is the server receiving the request.

require 'json'

# in, e.g. Sinatra

post '/my/callback/url' do
  # Retrieve the request's body and parse it as JSON
  event_json = JSON.parse(request.body.read)

  # Do something with event_json
end