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, like an LCD display or a buzzer, or control features in your firmware from the cloud.
Together with Ubidots' Events engine and Particle functions, it's 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 how to trigger Particle functions registered by your devices in Particle's cloud using Ubidots' Events.
NOTE: If you are not yet familiar Particle functions, we recommend referring to their docs here before reading this article.
Even though the native "Particle functions" action is no longer available in Ubidots' Events module, the same results can be achieved using the "Trigger webhook" action, as is explained in this article. |
Requirements
Ubidots account, paid or trial.
Particle account and registered device.
1. Create a Particle token
In order to trigger Particle functions from Ubidots' Events engine, it's first necessary to 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 found 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 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 code below.
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
Follow the steps below to set up an event:
Step 1: Head to "Data" → "Events" and click on the “+” button.
Step 2: Configure the Event's logic by using AND (“+ add trigger”)/OR (“+ add OR group”) operators.
Step 3: Once the Event's logic is defined, click on "next" and move to the following section of this guide.
We'll base the example of this guide on the logic depicted in the image below:
NOTE: For additional details on how to configure conditional and complex Event triggers, check out our Creating Conditional Events and Alerts user guide.
4. Set up the Event's action
Once in the "actions" tab of the Event configuration, follow the steps below to configure the action to send data to your Particle device:
In order to interact with our Particle device, we'll use the "Trigger webhook" action.
Step 1: Click on "+ add action".
Step 2: Select the "Trigger webhook" option.
Step 3: Fill all the action's fields like this:
HTTP method: Post.
URL:
https://api.particle.io/v1/devices/:deviceId/:functionName. Make sure to replace ":deviceId" with your Ubidots device's ID (this can easily be done using the "bookmark" shown in the image below) and to also replace ":functionName" with your Particle function's name (in our example it's "Switch").
Headers: Leave the default header unchanged and add another one by clicking on the "+ add header" button. Make the following changes to that header:
First text field: Delete the default text and, instead, type
AuthorizationSecond text field: Delete the default text and, instead, type "Bearer " followed by your Particle's token (the one you generated in the first section of this guide).
It should look like "Bearer <YOUR_TOKEN>".
Payload: Delete the default content and, instead, enter a JSON object with the key "arg" and any string as its value. In our example we'll use this one
{"arg": "ON"}Configure the “back to normal” payload. For our example, we used
{"arg": "OFF"}here.
Optionally, enable the “repeat action” option if you want to repeat the action multiple times while the event is triggered. You can choose how often and up to how many times the action will be repeated. There’s a limit of 50 action repetitions.
Step 4: Click on the "save" button.
Step 5: After completing the action configuration you’ll proceed to the final step, the “settings” tab. There, you’ll name the event, give it a description (optional), tag it (optional), and determine the activity window in which the event should be executed.
5. Results
Now, with both the Particle device running the firmware of section 2 and the Event created with the Trigger webhook action correctly configured, it's time to test everything. For this, we’re using a Switch widget to trigger the event and, hence, turn the Particle device built-in LED ON and OFF:
The Particle device will turn its built-in LED On and OFF accordingly:
