Data Foundry Boost

Contributed by Roy van den Heuvel

This is the Data Foundry Boost (DF Boost) VS Code extension. It enables users of the Data Foundry platform to quickly build scripts that integrate project participants and devices. You can run these scripts in the Data Foundry Script Editor.

Do you want to set up an experiment with multiple users and devices via Data Foundry? Then DF Boost could be useful for you!

The general idea of DF Boost is that you create small pieces of logic (Triggers) first, and then select which Participants or Devices should make use of that piece of logic. This way, you can rapidly scale and change system behaviors over large groups of users without reprogramming your devices. Go try it out!

Installation

First, you'll need Visual Studio Code, one of the most popular programming environments in the world. It's perfect if you want to take your programming skills to the next level and grow beyond the Arduino IDE.

You can install the DF Boost via the VS Code Extension Marketplace or by searching for Data Foundry Boost and install from the Extension page.

Getting Started

To get started with DF Boost, first set up your Project on the Data Foundry website. There, you add your Resources (datasets, devices and participants) to your Project.

After setting up Data Foundry Project, open up VS Code and launch DF Boost. You'll be prompted to log in with an API key, which can be found on the Profile page on the Data Foundry website. Copy-paste it into the VS Code prompt. Now, you have connected your Data Foundry account to DF Boost, allowing you to import information such as Participants and Devices.

The DF Boost Workflow

Now you can start linking together system components through the Boost workflow:

  1. Design your Triggers, which are pieces of system behavior that trigger based on specific values and run on Data Foundry.
  2. Select your Participants and Devices. You can select which Participants and Devices should listen to your Triggers.
  3. Now your main components are selected, you can Implement your Boost script. This generates the Javascript code that will run on Data Foundry. You can edit the code with your own functions, or deploy immediately to run your experiments.

Triggers

Here you define the main conditions, called Triggers which publish data to an OOCSI channel. All subscribed devices get notified. For instance, here you specify to send out a message when the temperature sensor gets too hot. With these triggers you create system behaviors you can then connect in 'Participants' to all your users and devices.

For every input and output Trigger, a seperate OOCSI channel is created. Make sure your devices use the same OOCSI channel names!

1. Add a new Trigger
2. Name your Trigger

3. Create your *input* Trigger
   1. Name your input OOCSI channel (e.g. "temperaturechannel")
   2. Add the input variable to the OOCSI channel (e.g. "temperature")
   3. Set a condition 
   4. Set a value to trigger on and define a type (int/float/long/string)

4. Create your *output* Trigger
   1. Name your output OOCSI channel (e.g. "motorchannel")
   2. Add the output variable to the OOCSI channel (e.g. "motorpower")
   3. Set a value to the selected output variable

Note: Currently, Triggers are straightforward IF-THEN logic (e.g. turn on LED when temperate below certain value), which means that you need to create an additional Trigger if you want to turn off the LED when the temperature is above a certain value.

Now you can move to the Participants & Devices tab to continue building your script.

Participants & Devices

Here you link your Devices and Triggers to your Participants. Make sure you have added your Participants and Devices in your Data Foundry project.

1. Select the Participants that you want to include in your program.

2. Select the Triggers for the specified Participant.

You can make Trigger exceptions for Participants, allowing you to make slight adjustments for specified Participants without making a new Trigger. This is especially handy when you have lots of Participants. 

3. Add the Devices that you want to attach to this Participant and Trigger.

If you're done linking everything together, you can go to the Implement tab to generate the Boost script.

Implementing Boost Scripts

In this step, the DF Boost script for your project based on your settings is generated for you. All OOCSI channels will be automatically made and configured. A DF Boost Script is a Javascript based piece of software that can run on Data Foundry's Script Editor. It allows you to complex logic such as updating datasets, triggering OOCSI messages or filter data and it runs on Data Foundry.

This is all generated based on your settings and uploaded to Data Foundry where it'll start to run! You can also tinker around with the code of course!

The structure of a DF Boost script is below:

  1. Helper functions
   1. Retrieves a device by its numerical ID.
   2. Retrieves a list of devices from a participant.
   3. Returns a list of participants which are linked to the specific device.
   4. Guards against undefined or null values.
   5. Adds device ID's and names from a participant to the output of the OOCSI channel.
   6. Compares inputValue to conditionValue.
   7. Gets a trigger exception for a specific trigger and participant when one is present.
   8. Sends the output to the devices belonging to the participant and creates an output log.
   9. Checks for an exception and sends the exception output to the participant devices when triggered.
  1. Trigger values
const tempmotortriggerDefinition = {
  id: 176663931,
  inputChannel: {
    channelName: 'temperaturechannel',
    valueName: 'Temperature',
  },
  outputChannel: {
    channelName: 'motorchannel',
    valueName: 'motorpower',
  },
  outputValue: '0',
  condition: '<',
  conditionValue: 24,
};
  1. Trigger logic function
function tempmotortriggerCheckForTrigger() {
  const inputValue = getInputData('Temperature');
  if (inputValue !== null) {
    const hasException = checkAndProcessExceptions(tempmotortriggerDefinition);
    // if the participant has an exception for the trigger, do not do the normal trigger procedure.
    if(hasException) {
      return;
    }
    const device = DF.getDevice(data.device_id);
    if (!device) {
      return;
    }
    const deviceParticipants = getClusteredParticipantsFromDeviceId(device.id);
    deviceParticipants.forEach(function (participant) {
      if(inputValue < 24) {
        sendTriggerOutput(participant, 0, 'motorchannel', 'motorpower');
      }
    });
  }
}
tempmotortriggerCheckForTrigger();

In Data Foundry's Script Editor, you can also add print statements to check on your Triggers! For example, you can add this after the sendTriggerOutput() function:

DF.Print("tempmotor Triggered!"); 

Lastly, you can also monitor the OOCSI activity on the channels you use in the script via the OOCSI Dashboard.

Devices

Since DF Boost scripts publish and subscribe to OOCSI channels and run their logic on Data Foundry, the code on your devices (Arduino, ESP, etc.) should make use of the same channel names and variables. You can use the OOCSI examples in the available libraries to check out how to make Receiver & Sender programs.

Sending

oocsi.newMessage("temperaturechannel");
oocsi.addString("device_id", "d11674718f0884552");
oocsi.addFloat("Temperature", t);
oocsi.sendMessage();
oocsi.check();

Receiving

if(oocsi.has("motorpower")) {
      Serial.println("has motorpower value in oocsi msg");
      Serial.println("motorpower value: ");
      Serial.print(oocsi.getInt("motorpower",-200));

    if (oocsi.getInt("motorpower", 0) == 0)    {
     digitalWrite(motorpin, LOW);
     Serial.println("motor LOW");
    }
    if (oocsi.getInt("lmotorpower", 0) == 1)     {
       digitalWrite(motorpin, HIGH);
       Serial.println("motor HIGH");
    } 
}else{
    Serial.println();
    Serial.print("no connection to output channel");  
    Serial.println();
}

Changelog

This project is currently in Beta, testing functionality at Industrial Design Eindhoven.

Contributors

  • Roy van den Heuvel (Researcher ID), Contact.
  • Jort Band (Developer BMD Studio),
  • Mathias Funk (Data Foundry)