Control device_trigger

device_trigger control

Control catalogue · Documentation home

Minimal field JSON:

{
  "id": "device_trigger",
  "type": "device_trigger",
  "name": "Device trigger"
}

Full field JSON:

{
  "id": "device_trigger",
  "type": "device_trigger",
  "name": "Device trigger",
  "default": "PRESS",
  "readonly": true,
  "controls": [],
  "ha": {
    "automation_type": "trigger",
    "topic": "$state",
    "type": "button_short_press",
    "subtype": "button_1",
    "payload": "PRESS"
  }
}

Properties in the full example:

Property	Required?	Meaning / default
id	Required	Stable application key; unique across registered pages.
type	Required	Enabled field type.
name	Required title¹	Display title; may be replaced by a nonempty names object.
default	Optional	Omit to use the built-in initial value.
readonly	Optional	Omit to use the preset editability policy.
controls	Optional	Omit to use the preset controls; supplying an array replaces them.
ha	Optional	Omit to use automatic HA discovery; supplied properties override defaults.

¹ name can be replaced by names. Other shared optional properties are listed in the catalogue.

Default / example: "PRESS"

Creates HA MQTT device_automation discovery with automation_type: "trigger", preset type button_short_press, subtype button_1 and payload PRESS. Override these in ha to describe your trigger; emit the configured payload string.

Integration with Home Assistant

MQTT component: device_automation. Requires the control’s feature flag, dynamic pages, MQTT and HA support to be enabled. ArdPortal registers MQTT Discovery and routes state/commands; the sketch implements device behavior. Action callbacks acknowledge acceptance, not physical completion.

Supported by ArdPortal: An MQTT device automation trigger (rather than a normal dashboard entity). The default trigger is button_short_press, subtype button_1, with payload PRESS; events are emitted through emitAppConfigEvent().

Not provided by the built-in integration / limits: No built-in HA automation actions/conditions, editable value or gesture detector. Changing ha.type, ha.subtype or ha.payload only describes the trigger; the application still sends the matching event.

Explicit ha properties can override Discovery metadata. They do not create additional hardware behavior, application value properties or command handlers by themselves. See HA integration for the shared setup.

Integration with Zigbee

Status: not mapped by ArdPortal. HA device-automation triggers are MQTT-specific here; this field does not emit Zigbee events. Enabling Zigbee does not create an endpoint for this field. The field remains usable in the portal and through MQTT/HA when those features are enabled.

This describes the current ArdPortal implementation, not a claim that Zigbee cannot represent a similar device through a standard cluster or a gateway-specific converter.

Possible extension, not implemented: On/Off or Scenes client commands. The device can emit standard commands; a gateway converter can expose them as automation triggers. HA MQTT device-automation type/subtype metadata cannot be sent unchanged as a standard Zigbee trigger definition, and all arbitrary triggers do not have native equivalents. See the mapping feasibility table.

See Zigbee integration for pairing, endpoint lifecycle, gateway limitations and OTA requirements.

Read and update values from C++

These examples use the field ID from the JSON above and an existing ArdPortal portal. Run them after page registration has finished and portal.portalAndAppConfigReady() is true. Call portal.loop() frequently. Register callbacks once in setup(); do not repeat setters on every loop iteration.

This field represents a transient action/event, not a durable setting. Do not persist its command and automatically replay it after restart. The state setters are not a substitute for action execution or event publication.

Publish an occurrence and read the current local value

ArdJSON::JSONVar occurrence = "PRESS";
if (!occurrence.isValid() || !portal.emitAppConfigEvent("device_trigger", occurrence)) {
  Serial.println("Event rejected: MQTT disconnected, queue full or invalid value");
}
const ArdJSON::JSONVar current = portal.getAppConfigValue("device_trigger");
if (current.isValid()) Serial.println(ArdJSON::JSON.stringify(current));

An accepted event updates local RAM and, with MQTT enabled, queues a nonretained message. It does not write ArdFS. With MQTT enabled, a disconnected broker or full queue returns false; the occurrence is not stored for replay. Without MQTT, supported events update local RAM only.

Automatic persistence

This control has no persistent setting value: actions and events are transient. Do not save its command as a setting or replay it after restart. Automatic ArdFS persistence applies to persistent setting controls through setAppConfigValue(), not to this action/event field. No separate storage key or manual ArdFS write is needed for using this control.

Back to control catalogue