Ikea Tradfri CoAP Docs

How can you communicate to your Ikea tradfri gateway/hub through coap-client. Tested with Tradfri hub version 1.3.0014, 1.8.0025 and 1.12.0.

Table of Contents

• Ikea Tradfri CoAP Docs
  • Table of Contents
  • Install coap-client
  • Authenticate
  • The URL
  • Devices
    • Get a list of all devices
    • Get info about a specific device
  • Groups
    • Get a list of all groups
    • Get info about a specific group
    • Add device to a specific group
    • Remove device from a specific group
    • Turn on all devices in a specific group
    • Payload
  • Scenes
    • Get a list of all scenes
    • Get info about a specific scene
    • Activating a scene
  • Endpoints
    • List all available endpoints
  • Sensor
  • Remote
  • Shortcut button
  • Bulbs
    • Your first bulb
    • Payload
    • Colors
      • Cold / Warm Bulbs
      • RGB Bulbs
    • More Colors
  • Plug
    • Your first plug
    • Payload
  • Blind
    • Your first blind
    • Payload
  • Endpoints
    • Global
    • Gateway
  • Codes
    • Devices
    • General parameters
    • Group parameters
    • Scene parameters
    • Bulb parameters
    • Plug parameters
    • Blind parameters
  • CoAP Protocol
    • CoAP Response Codes
    • CoAP Method Codes
  • License

Install coap-client

Before you can talk to you Ikea gateway/hub you need to install the coap-client:

1. Download the install-coap-client.sh from github.
2. Chmod the file so you can run it.
3. Run the file as root.

Authenticate

First we need to create a preshared key. This key can then be used to authenticate yourself: Please note: this key will expire if you don't use it in 6 weeks from activation. Every time you use this key the time will be extended accordingly.

coap-client -m post -u "Client_identity" -k "$TF_GATEWAYCODE" -e "{\"9090\":\"$TF_USERNAME\"}" "coaps://$TF_GATEWAYIP:5684/15011/9063"

• $TF_USERNAME: Can be a random name as long as you use it in the other requests you want to make
• $TF_GATEWAYCODE: Is the security code at the bottom of your Gateway/HUB. It should be 16 characters long.
• $TF_GATEWAYIP: Is the IP of your Gateway/HUB

This will then respond something like this:

{
  "9091": "$TF_PRESHARED_KEY", // Preshared Key
  "9029": "1.3.0014" // Gateway Firmware version
}

The URL

To control a bulb you need to know it's URL. This is very easy. The URL's all begin with coaps://$TF_GATEWAYIP:5684/15001

The bulbs will have addresses beginning at 65537 for the first bulb, 65538 for the second, and so on. So, to control the first bulb, you would use the following url:

coaps://$TF_GATEWAYIP:5684/15001/65537

Devices

Get a list of all devices

To get a complete list of all devices connected to your hub use the following command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/15001"

Get info about a specific device

To check the current status of a connected device and to know which device is linked to a specified id, use this command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/15001/$TF_DEVICEID"

$TF_DEVICEID is an id from the list generated by the previous command. Ids are 5 digits long.

Groups

Get a list of all groups

To get a complete list of all groups use the following command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/15004"

Get info about a specific group

To check the current status of a group and to know which devices are linked to the specified id, use this command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/15004/$TF_GROUPID"

$TF_GROUPID is an id from the list generated by the previous command. Ids are 6 digits long.

Add device to a specific group

To add a member device to a group, use this command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "9038": $TF_GROUPID, "9003": [ $TF_DEVICEID ] }' "coaps://$TF_GATEWAYIP:5684/15004/add"

Remove device from a specific group

To remove a member device from a group, use this command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "9038": $TF_GROUPID, "9003": [ $TF_DEVICEID ] }' "coaps://$TF_GATEWAYIP:5684/15004/remove"

Turn on all devices in a specific group

To control a specific group, use this command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "5850": 1 }' "coaps://$TF_GATEWAYIP:5684/15004/$TF_GROUPID"

$TF_GROUPID is an id from the list generated by the Get a list of all groups command. Ids are 6 digits long.

Payload

Here is an example payload for coap-client with explanation what each field does:

{
  "5850": 1, // on / off (needs to be set to 1 to switch scenes)
  "5851": 254, // dimmer (1 to 254)
  "5712": 10, // transition time (fade time)
  "9039": 196621 // scene id for activating/switching scenes (id comes from the list generated by the `Get a list of all scenes` command. Ids are 6 digits long.)
}

Scenes

Note: scenes where formerly known as moods inside the Ikea Tradfri app. This change was introduced at version 1.12.0

Get a list of all scenes

To get a complete list of all scenes use the following command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/15005/$TF_GROUPID"

$TF_GROUPID is an id from the list generated by the Get a list of all groups command. Ids are 6 digits long.

Get info about a specific scene

To get the current configuration of a scene and to know which devices are linked to the specified id, use this command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/15005/$TF_GROUPID/$TF_SCENEID"

$TF_SCENEID is an id from the list generated by the previous command. Ids are 6 digits long.

$TF_GROUPID is an id from the list generated by the Get a list of all groups command. Ids are 6 digits long.

Activating a scene

A scene can be activated by controlling a specific group. From this endpoint you are able to set a scene on the specified group. A detailed payload can be found in the Groups > Payload chapter. The following command can be used to activate a scene in a group:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "5850": 1, "9039": $TF_SCENEID }' "coaps://$TF_GATEWAYIP:5684/15004/$TF_GROUPID"

$TF_GROUPID is an id from the list generated by the Get a list of all groups command. Ids are 6 digits long.

$TF_SCENEID is an id from the list generated by the Get a list of all scenes command. Ids are 6 digits long.

Endpoints

List all available endpoints

To get a complete list of available endpoints on your gateway use the following command:

coap-client -m get -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" "coaps://$TF_GATEWAYIP:5684/.well-known/core"

Sensor

The (motion) sensor is unsupported at the moment, since the gateway doesn't receive any useful information from the sensor. The cause of this could be since the device is running of batteries. And if the sensor needs to send data back constantly to the gateway it would run out of them pretty quickly. If someone has more information about the sensor please open an issue of create a pull request to update the documentation.

Remote

The remote is unsupported at the moment, since the gateway doesn't receive any useful information from the remote. The cause of this could be since the device is running of batteries. And if the remote needs to send data back constantly to the gateway it would run out of them pretty quickly. If someone has more information about the remote please open an issue of create a pull request to update the documentation.

Shortcut button

The Ikea shortcut button was introduced around november 2020.

The button is unsupported at the moment, since the gateway doesn't receive any useful information from the button. The cause of this could be since the device is running of batteries. And if the button needs to send data back constantly to the gateway it would run out of them pretty quickly. If someone has more information about the button please open an issue of create a pull request to update the documentation.

Bulbs

Your first bulb

To set the brightness of your first bulb to 50% use the following command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "3311": [{ "5851": 127 }] }' "coaps://$TF_GATEWAYIP:5684/15001/$TF_DEVICEID"

Payload

Here is an example payload for coap-client with explanation what each field does:

{
  "3311": [
    {
      "5850": 1, // on / off
      "5851": 254, // dimmer (1 to 254)
      "5706": "f1e0b5", // color in HEX (Don't use in combination with: color X and/or color Y)
      "5709": 65535, // color X (Only use in combination with color Y)
      "5710": 65535, // color Y (Only use in combination with color X)
      "5712": 10 // transition time (fade time)
    }
  ]
}

Colors

The following colors where taken from the Ikea Android app (these could be used in field "5706"):

Please note: If you are using another HEX value then these the lamp will default to the Warm Glow color.

Cold / Warm Bulbs

"f5faf6": "White",
"f1e0b5": "Warm",
"efd275": "Glow"

RGB Bulbs

"4a418a": "Blue",
"6c83ba": "Light Blue",
"8f2686": "Saturated Purple",
"a9d62b": "Lime",
"c984bb": "Light Purple",
"d6e44b": "Yellow",
"d9337c": "Saturated Pink",
"da5d41": "Dark Peach",
"dc4b31": "Saturated Red",
"dcf0f8": "Cold sky",
"e491af": "Pink",
"e57345": "Peach",
"e78834": "Warm Amber",
"e8bedd": "Light Pink",
"eaf6fb": "Cool daylight",
"ebb63e": "Candlelight",
"efd275": "Warm glow",
"f1e0b5": "Warm white",
"f2eccf": "Sunrise",
"f5faf6": "Cool white"

More Colors

Ikea RGB bulbs can produce more colors then the list above.

They can produce all colors in the xyY color space.

To understand how this color space works take a look at the diagram below:

To create your own color you need define two values (x and y) from 0 to 65535 with this command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "3311": ["5709": 65535, "5710": 65535] }' "coaps://$TF_GATEWAYIP:5684/15001/$TF_DEVICEID"

Plug

The Ikea plug was introduced around oktober 2018.

Also this device can be controlled with the same api.

Your first plug

To turn on a plug use the following command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "3312": [{ "5850": 1 }] }' "coaps://$TF_GATEWAYIP:5684/15001/$TF_DEVICEID"

Payload

Here is an example payload for coap-client with explanation what each field does:

{
  "3312": [
    {
      "5850": 1, // on / off
      "5851": 254 // dimmer (0 to 254) (As of writing there arn't any dimmable plugs. Value's above 0 will simply turn on the plug)
    }
  ]
}

Blind

The Ikea blinds where introduced around august 2019.

Also this device can be controlled with the same api.

Your first blind

To change position of a blind use the following command:

coap-client -m put -u "$TF_USERNAME" -k "$TF_PRESHARED_KEY" -e '{ "15015": [{ "5536": 0.0 }] }' "coaps://$TF_GATEWAYIP:5684/15001/$TF_DEVICEID"

Payload

Here is an example payload for coap-client with explanation what each field does:

{
  "15015": [
    {
      "5536": 0.0, // position (0 to 100)
    }
  ]
}

Endpoints

Global

Gateway

Please note: You need to use -m post for the reboot command to work.

Codes

Devices

General parameters

Group parameters

Scene parameters

Bulb parameters

Plug parameters

Blind parameters

CoAP Protocol

CoAP Response Codes

Below is a snippet from https://tools.ietf.org/html/rfc7252 containing the default CoAP response codes:

+------+------------------------------+-----------+
| Code | Description                  | Reference |
+------+------------------------------+-----------+
| 2.01 | Created                      | [RFC7252] |
| 2.02 | Deleted                      | [RFC7252] |
| 2.03 | Valid                        | [RFC7252] |
| 2.04 | Changed                      | [RFC7252] |
| 2.05 | Content                      | [RFC7252] |
| 4.00 | Bad Request                  | [RFC7252] |
| 4.01 | Unauthorized                 | [RFC7252] |
| 4.02 | Bad Option                   | [RFC7252] |
| 4.03 | Forbidden                    | [RFC7252] |
| 4.04 | Not Found                    | [RFC7252] |
| 4.05 | Method Not Allowed           | [RFC7252] |
| 4.06 | Not Acceptable               | [RFC7252] |
| 4.12 | Precondition Failed          | [RFC7252] |
| 4.13 | Request Entity Too Large     | [RFC7252] |
| 4.15 | Unsupported Content-Format   | [RFC7252] |
| 5.00 | Internal Server Error        | [RFC7252] |
| 5.01 | Not Implemented              | [RFC7252] |
| 5.02 | Bad Gateway                  | [RFC7252] |
| 5.03 | Service Unavailable          | [RFC7252] |
| 5.04 | Gateway Timeout              | [RFC7252] |
| 5.05 | Proxying Not Supported       | [RFC7252] |
+------+------------------------------+-----------+

CoAP Method Codes

Below is a snippet from https://tools.ietf.org/html/rfc7252 containing the default CoAP method codes:

+------+--------+-----------+
| Code | Name   | Reference |
+------+--------+-----------+
| 0.01 | GET    | [RFC7252] |
| 0.02 | POST   | [RFC7252] |
| 0.03 | PUT    | [RFC7252] |
| 0.04 | DELETE | [RFC7252] |
+------+--------+-----------+

License

MIT