API: Device Types

From Yombo
Jump to: navigation, search

Summary

A device type defines what commands can be used for a certain device. For example, lamp modules can be turned on, off, set to a brightness level, or a few other types of commands. Device types are added to modules to determine what devices a module can manage.

GET - All device types

Retrieve all device types available to the current user.

Filters

List of available filters:

  • label
  • machine_label
  • description
  • public
  • status
  • created_at
  • updated_at

Request URLs

  • GET https://api.yombo.net/api/v1/device_type

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_type?_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_type?_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;">

{
    "response": {
        "uri": "/api/v1/device_type?_pagelimit=2",
        "uri_description": "List of device types. ",
        "doc_uri": "https://yombo.net/API:Device_types",
        "device_type": [
            {
                "id": "7BxzOXpb",
                "category_id": "dD8X67zW",
                "machine_label": "x10_house",
                "label": "X10 House Code",
                "description": "Send an X10 housecode - A single letter A-P.",
                "platform": null,
                "public": 2,
                "status": 1,
                "created_at": 1482065387,
                "updated_at": 1482065387,
                "variable_groups": [],
                "variable_fields": []
            },
            {
                "id": "pyXnExEL",
                "category_id": "dD8X67zW",
                "machine_label": "x10_lamp",
                "label": "X10 Lamp",
                "description": "An X10 lamp module or device.",
                "platform": "x10_light,light",
                "public": 2,
                "status": 1,
                "created_at": 1482065387,
                "updated_at": 1482065387,
                "variable_groups": [
                    {
                        "id": "VnogrX2jXAzEJ",
                        "relation_id": "pyXnExEL",
                        "relation_type": "device_type",
                        "group_machine_label": "x10_address",
                        "group_label": "X10 Address 1",
                        "group_description": "X10 Address information",
                        "group_weight": 1,
                        "status": 1,
                        "created_at": 1482065388,
                        "updated_at": 1482065388
                    }
                ],
                "variable_fields": [
                    {
                        "id": "90MlzLxOo5XAr2",
                        "group_id": "VnogrX2jXAzEJ",
                        "field_machine_label": "house",
                        "field_label": "House Code",
                        "field_description": "House code A-P.",
                        "field_weight": 0,
                        "value_required": 0,
                        "value_max": 0,
                        "value_min": 0,
                        "encryption": "nosuggestion",
                        "value_casing": "none",
                        "input_type_id": "gowWdDyk",
                        "default_value": "",
                        "field_help_text": "The house code of the X10 module, in the range between A and P.",
                        "multiple": false,
                        "created_at": 1482065388,
                        "updated_at": 1482065389
                    },
                    {
                        "id": "XJYae1q6oANlp0",
                        "group_id": "VnogrX2jXAzEJ",
                        "field_machine_label": "unit_code",
                        "field_label": "Unit Code",
                        "field_description": "X10 unit code, 1-16",
                        "field_weight": 1,
                        "value_required": 0,
                        "value_max": 16,
                        "value_min": 1,
                        "encryption": "nosuggestion",
                        "value_casing": "none",
                        "input_type_id": "PLDAaDBX",
                        "default_value": "",
                        "field_help_text": "",
                        "multiple": false,
                        "created_at": 1482065388,
                        "updated_at": 1499459267
                    }
                ]
            }
        ],
        "locator": "device_type",
        "locator_type": "objects"
    },
    "code": 200,
    "warnings": [],
    "pages": {
        "total_items": 40,
        "page_limit": 2,
        "total_pages": 20,
        "page_start": 1
    },
    "message": "OK",
    "html_message": "OK"
}

GET - Specific device type

Retrieve a specific device_type id.

Request URLs

  • GET https://api.yombo.net/api/v1/device_type/{device_type_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_type/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_type/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;">

{
    "response": {
        "uri": "/api/v1/device/j2z8gbJxGQl4qwM6",
        "uri_description": "Detailed information for a single device.",
        "doc_uri": "https://yombo.net/API:Device_types",
        "device": {
            "id": "YnxO5X4gLqwOgWNE",
            "gateway_id": "km8M7lRv0E31ebmx",
            "device_type_id": "9oDQ0XVy",
            "machine_label": "front_porch_string_light",
            "label": "String Light",
            "description": "Mini lights on the front patio.",
            "location_id": "r3RbaPD1m1Y0Qw",
            "area_id": "qYJXzmMjg60ZNW",
            "notes": null,
            "attributes": null,
            "voice_cmd": null,
            "voice_cmd_order": null,
            "voice_cmd_src": null,
            "pin_code": null,
            "pin_required": 0,
            "pin_timeout": null,
            "statistic_label": "myhouse.outside.front.string_lights",
            "statistic_lifetime": 365,
            "statistic_type": null,
            "statistic_bucket_size": null,
            "data": null,
            "status_set_at": "2018-02-12 14:59:27",
            "energy_usage": 0,
            "human_status": "0.0%",
            "human_message": "Front Porch String Light is now 0.0%",
            "machine_status": "0",
            "machine_status_extra": "{'brightness': 0.0}",
            "energy_type": "electric",
            "energy_tracker_source": null,
            "energy_tracker_device": null,
            "energy_map": {
                "0.0": 0,
                "1.0": 0
            },
            "status": 1,
            "created_at": 1496367526,
            "updated_at": 1498782766,
            "variable_data": [
                {
                    "gateway_id": "",
                    "id": "MBq9KeOv8LmRrEQ3YN",
                    "field_id": "PANMDg4rqoY9Ox",
                    "relation_id": "YngLqwOgWxO5X4NE",
                    "relation_type": "device",
                    "data": "11.11.11",
                    "data_weight": 0,
                    "created_at": 1496367527,
                    "updated_at": 1496367527
                }
            ]

        },
        "locator": "device",
        "locator_type": "object"
    },
    "code": 200,
    "warnings": [],
    "message": "OK",
    "html_message": "OK"
}

POST - Create new device type

Creates a new device type. Rules for public and status fields apply.

Request URLs

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

Parameters

Name Type Description
Required
machine_label string An ummutable label for developers to use. A computer version of the `label`.
label string A short human friendly label for the device type.
description string A description of what the device type does.
category_id string Categorize the device type. Must be a ‘device_type’ category.
Optional
status integer Default: 1 - A status for the device type.
public integer Default: 0 - If the device type should be public.

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": "Cleaning Robot",  "machine_label": "cleaning_robot",
"description": "A robot that cleans stuff.",
"category": "NKq9kVmM"}' \
https://api.yombo.net/api/v1/device_type

  <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_type'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "label": "Cleaning Robot",
    "machine_label": "RoboClean",
    "description": "A robot that cleans stuff.",
    "category": "NKq9kVmM",
    }

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;">

{
    "response": {
        "uri": "/api/v1/device_type",
        "uri_description": "Create new device type.",
        "doc_uri": "https://yombo.net/API:Device_types",
        "device_type": {
            "id": "QAJqr8xZ",
            "category_id": "NKq9kVmM",
            "machine_label": "cleaning_robot",
            "label": "Cleaning Robot",
            "description": "A robot that cleans stuff.",
            "platform": null,
            "public": 0,
            "status": 1,
            "created_at": 1518558431,
            "updated_at": 1518558431
        },
        "locator": "device_type",
        "locator_type": "object"
    },
    "code": 201,
    "warnings": [],
    "message": "Created",
    "html_message": "Created"
}

PUT / PATCH - Update a device type

Update a device type. 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_type/{device_type_id}
  • PUT https://api.yombo.net/api/v1/device_type/{device_type_id}

Parameters

See post new device type 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 '{"gateway_id": "km8M7lRv0E31ebmx", "pin_required": 0,
"description": "A robot that cleans up messes.",
"category": "NKq9kVmM"}' \
https://api.yombo.net/api/v1/device_type/QAJqr8xZ

  <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_type/QAJqr8xZ'
headers = {
    'x-api-key': 'abc123xyz789',
    'authorization': 'Waro7g0Mwl4YBJ...',
    }

payload = {
    "label": "Cleaning Robot",
    "machine_label": "RoboClean",
    "description": "A robot that cleans up messes.",
    "category": "NKq9kVmM",
    }

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;">

{
    "response": {
        "uri": "/api/v1/device_type/QAJqr8xZ",
        "uri_description": "Update (patch) device type.",
        "doc_uri": "https://yombo.net/API:Device_types",
        "device_type": {
            "id": "QAJqr8xZ",
            "category_id": "NKq9kVmM",
            "machine_label": "cleaning_robot",
            "label": "Cleaning Robot",
            "description": "A robot that cleans up messes.",
            "platform": null,
            "public": 0,
            "status": 1,
            "created_at": 1518558431,
            "updated_at": 1518558612
        },
        "locator": "device_type",
        "locator_type": "object"
    },
    "code": 200,
    "warnings": [],
    "message": "OK",
    "html_message": "OK"
}

DELETE - Delete a device type

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

Request URLs

  • DELETE https://api.yombo.net/api/v1/device_type/{device_type_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..." \
-X DELETE https://api.yombo.net/api/v1/device_type/QAJqr8xZ

  <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_type/QAJqr8xZ'
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;">

{
    "response": {
        "uri": "/api/v1/device_type/QAJqr8xZ",
        "uri_description": "Delete a device type.",
        "doc_uri": "https://yombo.net/API:Device_types",
        "device_type": "Deleted",
        "locator": "device_type",
        "locator_type": "string"
    },
    "code": 200,
    "warnings": [],
    "message": "Deleted",
    "html_message": "Deleted"
}
Retrieved from "https://yombo.net/w/index.php?title=API:Device_types&oldid=13238"