Documentation

Action Extension

The action extension enables custom actions that emit events or run commands, extending MudPi's core action system.

Overview

Actions are a core concept of MudPi. Many components and the core system provide actions to interact with them. This extension enables custom actions that may not be provided by default. Your custom action can emit an event or run a command.

Event Actions

An event action will emit an event you provide in the action configs. This is useful if you want to set up your own events to interact with or emit MudPi events to create more complex operations. For example, an event action could emit an event over MQTT to devices listening to trigger a refresh.

Command Actions

A command action will run a command string you provide in the action option. This command can be an actual command or a file to run. If you wish to run an actual command and not a file you should set shell to true. The event data that triggers the action will be passed as an argument in the form of a JSON object.

Tip

Command actions open up a wide range of user-defined actions. For example, you could fire a script that sends you an SMS message when your water tank is low.

Settings

Option	Type	Required	Description
`type`	String	Yes	Type of action. Options: `event`, `command`
`key`	String	Yes	A unique slug to identify the action. This is used in trigger configuration.
`name`	String	No	Friendly display name of the action. Useful for UI.

Event Action Settings

Event actions will emit an event that you set in the action option on the channel you set in the topic. Try emitting a "Switch" or "Toggle" event to a topic a relay is set to.

Option	Type	Required	Description
`action`	Object	Yes	Event object that will be emitted.
`topic`	String	Yes	Channel to emit the event on.

Command Action Settings

Option	Type	Required	Description
`action`	String	Yes	Command string or file path to be executed.
`shell`	Boolean	No	Setting to expand full shell to execute command. Must be `true` if command is not a file. Default: `false`

Example Configs

Event Action Config

This configuration will send a MyCustomEvent event on the topic your/custom/topic.

mudpi.config.json

{
  "action": [
    {
      "key": "custom_event_action",
      "type": "event",
      "name": "Emit Custom Event",
      "action": {"event": "MyCustomEvent", "data": "Look ma an event!"},
      "topic": "your/custom/topic"
    }
  ]
}

Command Action Config

This is an example of a command action that fires a send_sms.py script.

mudpi.config.json

{
  "action": [
    {
      "type": "command",
      "key": "send_sms_text",
      "action": "python3 send_sms.py",
      "shell": true
    }
  ]
}

Previous ← Extensions Next BME680 Extension →