Actions

Actions are operations MudPi can make typically in response to a trigger. Most components in MudPi provide some actions to interact with them for you. For example a toggle provides a turn_on action to turn it on. Depending on the component it will offer different actions out of the box.

There are three categories of actions within MudPi: namespace, component and custom. Namespace actions are registered under a namespace and can interact with all components registered under it. Component actions typically correspond to a specific component or system. Custom actions are created by the user and you learn more under the action extension docs.

Calling Actions

Actions can be called in a few ways. The first is through a trigger by putting the action command string you want to call in the trigger actions configuration.

Depending on what type of action you want to trigger there are a few available command string formats.

Namespace Actions

To call an action on all component in a namepsace you can call namespace actions. The format for a namespace action command string is {namespace}.{action}. For example calling toggle.turn_off would turn off all the toggles loaded. If you want to call only a specific list of components under a namespace you can pass in a components list in the action data.

Component Actions

Another way to interact with a single comonent is a component action. The format for a component action command string is .{component_key}.{action}. Note the leading period.

Interface Actions

Some interfaces also provide actions on an interface level. For example the timer extension provides some additional actions only available to timer sensors. The format to call actions for all components from an interface is {namespace}.{interface}.{action}. So in the example of the timer sensor it would be sensor.timer.start.

Custom Actions

If you use the custom actions extension you can call them with a action command string format of .{action_key}. Note the leading period.

Below is an example of a trigger set to call the turn_on action for a toggle named example_toggle_1 using a component action format.

"trigger": {
    "key": "example_trigger",
    "interface": "cron",
    "action": ".example_toggle_1.turn_on",
    "schedule": "*/2 * * * *"
},
"toggle": {
    "key": "example_toggle_1",
    "interface": "example"
}

Call Actions from the Core

The mudpi core instance has an attibute actions that is a registry of all the actions for the system. To call an action directly from the core instance you can use the call() method.

mudpi.actions.call('.example_toggle_1.turn_on', action_data=None)

Call Actions via Events

The other method of triggering an action is by publishing an event on the topic action_call with your action call in the event data. Using the events attribute on the mudpi core instance we can emit such an event.

mudpi.events.publish('action_call', {
    "action": ".example_toggle_1.turn_on",
    "data": None
})

If you want to test actions you could also use the redis-cli to publish some events manually.

PUBLISH action_call '{"action": ".example_toggle_1.turn_on"}'

Custom Actions

MudPi also provides an action extension for you to make custom actions. These are useful if you want to add additional behavior not supported by the default provided actions.