Dataplicity “Custom Actions" for controlling RPi GPIOs

This example configures Dataplicity to control GPIOs on your Raspberry Pi from the Dataplicity Mobile app. In good tradition, we wire up a few LEDs to prove the point.

Connect the LEDs to your Raspberry Pi GPIO

We start by wiring two LEDs to Raspberry Pi GPIOs, a red one on BCM GPIO #23 and a green one on BCM GPIO #24, as shown in schematic below:

Here's our own test setup:

Add dataplicity to gpio system group

Control of GPIOs is normally a privileged (ie superuser) function. In some OSes, including Raspbian, device rules allow any user in the 'gpio' system group to also control them.

As all Dataplicity Custom Actions run in the context of the dataplicity system user, you need to allow the Dataplicity Agent to control GPIOs by adding the dataplicity user to the 'gpio' system group.

If you are not already logged in as a sudo-able user, or if you are logged in via the Dataplicity Terminal, you'll need to switch to a sudo-able account first:

su pi
<your password, typically "raspberry">

We can add the 'dataplicity' user to the 'gpio' group with 'usermod':

sudo usermod -a -G gpio dataplicity

You will need to restart the Dataplicity Agent for the new permissions to take effect:

sudo supervisorctl restart all

Create directory structure and config file

Create the directory /home/dataplicity/actions/on-off/leds as follows:

mkdir -p /home/dataplicity/actions/on-off/leds

In /home/dataplicity/ create a file named dataplicity.actions.conf as follows:

[section:Control LEDs]

[onoff:Red LED]
on:/home/dataplicity/actions/on-off/leds/control-state red on
off:/home/dataplicity/actions/on-off/leds/control-state red off
get:/home/dataplicity/actions/on-off/leds/get-state red

[onoff:Green LED]
on:/home/dataplicity/actions/on-off/leds/control-state green on
off:/home/dataplicity/actions/on-off/leds/control-state green off
get:/home/dataplicity/actions/on-off/leds/get-state green

Prepare ActionMethod scripts

In /home/dataplicity/actions/on-off/leds create a file named get-state with the following content:

#!/bin/bash
#
# DESCRIPTION:
#     This is a Custom Actions program that gets the state in which the LEDs are in.
#
# PRE-REQUISITES:
#     For this script to work the "dataplicity" user has to be added
#     to "gpio" group. This can be done from sudo account such as "pi"
#     with the use of the following command:
#         "sudo usermod -a -G gpio dataplicity"
#

# Check if "dataplicity" user is in "gpio" group
grep gpio /etc/group | grep dataplicity > /dev/null

if [[ $? -eq 1 ]]; then
    echo "Can't run script, Please add \"dataplicity\" user to \"gpio\" group."
    exit 1
fi

# Enforce user to supply one argument
if [[ $# -ne 1 ]]; then
    echo "[$0] Incorrect amount of arguments, 1 required."
	echo "Argument 1 must be: \"red\" or \"green\"."
    exit 1
fi

# Check if LED_PIN argument is correct
case $1 in
    red)
        LED_PIN=23
        ;;
    green)
        LED_PIN=24
        ;;
    *)
        echo "[$0] Incorrect argument - \"red\" or \"green\" expected."
        exit 1
        ;;
esac

# Check if LED GPIO pin was previously initialized
ls /sys/class/gpio/ | grep gpio$LED_PIN > /dev/null

# If not initialized return error, else return current state
if [[ $? -eq 1 ]]; then
    echo "[[[ReturnError:LED Not Initialized]]]"
else
    echo "[[[ReturnOK:$(cat /sys/class/gpio/gpio$LED_PIN/value)]]]"
fi

In /home/dataplicity/actions/on-off/leds place the file below named control-state.

#!/bin/bash
#
# DESCRIPTION:
#     This is a Custom Actions program that controls LEDs.
#
# PRE-REQUISITES:
#     For this script to work the "dataplicity" user has to be added
#     to "gpio" group. This can be done from sudo account such as "pi"
#     with the use of the following command:
#         "sudo usermod -a -G gpio dataplicity"
#


# Check if "dataplicity" user is in "gpio" group
grep gpio /etc/group | grep dataplicity > /dev/null

if [[ $? -eq 1 ]]; then
    echo "Can't run script, Please add \"dataplicity\" user to \"gpio\" group."
    exit 1
fi


# Enforce user to supply two arguments
if [[ $# -ne 2 ]]; then
    echo "[$0] Incorrect amount of arguments, 2 required."
	echo "Argument 1 must be: \"red\" or \"green\"."
	echo "Argument 2 must be: \"on\" or \"off\"."
    exit 1
fi


# Check if LED_PIN argument is correct
case $1 in
    red)
        LED_PIN=23
        ;;
    green)
        LED_PIN=24
        ;;
    *)
        echo "[$0] Incorrect argument ($1) - \"red\" or \"green\" expected."
        exit 1
        ;;
esac


# Check if CONTROL argument is correct
case $2 in
    on)
        CONTROL=1
        ;;
    off)
        CONTROL=0
        ;;
    *)
        echo "[$0] Incorrect argument ($2) - \"on\" or \"off\" expected."
        exit 1
        ;;
esac


# Check if LED GPIO pin was previously initialized
ls /sys/class/gpio/ | grep gpio$LED_PIN > /dev/null

# Initialize, if not previously initialized
if [[ $? -eq 1 ]]; then
    echo "$LED_PIN" > /sys/class/gpio/export
    sleep 0.5
fi


# Switch LED ON or OFF
echo "out" > /sys/class/gpio/gpio$LED_PIN/direction
echo "$CONTROL" > /sys/class/gpio/gpio$LED_PIN/value


# Custom Action executed succesfully
echo "[[[ReturnOK]]]"

Set the file permissions on the ActionMethod scripts to be executable:

chmod 755 /home/dataplicity/actions/on-off/leds/*

Control the LEDs from your mobile

When everything is in place, open your device in the Dataplicity Mobile App and select "Custom Actions" from the drop down menu. From there, the new interface you have designed should appear, and should allow you to control the GPIOs you have wired up.

Happy hacking!