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:
Input.GetConfig
to obtain the component's configurationInput.SetConfig
to update the component's configurationInput.GetStatus
to obtain the component's statusInput.ResetCounters
to reset component's energy counters (if applicable)Input.Trigger
to emit input events on demand without actual change on the physical inputs (only for typebutton
) Only available for PlusI4 and PlusI4 DC, I4 Gen3 and I4 DC Gen3
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
Property | Type | Description |
---|---|---|
| number | Id of the Input component instance |
| object | Configuration that the method takes |
Find more about the config properties in config section
Input.GetConfig
Properties:
Property | Type | Description |
---|---|---|
| number | Id of the Input component instance |
Find the Input.GetConfig response properties in config section
Input.GetStatus
Properties:
Property | Type | Description |
---|---|---|
| number | Id of the Input component instance |
Find more about the status response properties in status section
Input.CheckExpression
Request
Property | Type | Description |
---|---|---|
| string | JS expression to evaluate |
| array | Input values on which to apply |
Response
results
or error if any of the request parameters is missing or of the wrong type
Property | Type | Description |
---|---|---|
| array | Array of 2-tuples, each containing an input and an output value: |
Input.ResetCounters
This method resets associated counters (if applicable).
Request
Parameters:
Property | Type | Description |
---|---|---|
| number | Id of the Input component instance. Required |
| array of strings | Array of strings, selects which counter to reset Optional |
If no 'type' is provided, the method will reset all available counters.
Response
Attributes in the result:
Property | Type | Description | ||||||
---|---|---|---|---|---|---|---|---|
| object | Information about the input counter prior to reset (shown if applicable)
|
Input.Trigger
Only available for PlusI4 and PlusI4 DC, I4 Gen3 and I4 DC Gen3
Emit input events on demand without actual change on the physical inputs (only for type button
)
Request
Parameters:
Property | Type | Description |
---|---|---|
| number | Id of the Input component instance. Required |
| string | Event to be emitted, one of: |
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:
Property | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
| number | Id of the Input component instance | |||||||||
| string or null | Name of the input instance | |||||||||
| string | Type of associated input. Range of values | |||||||||
| boolean | Global enable flag. When disabled, the input instance doesn't emit any events and reports status properties as | |||||||||
| boolean | (only for type | |||||||||
| boolean | (only for type | |||||||||
| number | (only for type | |||||||||
| array or null | (only for type | |||||||||
| number | (only for type | |||||||||
| object | (only for type
| |||||||||
| number | (only for type | |||||||||
| number | (only for type | |||||||||
| number | (only for type | |||||||||
| object | (only for type
| |||||||||
| object | (only for type
|
Valid range
values depend on the device.
range | 0 | 1 |
---|---|---|
PlusUni | 0-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.
Property | Type | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| number | Id of the Input component instance | ||||||||||||||||||
| boolean or null | (only for type | ||||||||||||||||||
| number or null | (only for type | ||||||||||||||||||
| number or null | (only for type | ||||||||||||||||||
| object | (only for type
| ||||||||||||||||||
| number | (only for type | ||||||||||||||||||
| number or null | (only for type | ||||||||||||||||||
| array of type string | Shown only if at least one error is present. May contain |
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 fromoff
toon
stateinput.toggle_off
- produced when the input instance is toggled fromon
tooff
state
- for Input instances of type button:
input.button_push
- produced when the button is pushed onceinput.button_longpush
- produced when the button is pushed once for a longer timeinput.button_doublepush
- produced when the button is pushed two consecutive timesinput.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 thanreport_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:
Property | Type | Description |
---|---|---|
| number | New analog value in percent |
| number or null |
|
- for Input instances of type count:
input.count_change
- produced when delta vs last status change is greater thancount_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 thanfreq_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:
Property | Type | Description |
---|---|---|
| number | Total pulses counted. |
| number or null |
|
input.freq_change
and input.freq_measurement
support two attributes, that can be used to compose conditional webhooks:
Property | Type | Description |
---|---|---|
| number | Measured frequency in Hz. |
| number or null |
|
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
- Input.GetConfig HTTP GET Request
- Input.GetConfig Curl Request
- Input.GetConfig Mos Request
http://192.168.33.1/rpc/Input.GetConfig?id=0
curl -X POST -d '{"id":1,"method":"Input.GetConfig","params":{"id":0}}' http://${SHELLY}/rpc
mos --port ${PORT} call Input.GetConfig '{"id":0}'
Response
- Input.GetConfig HTTP GET Response
- Input.GetConfig Curl Response
- Input.GetConfig Mos Response
{
"id": 0,
"name": "name",
"type": "switch",
"enable": true,
"invert": false
}
{
"id": 1,
"src": "shellypro1-84cca87c1f90",
"params": {
"id": 0,
"name": "name",
"type": "switch",
"enable": true,
"invert": false
}
}
{
"id": 0,
"name": "name",
"type": "switch",
"enable": true,
"invert": false
}
Input.SetConfig example
- Input.SetConfig HTTP GET Request
- Input.SetConfig Curl Request
- Input.SetConfig Mos Request
http://192.168.33.1/rpc/Input.SetConfig?id=0&config={"name":"Input0"}
curl -X POST -d '{"id":1,"method":"Input.SetConfig","params":{"id":0,"config":{"name":"Input0"}}}' http://${SHELLY}/rpc
mos --port ${PORT} call Input.SetConfig '{"id":0,"config":{"name":"Input0"}}'
Response
- Input.SetConfig HTTP GET Response
- Input.SetConfig Curl Response
- Input.SetConfig Mos Response
{
"restart_required": false
}
{
"id": 1,
"src": "shellypro1-84cca87c1f90",
"params": {
"restart_required": false
}
}
{
"restart_required": false
}
Input.GetStatus example
- Input.GetStatus HTTP GET Request
- Input.GetStatus Curl Request
- Input.GetStatus Mos Request
http://192.168.33.1/rpc/Input.GetStatus?id=0
curl -X POST -d '{"id":1,"method":"Input.GetStatus","params":{"id":0}}' http://${SHELLY}/rpc
mos --port ${PORT} call Input.GetStatus '{"id":0}'
Response
- Input.GetStatus HTTP GET Response
- Input.GetStatus Curl Response
- Input.GetStatus Mos Response
{
"id": 0,
"state": false
}
{
"id": 1,
"src": "shellypro1-84cca87c1f90",
"params": {
"id": 0,
"state": false
}
}
{
"id": 0,
"state": false
}
Input.CheckExpression example
- Input.CheckExpression HTTP GET Request
- Input.CheckExpression Curl Request
- Input.CheckExpression Mos Request
http://192.168.33.1/rpc/Input.CheckExpression?expr="(x/3)+4"&inputs=[1,2,3]
curl -X POST -d '{"id":1,"method":"Input.CheckExpression","params":{"expr":"(x/3)+4","inputs":[1,2,3]}}' http://${SHELLY}/rpc
mos --port ${PORT} call Input.CheckExpression '{"expr":"(x/3)+4","inputs":[1,2,3]}'
Response
- Input.CheckExpression HTTP GET Response
- Input.CheckExpression Curl Response
- Input.CheckExpression Mos Response
{
"results": [
[
1,
4.333333
],
[
2,
4.666667
],
[
3,
5
]
]
}
{
"id": 1,
"src": "shellypro1-84cca87c1f90",
"params": {
"results": [
[
1,
4.333333
],
[
2,
4.666667
],
[
3,
5
]
]
}
}
{
"results": [
[
1,
4.333333
],
[
2,
4.666667
],
[
3,
5
]
]
}
Input.ResetCounters example
- Input.ResetCounters HTTP GET Request
- Input.ResetCounters Curl Request
- Input.ResetCounters Mos Request
http://192.168.33.1/rpc/Input.ResetCounters?id=0&type=["counts"]
curl -X POST -d '{"id":1,"method":"Input.ResetCounters","params":{"id":0,"type":["counts"]}}' http://${SHELLY}/rpc
mos --port ${PORT} call Input.ResetCounters '{"id":0,"type":["counts"]}'
Response
- Input.ResetCounters HTTP GET Response
- Input.ResetCounters Curl Response
- Input.ResetCounters Mos Response
{
"counts": {
"total": 177
}
}
{
"id": 1,
"src": "shellyplusuni-441793ce3f08",
"params": {
"counts": {
"total": 177
}
}
}
{
"counts": {
"total": 177
}
}
Input.Trigger example
- Input.Trigger HTTP GET Request
- Input.Trigger Curl Request
- Input.Trigger Mos Request
http://192.168.33.1/rpc/Input.Trigger?id=0&event_type="single_push"
curl -X POST -d '{"id":1,"method":"Input.Trigger","params":{"id":0,"event_type":"single_push"}}' http://${SHELLY}/rpc
mos --port ${PORT} call Input.Trigger '{"id":0,"event_type":"single_push"}'
Response
- Input.Trigger HTTP GET Response
- Input.Trigger Curl Response
- Input.Trigger Mos Response
null
{
"id": 1,
"src": "shellyi4g3-543204516120",
"params": null
}
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
}
]
}
}