UbiFunctions is a serverless computing environment designed for IoT applications, eliminating the need for additional servers. This guide will walk you through the use of UbiFunctions to enhance your Ubidots experience, whether by extracting data from third-party APIs, customizing HTTP API gateways, or transforming and analyzing sensor data.
Requirements
An Ubidots account with Industrial plan.
An Enterprise plan is required to use Global Properties in UbiFunctions.
1. What is an UbiFunction?
An UbiFunction is user-defined code that runs on-demand. It can be triggered in two ways:
By making an HTTP GET or POST request to the automatically generated UbiFunction URL.
Based on a predefined repeat interval.
2. When to use UbiFunctions?
You can use UbiFunctions to extend Ubidots’ capabilities with your custom logic. Most use-cases fall into the following three categories:
Extracting data from 3rd party APIs
Customizing your own HTTP API gateway
Transforming and analyzing sensor data
2.1. Extracting data from 3rd party APIs
Most web applications have an API and in most cases, you’ll be able to access your data programmatically without much difficulty.
You can use UbiFunctions to turn on or off a Bitcoin cluster based on the Bitcoin/energy price relationship or analyze the relationship between commodity prices and weather conditions.
Weather data extraction example:
AmbientWeather devices → AmbientWeather Cloud → Ubidots (see example)
2.2. Customizing your own HTTP API gateway
In cases where HTTP communication with Ubidots is problematic or changing HTTP methods, payloads, or URLs is difficult, UbiFunctions allows you to create custom HTTP APIs to ingest and transform data to fit Ubidots’ expected formats.
LoRaWAN Devices --> Comcast machineQ Platform --> Ubidots (show me how)
LoRaWAN Devices --> The Things Network --> Ubidots (show me how)
Sigfox Devices -->Sigfox Cloud --> Ubidots (show me how)
2.3. Transforming and analyzing sensor data
With UbiFunctions, you have access to many Python and Node.js libraries for data transformation and analysis.
Here some possible use-cases for data transformation and analysis:
Assign a GPS location to your devices, based in the neighboring WiFi routers or cell tower IDs. See example.
Assess the probability of an accident in the shop floor, based on a worker’s properties (i.e., city, production process, shift) and a machine’s variables (i.e., speed, temperature, pressure, vibration).
3. Understanding the function’s module
After accessing the functions page, from “devices” → “functions”, you’ll see a table with all your functions (in case you’ve already created any, that is) and the button to create them.
The functions’ table has the following characteristics:
A search bar to find specific functions based on their name.
The name of your functions.
The date in which the functions were created.
The functions’ URL.
A button (represented with three dots) next to each function with the following options:
Log: Detailed information about your function’s executions. Logs are explained below in this guide.
Edit: Functions can be modified using this option.
Disable: Used in case you need to temporarily turn off your function, but wish to keep it for later use.
Delete: Used to permanently delete your function.
By clicking on the “+” or the edit buttons, you’ll access the function and its configuration. Every function is divided into three major tabs which are explained below:
3.1. Function’s code editor
This tab contains the following features:
Code editor: Where you write your function’s code.
HTTP method dropdown menu: Choose to make either GET or POST requests. This option is also located in the function’s settings.
Function’s URL: Always available to be easily copied.
Runtime: Choose from the available options of Python or Node runtimes. This option is also located in the function’s settings.
Console: The output and results of your function’s tests are displayed here.
Save & run test button: Test your function with a dummy JSON.
Save & deploy button: Once your function is ready, save your latest changes and deploy it.
3.2. Function’s settings
The following are the available settings to define how a function works:
Name: Your function’s identifier. Keep in mind this name will later become part of the function's URL. The URL can’t be changed later, even if the function’s name is modified.
Runtime: The version of Python or Node that you choose to run your function with will define, to a large extent, what your function will be able to do. Check the available runtimes and the libraries that are supported for each one of them in this guide.
HTTP method: Either GET or POST can be chosen as the method. A GET method is used to request data from a specified resource, while POST is used to send data to a server to create/update a resource.
HTTPS endpoint URL: Here goes the URL of the 3rd party platform to which you'll make the requests.
MQTT host: Send data to this function using MQTT
MQTT username: Achieve MQTT authentication using the username displayed in this field and one of your tokens as the password.
MQTT topic: Payloads received in this topic will be forwarded to this function
Token: You can use the dropdown menu to select the token that will authenticate your requests. You can call in your function’s code using the token key; this spares you from having to copy-pasting API tokens in the code directly.
Environment variables: Select any number of environment variables you have previously created through the Global Properties module. With these properties, you can easily store global variables to speed development and keep resources organized. Follow the Global Properties guide to learn how to use them.
Max execution time: If a function isn't executed within this time, it's terminated and a 502 response is generated. By default, this time is 10 seconds and can be increased depending on your plan, as follows:
Entrepreneur: Up to 30 seconds.
Professional: Up to 30 seconds.
Industrial: Up to 60 seconds.
All Enterprise tiers: Up to 60 seconds.
Notes:
- Functions can have "max execution times" above 60 seconds if it's agreed upon between the user and Ubidots. However, if one of this "special" functions takes over 60 seconds to be executed (even with it's higher “max execution time”), it becomes asynchronous. This means that the function will run, but Ubidots won’t wait for its response; the response of an asynchronous function will be available in its logs.
- If you require higher execution times, reach out to us at sales@ubidots.com
Time-based trigger: If you need your function to run at periodic time intervals, define a time-based trigger, expressed in minutes. The minimum value is 1 and the maximum is 60.
Crontab expression: Specify, based on the date/time, the frequency at which the functions will be executed.
Raw function: Use raw functions to achieve an advanced level of customization. Raw functions allow you to:
Use a custom endpoint path.
Receive and respond custom headers.
Set custom response codes.
Receive and respond custom content-type headers for the request body and response.
Receive any type of data structure (object, string, array, images, etc.). Keep in mind, however, that it will be parsed to a string. Normal functions (those that don’t use raw) can only receive JSON in their bodies.
CORS policy: Used to enable the function being called from web browser's URLs different from parse.ubidots.com.
3.3. Function’s logs
The logs’ page is divided into two sections, the left pane and the content area. In them, you’ll find the following information.
Logs’ list: Located in the left pane, you’ll find the list of logs of all the executions of your function. Each item of the list contains the date and time of the execution, the execution’s ID, and the function’s execution time. Every item of the list can be clicked to access more information.
Results: Located in the content area, the results of the function’s return statement will be displayed in this field. If your function doesn’t have a return statement, a “null” message will be displayed.
Output: Located below the results field, whatever your function prints will be displayed here. Also, server messages will be displayed here as well when an error occurs on the server side or the function times out.
4. Coding an UbiFunction
UbiFunctions accepts NodeJS LTS or Python3, which means you can use Javascript or Python code to extract, transform, and analyze data. Your function receives "args" as a dictionary, which you can then access in your code to perform the desired data transformation. The code is run whenever the endpoint URL is requested.
Function example:
By default, every new UbiFunction is populated with a sample code that uses input data (token, device, & temp value) to make a request to Ubidots’ API. This sample code demonstrates a simple HTTP GET endpoint that receives an Ubidots token, a device label, and a temperature value as URL parameters, then uses this data to make an HTTP POST request to Ubidots’ API.
You can actually test the sample function by clicking on the “save & deploy” button, then paste the following URL into your web browser (updating the username and token of your account.
Note: The identifier of any function within UbiFunctions is its name. Here, the test function is named "new-function" and accordingly, by testing the sample function provided, the UbiFunctions engine will identify this particular function in your account (no one else's) and report back a temperature value and token.
You may now begin coding your function. Please note that the return payload must always be in a dictionary format. Sending a single variable cannot be understood and must be returned in a dictionary format.
YES |
|
NO |
|
To know what libraries UbiFunctions modules currently supports, please check this article UbiFunctions & Plugins: Supported libraries.
More examples:
5. Running the function
During the development process, you will want to test your function to see if you are on the right track towards the desired output. To do so, click on the "save & run test” button. This will bring up a modal screen requesting some input data to test it with. Enter a JSON dictionary of sample inputs if required. The console will display the function’s output and logs. You may leave this blank if your function does not require an input.
In the case of Ubidots default sample function, enter the JSON payload below containing the parameters you look to pass through the HTTP GET request:
{
"token":"your-token",
"Device":"sample-function",
"Temperature":"45"
}
After clicking on the "save" button, a console window will emerge with both the function’s output and the logs of the results:
Function’s output: This is what your function returns. It must be in a JSON dictionary format. In your code, make sure to use "return" to quit the function and return the dictionary.
Logs: This is used to debug purposes. Use console.log("hello") to leave trails in this console.
Note: For your function to be fully deployed after clicking on the “save & deploy” button, wait some time (about 10 seconds are usually enough).
6. Billing of UbiFunctions
UbiFunctions are included in Industrial plans and above.
Executions are timed-out after 30 or 60 seconds, based on your plan. If you wish to extend this time, please reach out to our support team.
If any execution surpasses 2 seconds; it is counted as 2 executions (or more, based on time length of the execution)
Executions are billed at increments of $5 per million executions.