GWAPI: Devices

From Yombo
Jump to: navigation, search

Gateway API Home

Various interactions with devices.

Get all devices

Get a listing of all commands.

Request URLs

  • GET http(s)://gateway.example.com/api/v1/device

Parameters

None

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-auth: kip8EaWvR7Y6eLN2c0t0L2z3oELs3hR0jeEDrAr6Ozm7EB" \
http://localhost:8080/api/v1/device
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'http://localhost:8080/api/v1/device'
headers = {
    'x-api-key': 'kip8EaWvR7Y6eLN2c0t0L2z3oELs3hR0jeEDrAr6Ozm7EB',
    }

response = requests.get(url, headers=headers)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
  1 {
  2     "code": 200,
  3     "message": "OK",
  4     "comments": {},
  5     "payload": [
  6         {
  7            "gateway_id": "73klRv01ebmxEm8M",
  8             "area": "Front Door",
  9             "location": "House",
 10             "area_label": "Front Door light",
 11             "full_label": "House Front Door light",
 12             "device_id": "9ReLWm2B3a01eOOa",
 13             "device_type_id": "9oDQ0XVy",
 14             "device_type_label": "insteon_lamp",
 15             "machine_label": "house_front_door_light",
 16             "label": "light",
 17             "description": "Front door light",
 18             "statistic_label": "None",
 19             "statistic_type": "none",
 20             "statistic_bucket_size": "None",
 21             "statistic_lifetime": "365",
 22             "pin_code": "********",
 23             "pin_required": 0,
 24             "pin_timeout": null,
 25             "voice_cmd": "None",
 26             "voice_cmd_order": "None",
 27             "created_at": 1519350360,
 28             "updated_at": 1519350952,
 29             "device_commands": [
 30                 "Qo36uPOkQ8oQyTc5bN",
 31                 "ONU7wBUPoivrj5xIph",
 32                 "5fIVFWQpXy7QccJY6h"
 33             ],
 34             "status_current": {
 35                 "status_id": "eq*B*l>*-}{X=4Y",
 36                 "device_id": "9ReLWm2B3a01eOOa",
 37                 "command_id": "aWvzB0ENZ23JO",
 38                 "gateway_id": "73klRv01ebmxEm8M",
 39                 "set_at": 1528765179.1184535,
 40                 "energy_usage": 0,
 41                 "energy_type": "none",
 42                 "human_status": "100%",
 43                 "human_message": "Front Door light is now 100%",
 44                 "machine_status": 1,
 45                 "machine_status_extra": {
 46                     "brightness": 255
 47                 },
 48                 "requested_by": {
 49                     "user_id": "Unknown",
 50                     "component": "Unknown"
 51                 },
 52                 "reported_by": "yombo.gateway.modules.InsteonPLM",
 53                 "request_id": null,
 54                 "uploaded": 0,
 55                 "uploadable": 1
 56             },
 57             "status_previous": {
 58                 "status_id": "OlvHtiVc{Nb^}EB",
 59                 "device_id": "9ReLWm2B3a01eOOa",
 60                 "command_id": "6qBJKkN6kw3nW",
 61                 "gateway_id": "73klRv01ebmxEm8M",
 62                 "set_at": 1528765169.687257,
 63                 "energy_usage": 0,
 64                 "energy_type": "none",
 65                 "human_status": "0%",
 66                 "human_message": "Front Door light is now 0%",
 67                 "machine_status": 0,
 68                 "machine_status_extra": {
 69                     "brightness": 255
 70                 },
 71                 "requested_by": {
 72                     "user_id": "Unknown",
 73                     "component": "Unknown"
 74                 },
 75                 "reported_by": "yombo.gateway.modules.InsteonPLM",
 76                 "request_id": null,
 77                 "uploaded": 0,
 78                 "uploadable": 1
 79             },
 80             "device_serial": "19.35.50",
 81             "device_mfg": "Insteon",
 82             "device_model": "Yombo",
 83             "device_platform": "light",
 84             "device_sub_platform": "insteon",
 85             "device_features": {
 86                 "power_control": true,
 87                 "all_on": false,
 88                 "all_off": false,
 89                 "pingable": true,
 90                 "pollable": true,
 91                 "sends_updates": true,
 92                 "allow_in_scenes": true,
 93                 "controllable": true,
 94                 "allow_direct_control": true,
 95                 "brightness": true,
 96                 "percent": true,
 97                 "color_temp": false,
 98                 "effect": false,
 99                 "rgb_color": false,
100                 "xy_color": false,
101                 "white_value": false,
102                 "transition": false,
103                 "number_of_steps": 255
104             },
105             "device_variables": {
106                 "address": {
107                     "id": "PANMDg4rqoY9Ox",
108                     "field_machine_label": "address",
109                     "field_label": "Device Address",
110                     "field_description": "Insteon device address. In the form of \"xx.xx.xx\". Example: 14.FB.3A",
111                     "field_help_text": "",
112                     "field_weight": 0,
113                     "value_min": null,
114                     "value_max": null,
115                     "value_casing": "nosuggestion",
116                     "value_required": 1,
117                     "encryption": "nosuggestion",
118                     "input_type_id": "KoQpXQbV",
119                     "default_value": "",
120                     "multiple": 0,
121                     "data_weight": 0,
122                     "created_at": 1496351271,
123                     "updated_at": 1496351401,
124                     "data": {
125                         "bRdXGNjDGpN3x7a5A4": {
126                             "id": "bRdXGNjDGpN3x7a5A4",
127                             "weight": 0,
128                             "created_at": 1519350361,
129                             "updated_at": 1519350361,
130                             "relation_id": "9ReLWm2B3a01eOOa",
131                             "relation_type": "device",
132                             "value": "19.35.50",
133                             "value_display": "19.35.50",
134                             "value_orig": "19.35.50"
135                         }
136                     },
137                     "values": [
138                         "19.35.50"
139                     ],
140                     "values_display": [
141                         "19.35.50"
142                     ],
143                     "values_orig": [
144                         "19.35.50"
145                     ]
146                 }
147             },
148             "enabled_status": 1
149         }
150     ]
151 }

Control Devices

It's very easy to control a device. When you send a control command, it may take a while to get the results, so a 'device command' id is returned. The status of the device command can be retrieved: To be documented

Request URLs

  • GET, POST http(s)://gateway.example.com/api/v1/device/{device}/command/{command}

Parameters

For GET requests, the parameters belong in the query string, while for POST, they belong in the POST data and formatted as JSON.

Name Type Description
Required
device string Device id, device machine label, or device label to control.
command string The command id, command machine label, or command label to send to the device.
Optional
pin_code string Access code for the device. Note: This is required if `pin_required` is set to 1.
delay integer How many seconds to delay sending the command.
max_delay integer If a command isn't sent right away, how long can the command be delayed. For example, if the device isn't responding or the peer gateway is offline.
not_before integer Like delay, but seconds since epoch that the command should run. Delay is a shortcut to: time() + delay
not_after integer Like max_delay, but seconds since epoch that the command should no longer be valid. This happens if the device is offline, or the peer gateway is offline. Max_delay is a shortcut to: time() + not_after
inputs dictionary A list of key/value inputs. This must be JSON formatted and should be send in as a POST request, not a GET request.
idempotence string A random string 10 to 150 characters in length. This helps to ensure the request is only processed once if it's submitted multiple times. idempotence keys kept for 30 minutes, after that, the same key can be used again and the request will be processed. See more: idempotence @ wikipedia

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-auth: kip8EaWvR7Y6eLN2c0t0L2z3oELs3hR0jeEDrAr6Ozm7EB" \
http://localhost:8080/api/v1/device/house_front_door_light/command/on
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'http://localhost:8080/api/v1/device/house_front_door_light/command/on'
headers = {
    'x-api-key': 'kip8EaWvR7Y6eLN2c0t0L2z3oELs3hR0jeEDrAr6Ozm7EB',
    }

response = requests.get(url, headers=headers)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
  1 {
  2     "code": 200,
  3     "message": "OK",
  4     "comments": {},
  5     "payload": {
  6         "device_command_id": "Qo36uPOkQ8oQyTc5bN",
  7         "device_command": {
  8             "request_id": "Qo36uPOkQ8oQyTc5bN",
  9             "persistent_request_id": null,
 10             "source_gateway_id": "73klRv01ebmxEm8M",
 11             "device_id": "9ReLWm2B3a01eOOa",
 12             "command_id": "aWvzB0ENZ23JO",
 13             "inputs": {},
 14             "created_at": 1528765178.0713155,
 15             "broadcast_at": 1528765178.0714827,
 16             "accepted_at": null,
 17             "sent_at": 1528765178.0769606,
 18             "received_at": 1528765178.0769646,
 19             "pending_at": null,
 20             "finished_at": 1528765178.0864108,
 21             "not_before_at": null,
 22             "not_after_at": null,
 23             "started": true,
 24             "command_status_received": false,
 25             "history": [
 26                 {
 27                     "time": 1528765178.0713155,
 28                     "status": "new",
 29                     "msg": "Created.",
 30                     "gid": "73klRv01ebmxEm8M"
 31                 },
 32                 {
 33                     "time": 1528765178.0714827,
 34                     "status": "broadcast",
 35                     "msg": "Command broadcasted to hooks and gateway coms.",
 36                     "gid": "73klRv01ebmxEm8M"
 37                 },
 38                 {
 39                     "time": 1528765178.0769606,
 40                     "status": "sent",
 41                     "msg": "Command sent to device or processing sub-system.",
 42                     "gid": "73klRv01ebmxEm8M"
 43                 },
 44                 {
 45                     "time": 1528765178.0769646,
 46                     "status": "received",
 47                     "msg": "Command received by the device or processing sub-system.",
 48                     "gid": "73klRv01ebmxEm8M"
 49                 },
 50                 {
 51                     "time": 1528765178.0864108,
 52                     "status": "done",
 53                     "msg": "Command delivered to PLM interface.",
 54                     "gid": "73klRv01ebmxEm8M"
 55                 }
 56             ],
 57             "status": "done",
 58             "requested_by": {
 59                 "user_id": "apiauth:LUNwRLryj47drGkkyqOLMAceV5zV...",
 60                 "component": "yombo.gateway.lib.webinterface.routes.api_v1.devices.device_command",
 61                 "gateway": "73klRv01ebmxEm8M"
 62             }
 63         },
 64         "status_current": {
 65             "status_id": "OlvHtiVc{Nb^}EB",
 66             "device_id": "9ReLWm2B3a01eOOa",
 67             "command_id": "6qBJKkN6kw3nW",
 68             "gateway_id": "73klRv01ebmxEm8M",
 69             "set_at": 1528765169.687257,
 70             "energy_usage": 0,
 71             "energy_type": "none",
 72             "human_status": "0%",
 73             "human_message": "Front Door light is now 0%",
 74             "machine_status": 0,
 75             "machine_status_extra": {
 76                 "brightness": 0
 77             },
 78             "requested_by": {
 79                 "user_id": "Unknown",
 80                 "component": "Unknown"
 81             },
 82             "reported_by": "yombo.gateway.modules.InsteonPLM",
 83             "request_id": null,
 84             "uploaded": 0,
 85             "uploadable": 1
 86         },
 87         "status_previous": {
 88             "status_id": "bSQ99Npc>9qWg4V",
 89             "device_id": "9ReLWm2B3a01eOOa",
 90             "command_id": "aWvzB0ENZ23JO",
 91             "gateway_id": "73klRv01ebmxEm8M",
 92             "set_at": 1528765167.3226473,
 93             "energy_usage": 0,
 94             "energy_type": "none",
 95             "human_status": "100%",
 96             "human_message": "Front Door light is now 100%",
 97             "machine_status": 1,
 98             "machine_status_extra": {
 99                 "brightness": 0
100             },
101             "requested_by": {
102                 "user_id": "Unknown",
103                 "component": "Unknown"
104             },
105             "reported_by": "yombo.gateway.modules.InsteonPLM",
106             "request_id": null,
107             "uploaded": 0,
108             "uploadable": 1
109         }
110     }
111 }
This page was last edited on 13 June 2018.