GWAPI: Devices
From Yombo
- Authentication
- Provided resources
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;">
{
"code": 200,
"message": "OK",
"comments": {},
"payload": [
{
"gateway_id": "73klRv01ebmxEm8M",
"area": "Front Door",
"location": "House",
"area_label": "Front Door light",
"full_label": "House Front Door light",
"device_id": "9ReLWm2B3a01eOOa",
"device_type_id": "9oDQ0XVy",
"device_type_label": "insteon_lamp",
"machine_label": "house_front_door_light",
"label": "light",
"description": "Front door light",
"statistic_label": "None",
"statistic_type": "none",
"statistic_bucket_size": "None",
"statistic_lifetime": "365",
"pin_code": "********",
"pin_required": 0,
"pin_timeout": null,
"voice_cmd": "None",
"voice_cmd_order": "None",
"created_at": 1519350360,
"updated_at": 1519350952,
"device_commands": [
"Qo36uPOkQ8oQyTc5bN",
"ONU7wBUPoivrj5xIph",
"5fIVFWQpXy7QccJY6h"
],
"status_current": {
"status_id": "eq*B*l>*-}{X=4Y",
"device_id": "9ReLWm2B3a01eOOa",
"command_id": "aWvzB0ENZ23JO",
"gateway_id": "73klRv01ebmxEm8M",
"set_at": 1528765179.1184535,
"energy_usage": 0,
"energy_type": "none",
"human_status": "100%",
"human_message": "Front Door light is now 100%",
"machine_status": 1,
"machine_status_extra": {
"brightness": 255
},
"requested_by": {
"user_id": "Unknown",
"component": "Unknown"
},
"reported_by": "yombo.gateway.modules.InsteonPLM",
"request_id": null,
"uploaded": 0,
"uploadable": 1
},
"status_previous": {
"status_id": "OlvHtiVc{Nb^}EB",
"device_id": "9ReLWm2B3a01eOOa",
"command_id": "6qBJKkN6kw3nW",
"gateway_id": "73klRv01ebmxEm8M",
"set_at": 1528765169.687257,
"energy_usage": 0,
"energy_type": "none",
"human_status": "0%",
"human_message": "Front Door light is now 0%",
"machine_status": 0,
"machine_status_extra": {
"brightness": 255
},
"requested_by": {
"user_id": "Unknown",
"component": "Unknown"
},
"reported_by": "yombo.gateway.modules.InsteonPLM",
"request_id": null,
"uploaded": 0,
"uploadable": 1
},
"device_serial": "19.35.50",
"device_mfg": "Insteon",
"device_model": "Yombo",
"device_platform": "light",
"device_sub_platform": "insteon",
"device_features": {
"power_control": true,
"all_on": false,
"all_off": false,
"pingable": true,
"pollable": true,
"sends_updates": true,
"allow_in_scenes": true,
"controllable": true,
"allow_direct_control": true,
"brightness": true,
"percent": true,
"color_temp": false,
"effect": false,
"rgb_color": false,
"xy_color": false,
"white_value": false,
"transition": false,
"number_of_steps": 255
},
"device_variables": {
"address": {
"id": "PANMDg4rqoY9Ox",
"field_machine_label": "address",
"field_label": "Device Address",
"field_description": "Insteon device address. In the form of \"xx.xx.xx\". Example: 14.FB.3A",
"field_help_text": "",
"field_weight": 0,
"value_min": null,
"value_max": null,
"value_casing": "nosuggestion",
"value_required": 1,
"encryption": "nosuggestion",
"input_type_id": "KoQpXQbV",
"default_value": "",
"multiple": 0,
"data_weight": 0,
"created_at": 1496351271,
"updated_at": 1496351401,
"data": {
"bRdXGNjDGpN3x7a5A4": {
"id": "bRdXGNjDGpN3x7a5A4",
"weight": 0,
"created_at": 1519350361,
"updated_at": 1519350361,
"relation_id": "9ReLWm2B3a01eOOa",
"relation_type": "device",
"value": "19.35.50",
"value_display": "19.35.50",
"value_orig": "19.35.50"
}
},
"values": [
"19.35.50"
],
"values_display": [
"19.35.50"
],
"values_orig": [
"19.35.50"
]
}
},
"enabled_status": 1
}
]
}
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;">
{
"code": 200,
"message": "OK",
"comments": {},
"payload": {
"device_command_id": "Qo36uPOkQ8oQyTc5bN",
"device_command": {
"request_id": "Qo36uPOkQ8oQyTc5bN",
"persistent_request_id": null,
"source_gateway_id": "73klRv01ebmxEm8M",
"device_id": "9ReLWm2B3a01eOOa",
"command_id": "aWvzB0ENZ23JO",
"inputs": {},
"created_at": 1528765178.0713155,
"broadcast_at": 1528765178.0714827,
"accepted_at": null,
"sent_at": 1528765178.0769606,
"received_at": 1528765178.0769646,
"pending_at": null,
"finished_at": 1528765178.0864108,
"not_before_at": null,
"not_after_at": null,
"started": true,
"command_status_received": false,
"history": [
{
"time": 1528765178.0713155,
"status": "new",
"msg": "Created.",
"gid": "73klRv01ebmxEm8M"
},
{
"time": 1528765178.0714827,
"status": "broadcast",
"msg": "Command broadcasted to hooks and gateway coms.",
"gid": "73klRv01ebmxEm8M"
},
{
"time": 1528765178.0769606,
"status": "sent",
"msg": "Command sent to device or processing sub-system.",
"gid": "73klRv01ebmxEm8M"
},
{
"time": 1528765178.0769646,
"status": "received",
"msg": "Command received by the device or processing sub-system.",
"gid": "73klRv01ebmxEm8M"
},
{
"time": 1528765178.0864108,
"status": "done",
"msg": "Command delivered to PLM interface.",
"gid": "73klRv01ebmxEm8M"
}
],
"status": "done",
"requested_by": {
"user_id": "apiauth:LUNwRLryj47drGkkyqOLMAceV5zV...",
"component": "yombo.gateway.lib.webinterface.routes.api_v1.devices.device_command",
"gateway": "73klRv01ebmxEm8M"
}
},
"status_current": {
"status_id": "OlvHtiVc{Nb^}EB",
"device_id": "9ReLWm2B3a01eOOa",
"command_id": "6qBJKkN6kw3nW",
"gateway_id": "73klRv01ebmxEm8M",
"set_at": 1528765169.687257,
"energy_usage": 0,
"energy_type": "none",
"human_status": "0%",
"human_message": "Front Door light is now 0%",
"machine_status": 0,
"machine_status_extra": {
"brightness": 0
},
"requested_by": {
"user_id": "Unknown",
"component": "Unknown"
},
"reported_by": "yombo.gateway.modules.InsteonPLM",
"request_id": null,
"uploaded": 0,
"uploadable": 1
},
"status_previous": {
"status_id": "bSQ99Npc>9qWg4V",
"device_id": "9ReLWm2B3a01eOOa",
"command_id": "aWvzB0ENZ23JO",
"gateway_id": "73klRv01ebmxEm8M",
"set_at": 1528765167.3226473,
"energy_usage": 0,
"energy_type": "none",
"human_status": "100%",
"human_message": "Front Door light is now 100%",
"machine_status": 1,
"machine_status_extra": {
"brightness": 0
},
"requested_by": {
"user_id": "Unknown",
"component": "Unknown"
},
"reported_by": "yombo.gateway.modules.InsteonPLM",
"request_id": null,
"uploaded": 0,
"uploadable": 1
}
}
}