Skip to content

api_smartbuttons.md

Latest commit

 

History

History
182 lines (128 loc) · 3.88 KB

api_smartbuttons.md

File metadata and controls

182 lines (128 loc) · 3.88 KB

Configure smartbuttons via the RESTful API

Overview

As the name already says, some buttons in your Wiser-by-Feller environment are smart. But don't worry, they are not smart at all, you still have to press the (smart-)button yourself.

A smartbutton can de married with a job. That means, by pressing the smartbutton a configured job will be executed.

Do not forget to include the authentication token in all your requests!

🐮 I have not get married yet, probably a smart decision?

Types of smartbuttons

They are two kind of smartbuttons:

  • Smartbuttons from type: scene

    • Example button-frontset (2x scene)

      Scene-Button-2

  • Smartbuttons from type: groupctrl

    • Example button-frontset (1x plus/minus)

      Group-Control-Button-Plus-Minus

Configure smartbuttons

The configuration of a smartbutton consists of the following steps:

  1. Activated the programming mode (program)

    • Choose between scene or groupctrl smartbuttons
    • Configure the blink-time. The default is 60 seconds
    • At this point the smartbuttons do not blinking yet

  2. Run the notify (notify)

    • Now the available smartbuttons will start blinking
      • scene-smartbuttons (will blinking purple)
      • groupctrl-smartbuttons (will blinking yellow)
    • As soon as one of the blinking smartbutton is pressed, all smartbuttons stop blinking and the notify request comes back with a response

  3. The Marriage

    • At this point you can configure a job. Now the marriage of the smartbutton within a job can take place.

Activated the programming mode

POST /api/smartbuttons/program

Activated the smartbutton programming-mode.

Possible attributes:

Key Description
on true to prepare programming mode or false to abort it (default: false)
timeout time in seconds to stay in programming mode (default: 60)
button_type type of buttons to program. scene or groupctrl (default: scene)

Example to activate the programming-mode with a scene-smartbutton

Request header:

POST /api/smartbuttons/program HTTP/1.1
Content-Type: application/json
host: example.com

Request body:

{
  "on": true,
  "timeout": 60,
  "button_type": "scene"
}

Response header:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
  "data": {
    "on": true,
    "button_type": "scene",
    "timeout": 60,
    "owner": "user"
  },
  "status": "success"
}

Run the notify

GET /api/smartbuttons/notify

Start blinking the smartbuttons and wait until one is pressed. This is a long lasting REST-API call. It blocks and wait until a smartbutton is pressed or the timeout is reached.

Example to notify the pressed smartbutton

Request header:

GET /api/smartbuttons/notify HTTP/1.1
host: example.com

Wait until until a smartbutton is pressed.

Response body:

{
  "data": {
    "button": 50
  },
  "status": "success"
}

The marriage

Finally we will get married!

PATCH /api/smartbuttons/ < id >

Example to marriage/link the smartbutton with a job

The request-body contains the unique job-id.

Request header:

PATCH /api/smartbuttons/50 HTTP/1.1
Content-Type: application/json
host: example.com

Request body:

{
  "job": 20
}

Response header:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
  "data": {
    "id": 50,
    "input_channel": 0,
    "device_addr": 48879,
    "device": "000BEEF",
    "input_type": 2,
    "job": 20,
  },
  "status": "success"
}

Just married, press the smartbutton and the job is executed.

🐮 This will be an everlasting love ❤️