Particle devices are compact and easy-to-code hardware development kits that provide everything you need to build cloud-connected projects. Particle combines an ARM micro-controller, a communication chip (WiFi, GPRS or 3G) and a web IDE with tons of community examples and libraries to make your development with Ubidots as simple and efficient as possible.

This tutorial explains how to interact with Ubidots REST API using Particle.

Requirements

Any Particle device.
Micro USB cable.
Active Ubidots Account
Particle Library by Ubidots

Device Software Setup
Ubidots Library: HTTP, TCP and UDP protocols
Send Values to Ubidots
Send Values with Context
Send Values with Timestamp
Send Values with GPS coordinates
Retrieve Values from Ubidots
7.1. Retrieve multiple variable last Values over TCP

1. Device Software Setup

Step 1: Setup and claim your Particle Device:

– Particle Electron: Follow this steps to set up the Particle data plan. Particle Electron steps.

– Particle Photon: You can setup your Particle Photon either Using your smartphone or Connecting it to your computer over USB.

Step 2: Create New App

In the Particle Build Web IDE, create a new app. For additional details in how to "Create New App," simply click here and follow the simple 3 step process.

NOTE: We titled this guide's project "Myapp". Whichever name you select, you will need to refer to the same name throughout your project. Whenever you see "Myapp," know this is a reference to your Particle IDE application.

Step 3: Add Ubidots library to "Myapp" project:

Go to the Libraries option on the right side panel
Search "Ubidots"
Select Ubidots Library
NOTE: Be aware not to choose UbidotsMQTT Library
Click on "INCLUDE IN PROJECT".
Select the project to include the library in. In this case "Myapp".
Click on "CONFIRM".

2. Ubidots Library: HTTP, TCP and UDP Protocols.

Ubidots' library for Particle devices is a light-weight firmware that utilizes in-code Instance Declaration and Protocol Selection with standard method invoking to either Send/Retrieve data to/from Ubidots.

For Example:

– Instance Declaration and Protocol Selection:

HTTP: Ubidots ubidots(UBI_TOKEN, UBI_HTTP);
TCP: Ubidots ubidots(UBI_TOKEN, UBI_TCP);
UDP: Ubidots ubidots(UBI_TOKEN, UBI_UDP);

Using one of the instances and protocols above, your device is authenticated with Ubidots cloud using the UBI_TOKEN (TOKENS) and select the method to communicate using one of the flags UBI_HTTP, UBI_TCP or UBI_UDP.
For additional information about Ubidots library for Particle devices refer to our GitHub repository.

3. Send Values to Ubidots

In the below examples you'll find sample codes to integrate to Ubidots from Particle Devices through the mentioned protocols mentioned above.

Following the below steps you'll be able to send data to Ubidots through any of the protocol supported by the library: HTTP, TCP, or UDP.

Step 1: Copy and paste the below code in your "Myapp" project.
Step 2: Enter a valid TOKEN from your Ubidots account.
Step 3: Choose Protocol by comment/uncomment the appropriate instance.
Step 4: Uncomment line 36 if you want to see debug messages on the serial monitor.
Step 5: Change the variable labels on lines 43, 44, 45 as needed.
Step 6: Verify the code.
Step 7: Flash the code to your Particle devices.
Step 8: Check your Ubidots account.

// This example sends data to multiple variables to 
// Ubidots API through HTTP, TCP or UDP protocol.

/****************************************
 * Include Libraries
 ****************************************/

#include "Ubidots.h"

/****************************************
 * Define Instances and Constants
 ****************************************/

#ifndef TOKEN
#define TOKEN "Your_Token"  // Put here your Ubidots TOKEN
#endif

Ubidots ubidots(TOKEN, UBI_TCP); // Comment this line to use another protocol.
//Ubidots ubidots(TOKEN, UBI_HTTP); // Uncomment this line to use HTTP protocol.
//Ubidots ubidots(TOKEN, UBI_UDP); // Uncomment this line to use UDP protocol


/****************************************
 * Auxiliar Functions
 ****************************************/

//Put here your auxiliar functions


/****************************************
 * Main Functions
 ****************************************/

void setup() {
  Serial.begin(115200);
  //ubidots.setDebug(true); // Uncomment this line to print debug messages.
}

void loop() {
  float value1 = analogRead(A0);
  float value2 = analogRead(A1);
  float value3 = analogRead(A2);

  ubidots.add("Variable_Name_One", value1); // Change for your variable name.
  ubidots.add("Variable_Name_Two", value2);
  ubidots.add("Variable_Name_Three", value3);

  bool bufferSent = false;
  bufferSent = ubidots.send(); // Will send data to a device label that matches the device Id

  if(bufferSent){
    // Do something if values were sent properly
    Serial.println("Values sent by the device");
  }

  delay(5000);
}

4. Send Values with Context

Following the below steps you'll be able to send data with context to Ubidots using any of the protocol supported by the library: HTTP, TCP, or UDP.

Step 1: Copy and paste the below code on "Myapp" project.
Step 2: Enter a valid TOKEN from your Ubidots account.
Step 3: Choose Protocol by comment/uncomment the appropriate instance.
Step 4: Uncomment line 36 if you want to see debug messages on the serial monitor.
Step 5: Change the variable labels on lines 52 as needed.
Step 6: Verify the code.
Step 7: Flash the code to your Particle devices.
Step 8: Check your Ubidots account.

// This example sends data and context to a variable to 
// Ubidots API through HTTP, TCP or UDP protocol.

/****************************************
 * Include Libraries
 ****************************************/

#include "Ubidots.h"

/****************************************
 * Define Instances and Constants
 ****************************************/

#ifndef TOKEN
#define TOKEN "Your_Token"  // Put here your Ubidots TOKEN
#endif

Ubidots ubidots(TOKEN, UBI_TCP); // Comment this line to use another protocol.
//Ubidots ubidots(TOKEN, UBI_HTTP); // Uncomment this line to use HTTP protocol.
//Ubidots ubidots(TOKEN, UBI_UDP); // Uncomment this line to use UDP protocol.


/****************************************
 * Auxiliar Functions
 ****************************************/

//Put here your auxiliar functions


/****************************************
 * Main Functions
 ****************************************/

void setup() {
    Serial.begin(115200);
    //ubidots.setDebug(true); // Uncomment this line for printing debug messages.
}

void loop() {
    float value = analogRead(A0);

    /* Adds context key-value pairs */
    ubidots.addContext("weather-status", "sunny");
    ubidots.addContext("time", "11:40:56 pm");

    /* Reserves memory to store context array */
    char* context = (char *) malloc(sizeof(char) * 60);

    /* Builds the context with the key-value pairs to send to Ubidots */
    ubidots.getContext(context);

    ubidots.add("temperature", value, context);  // Change for your variable name

    bool bufferSent = false;
    bufferSent = ubidots.send();  // Will send data to a device label that matches the device Id

    if(bufferSent){
        // Do something if values were sent properly
        Serial.println("Values sent by the device");
    }

    free(context);
    delay(5000);
}

5. Send Values with Timestamp

Following the below steps you'll be able to send data with timestamp to Ubidots through any of the protocol supported by the library: HTTP, TCP or UDP.

Step 1: Copy and paste the below code on "Myapp" project.
Step 2: Enter a valid TOKEN from your Ubidots account.
Step 3: Choose Protocol by comment/uncomment the appropriate instance.
Step 4: Uncomment line 36 if you want to see debug messages on the serial monitor.
Step 5: Change the variable labels on lines 43 as needed.
Step 6: Verify the code.
Step 7: Flash the code to your Particle devices.
Step 8: Check your Ubidots account.

// This example sends data along with timestamp in POSIX ms standard
// to a variable to Ubidots API through HTTP, TCP or UDP protocol.

/****************************************
 * Include Libraries
 ****************************************/

#include "Ubidots.h"

/****************************************
 * Define Instances and Constants
 ****************************************/

#ifndef TOKEN
#define TOKEN "Your_Token"  // Put here your Ubidots TOKEN
#endif

Ubidots ubidots(TOKEN, UBI_TCP); // Comment this line to use another protocol.
//Ubidots ubidots(TOKEN, UBI_HTTP); // Uncomment this line to use HTTP protocol.
//Ubidots ubidots(TOKEN, UBI_UDP); // Uncomment this line to use UDP protocol.


/****************************************
 * Auxiliar Functions
 ****************************************/

//Put here your auxiliar functions


/****************************************
 * Main Functions
 ****************************************/

void setup() {
  Serial.begin(115200);
  //ubidots.setDebug(true);  // Uncomment this line for printing debug messages
}

void loop() {
  float value = analogRead(A0);
  unsigned long timestamp_seconds = Time.now();

  ubidots.add("temperature", value, NULL, timestamp_seconds);  // Change for your variable name

  bool bufferSent = false;
  bufferSent = ubidots.send();  // Will send data to a device label that matches the device Id

  if(bufferSent){
    // Do something if values were sent properly
    Serial.println("Values sent by the device");
  }

  delay(5000);
}

6. Send Values with GPS Coordinates

Following the below steps you'll be able to send data with GPS Coordinates as context to Ubidots through any of the protocol supported by the library: HTTP, TCP or UDP.

Step 1: Copy and paste the below code on "Myapp" project.
Step 2: Enter a valid TOKEN from your Ubidots account.
Step 3: Choose Protocol by comment/uncomment the appropriate instance.
Step 4: Uncomment line 36 if you want to see debug messages on the serial monitor.
Step 5: Change the variable labels on lines 65 as needed.
Step 6: Verify the code.
Step 7: Flash the code to your Particle devices.
Step 8: Check your Ubidots account.

// This example send data with hardcoded GPS Coordinates 
// to a variable to Ubidots API through HTTP, TCP or UDP protocol.

/****************************************
 * Include Libraries
 ****************************************/

#include "Ubidots.h"

/****************************************
 * Define Constants
 ****************************************/

#ifndef TOKEN
#define TOKEN "Your_Token"  // Put here your Ubidots TOKEN
#endif

Ubidots ubidots(TOKEN, UBI_TCP); // Comment this line to use another protocol.
//Ubidots ubidots(TOKEN, UBI_HTTP); // Uncomment this line to use HTTP protocol.
//Ubidots ubidots(TOKEN, UBI_UDP); // Uncomment this line to use UDP protocol.


/****************************************
 * Auxiliar Functions
 ****************************************/

//Put here your auxiliar functions


/****************************************
 * Main Functions
 ****************************************/

void setup() {
  Serial.begin(115200);
  //ubidots.setDebug(true); //Uncomment this line for printing debug messages
}

void loop() {
  float value = analogRead(A0);

  /* Harcoded Coordinates */
  float latitude = 37.773;
  float longitude = -6.2345;

  /* Reserves memory to store context keys values, add as much as you need */
  char* str_lat = (char *) malloc(sizeof(char) * 10);
  char* str_lng = (char *) malloc(sizeof(char) * 10);

  /* Saves as char the coordinates */
  sprintf(str_lat, "%f", latitude);
  sprintf(str_lng, "%f", longitude);

  /* Reserves memory to store context array */
  char* context = (char *) malloc(sizeof(char) * 30);

  /* Adds context key-value pairs */
  ubidots.addContext("lat", str_lat);
  ubidots.addContext("lng", str_lng);

  /* Builds the context with GPS coordinates to send to Ubidots */
  ubidots.getContext(context);

  /* Sends the position */
  ubidots.add("position", value, context); // Change for your variable name

  bool bufferSent = false;
  bufferSent = ubidots.send(); // Will send data to a device label that matches the device Id

  if(bufferSent){
    // Do something if values were sent properly
    Serial.println("Values sent by the device");
  }

  /* frees memory */
  free(str_lat);
  free(str_lng);
  free(context);
 
  delay(5000);
}

7. Retrieve Values from Ubidots

Following the below steps you'll be able to retrieve data from Ubidots using HTTP or TCP.
IMPORTANT NOTE: UDP Protocol does not support retrieving data since this protocol is only meant to forward messages from client to server.

Step 1: Copy and paste the below code on "Myapp" project.
Step 2: Enter a valid TOKEN from your Ubidots account.
Step 3: Choose Protocol by comment/uncomment the appropriate instance.
Step 4: Uncomment line 33 if you want to see debug messages on the serial monitor.
Step 5: Enter Device and Variable Label on line 38 to retrieve last value from.
Step 6: Verify the code.
Step 7: Flash the code to your Particle devices.
Step 8: Check your Ubidots account.

// This example retrieves last value of variable from the Ubidots API.

/****************************************
 * Include Libraries
 ****************************************/

#include "Ubidots.h"

/****************************************
 * Define Instances and Constants
 ****************************************/

#ifndef TOKEN
#define TOKEN "Your_Token"  // Put here your Ubidots TOKEN
#endif

Ubidots ubidots(TOKEN, UBI_TCP); // Comment this line to use another protocol.
//Ubidots ubidots(TOKEN, UBI_HTTP); // Uncomment this line to use HTTP protocol.

/****************************************
 * Auxiliar Functions
 ****************************************/

//Put here your auxiliar functions


/****************************************
 * Main Functions
 ****************************************/

void setup() {
  Serial.begin(115200);
  //ubidots.setDebug(true); //Uncomment this line for printing debug messages
}

void loop() {
  /* Obtains last value values using. */
  float value = ubidots.get("weather-station", "temperature");  

  // Evaluates the results obtained
  if(value!=ERROR_VALUE){
    Serial.print("value:");
    Serial.println(value);
  }

  delay(5000);
}

7.1. Retrieve multiple variable last values over TCP

Following the below steps you'll be able to retrieve multiple last variable valuie from Ubidots over TCP.

Step 1: Copy and paste the below code on "Myapp" project.
Step 2: Enter a valid TOKEN from your Ubidots account.
Step 3: Uncomment line 33 if you want to see debug messages on the serial monitor.
Step 4: Enter Device and Variable Labels on lines 38 and 39 respectively to retrieve last values from. Note that Variable labels must be in a comma-separated list format
Step 5: Verify the code.
Step 6: Flash the code to your Particle devices.
Step 7: Check your Ubidots account.

Important note: In order to avoid memory overflow issues, we do recommend adding up to 20 variable labels.

// This example retrieves last value of a variable from the Ubidots API
// using TCP protocol.

/****************************************
 * Include Libraries
 ****************************************/

#include "Ubidots.h"

/****************************************
 * Define Constants
 ****************************************/

#ifndef UBIDOTS_TOKEN
#define UBIDOTS_TOKEN ""  // Put here your Ubidots TOKEN
#endif

Ubidots ubidots(UBIDOTS_TOKEN, UBI_TCP);

/****************************************
 * Auxiliar Functions
 ****************************************/

// Put here your auxiliar functions

/****************************************
 * Main Functions
 ****************************************/

void setup() {
  Serial.begin(115200);
// Uncomment this line to print debug messages
  ubidots.setDebug(true);
}

void loop() {
  /* Obtain multiple last values from a comma separated variables list */
  const char* deviceLabel = "machine1";
  const char* variablesList = "var1,var2,var3";
  tcpMap myMap = ubidots.getMultipleValues(deviceLabel, variablesList);

  /* Access to retrieved values based on the ordered list returned */
  float var1_value = myMap[0];
  float var2_value = myMap[1];
  float var3_value = myMap[2];

  // Evaluates the results obtained
  if (var1_value != ERROR_VALUE) {
    Serial.printf("Value for variable var_1: %f", var1_value);
  }
  if (var2_value != ERROR_VALUE) {
    Serial.printf("Value for variable var_2: %f", var2_value);
  }
  if (var3_value != ERROR_VALUE) {
    Serial.printf("Value for variable var_2: %f", var3_value);
  }
  delay(5000);
}