Skip to Content
🚀 We just launched! Please star us on Github!

Hardware Inputs & Wall Controllers

Smart Panel provides first-class support for physical hardware inputs — including wall switches, momentary push buttons, multi-button scene controllers, rotary dials, and potentiometers.

Whether you are using a dedicated wall switch module (such as a Shelly Plus i4), smart relays with switch inputs (Shelly Pro 4PM), smart dimmers (Shelly Pro Dimmer 2PM), Zigbee battery remotes, or embedded panel buttons, Smart Panel normalizes their signals into a unified event architecture.

Hardware inputs operate with sub-millisecond local latency. Push-button clicks are delivered directly through the internal event bus without waiting for database writes or cloud round-trips.


Input Types & Semantics

Smart Panel organizes hardware inputs into three standard channel categories:

1. Push Buttons (button)

Momentary push buttons, tactile switches, and scene keypads emit ephemeral event occurrences.

  • Properties:
    • event (EVENT_ONLY): Emits discrete gestures such as press, double_press, triple_press, long_press, down (press down edge), and up (release edge).
    • detected (READ_ONLY, optional): Indicates whether the button is actively held down (true/false).
  • No Stale State: Because button events are ephemeral, they do not retain a static value in storage. Reconnecting devices or restarting the backend will never replay past button clicks.

2. Binary Inputs (binary_input)

Bistable physical switches, wall rocker switches, or contact sensors represent persistent state.

  • Properties:
    • state (READ_ONLY): Reflects the current electrical contact position (true for closed/on, false for open/off).
  • Stateful Storage: Transitions are stored and queryable via the REST API and WebSocket channels.

3. Analog Inputs (analog_input)

Continuous physical controls like rotary dials, sliders, or 0–10V potentiometers.

  • Properties:
    • value (READ_ONLY): Current measurement value (floating-point number or integer).

Architectural Guarantees

Channel-Scoped Deduplication

Hardware protocols (such as Shelly Gen 2 RPC or Zigbee) may retransmit packets during network disruptions. Smart Panel applies deduplication scoped strictly by deviceId + channelId + sourceOccurrenceId.

  • Duplicate packets arriving within a sliding debounce window are automatically dropped.
  • Simultaneous presses on distinct channels with the same sequence counter are preserved independently.
  • Repeated rapid clicks without external sequence IDs are always treated as separate, valid occurrences.

Actuator and Input Isolation

On mixed devices (e.g. smart dimmers or smart relays with physical switch terminals):

  • Issuing commands to the actuator (turning on a light or adjusting brightness) never triggers spurious button events.
  • Physical input events do not directly mutate actuator state in the devices core; occurrences are delivered as events only, reserving actuator state changes and action routing for future automation capabilities.

Integration Matrix

IntegrationSupported ChannelsGestures / EventsNotes
Shelly Next-Genbutton, binary_input, analog_inputbtn_down, btn_up, single_push, double_push, triple_push, long_pushShelly Plus i4, Pro 4PM, Pro Dimmer 2PM
Shelly v1button, binary_inputS (single), SS (double), SSS (triple), L (long)Shelly 1, 2.5, Dimmer 2
Home Assistantbutton, binary_input, analog_inputpress, double_press, long_pressSynchronized via HASS entity events
Homey SHSbutton, binary_inputpress, double_press, long_pressMapped from Homey device capabilities
HomeKitbuttonsingle_press, double_press, long_pressStateless programmable switch profile
WLEDbutton, analog_inputpress, long_press, valueESP32 physical buttons and rotary dials
Zigbee2MQTTbutton, binary_input, analog_inputsingle, double, triple, hold, releasePhilips Hue Dimmer, IKEA remotes, etc.
reTerminalbuttonpress, down, upBuilt-in physical buttons F1–F4
Virtual Devicesbutton, binary_input, analog_inputPassthrough from sourceAllows mirroring or aliasing physical inputs
Third-Partybutton, binary_input, analog_inputConfigurableIngestion via HTTP REST / Webhooks

Testing & Simulation

The Simulator Plugin provides full emulation of hardware inputs for testing and automated scenarios.

You can simulate physical occurrences via the REST endpoint:

POST /api/v1/plugins/simulator/simulator/:deviceId/simulate-occurrence Content-Type: application/json Authorization: Bearer <TOKEN> { "data": { "channel_id": "<BUTTON_CHANNEL_UUID>", "event": "press" } }

Predefined simulator scenarios (such as small-apartment) include 4-button wall controllers, smart dimmers with push button inputs, and auxiliary analog controls ready for development and testing.

Last updated on