Use-case: Data-enabled design II (informed step)

Continuation of the first part of the Data-enabled Design use-case. We process incoming data with a script, and conditionally trigger an intervention and log data about this intervention.

CONTEXT

Data Enabled Design focuses on the use of data as a creative material in the design process. In this use-case we continue from the previous Data-enabled Design use-case. Next to logging and annotating data as seen before, you can use the power of scripting to process contextual data and trigger all kinds of actions. In this example, we want to compare incoming data from the context to historical contextual data and trigger an action via an OOCSI channel (in a certain condition). Also, we use the Telegram integration to alert the participant to provide a quick diary entry in another condition, and to notify the researcher once the diary has been filled.

EXAMPLE

An example of this is a contextual deployment where two devices measure climate values (temperature and humidity). We store both values from the devices in an IoT dataset (with the two device IDs) and use scripting to compare the incoming value of one device to the last historical value of the other device. If the values for either humidity or temperature differ by five unit points (e.g., degrees for temperature), then we notify the participant via Telegram about the climate difference and ask them to fill a short diary entry. We use another script to notify the research once the diary entry has been submitted.

WHAT YOU NEED

  • All the requirements from the previous use-case including the diary dataset
  • Changes to the probes, so they can remotely act or change their behavior
  • An additional script (dataset)
  • Telegram app installed on your and your participants phones

HOW TO USE THIS

Complete basic setup

Follow the links in the bullet list to complete the basic setup

  • Use the basic setup that is required for the first part
  • Add a new script to the project
  • Install a Telegram client on your computer or smart phone, and on your participants' phones
    • Make sure you and your participants have the Telegram app installed. In the Telegram app, search for ‘DataFoundryBot’ and start a conversation with the bot. In the conversation, select that you are a researcher. The Telegram Bot will ask you for your email address and to enter your PIN from your Data Foundry profile page.
    • To select the project, type /projects in the Telegram conversation with the Data Foundty bot. You will get an overview of all the projects you have created in Telegram so far. Then you can select the project by its number. For example, you can type /project 2 to get your second project in the list. From this point onwards, you can receive messages from the script (see below): when the participant has filled in the diary, the researcher will be notified through Telegram.

Trigger interventions through scripting via Telegram

An intervention can also be triggered through a code that is integrated in Data Foundry. Through scripting, you can send messages to OOCSI directly, to feed data into other datasets or to control devices and actuation. Using a script to send messages is a great way to alert researchers about new data entries or interesting data that differs from previously seen data. On the scripting documentation page, you can find a detailed explanation of scripting and how to use it. For this use case specifically, we use scripting in two ways: to trigger an intervention for a participant and to notify the researcher about a newly filled form.

What is the intervention? Once the participant's device sends a new temperature value over an OOCSI channel, we check the value and compare it to the previous values. If the value differs by 2 units from the mean of the previous value, we will send a message to the participant to fill a form with some information about new things going on in the context. In the other case, we will remind the participant to fill the diary for today.

To create a new script do the following:

  • On your Data Foundry homepage, select add ‘script’
  • Choose your project and provide the name of the script
  • Enter script code on into the text area
// retrieve id of first participant in project
var pid = participants[0].id;

// retrieve device id for participant
// short cut: just first device
var did = devices[0].id;

// retrieve device data (10 last items)
var data = DF.eventData.get(did, 10);

// calculate mean from all retrieved data items
var mean = ...;

// check whether something new is happening
// short cut: new data is outside +/- 2 mean of last 10 items
if(data.temperature < mean - 2 || data.temperature > mean + 2) {
	// send a Telegram message to this participant and turn the word 'diary' into a clickable link
	// note: you might want to check the time here and only send a reminder once per hour or less, don't spam your participants ;-)
	DF.telegramParticipant(pid, "Hey, you used your thermostat in a new way today, can you quickly write a short \diary entry about today? Thank you.");
	DF.print("Participant message about diary");
} 
// OOCSI intervention for smaller deviations of +/- 0.5 - 2 from the mean
else if(data.temperature < mean - 0.5 || data.temperature > mean + 0.5){
	// send am OOCSI message to the channel for a particular intervention (see intervention type and parameters)
	DF.oocsi("interventionChannel", {"device_id": did, "intervention_type": 1, "intervention_parameter1": true, "intervention_parameter2": 4.9});
	DF.print("Intervention via OOCSI channel");
}

Before installing this script, you can test it on the script page (bottom left). Just enter a piece of data that would come from the participant's device and click Test with data. After a short moment, you should see a first result (or an error message). You might want to disable the messaging to the participants and instead send a message to yourself. with DF.telegramResearchers(...).

After the script runs fine, you can install it on the OOCSI channel that receives data messages from the participants' devices. Once one of these devices sends an event with a temperature measurement, you will see that the script runs and produces an output. That's why we added the DF.print statements in the code above.

Remotely trigger messages upon diary entry submission

As a researcher, you might want to know about a participant filling in a diary entry via Telegram. Let's see how you can get a Telegram notification whenever a diary entry is filled. First, you need to activate the OOCSI output stream on the diary dataset configuration (last tab). Here you enter a channel name that will receive a message once the diary dataset is updated.

Now you create another script and enter the following code:

// find participant number from diary update data
// the diary update data will contain the participant id (amongst other items)
var pid = data.participant_id;

// find matching participant
var participant = participants.filter(function(d) { return d.id == pid; })[0];

// send a Telegram message to all researchers in the project
DF.telegramResearchers('Hey, a new diary entry has been submitted by participant ' + participant.name);

After testing the code in this script, you can install it on the channel that you used in the configuration of the OOCSI output streams for the diary dataset. Once a new diary entry is submitted from a participant, you will receive a notification in Telegram.

There is a lot more that you can do with scripting in Data Foundry. Check out the documentation.