Skip to main content

Input

The Input component handles 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 two modes:

  • Digital inputs sense a 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.

The Input component uses Input as 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

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 (only if applicable).

invert

boolean

(only for type switch, button) 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.

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. Accepted range is device-specific, default [1.0..50.0]% unless specified otherwise

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 valid value could not be obtained)

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 longer time
    • input.button_doublepush - produced when the button is pushed two consecutive times
    • input.button_triplelepush - produced when the button is pushed three consecutive times
  • for Input instances of type analog:
    • input.analog_change - produced when 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 one attribute, that can be used to compose conditional webhooks:

PropertyTypeDescription

percent

number

New analog value in percent

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

Examples

Input.GetConfig example

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

Response

{
"id": 0,
"name": "name",
"type": "switch",
"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
}

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
}
]
}
}