Dataplicity Developer Hub

Dataplicity Documentation

Here you'll find announcements for new features and comprehensive guides to help you integrate Dataplicity into your Raspberry Pi projects.

Get Started    Announcements

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.

Action
Required methods

onoff

get, on, off

percentage

get, poll

option

get, set, options

action

do

slider

get, set, min, max

textfield

get, 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" (stdout, see https://en.wikipedia.org/wiki/Standard_streams) of ActionMethod scripts, and are always of the format [[[Return.*]]].

"onoff" Action

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
  • Raspbian system services
Before & After clicking Off/On button

Before & After clicking Off/On button

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" Action

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
Progress bar when set to monitor something

Progress bar when set to monitor something

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" Action

This Action creates a multiple choice menu.

Example use cases for the option Action are:

  • Fan speed control
  • Dimmer switch
Before & After clicking Multiple Choice button

Before & After clicking Multiple Choice button

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" 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'
Before clicking Action Button

Before clicking Action Button

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" Action

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
Before & After sliding a Slider.

Before & After sliding a Slider.

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" Action

This Action lets the user display a specific text.

Example use cases for the textfield Action are:

  • Status of a system service
Text field displaying a value

Text field displaying a value

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

Actions