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.

ActionRequired methods
onoffget, on, off
percentageget, poll
optionget, set, options
actiondo
sliderget, set, min, max
textfieldget, poll

🚧

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.
800

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:

[onoff:Off/On]
on:~dataplicity/actions/on-off/on.sh
off:~dataplicity/actions/on-off/off.sh
get:~dataplicity/actions/on-off/get.sh


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.
792

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:

[percentage:Progress Bar]
get:~dataplicity/actions/diskPercent/get.sh
poll:2.5


option

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

  • Fan speed control, Dimmer switch.
800

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:

[option:Multiple Choice]
options:option 1, Option 2, Option 3, Option 4
get:~dataplicity/actions/fan/get.sh
set:~dataplicity/actions/fan/set.sh


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'.
479

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:

[action:Action Click]
do:~dataplicity/actions/sayHello/do.sh


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.
793

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:

[slider:Slider]
min:-15
max:15
set:~dataplicity/actions/air/set.sh
get:~dataplicity/actions/air/get.sh


textfield

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

  • Status of a system service.
796

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:

[textfield:Text Field]
poll:4
get:~dataplicity/actions/hddtemp/get.sh