API: Devices

From Yombo
Jump to: navigation, search

Yombo Gateway devices can be added, updated, disabled, and deleted. Devices are things that can be controlled, such as lights, fans, switches, thermostats, etc. Commands are used to control the devices.

To manage device variables, see variables.

GET - All devices

Retrieve all devices available to the current user.

Filters

List of available filters:

  • gateway_id
  • device_type_id
  • voice_cmd
  • machine_label
  • voice_cmd_order
  • voice_cmd_src
  • pin_required
  • pin_timeout
  • statistic_label
  • energy_type
  • energy_tracker_source
  • energy_tracker_device
  • machine_label
  • label
  • description
  • status
  • created_at
  • updated_at

Request URLs

  • GET https://api.yombo.net/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-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
https://api.yombo.net/api/v1/device?_pagelimit=2
  <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 = 'https://api.yombo.net/api/v1/device?_pagelimit=2'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }
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     "response": {
  3         "uri": "/api/v1/device?_pagelimit=2",
  4         "uri_description": "List of devices.",
  5         "doc_uri": "https://yombo.net/API:Devices",
  6         "device": [
  7             {
  8                 "id": "j2z8GQl4qwMgbJxGQl4qwM6",
  9                 "gateway_id": "km8M7lRv0E31ebmx",
 10                 "device_type_id": "d3Doyxr1",
 11                 "machine_label": "nest_kelvin",
 12                 "label": "Kelvin",
 13                 "description": "Kelvin",
 14                 "location_id": "rD1m1Y0Qw3RbaP",
 15                 "area_id": "z1g1r3RbaPDY0Q",
 16                 "notes": null,
 17                 "attributes": null,
 18                 "voice_cmd": null,
 19                 "voice_cmd_order": null,
 20                 "voice_cmd_src": null,
 21                 "pin_code": null,
 22                 "pin_required": 0,
 23                 "pin_timeout": null,
 24                 "statistic_label": "myhouse.hallway.kelvin",
 25                 "statistic_lifetime": 0,
 26                 "statistic_type": "none",
 27                 "statistic_bucket_size": null,
 28                 "data": null,
 29                 "status_set_at": null,
 30                 "energy_usage": null,
 31                 "human_status": null,
 32                 "human_message": null,
 33                 "machine_status": null,
 34                 "machine_status_extra": null,
 35                 "energy_type": "electric",
 36                 "energy_tracker_source": null,
 37                 "energy_tracker_device": null,
 38                 "energy_map": {
 39                     "0.0": 0,
 40                     "1.0": 0
 41                 },
 42                 "status": 1,
 43                 "created_at": 1494534073,
 44                 "updated_at": 1517894682,
 45                 "variable_data": [
 46                     {
 47                         "gateway_id": "",
 48                         "id": "Q9K3mJqQP2BZ93kn1A",
 49                         "field_id": "NMwJEgPdg56Aab",
 50                         "relation_id": "j2z8gbJxGQl4qwM6",
 51                         "relation_type": "device",
 52                         "data": "nest@schwenk.name",
 53                         "data_weight": 0,
 54                         "created_at": 1494534074,
 55                         "updated_at": 1494534074
 56                     },
 57                     {
 58                         "gateway_id": "",
 59                         "id": "jlWBry5RnadEObLmzg",
 60                         "field_id": "RrmJ01k4o4wEqM",
 61                         "relation_id": "j2z8gbJxGQl4qwM6",
 62                         "relation_type": "device",
 63                         "data": "02LA0AB120GPA481",
 64                         "data_weight": 0,
 65                         "created_at": 1494534074,
 66                         "updated_at": 1494534074
 67                     },
 68                     {
 69                         "gateway_id": "",
 70                         "id": "1m6BYXlOr3a8ZA9jNL",
 71                         "field_id": "A0xZXLb9oQKWrj",
 72                         "relation_id": "j2z8gbJxGQl4qwM6",
 73                         "relation_type": "device",
 74                         "data": "-----BEGIN PGP MESSAGE-----\n\nhQIMAzlvDmhUlvf8AQ//fsP4JrpvAgf9T6MCgsMqIYhqNZN06QU2jvbXmmEV4oHi\nV+kl7/oHnXmo4eZANMbk8TqI52TbPLAGGddJo8F5hosk5rnFV9EszRuA58GBZWF6\no5fkylDPN3h1I7g8x5e9qTgnkPocBR6+O3wx+qFyydoIP27pbpqxqKYftoxTayFd\naCs4tZx6z0incOtXmemm8JxuyT++URF2P3wHR+XF0KPGlGHaaIQohPdq6ER9OBK8\nXQh81C+ZcfG89zbvQn0wNpBM+cH4as2SoYB+NBA06kF3aMz6E7KPIXWjtaXx9GyH\ne2CLmOXX4n0V2841cfB3Q+cFX7iN4HHR3Wu2v4tXvcJ8wn2ZXPV/TiuArUN6jsP0\nfut+Ir9s8vdKCbUCuVNV6bm9kEXHPxGiefw8NEFOcYhbkBjY7BF1hszhGRve4aYCSGJnS\nRwFzu/nxZNlrOSv2JQlEeINqVd7PTABqYBgA5qxG6KUt3fCqEUeHD0LSA0l2LWiE\n/mqqFjvSEny2UVNoJM02Q6PCEsiGaEw/\n=gzj7\n-----END PGP MESSAGE-----\n",
 75                         "data_weight": 0,
 76                         "created_at": 1494534074,
 77                         "updated_at": 1517894682
 78                     }
 79                 ]
 80             },
 81             {
 82                 "id": "YnxO5X4gLqwOgWNE",
 83                 "gateway_id": "km8M7lRv0E31ebmx",
 84                 "device_type_id": "9oDQ0XVy",
 85                 "machine_label": "front_porch_string_light",
 86                 "label": "String Light",
 87                 "description": "Mini lights on the front patio.",
 88                 "location_id": "r3RbaPD1m1Y0Qw",
 89                 "area_id": "qYJXzmMjg60ZNW",
 90                 "notes": null,
 91                 "attributes": null,
 92                 "voice_cmd": null,
 93                 "voice_cmd_order": null,
 94                 "voice_cmd_src": null,
 95                 "pin_code": null,
 96                 "pin_required": 0,
 97                 "pin_timeout": null,
 98                 "statistic_label": "myhouse.outside.front.string_lights",
 99                 "statistic_lifetime": 365,
100                 "statistic_type": null,
101                 "statistic_bucket_size": null,
102                 "data": null,
103                 "status_set_at": "2018-02-12 14:59:27",
104                 "energy_usage": 0,
105                 "human_status": "0.0%",
106                 "human_message": "Front Porch String Light is now 0.0%",
107                 "machine_status": "0",
108                 "machine_status_extra": "{'brightness': 0.0}",
109                 "energy_type": "electric",
110                 "energy_tracker_source": null,
111                 "energy_tracker_device": null,
112                 "energy_map": {
113                     "0.0": 0,
114                     "1.0": 0
115                 },
116                 "status": 1,
117                 "created_at": 1496367526,
118                 "updated_at": 1498782766,
119                 "variable_data": [
120                     {
121                         "gateway_id": "",
122                         "id": "MBq9KeOv8LmRrEQ3YN",
123                         "field_id": "PANMDg4rqoY9Ox",
124                         "relation_id": "YngLqwOgWxO5X4NE",
125                         "relation_type": "device",
126                         "data": "11.11.11",
127                         "data_weight": 0,
128                         "created_at": 1496367527,
129                         "updated_at": 1496367527
130                     }
131                 ]
132             }
133         ],
134         "locator": "device",
135         "locator_type": "objects"
136     },
137     "code": 200,
138     "warnings": [],
139     "pages": {
140         "total_items": 22,
141         "page_limit": 2,
142         "total_pages": 11,
143         "page_start": 1
144     },
145     "message": "OK",
146     "html_message": "OK"
147 }

GET - Specific device

Retrieve a specific device id.

Request URLs

  • GET https://api.yombo.net/api/v1/device/{device_id}

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-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
https://api.yombo.net/api/v1/device/j2z8GQl4qwMgbJxGQl4qwM6
  <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 = 'https://api.yombo.net/api/v1/device/j2z8GQl4qwMgbJxGQl4qwM6
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }
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     "response": {
 3         "uri": "/api/v1/device/j2z8gbJxGQl4qwM6",
 4         "uri_description": "Detailed information for a single device.",
 5         "doc_uri": "https://yombo.net/API:Devices",
 6         "device": {
 7             "id": "YnxO5X4gLqwOgWNE",
 8             "gateway_id": "km8M7lRv0E31ebmx",
 9             "device_type_id": "9oDQ0XVy",
10             "machine_label": "front_porch_string_light",
11             "label": "String Light",
12             "description": "Mini lights on the front patio.",
13             "location_id": "r3RbaPD1m1Y0Qw",
14             "area_id": "qYJXzmMjg60ZNW",
15             "notes": null,
16             "attributes": null,
17             "voice_cmd": null,
18             "voice_cmd_order": null,
19             "voice_cmd_src": null,
20             "pin_code": null,
21             "pin_required": 0,
22             "pin_timeout": null,
23             "statistic_label": "myhouse.outside.front.string_lights",
24             "statistic_lifetime": 365,
25             "statistic_type": null,
26             "statistic_bucket_size": null,
27             "data": null,
28             "status_set_at": "2018-02-12 14:59:27",
29             "energy_usage": 0,
30             "human_status": "0.0%",
31             "human_message": "Front Porch String Light is now 0.0%",
32             "machine_status": "0",
33             "machine_status_extra": "{'brightness': 0.0}",
34             "energy_type": "electric",
35             "energy_tracker_source": null,
36             "energy_tracker_device": null,
37             "energy_map": {
38                 "0.0": 0,
39                 "1.0": 0
40             },
41             "status": 1,
42             "created_at": 1496367526,
43             "updated_at": 1498782766,
44             "variable_data": [
45                 {
46                     "gateway_id": "",
47                     "id": "MBq9KeOv8LmRrEQ3YN",
48                     "field_id": "PANMDg4rqoY9Ox",
49                     "relation_id": "YngLqwOgWxO5X4NE",
50                     "relation_type": "device",
51                     "data": "11.11.11",
52                     "data_weight": 0,
53                     "created_at": 1496367527,
54                     "updated_at": 1496367527
55                 }
56             ]
57 
58         },
59         "locator": "device",
60         "locator_type": "object"
61     },
62     "code": 200,
63     "warnings": [],
64     "message": "OK",
65     "html_message": "OK"
66 }

POST - Create new device

Creates a new device. Rules for status fields apply.

Request URLs

  • POST https://api.yombo.net/api/v1/device

Parameters

Name Type Description
Required
gateway_id string Gateway ID to assign device to.
pin_required integer 0 if not access code required, 1 if it does.
machine_label string A short computer based label to reference the device internally. Used in automation rules, scenes, and more. Used to uniquely identify the device, regardless if the label changes.
label string A short human friendly label for the device.
description string A description of what the device does.
notes string Detailed notes about the device.
location_id string What general location the device is in. See API:Locations
area_id string What area inside the location the device is in. See API:Locations
Optional
pin_code string Access code for the device. Note: This is required if `pin_required` is set to 1.
pin_timeout integer How long an application can remember the pin code for the user after the user enters it. Note: This is required if `pin_required` is set to 1.
voice_cmd string To be documented later. Leave blank for now.
voice_cmd_order string To be documented later. Leave blank for now.
voice_cmd_src string To be documented later. Leave blank for now.
status integer Default: 1 - The status of the device. Possible values: 0=disabled, 1=enabled, 2=mark for deletion

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-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
-X POST -d '{"gateway_id": "km8M7lRv0E31ebmx", "pin_required": 0,
"label": "RoboClean",  "machine_label": "roboclean",
"location_id":"r3RbaPD1m1Y0Qw", "area_id":"qYJXzmMjg60ZNW",
"description": "A robot that does my dishes.",
"notes": "Built from scratch, took me 120 years to complete and was bought out be GE and killed."}' \
https://api.yombo.net/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 = 'https://api.yombo.net/api/v1/device'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "gateway_id": "km8M7lRv0E31ebmx",
    "pin_required": 0,
    "label": "RoboClean",
    "description": "A robot that does my dishes.",
    "notes": "Built from scratch, took me 120 years to complete and was bought out be GE and killed.",
    "location_id": "r3RbaPD1m1Y0Qw",
    "area_id": "qYJXzmMjg60ZNW",
    }

response = requests.post(url, headers=headers, json=payload)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3         "uri": "/api/v1/device",
 4         "uri_description": "Create new device.",
 5         "doc_uri": "https://yombo.net/API:Devices",
 6         "device": {
 7             "id": "dlyE3lxbXMQVAZEK",
 8             "gateway_id": "km8M7lRv0E31ebmx",
 9             "device_type_id": "9oDQ0XVy",
10             "machine_label": "roboclean2",
11             "label": "RoboClean2",
12             "description": "An example garage door.",
13             "location_id": "r3RbaPD1m1Y0Qw",
14             "area_id": "qYJXzmMjg60ZNW",
15             "notes": "A robot that does my dishes.",
16             "attributes": null,
17             "voice_cmd": null,
18             "voice_cmd_order": null,
19             "voice_cmd_src": null,
20             "pin_code": null,
21             "pin_required": 0,
22             "pin_timeout": null,
23             "statistic_label": null,
24             "statistic_lifetime": null,
25             "statistic_type": null,
26             "statistic_bucket_size": null,
27             "data": null,
28             "status_set_at": null,
29             "energy_usage": null,
30             "human_status": null,
31             "human_message": null,
32             "machine_status": null,
33             "machine_status_extra": null,
34             "energy_type": null,
35             "energy_tracker_source": null,
36             "energy_tracker_device": null,
37             "energy_map": {
38                 "0.0": 0,
39                 "1.0": 0
40             },
41             "status": 0,
42             "created_at": 1518513322,
43             "updated_at": 1518513322
44         },
45         "locator": "device",
46         "locator_type": "object"
47     },
48     "code": 201,
49     "warnings": [],
50     "message": "Created",
51     "html_message": "Created"
52 }

PUT / PATCH - Update a device

Update a device. When using PUT, all required parameters must be sent. When using PATCH, only send in desired changes.

Request URLs

  • PATCH https://api.yombo.net/api/v1/device/{device_id}
  • PUT https://api.yombo.net/api/v1/device/{device_id}

Parameters

See post new device parameters.

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-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
-X PATCH -d '{"description":
"A robot that does my dishes and laundry."}' \
https://api.yombo.net/api/v1/device/WQ9akXabloyqb
  <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 = 'https://api.yombo.net/api/v1/device/WQ9akXabloyqb'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "description": "A robot that does my dishes and laundry.",
    }

response = requests.patch(url, headers=headers, json=payload)
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "response": {
 3     "response": {
 4         "uri": "/api/v1/device/dbXMQVlyE3lxAZEK",
 5         "uri_description": "Update (put) device.",
 6         "doc_uri": "https://yombo.net/API:Devices",
 7         "device": {
 8             "id": "dlyE3lxbXMQVAZEK",
 9             "gateway_id": "km8M7lRv0E31ebmx",
10             "device_type_id": "9oDQ0XVy",
11             "machine_label": "roboclean2",
12             "label": "RoboClean2",
13             "description": "An example garage door.",
14             "location_id": "r3RbaPD1m1Y0Qw",
15             "area_id": "qYJXzmMjg60ZNW",
16             "notes": "A robot that does my dishes.",
17             "attributes": null,
18             "voice_cmd": null,
19             "voice_cmd_order": null,
20             "voice_cmd_src": null,
21             "pin_code": null,
22             "pin_required": 0,
23             "pin_timeout": null,
24             "statistic_label": null,
25             "statistic_lifetime": null,
26             "statistic_type": null,
27             "statistic_bucket_size": null,
28             "data": null,
29             "status_set_at": null,
30             "energy_usage": null,
31             "human_status": null,
32             "human_message": null,
33             "machine_status": null,
34             "machine_status_extra": null,
35             "energy_type": null,
36             "energy_tracker_source": null,
37             "energy_tracker_device": null,
38             "energy_map": {
39                 "0.0": 0,
40                 "1.0": 0
41             },
42             "status": 0,
43             "created_at": 1518513322,
44             "updated_at": 1518513405
45         },
46         "locator": "device",
47         "locator_type": "object"
48     },
49     "code": 200,
50     "warnings": [],
51     "message": "OK",
52     "html_message": "OK"
53 }

DELETE - Delete a device

Delete a device. This doesn't actually delete the device right away, but simply marks it for deletion later. This is the same as setting the status to 2. To undelete the device, simply change the status back to 1.

Request URLs

  • DELETE https://api.yombo.net/api/v1/device/{deviceid}

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-key: abc123xyz789" \
-H "authorization: Bearer Waro7g0Mwl4YBJ..." \
-X DELETE https://api.yombo.net/api/v1/device/WQ9akXabloyqb
  <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 = 'https://api.yombo.net/api/v1/device/WQ9akXabloyqb'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

response = requests.put(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     "response": {
 3         "uri": "/api/v1/device/j2z8gbJxqN74qwM6",
 4         "uri_description": "Delete a device.",
 5         "doc_uri": "https://yombo.net/API:Devices",
 6         "device": "Deleted",
 7         "locator": "device",
 8         "locator_type": "string"
 9     },
10     "code": 200,
11     "warnings": [],
12     "message": "Deleted",
13     "html_message": "Deleted"
14 }
This page was last edited on 12 June 2018.