Blinds position

The plugin emulates the blinds position using a timer, but it can be optionally used to poll the current position (with pos_url), include the target position in the request (with %%POS%%), and trigger a change in blind position via webhook.

Poll current position

pos_url must report the current state of the blinds as an integer (0-100) in either plain text or JSON format, e.g. {"current_position": 40}. If JSON is used, JSON keys are filtered to look for a single numeric response, but the JSON handling is not very robust and will cause unexpected results if multiple numeric keys are present.

pos_url defaults to a simple GET request, ignoring headers or other methods specified in http_options. If more robust handling is required, pos_url can be defined as a complete request/requestretry object as specified in Advanced URL above.

If more robust handling of pos_url responses in JSON format is needed, pos_jsonata can be defined. This allows a JSONata expression to be set to parse the result. For example, considering the following JSON response:

{
    "example": { "value": 4 }
}

So, pos_jsonata could be set to example.value (as below) to produce the value of 4.

    "pos_jsonata": "example.value",

Also, note that if the returned value is not in JSON format, $ can be used in some instances. For example, the expression below could be used to replace " in the case of a simple string response like "25".

    "pos_jsonata": "$replace($, '\"', '')",

The JSONata Exerciser can be a helpful tool for developing custom expressions.

Ensure that the motion time is configured properly, even when pos_url is set, as it is used to obtain an estimate of blind position to avoid multiple web requests to the pos_url. (After the estimated position is reached, the position will be confirmed).

pos_poll_ms is specified in ms, and defaults to 15000 ms (15 s). It can be used to set the polling frequency, particularly useful in cases where the blinds can also be controlled externally.

Include target position in request

For up_url and down_url, the variable %%POS%% can be included in the URL, which will be replaced with the desired target before the URL is requested. For example, use of http://1.2.3.4/window/up?pos=%%POS%% would be modified to http://1.2.3.4/window/up?pos=100 if the position 100 was requested. This is useful for cases where blinds offer the ability to directly specify the value.

When %%POS%% is used, note that stop_url will not be sent. (Because the blinds can receive a specific position, there is no need to send an additional stop command.)

NOTE: In scenarios where %%POS%% is part of a body object and required to be sent as an integer instead of a string, { pos: "%%POSINT%%" } can be used. In this case, it will be replaced with the target position as an integer value, e.g., { pos: 5 }.

If transforming %%POS%% or %%POSINT%% values before sending is desired (e.g., the endpoint uses a different numerical scheme), send_pos_jsonata can be defined. This allows a JSONata expression to be used to pre-parse the value instead of the default HomeKit 0-100 values.

So, send_pos_jsonata could be set to a custom expression like $round( ( 100 - $number($) ) * 255 / 100 ) where $ represents the target position value. The JSONata Exerciser can be a helpful tool for developing custom expressions.

Triggering target position (via webhook)

If the following parameters are defined, the position can be updated using a webhook. At a minimum, webhook_port must be defined. webhook_http_auth_user / webhook_http_auth_pass are used for basic authentication. If webhook_https is true, then an SSL connection is used instead. If webhook_https_keyfile / webhook_https_keyfile are not defined, a self-signed certificate will be used instead.

Once defined, this can be updated as follows: http://homebridgeip:port/?pos=##, where pos= any integer between 0-100. A simple JSON where success is true or false is returned. Additional information is returned in the logs.

For example, http://192.168.1.40:51828/?pos=30.

This implementation does take into account whether or not the blinds are moving, but will be most reliable in cases when blinds are stationary.

      "webhook_port": 51828,
      "webhook_http_auth_user": "username",
      "webhook_http_auth_pass": "password",
      "webhook_https": false,
      "webhook_https_keyfile": "/path/to/https.key",
      "webhook_https_certfile": "/path/to/https.crt",