Actions

Actions are a core concepts of MudPi. Many components and 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

A event action will simply emit an event you provide in the action configs. This is useful if you want to setup your own events to interact with or possibly want to emit MudPi events to create more complex operations. An example of a event action that may be useful could be an event gets emitted over MQTT to devices listening to trigger a refresh. While you could possibly get the same effect by including the devices into MudPi and having MudPi refresh them it could be far simpler to just emit an event to an already operational device. Without custom actions it would not be possible to make this behavior easily.

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.

Command actions leaves the opportunity for a wide range of user define actions. This feature is a great way to add custom actions to MudPi allowing you build quite a robust setup. For example you could fire a script that sends you a 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 Specific Settings

Event actions will emit an event that you set in the action option and 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 Specific 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

Here are some sample configurations for the custom actions.

Event Action Config

This configuration will send a MyCustomEvent event on the topic your/custom/topic which would ideally do something else you want to hook this event into.

{
"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.

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