Calling Functions

Introduction

The Datacake platform allows calling Particle.Function() and here we also used a principle which is already known from the world of LoRaWAN devices.

We are talking about so-called "downlinks", i.e. commands or data which are sent back to the device. Datacake has a graphical editor for such downlinks and a downlink is composed of the following parts:

• Code snippet for the preparation / encoding of the data

• Database access to read from current values

• Trigger mechanism for automated sending of Downlinks / calling Particle Function

Your first Downlink

Open Downlink Tab

In the Device View on your Particle device in Datacake, navigate to the Downlink section using the tab bar.

In this overview you can see a table with all existing downlinks.

If you have created the device via a template, such as for Particle Asset Tracker One, then it may be that downlinks are already present here.

Create a new Downlink

To add a new downlink, please click the "Add Downlink" button at the top right of the downlink listing table.

Principle

Creating a downlink requires programming a code snippet that collects the data and commands from the Datacake platform and then appropriately transfers them into a message as info to the Particle function call.

This is similar to the principle of payload decoding, except that data is not received here, but prepared accordingly.

Advantages

The advantage of downlinks is that you can write an adapter for your particle function or devices using the code snippet. This code serves as a "glue" between your device and the Datacake platform. This gives you the following options:

• Evaluations of measurement data.

• Summarize measurement and configuration data into one command.

• Evaluation if downlink should really be executed (useful for automatic triggers).

The Editor

Downlinks can be created directly in Datacake via a simply designed code editor.

Simply click on the "Add Downlink" button to create a new downlink. A modal opens with all necessary configuration options and code editor.

Testing

To make creating a downlink easier, we allow you to try out the downlink. For this purpose, there is an area at the end of the editor where you can run the code snippet once.

If the downlink is executed via the "Try Encoder" button, this is only virtual. No particle function is triggered.

Basic Example

Let's assume you are running the following piece of code on your device (taken from the Particle.io Documentation Examples):

// Code on Particle.io Device:

int brewCoffee(String command);

void setup() {
  Particle.function("brew", brewCoffee);
}

void loop() {
}

int brewCoffee(String command) {
  if(command == "coffee") {
    activateWaterHeater();
    activateWaterPump();
    return 1;
  }
  else return -1;
}

So the Datacake Downlink expects a code snippet like this:

// Datacake Downlink Encoder

function Encoder(measurements) {
    return ["functionName", "argument"];
}

For the above Device-Code Example the Code-Snippet for the Downlink to start Brew process on the Device would look like this:

// Datacake Downlink Encoder

function Encoder(measurements) {
    return ["brew", "coffee"];
}

Evaluating Measurements

In the downlink code snippet, current measured values can be brought in for evaluation.

// Datacake Downlink Encoder

function Encoder(measurements) {
    
    var shouldBrew = measurements.SHOULD_BREW.value;
    
    if (shouldBrew) {
        return ["brew", "coffee"];
    }
    
    return ["", ""]; // Return this to not call Particle Function
}

Querying User Input

If you want to prompt the user for user input before sending a downlink, you can mark the fields to be queried as "Fields Used".

If the user then triggers the downlink manually (via the downlink button in the tab or directly on the dashboard), a small modal with a form appears that prompts the user to make the appropriate entries.

Automated Triggering

If you have defined fields in your downlink that must be set before the downlink is triggered, then below these fields you have the option to define these fields as triggers.

To do this, simply activate the checkbox to enable the trigger function.

What is a Trigger?

If a trigger is activated, then a change (writing of a measured value) of a measured value at this database field will cause the downlink to be triggered automatically. Which means:

• If a new value is written to the database field that is defined in the downlink settings, then this downlink is being triggered automatically in the background.

When to use?

If you create a widget on your device dashboard that writes a value to a field, then you can use that field to trigger a downlink on it.

Switches and Slider on Dashboard

A simple example here is using a switch or slider widget to set configuration or on-off.

If the value is changed via the widget, the new value is written to the field and this triggers the downlink which calls a Particle Function on the device.

Sending a Downlink manually

There are different ways to send a downlink or to call a particle function. A direct, manual way is to simply click on the trigger button in the list of downlinks.

But also here there are two different buttons which we will now discuss in more detail.

Send Downlink

If the downlink does not require any user input (for setting special configuration values, etc.) then it is sent immediately after clicking the "Send Downlink" button.

The particle function is then called via the API according to the definition and the code snippet in the downlink.

Configure and Send Downlink

If you have defined fields as in the following screenshot, which must be set by the user before sending / calling the downlink, then the button is "Configure and Send Downlink".

When calling the downlink, you will then see a small modal asking you to enter new values for the selected fields.

After confirmation, the downlink is sent accordingly (Particle Function called) and the values entered via the modal are written to the database in advance (and used in the downlink).

Automated Triggering

If you have defined fields in your downlink that must be set before the downlink is triggered, then below these fields you have the option to define these fields as triggers.

To do this, simply activate the checkbox to enable the trigger function.

What is a Trigger?

If a trigger is activated, then a change (writing of a measured value) of a measured value at this database field will cause the downlink to be triggered automatically. Which means:

• If a new value is written to the database field that is defined in the downlink settings, then this downlink is being triggered automatically in the background.

When to use?

If you create a widget on your device dashboard that writes a value to a field, then you can use that field to trigger a downlink on it.

Switches and Slider on Dashboard

A simple example here is using a switch or slider widget to set configuration or on-off.

If the value is changed via the widget, the new value is written to the field and this triggers the downlink which calls a Particle Function on the device.

Debugging

The calling of downlinks and the associated API calls for the particle functions are logged in the debug log of the device.

API Response

If errors occur when calling the particle function, the particle API will inform us. This error description is also printed in the log.