Particle allows devices to expose custom functions through their Cloud so they can be triggered with an API call. With Particle.function, code on the device can be run when requested from the cloud API. You typically do this when you want to control something on your device, say a LCD display or a buzzer, or control features in your firmware from the cloud.
Now, together with Ubidots’ Events engine and Particle functions, it is possible to run code on demand based on complex variable’s conditions or in a time weekly basis, in your Devices
In this article, you will learn to trigger Particle functions registered by your devices in Particle Cloud from Ubidots’ Events engine.
NOTE: If you are not yet familiar Particle functions, we recommend referring to their Docs here before reading this article.
Requirements
Ubidots account, paid or trial.
Particle account and registered Device.
Table of Contents
Create a Particle Token
Flash code to Particle Device
Create an Event “If Triggers”
Set up Particle functions “Then Action”
Results
1. Create a Particle Token
In order to use Particle Action from Ubidots’ Events engine, it is necessary to first generate a Particle token that allows interacting with their API. This is only possible using Particle’s CLI.
NOTE: If you haven’t installed it yet, follow the steps here according to your OS.
Step 1: Open a terminal and run the command particle login
Step 2: Enter your Particle account email address and password
Step 3: Run the command particle token create --never-expires. You’ll need to enter the email address and password again.
Step 4: Copy and Save this token. You’ll need it later.
2. Flash code to Particle device
Let’s flash dummy code to your Particle device to test the Particle function action later on.
Step 1: Go to Particle’s web IDE.
Step 2: Create a new App and name it at will.
Step 3: Copy and Paste the below code.
int switchBuiltinLed(String command);
int led = D7; // Built-in LED
/****************************************
* Auxiliar Functions
****************************************/
int switchBuiltinLed(String command) {
// look for the matching argument "ON"
if (command == "ON") {
digitalWrite(led, HIGH);
return 1;
}
// look for the matching argument "OFF"
else if (command == "OFF") {
digitalWrite(led, LOW);
return 1;
}
return -1;
}
/****************************************
* Main Functions
****************************************/
void setup() {
Particle.function("Switch", switchBuiltinLed);
pinMode(led, OUTPUT);
}
void loop() {
}
NOTE: A function callback process needs to return as quickly as possible otherwise the cloud call will timeout.
Step 4: Flash the code.
NOTE: Up to 15 cloud functions may be registered and each function name is limited to a maximum of 12 characters (prior to Particle’s firmware v0.8.0) or 64 characters (since Particle’s firmware v0.8.0).
3. Create an Event “If Triggers”
Follow the below steps to set up an event “If Triggers” sections:
Step 1: Head to the Events window and Click the “+” button.
Step 2: Configure the Event logic using Ubidots’ “ANDs” / “ORs” operators.
NOTE: For additional details on how to configure conditional and complex Event triggers, check out our Creating Conditional Events and Alerts user guide.
For next sections, we will use the “If Triggers” as depicted in the image below:
4. Set up Particle functions “Then Action”
In the next section, “Then Action”, follow the below steps to configure a Particle Function action:
Step 1: Select the Particle Function option
Step 2: Fill the fields related to particle:
– Access Token: The token created in section 1.
– Particle Device ID: The particle Device ID that will be triggered. Normally, it’s best to enter the “Device label” bookmark
– Particle Function Key: The Particle funcKey in the code. In the example herein we used “Switch”
Step 3: Fill the fields related to the messages. Particle expects a message formatted as args={string_data}, however, Ubidots events engine takes care of adding the prefix args= so you only need to input the {string_data} portion.
– Active trigger: message to send. In the case herein {string_data} will be “ON”.
– Back to normal: message to send when condition isn’t true anymore. Here we used “OFF”.
NOTES:
– A cloud function is set up to take one argument of the String datatype. This argument length is limited to a max of 63 characters (prior to Particle’s firmware v0.8.0) or 622 characters (since Particle’s firmware v0.8.0). The String is UTF-8 encoded.
– Only use letters, numbers, underscores and dashes in function names. Spaces and special characters may be escaped by different tools and libraries causing unexpected results.
Step 4: Enable, or leave disable, the Repeat events. More info here.
Step 5: Continue to the end, Name the event and Set the active days and hours. Save it.
5. Results
Now with both the Particle device running the firmware in section 2 and the Event already created with the Particle function action, it’s time to test it. To this, we’re using a Switch widget to trigger the event and hence turn ON and OFF the Particle built-in LED:
The Particle Device will turn its built-in LED On and OFF accordingly:
