Skip to main content

Cover

The Cover component handles the operation of motorized garage doors, window blinds, roof skylights etc. It uses Cover as RPC namespace and provides the methods:

Methods

Cover.SetConfig

Preconditions:

Cover configuration can not be changed if:

  • Cover is moving at the time of the request
  • Cover calibration is running at the time of the request

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

config

object

Configuration that the method takes

The parameters in config must meet the following restrictions:

  • name: [0..64]chars
  • power_limit: [0..max_rated]W or null to set default (= max_rated)
  • voltage_limit: (undervoltage_limit..max_rated]V or null to set default (= max_rated)
  • undervoltage_limit: [0..voltage_limit)V or null to set default (= 0 -> disabled)
  • current_limit: [0..max_rated]A or null to set default (= max_rated)
  • motor.idle_power_thr: [0..50]W
  • motor.idle_confirm_period: [0.25..0.75]seconds
  • maxtime_open: [0.1..300]sec
  • maxtime_close: [0.1..300]sec
  • obstruction_detection.power_thr: [0..max_rated]W
  • obstruction_detection.holdoff: [0.1..300]seconds

Find more about the config properties in config section

Cover.GetConfig

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

Find more about the config properties in config section

Cover.GetStatus

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

Find more about the status properties in status section

Cover.Calibrate

Preconditions:

Cover will not accept the command if:

  • Cover has any of the following errors set at the time of the request: safety_switch, overpower, overvoltage, undervoltage, overcurrent, obstruction, overtemp
  • Cover is moving at the time of the request
  • Cover is already calibrating

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

Response:

null on success; error if request can not be executed or failed

Notes:

1) The calibration procedure will be aborted if:

  • Cover fails to reach fully open / fully closed position within the configured timeout maxtime_open / maxtime_close. This can happen if a) maxtime_open / maxtime_close are set too low and the Cover stops before reaching the end positions, or b) there is a physical problem with the limit switches and the end positions can not be detected;
  • Any Cover safety feature (except obstruction detection, see point 3) is triggered during the calibration procedure (overpower, overtemp, etc.);
  • Cover receives an external command to stop during the calibration procedure (via input, RPC call, etc.);
  • Cover reports a mismatch between motor feedback and expected state during the calibration procedure, e.g. motor turning in wrong direction;
  • The device reboots (for any reason, incl. ota, factory reset, etc.) during the calibration procedure;

2) Once started, the calibration procedure invalidates any previous calibration data, and only saves new calibration data if the complete procedure finishes successfully. If the calibration procedure is interrupted due to any of the reasons described in point 1), calibration data will not be available.

3) During calibration, obstruction detection is ignored and the Cover will not stop if the power consumption rises above the obstruction detection threshold.

Cover.Open

Preconditions:

Cover will not accept the command if:

  • An overvoltage error is set at the time of the request
  • An undervoltage error is set at the time of the request
  • An overtemp error is set at the time of the request
  • An engaged safety_switch prohibits movement in the requested direction
  • Cover calibration is running at the time of the request

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

duration

number

If duration is not provided, Cover will fully open, unless it times out because of maxtime_open first. If duration (seconds) is provided, Cover will move in open direction for the specified time. duration must be in range [0.1..maxtime_open]Optional

Response:

null on success; error if request can not be executed or failed

Cover.Close

Preconditions:

Cover will not accept the command if:

  • An overvoltage error is set at the time of the request
  • An undervoltage error is set at the time of the request
  • An overtemp error is set at the time of the request
  • An engaged safety_switch prohibits movement in the requested direction
  • Cover calibration is running at the time of the request

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

duration

number

If duration is not provided, Cover will fully close, unless it times out because of maxtime_close first. If duration (seconds) is provided, Cover will move in close direction for the specified time. duration must be in range [0.1..maxtime_open]Optional

Response:

null on success; error if request can not be executed or failed

Cover.Stop

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

Response:

null on success; error if request can not be executed or failed

Cover.GoToPosition

Preconditions:

Cover will not accept the command if:

  • Cover is not calibrated or Cover calibration is running at the time of the request

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

pos

number

Required and mutually exclusive (at least one of them pos/rel be provided, but not both at the same time). pos represents target position in %, allowed range [0..100]. If rel is provided, Cover will move to a target_position = current_position + rel. If the value of rel is so big that it results in overshoot (i.e. target_position is beyond fully open / fully closed), target_position will be silently capped to fully open / fully closed

rel

number

Required and mutually exclusive (at least one of them pos/rel be provided, but not both at the same time). rel represents relative move in %, allowed range [-100..100]

Response:

null on success; error if request can not be executed or failed

Configuration

The configuration of the Cover component contains information about the input mode, the timers and the protection settings of the chosen cover instance. To Get/Set the configuration of the Cover component its id must be specified.

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

name

string

Name of the Cover component instance

in_mode

string

One of single, dual or detached, only present if there is at least one input associated with the Cover instance:

ValueDescription

single

Cover operation in both open and close directions is controlled via a single input. In this mode, only input_0 is used to open/close/stop the Cover. It doesn't matter if input_0 has in_type=switch or in_type=button, the behavior is the same: each switch toggle or button press cycles between open/stop/close/stop/... In single mode, input_1 is free to be used as a safety switch (e.g. end-of-motion limit switch, emergency-stop, etc.), see below

dual

Cover operation is controlled via two inputs, one for open and one for close. In this mode, input_0 is used to open the Cover, input_1 is used to close the Cover.The exact behavior depends on the in_type of the inputs: if in_type = switch: toggle the switch to ON to move in the associated direction; toggle the switch to OFF to stop, if in_type = button: press the button to move in the associated direction; press the button again to stop

detached

Cover operation via the input/inputs is prohibited

initial_state

string

Defines Cover target state on power-on, one of open (Cover will fully open), closed (Cover will fully close) or stopped (Cover will not change its position)

power_limit

number

Watts, limit that must be exceeded to trigger an overpower error

voltage_limit

number

Volts, limit that must be exceeded to trigger an overvoltage error

undervoltage_limit

number

Volts, limit that must be subceeded to trigger an undervoltage error

current_limit

number

Amperes, limit that must be exceeded to trigger an overcurrent error

motor

object

configuration of the Cover motor. The exact contents depend on the type of motor used. The descriptions below are valid when an AC motor is used

motor.idle_power_thr

number

Watts, threshold below which the motor is considered stopped

motor.idle_confirm_period

number

Seconds, minimum period of time in idle state before state is confirmed

maxtime_open

number

Default timeout after which Cover will stop moving in open direction

maxtime_close

number

Default timeout after which Cover will stop moving in close direction

swap_inputs

Only present if there are two inputs associated with the Cover instance, defines whether the functions of the two inputs are swapped. The effect of swap_inputs is observable only when in_mode != detached:

ValueDescription

false

When swap_inputs is false: If in_mode = dual: input_0 is used to open, input_1 is used to close. If in_mode = single: input_0 is used to open/close/stop, input_1 is used as safety switch or is not used at all

true

When swap_inputs is true: If in_mode = dual: input_0 is used to close, input_1 is used to open. If in_mode = single: input_0 is used as safety switch or is not used at all, input_1 is used to open/close/stop

invert_directions

boolean

Defines the motor rotation for open and close directions (changing this parameter requires a reboot):

ValueDescription

false

On open motor rotates clockwise, on close motor rotates counter-clockwise

true

On open motor rotates counter-clockwise, on close motor rotates clockwise

obstruction_detection

object

Defines the behavior of the obstruction detection safety feature

PropertyTypeDescription

enable

boolean

true when obstruction detection is enabled, false otherwise

direction

string

The direction of motion for which safety switch should be monitored, one of open, close, both

action

string

The recovery action which should be performed if the safety switch is engaged while moving in a monitored direction, one of:

ValueDescription

stop

Immediately stop Cover

reverse

Immediately stop Cover, then move in the opposite direction until a fully open or fully closed position is reached. If Cover encounters a new obstruction while reversing from a previous one, it will unconditionally stop

power_thr

number

Watts, power consumption above this threshold should be interpreted as objects obstructing Cover movement. This property is editable at any time, but note that during the cover calibration procedure (Cover.Calibrate), power_thr will be automatically set to the peak power consumption + 15%, overwriting the current value. The automatic setup of power_thr during calibration will only start tracking power values when the holdoff time (see below) has elapsed

holdoff

number

Seconds, time to wait after Cover starts moving before obstruction detection is activated (to avoid false detections because of the initial power consumption spike)

safety_switch

object

Defines the behavior of the safety switch feature, only present if there are two inputs associated with the Cover instance. The safety_switch feature will only work when in_mode=single

PropertyTypeDescription

enable

boolean

true when safety switch is enabled, false otherwise

direction

string

The direction of motion for which safety switch should be monitored, one of open, close, both

action

string

The recovery action which should be performed if the safety switch is engaged while moving in a monitored direction, one of:

ValueDescription

stop

Immediately stop Cover, then wait for a command to move in an allowed direction (see below)

reverse

Immediately stop Cover, then move in the opposite direction until a fully open or fully closed position is reached. action = reverse requires that allowed_move = reverse

pause

Immediately stop Cover, then either: wait for a command to move in an allowed direction (see below) or automatically continue movement in the same direction (i.e. the one that was interrupted) when the safety switch is disengaged

allowed_move

string or null

Allowed movement direction when the safety switch is engaged while moving in a monitored direction:

ValueDescription

null

null means Cover can't be moved in neither open nor close directions while the safety switch is engaged

reverse

the only other option is reverse, which means Cover can only be moved in the direction opposite to the one that was interrupted (for example, if the safety switch was hit while opening, Cover can only be commanded to close if the switch is not disengaged)

Config defaults:

  • name = null
  • in_mode = dual
  • initial_state = stopped
  • power_limit = max rated
  • voltage_limit = max rated
  • undervoltage_limit = 0
  • current_limit = max rated
  • motor.idle_power_thr = 2
  • motor.idle_confirm_period = 0.25
  • maxtime_open = 60
  • maxtime_close = 60
  • swap_inputs = false
  • invert_directions = false
  • obstruction_detection.enable = false
  • obstruction_detection.direction = both
  • obstruction_detection.action = stop
  • obstruction_detection.power_thr = 1000
  • obstruction_detection.holdoff = 1
  • safety_switch.enable = false
  • safety_switch.direction = both
  • safety_switch.action = stop
  • safety_switch.allowed_move = null

Status

The status of the Cover component contains information about the temperature, voltage, accumulated energy level and other physical characteristics of the cover instance. To obtain the status of the Cover component its id must be specified.

Properties:

PropertyTypeDescription

id

number

The numeric ID of the Cover component instance

source

string

Source of the last command

state

string

One of open (Cover is fully open), closed (Cover is fully closed), opening (Cover is actively opening), closing (Cover is actively closing), stopped (Cover is not moving, and is neither fully open nor fully closed, or the open/close state is unknown), calibrating (Cover is performing a calibration procedure)

apower

number

Active power in Watts

voltage

number

Volts

current

number

Amperes

pf

number

power factor

aenergy

object

Energy counter information, same as in the Switch component status

current_pos

number ot null

Only present if Cover is calibrated. Represents current position in percent from 0 (fully closed) to 100 (fully open); null if position is unknown

target_pos

number or null

Only present if Cover is calibrated and is actively moving to a requested position in either open or close directions. Represents the target position in percent from 0 (fully closed) to 100 (fully open); null if target position has been reached or the movement was cancelled

move_timeout

number

Seconds, only present if Cover is actively moving in either open or close directions. Cover will automatically stop after the timeout expires

move_started_at

number

Only present if Cover is actively moving in either open or close directions. Represents the time at which the movement has begun

pos_control

bool

False if Cover is not calibrated and only discrete open/close is possible; true if Cover is calibrated and can be commanded to go to arbitrary positions between fully open and fully closed

temperature

object

Temperature sensor information, only present if a temperature monitor is associated with the Cover instance

errors

array

Only present if an error condition has occurred

The errors are set when one or more of the following conditions occurs:

ErrorCondition

overtemp

When temperature exceeds predefined limit, Cover will stop immediately

overpower

When power exceeds configured limit, Cover will stop immediately

overvoltage

When voltage exceeds configured limit, Cover will stop immediately

undervoltage

When voltage subceeds configured limit, Cover will stop immediately

overcurrent

When current exceeds configured limit, Cover will stop immediately

obstruction

When an obstruction is hit, Cover will execute a configured recovery action (stop or reverse)

safety_switch

When the safety switch is engaged while Cover is moving in one of the monitored directions (see safety_switch.direction below) the error will be set immediately, Cover will execute a configured recovery action (stop, reverse of pause). When the safety switch is engaged while Cover is idle or moving in a non-monitored direction, the error will be set on the first open/close/go to position command that requests a movement in one of the monitored directions (see safety_switch.direction below)

bad_feedback:rotating_in_wrong_direction

When power meters feedback indicates the motor is rotating in a different direction than commanded; Cover will stop immediately

bad_feedback:both_directions_active

When power meters feedback indicates both outputs connected to the motor are active simultaneously (this should never be possible); Cover will stop immediately

bad_feedback:failed_to_halt

When power meters feedback indicates the motor is still rotating though it has been commanded to stop

cal_abort:timeout_open

When calibration is aborted since Cover failed to reach fully open position within the configured timeout (maxtime_open)

cal_abort:timeout_close

When calibration is aborted since Cover failed to reach fully closed position within the configured timeout (maxtime_close)

cal_abort:safety

When calibration is aborted since a Cover safety feature got triggered during the calibration process (this means that at least one of overtemp, overpower, overvoltage, undervoltage, overcurrent, safety_switch will also be present in errors)

cal_abort:ext_command

When calibration is aborted since Cover received an external command to stop during the calibration process (via input, RPC call, etc.)

cal_abort:bad_feedback

When calibration is aborted since Cover reported a mismatch between expected motor state and power meters feedback during the calibration process (this means that at least one of bad_feedback:rotating_in_wrong_direction, bad_feedback:both_directions_active, bad_feedback:failed_to_halt will also be present in errors)

cal_abort:implausible_time_to_fully_close

When calibration is aborted since the measured time to fully close is negative or 0

cal_abort:implausible_time_to_fully_open

When calibration is aborted since the measured time to fully open is negative or 0

cal_abort:implausible_power_consumption_in_close_dir

When calibration is aborted since measured power consumption in close direction is negative or 0

cal_abort:implausible_power_consumption_in_open_dir

When calibration is aborted since measured power consumption in open direction is negative or 0

cal_abort:too_many_steps_to_close

When calibration is aborted since it took more steps than allowed to reach fully closed position during the 10-step-calibration-movement

cal_abort:too_few_steps_to_close

When calibration is aborted since it took fewer steps than allowed to reach fully closed position during the 10-step-calibration-movement

cal_abort:implausible_time_to_fully_close_w_steps

When calibration is aborted since the time to reach fully closed position during the 10-step-calibration-movement is negative or 0

cal_abort:implausible_step_duration_in_open_dir

When calibration is aborted since the actual step duration during the 10-step-calibration-movement in open direction is negative or 0

cal_abort:too_many_steps_to_open

When calibration is aborted since it took more steps than allowed to reach fully open position during the 10-step-calibration-movement

cal_abort:too_few_steps_to_open

When calibration is aborted since it took fewer steps than allowed to reach fully open position during the 10-step-calibration-movement

cal_abort:implausible_time_to_fully_open_w_steps

When calibration is aborted since the time to reach fully open position during the 10-step-calibration-movement is negative or 0

The errors are cleared when the device recovered from the wrong condition:

ErrorCondition

overtemp

when temperature falls below a predefined limit

overpower

On the first open/close/go to position command after the emergency stop

overvoltage

When voltage falls below configured limit

undervoltage

When voltage goes above configured limit

overcurrent

On the first open/close/go to position command after the emergency stop

obstruction

On the first open/close/go to position command after the recovery action

safety_switch

When the safety switch is disengaged

bad_feedback

On the first open/close/go to position/calibrate command after the emergency stop

cal_abort

On the first open/close/calibrate command after the error has been set

Webhook Events

There are five events related to the Cover component that can trigger webhooks:

  • cover.open: Cover has reached fully open position
  • cover.closed: Cover has reached fully closed position
  • cover.opening: Cover has begun moving in open direction
  • cover.closing: Cover has begun moving in close direction
  • cover.stopped: Cover has stopped moving, but is neither fully open nor fully closed

Calibration KB

Overview

The purpose of the Cover component calibration procedure is to endow position control. Once successfully calibrated, positioning between 0% and 100% becomes available. An uncalibrated Cover component supports only Open and Close commands.

Whether a Cover component is calibrated or not can be derived from the boolean pos_control status attribute, which reflects the presence of valid calibration data. If valid calibration data is available this attribute is set to true.

The calibration procedure relies on feedback from the device's power meters. Most motors used in roller shutters, blinds, garage doors, etc. have integrated limit switches or load control electronics which cut off power to the motor when fully open / fully closed positions are reached. During the calibration procedure, the Cover component constantly monitors the power meter's feedback, and treats power consumption drops below motor.idle_power_thr as an end position.

Correctly detecting fully open / fully closed positions is essential for calculating calibration data, and therefore, the success of the calibration procedure. Calibration will fail if the motor's power consumption can not be monitored (e.g. when the hardware setup is such that the Cover component controls the motor via intermediate switches, contactors, etc.). The absence of valid calibration data is considered as an indication that adequate power meter's feedback can not be acquired and power meter readings will be ignored during Cover component operation in regards to movement control and monitoring. In this case, the Cover component will rely solely on maxtime_open / maxtime_close to report that end positions are reached.

Before starting the calibration procedure

This checklist can be useful to rule out configuration, electrical or other hardware problems before starting:

  • It should be confirmed that the cover can be operated in both directions with simple Open / Close / Stop commands. It should be possible to perform a complete movement from fully open position to fully closed position and vice-versa without a timeout. If not, maxtime_open and/or maxtime_close should be increased.

  • The power consumption of the motor apower should rise above motor.idle_power_thr while moving, and should fall below motor.idle_power_thr when stopped. If not, motor.idle_power_thr should be adjusted accordingly.

  • For vertical covers, invert_directions parameter should be setup correctly (Open should cause upward movement, Close should cause downward movement). The calibration procedure can run anyway, but will result in reduced position control accuracy.

  • Before starting calibration, cover must be idle (stopped) and all of the following errors must be cleared: safety_switch, overpower, overvoltage, undervoltage, overcurrent, obstruction, overtemp. If these conditions are not met, the calibration request will be rejected.

warning

Aside from calculating movement parameters, during the calibration procedure the Cover component will monitor the peak power consumption and automatically set the value of obstruction_detection.power_thr. Hence, the obstruction detection protection mechanism will be disabled for the duration of the calibration procedure, regardless of the obstruction_detection.enable property. Before starting calibration, it must be ensured there are no objects obstructing the movement and the device should not be left without supervision while calibration is in progress.

Calibration workflow

The execution flow of the calibration procedure is as follows:

  • 1) Go to initial position (fully open)
  • 2) Go to fully closed position in one uninterrupted movement
  • 3) Go to fully open position in one uninterrupted movement
  • 4) Go to fully closed position in consecutive movement steps
  • 5) Go to fully open position in consecutive movement steps

The gathered measurements are used to calculate calibration data consisting of:

  • the time it takes to travel 1% in close direction
  • the time it takes to travel 1% in open direction
  • the motor ramp-up time in close direction
  • the motor ramp-up time in open direction

When calibration data is available, the Cover component will keep track of the duration of each movement and use the calibration data to determine the current position relative to the end positions. Similarly, the Cover component will use the calibration data to translate GoToPosition requests to movement durations in the corresponding direction.

Troubleshooting

1) Calibration fails with error cal_abort:timeout_open / cal_abort:timeout_close

Reason

The Cover component failed to detect a fully open / fully closed position within the configured timeout maxtime_open / maxtime_close

Mitigation

  • If the cover stops moving before (visibly) reaching the end positions, the timeouts are probably too short. Try to increase maxtime_open / maxtime_close;
  • If the cover reaches the end positions but the calibration still fails with the same error, it is possible that the motor's power consumption remains above motor.idle_power_thr even when the motor has stopped. Try to icrease the value of motor.idle_power_thr.

2) Calibration fails with error cal_abort:implausible_power_consumption_in_close_dir / cal_abort:implausible_power_consumption_in_open_dir

Reason

The Cover component didn't detect positive power consumption during the calibration procedure.

Mitigation

  • Check the reported power consumption when a simple Open / Close command is issued. If the power consumption is 0 while the cover is moving, check the hardware setup;
  • If the power consumption is OK during simple Open / Close but calibration still fails, it is possible that the value of obstruction_detection.holdoff is configured to be greater than the time to fully open / fully close, which effectively impedes power monitoring during this period. Try to decrease the value of obstruction_detection.holdoff.

3) Device is calibrated succesfully (pos_control=true) but current position is unknown (current_pos=null)

Reason

In certain conditions (e.g. after power outage) the Cover component can loose track of its current position. This doesn't mean that calibration data is lost or broken, but only that the cover needs to be moved to a known reference point to resume tracking the current position.

Mitigation

Open / Close the cover until a fully open / fully closed position is reached.

4) Cover.GoToPosition fails with "-109 Precondition failed: Current position unknown!"

Reason

Position control is only possible if cover movement starts at a known reference point. If the Cover component has lost its current position (see previous point), it's not possible to execute position requests.

Mitigation

Open / Close the cover until a fully open / fully closed position is reached.

5) Position control looses accuracy over time

Reason

The Cover component position control relies on time counting to keep track of the current position and execute GoToPosition requests. As an open-loop control system the only reference points that can be feedback-confirmed during cover movement are the fully open / fully closed positions. If the cover is moved many times between fully open / fully closed without ever reaching them, error is accumulated and position control accuracy deteriorates.

Mitigation

Open / Close the cover until a fully open / fully closed position is reached.

Examples

Cover.SetConfig example

Note: Setting a specific section.configurationOption (for example motor.idle_power_thr) can be done via:

http://192.168.33.1/rpc/Cover.SetConfig?id=0&config={"motor":{"idle_power_thr":3}}

Response

{
"restart_required": false
}

Cover.GetConfig example

http://192.168.33.1/rpc/Cover.GetConfig?id=0

Response

{
"id": 0,
"name": "myCover",
"motor": {
"idle_power_thr": 2,
"idle_confirm_period": 0.25
},
"maxtime_open": 60,
"maxtime_close": 60,
"initial_state": "stopped",
"invert_directions": false,
"in_mode": "dual",
"swap_inputs": false,
"safety_switch": {
"enable": false,
"direction": "both",
"action": "stop",
"allowed_move": null
},
"power_limit": 2800,
"voltage_limit": 280,
"undervoltage_limit": 0,
"current_limit": 10,
"obstruction_detection": {
"enable": false,
"direction": "open",
"action": "stop",
"power_thr": 120,
"holdoff": 1
}
}

Cover.GetStatus example

http://192.168.33.1/rpc/Cover.GetStatus?id=0

Response

{
"id": 0,
"source": "limit_switch",
"state": "open",
"apower": 0,
"voltage": 233,
"current": 0,
"pf": 0,
"aenergy": {
"total": 48.996,
"by_minute": [
0,
0,
0
],
"minute_ts": 1654604045
},
"temperature": {
"tC": 55.4,
"tF": 131.7
},
"pos_control": true,
"current_pos": 100
}

Cover.Calibrate example

http://192.168.33.1/rpc/Cover.Calibrate?id=0

Response

null

Cover.Open example

http://192.168.33.1/rpc/Cover.Open?id=0

Response

null

Cover.Close example

http://192.168.33.1/rpc/Cover.Close?id=0

Response

null

Cover.GoToPosition example

http://192.168.33.1/rpc/Cover.GoToPosition?id=0&pos=20

Response

null