Skip to main content
Version: 1.0

Input

The Input component handles the external digital or analog input terminals of a device. Input components are identified with input:<id> in objects containing multiple component payloads. Inputs can trigger webhooks, control switches and optionally perform factory reset.

Inputs can support one of three modes:

  • Digital inputs sense discrete HIGH / LOW input states and can be configured to work with attached momentary buttons or toggle switches.
  • Analog inputs can be configured to work as discrete inputs, but also support reading the analog value of the input, represented as a range between 0 and 100 %. Whether an input is analog capable is reflected on the page of each device model.
  • Counter inputs report accumulated counts and frequency

The Input component uses Input as the RPC namespace and implements the minimal component interface:

note

Factory reset by input is a way to roll back any changes made to the device and return it to its factory configuration. This action is possible only in the first 60 seconds after boot. The user should toggle the input 5 times and the device will be reset to its factory settings. Factory reset can also be done using an RPC call.

Methods

Input.SetConfig

PropertyTypeDescription

id

number

Id of the Input component instance

config

object

Configuration that the method takes

Find more about the config properties in config section

Input.GetConfig

Properties:

PropertyTypeDescription

id

number

Id of the Input component instance

Find the Input.GetConfig response properties in config section

Input.GetStatus

Properties:

PropertyTypeDescription

id

number

Id of the Input component instance

Find more about the status response properties in status section

Input.CheckExpression

Request

PropertyTypeDescription

expr

string

JS expression to evaluate

inputs

array

Input values on which to apply expr. Elements are allowed to be null

Response

results or error if any of the request parameters is missing or of the wrong type

PropertyTypeDescription

results

array

Array of 2-tuples, each containing an input and an output value: [input, output]. Input values are those from the request, but after processing into a number internally and back to a string. Outputs are corresponding results of the evaluated expression, and can be null. If the JS interpreter fails to parse or evaluate the expression a third element is added to the array, so it becomes [input, output, error message]

Input.ResetCounters

This method resets associated counters (if applicable).

Request

Parameters:

PropertyTypeDescription

id

number

Id of the Input component instance. Required

type

array of strings

Array of strings, selects which counter to reset Optional

note

If no 'type' is provided, the method will reset all available counters.

Response

Attributes in the result:

PropertyTypeDescription

counts

object

Information about the input counter prior to reset (shown if applicable)

PropertyTypeDescription

total

number

Last total counter value

Input.Trigger

Emit input events on demand without actual change on the physical inputs (only for type button)

Request

Parameters:

PropertyTypeDescription

id

number

Id of the Input component instance. Required

event_type

string

Event to be emitted, one of: btn_down, btn_up, single_push, double_push, triple_push and long_push Required

Response

null on success or error if any of the request parameters is missing, wrong or type is different from button

Configuration

The configuration of the Input component contains information about the type, invert, and factory reset settings of the chosen input instance. To Get/Set the configuration of the Input component its id must be specified.

Properties:

PropertyTypeDescription

id

number

Id of the Input component instance

name

string or null

Name of the input instance

type

string

Type of associated input. Range of values switch, button, analog, count (only if applicable).

enable

boolean

Global enable flag. When disabled, the input instance doesn't emit any events and reports status properties as null. Applies for all input types

invert

boolean

(only for type switch, button, analog) True if the logical state of the associated input is inverted, false otherwise. For the change to be applied, the physical switch has to be toggled once after invert is set. For type analog inverts percent range - 100% becomes 0% and 0% becomes 100%

factory_reset

boolean

(only for type switch, button) True if input-triggered factory reset option is enabled, false otherwise (shown if applicable)

report_thr

number

(only for type analog) Analog input report threshold in percent. The accepted range is device-specific, default [1.0..50.0]% unless specified otherwise

range_map

array or null

(only for type analog) Remaps 0%-100% range to values in array. The first value in the array is the min setting, and the second value is the max setting. Array elements are of type number. Float values are supported. The accepted range for values is from 0% to 100%. Default values are [0, 100]. max must be greater than min. Equality is supported.

range

number

(only for type analog) Analog input range, which is device-specific. See the table below.

xpercent

object

(only for type analog) Value transformation config for status.percent

PropertyTypeDescription

expr

string or null

JS expression containing x, where x is the raw value to be transformed (status.percent), for example "x+1". Accepted range: null or [0..100] chars. Both null and "" mean value transformation is disabled.

unit

string or null

Unit of the transformed value (status.xpercent), for example, "m/s". Accepted range: null or [0..20] chars. Both null and "" mean value transformation is disabled.

count_rep_thr

number

(only for type count) Counts report threshold in number of pulses. Accepted range [1 - 2147483647]

freq_window

number

(only for type count) Reference time in seconds for base of frequency measurement. Accepted range [1 - 3600]

freq_rep_thr

number

(only for type count) Frequency report threshold in percent. Accepted range [0 - 10000]

xcounts

object

(only for type count) Value transformation config for status.counts.total and status.counts.by_minute

PropertyTypeDescription

expr

string or null

JS expression containing x, where x is the raw value to be transformed (status.counts.total and status.counts.by_minute), for example "x+1". Accepted range: null or [0..100] chars. Both null and "" mean value transformation is disabled.

unit

string or null

Unit of the transformed values (status.counts.xtotal and status.counts.xby_minute), for example, "m/s". Accepted range: null or [0..20] chars. Both null and "" mean value transformation is disabled.

xfreq

object

(only for type count) Value transformation config for status.freq

PropertyTypeDescription

expr

string or null

JS expression containing x, where x is the raw value to be transformed (status.freq), for example "x+1". Accepted range: null or [0..100] chars. Both null and "" mean value transformation is disabled.

unit

string or null

Unit of the transformed value (status.xfreq), for example, "m/s". Accepted range: null or [0..20] chars. Both null and "" mean value transformation is disabled.

Valid range values depend on the device.

range01
PlusUni0-15VDC (default)0-30VDC

Status

The status of the Input component contains information about the state of the chosen input instance. To obtain the status of the Input component its id must be specified.

PropertyTypeDescription

id

number

Id of the Input component instance

state

boolean or null

(only for type switch, button) State of the input (null if the input instance is stateless, i.e. for type button)

percent

number or null

(only for type analog) Analog value in percent (null if the valid value could not be obtained)

xpercent

number or null

(only for type analog) percent transformed with config.xpercent.expr. Present only when both config.xpercent.expr and config.xpercent.unit are set to non-empty values. null if config.xpercent.expr can not be evaluated.

counts

object

(only for type count) Information about the counted pulses.

PropertyTypeDescription

total

number

Total pulses counted.

xtotal

number or null

total transformed with config.xcounts.expr. Present only when both config.xcounts.expr and config.xcounts.unit are set to non-empty values. null if config.xcounts.expr can not be evaluated.

by_minute

array of type number

Pulse counts for the last three complete minutes. The 0-th element indicates the counts accumulated during the minute preceding minute_ts. Present only if the device clock is synced.

xby_minute

number or null

by_minute values transformed with config.xcounts.expr. Present only when both config.xcounts.expr and config.xcounts.unit is set to non-empty values and the device clock is synced. null if config.xcounts.expr can not be evaluated.

minute_ts

number

Unix timestamp marking the start of the current minute (in UTC).

freq

number

(only for type count) Measured frequency in Hz. Determined at every elapsed freq_window period.

xfreq

number or null

(only for type count) freq transformed with config.xfreq.expr. Present only when both config.xfreq.expr and config.xfreq.unit are set to non-empty values. null if config.xfreq.expr can not be evaluated.

errors

array of type string

Shown only if at least one error is present. May contain out_of_range, read

Webhook Events

Currently, depending on the type of Input component different events that can trigger webhooks are available:

  • for Input instances of type switch:
    • input.toggle_on - produced when the input instance is toggled from off to on state
    • input.toggle_off - produced when the input instance is toggled from on to off state
  • for Input instances of type button:
    • input.button_push - produced when the button is pushed once
    • input.button_longpush - produced when the button is pushed once for a longer time
    • input.button_doublepush - produced when the button is pushed two consecutive times
    • input.button_triplepush - produced when the button is pushed three consecutive times
  • for Input instances of type analog:
    • input.analog_change - produced when the analog value percent delta between two measurements is greater than report_thr
    • input.analog_measurement - produced on a monotonic measurement period (60s)

input.analog_change and input.analog_measurement support two attributes, that can be used to compose conditional webhooks:

PropertyTypeDescription

percent

number

New analog value in percent

xpercent

number or null

percent transformed with config.xprecent.expr

  • for Input instances of type count:
    • input.count_change - produced when delta vs last status change is greater than count_rep_thr
    • input.count_measurement - produced on a monotonic measurement period (60s)
    • input.freq_change - produced when the frequency delta between two measurements is greater than freq_rep_thr
    • input.freq_measurement - produced on a monotonic measurement period (60s)

input.count_change and input.count_measurement support two attributes, that can be used to compose conditional webhooks:

PropertyTypeDescription

total

number

Total pulses counted.

xtotal

number or null

total transformed with config.xcounts.expr

input.freq_change and input.freq_measurement support two attributes, that can be used to compose conditional webhooks:

PropertyTypeDescription

freq

number

Measured frequency in Hz.

xfreq

number or null

freq transformed with config.xfreq.expr

Notifications

This section describes notifications for events specific to the Input component. For general information please see this page.

Instances of the Input component can send notifications for the following events:

  • btn_down
  • btn_up
  • single_push
  • double_push
  • triple_push
  • long_push

Rate Limit for Notifications

In certain cases, the Input component generates an excessive amount of event or status change notifications which may cause degraded performance or even outages in certain scenarios. To mitigate this, a rate-limiting algorithm (sliding time window) is applied to the generated notifications. If the limit is reached event notifications will be dropped, while status changes will accumulate until the rate limit is no longer enforced. At the end of the time period, an event notification is sent with the counts of missed events and status change notifications, as well as a status change notification if changes were accumulated during the time the rate limiter was active. The limit applied is 80 notifications for a period of 60 seconds.

Examples

Input.GetConfig example

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

Response

{
"id": 0,
"name": "name",
"type": "switch",
"enable": true,
"invert": false
}

Input.SetConfig example

http://192.168.33.1/rpc/Input.SetConfig?id=0&config={"name":"Input0"}

Response

{
"restart_required": false
}

Input.GetStatus example

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

Response

{
"id": 0,
"state": false
}

Input.CheckExpression example

http://192.168.33.1/rpc/Input.CheckExpression?expr="(x/3)+4"&inputs=[1,2,3]

Response

{
"results": [
[
1,
4.333333
],
[
2,
4.666667
],
[
3,
5
]
]
}

Input.ResetCounters example

http://192.168.33.1/rpc/Input.ResetCounters?id=0&type=["counts"]

Response

{
"counts": {
"total": 177
}
}

Input.Trigger example

http://192.168.33.1/rpc/Input.Trigger?id=0&event_type="single_push"

Response

null

Notifications example

  • Button press (only when Input type = button):

Example 1:

Notify that a button press event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266595.43,
"events": [
{
"component": "input:0",
"id": 0,
"event": "btn_down",
"ts": 1631266595.43
}
]
}
}
  • Button release (only when Input type = button):

Example 2:

Notify that a button release event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266564.64,
"events": [
{
"component": "input:0",
"id": 0,
"event": "btn_up",
"ts": 1631266564.64
}
]
}
}
  • Single button push (only when Input type = button):

Example 3:

Notify that a button single push event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266595.44,
"events": [
{
"component": "input:0",
"id": 0,
"event": "single_push",
"ts": 1631266595.44
}
]
}
}
  • Double button push (only when Input type = button):

Example 4:

Notify that a button double push event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266647.44,
"events": [
{
"component": "input:0",
"id": 0,
"event": "double_push",
"ts": 1631266647.44
}
]
}
}
  • Triple button push (only when Input type = button):

Example 5:

Notify that a button triple push event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266647.44,
"events": [
{
"component": "input:0",
"id": 0,
"event": "triple_push",
"ts": 1631266647.44
}
]
}
}
  • Long button push (only when Input type = button):

Example 6:

Notify that a button long push event has occurred.
{
"src": "shellypro4pm-f008d1d8b8b8",
"dst": "user_1",
"method": "NotifyEvent",
"params": {
"ts": 1631266629.79,
"events": [
{
"component": "input:0",
"id": 0,
"event": "long_push",
"ts": 1631266629.79
}
]
}
}