Actions

There are presently six types of Action:
-onoff (a slider)
-percentage (a bar indicating a percentage, could be used to show disk space for example)
-option (a dropdown selector, could be used to pick a lighting colour from a list)
-action (a button that executes a script)
-slider (a sliding bar, could be used to control an output 'volume' for example)
-textfield (simply queries the device and displays the result in a text field)

ActionMethods

Each Action supports one or more ActionMethods such as get, set or do. To ensure full functionality for a given Action, all required ActionMethods for the Action must point to a valid ActionMethod script on the device.

Required ActionMethods

The following table enumerates the required ActionMethods for all currently supported Actions.

🚧

Use of an unsupported ActionMethod will result in an error.

ActionMethods are unique to each Action. For example onoff supports get, on, off, but does not support do.

Script return codes

Every ActionMethod script is expected to return an exit code. Any non-zero exit code would be interpreted as a failure to run the script correctly, while 0 is associated with the completion of an action.

By way of example, an ActionMethod script may return exit code 5 as follows:

exit 5

Status messages

Some Actions understand formatted strings which can provide additional context-specific information to the user.

Status messages are described in more detail below, however by way of example, onoff can accept a [[[ReturnOK]]] in response to certain commands. To offer this response from an ActionMethod shell script, use the following inside the script:
echo [[[ReturnOK]]]

These formatted strings must appear in the Standard Output of ActionMethod scripts, and are always of the format [[[Return.*]]].

onoff

This Action creates a bi-state slider which can be 'enabled' or 'disabled'. Example use cases for onoff Actions are:

• GPIOs, LEDs, Switches, Home automation, Raspberry Pi OS system services.

onoff has three methods - 'get', 'on', and 'off' - all of which require a script as a parameter.

• The script pointed to by get is run to determine the initial status of the indicator when the page is loaded. The script must return either "[[[ReturnError:<string>]]]" or "[[[ReturnOK:<1 or 0>]]]".
• The on script is called when the indicator is adjusted from the Off state to the On state, and must return "[[[ReturnOK]]]".
• The off script is called when the indicator is adjusted from the Off state to the On state, and must return "[[[ReturnOK]]]".

An example configuration file entry for an onoff Action may look like this:

percentage

This Action creates a graphical bar to represent a percentage value. Example use cases for the percentage Action are:

• Disk space monitoring, Long running file download progress, Tank water level, Tracking progress of a long running task, Show battery consumption.

percentage has two methods - 'get', and 'poll':

• get takes a script as a parameter. The script pointed to by get is run to determine the initial status of the indicator when the page is loaded. The script must return either "[[[ReturnError:<string>]]]" or "[[[ReturnOK:<1 or 0>]]]".
• poll takes an integer value between, which represents the number of seconds between refreshes.

An example configuration file entry for an percentage Action may look like this:

option

This Action creates a multiple choice menu. Example use cases for the option Action are:

• Fan speed control, Dimmer switch.

option has three methods - get, set and options:

• get takes a script as a parameter. The script pointed to by get is run to determine the initial status of the indicator when the page is loaded. The script must return either "[[[ReturnError:<string>]]]" or "[[[ReturnOK:<1 or 0>]]]".
• set takes a script as a parameter. The script executes a user defined action.
• options takes a multiple amount of comma separated strings. They all represent choices for an argument that is passed to set script. The argument will influence the set script by providing things such as the amount of speed or dim for previously mentioned use cases.

An example configuration file entry for an option Action may look like this:

action

This Action executes a script that does not fit under a more specific Action. Example use cases for the action Action are:

• Running scripts (including longer running scripts), Arbitrary actions that should be triggered by means of a 'button press'.

action has just one method - do:

• do takes a script as a parameter. The script pointed to by do is run after the user clicks on the Action. The script must return either "[[[ReturnError]]]" or "[[[ReturnOK]]]".

An example configuration file entry for an action Action may look like this:

slider

This Action lets the user slide to a specific value and then sets that value. Example use cases for the slider Action are:

• Motor speed.

slider has four methods - get, set, min and max:

• get takes a script as a parameter. The script pointed to by get is run to determine the initial status of the indicator when the page is loaded. The script must return either "[[[ReturnError:<string>]]]" or "[[[ReturnOK:<1 or 0>]]]".
• set takes a script as a parameter. The script executes a user defined action.
• min sets the lowest possible value that will be used as argument that is passed to set script.
• max sets the highest possible value that will be used as argument that is passed to set script.

An example configuration file entry for a slider Action may look like this:

textfield

This Action lets the user display a specific text. Example use cases for the textfield Action are:

• Status of a system service.

textfield has two methods - get, and poll:

• get takes a script as a parameter. The script pointed to by get is run to determine the initial text when the page is loaded. The script must return either "[[[ReturnError:<string>]]]" or "[[[ReturnOK:<1 or 0>]]]".
• poll takes an integer value between which represents the number of seconds between refreshes.

An example configuration file entry for a textfield Action may look like this: