One feature developers using Ubidots love most is the automatic device creation when the first dot of data is received in a user's account (in case you did not know this, check out the article “Automatically provision Devices and Variables with Ubidots API labels”). Here’s a simplified flow diagram of how Ubidots understands and recognizes a device:
Device Types further automate the device onboarding process by not only creating the new device in Ubidots, but also configuring its variables, properties, and appearance. With Device Types, deployments are as simple as uploading code with the correct token and letting Ubidots take care of the rest.
Requirements
An active Ubidots account.
1. Why Device Types?
To give you an idea of how much time you can save with this feature, here’s a real-life onboarding workflow prior to switching to Device Types:
Create a device in Ubidots
Flash firmware to device with API identifier given by IoT platform
Create 10 variables within the device
Specify units for each variable
Specify range for each variable
Specify custom offset for some of the variables
Create properties: City, installation date, and firmware version
For a deployment of 1,000 devices, this would have to be done 1,000 times!
On the other hand, with Device Types, the process becomes as simple as:
Creating a Device Type with corresponding properties, variables, units, ranges and formulas.
Flashing the same firmware to all devices.
With Device Types, every time a device is created, the specified device type is automatically applied, saving you the configuration and development time needed to launch hundreds of the same device.
2. Creating a Device Type
Step 1 : Create a new device type
To create a device type, go to the “Devices” tab in your Ubidots account, then click on “types”, followed by the “+” button in the upper right corner:
Step 2: Device type name and appearance
Next, you'll be presented with a panel to configure the settings of your device type. In the first step you will be able to modify the name, API label, description, the icon you want to display for your device, and the colors of the variables and devices. Keep in mind that the API label of the device type will automatically be generated based on the name you enter.
IMPORTANT NOTE: The API label of the device type is a unique identifier that allows Ubidots to know which device type to apply when a new dot is received by the platform. This can be specified in your request using the parameter "type" in the request URL. For example:
curl -X POST 'https://industrial.api.ubidots.com/api/v1.6/devices/device-label/?type=device-type-label' \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: YOUR-TOKEN' \
-d '{"temperature":10}'
Step 3 (optional): Configure device properties
If you use the Ubidots device properties feature, then this step is for you.
By specifying custom properties for the device type, every new device will be created with the same applied set of properties. In this step you will be able to add properties in these formats: True or false, date, list, text, number, device, and JSON.
Here's an example of what a property configuration might look like:
Step 4 (optional): Configure variables
Click on the button “+ add variable” to add as many variables as needed (raw or synthetic).
For each raw variable, you can set these basic fields:
Name: The variable name that will appear in the list of variables of the device. This is simply a human-friendly name.
API label: An identifier within all the device’s variables. It can be different than the variable name and should match the payload. Example: If the payload from the physical device is ”{“temp”:10}”, then the variable API label in the device type should be “temp”.
Description: The description of the variable as you’d like it to appear for to end users.
Icon code: Fontawesome’s icon name. This icon is a simple visual reminder to the type of sensor you are working with.
Color: Optionally, override the color of the variable, as set in the “appearance” step above.
Unit: The variable's unit of measurement.
Allowed range: The min. and max. ranges for your variable.
Scaling function: Allows you to apply linear transformation to the data.
Visible to end-users: By default it's selected. If not selected, then this variable will only be seen by the admin, not the app's users.
Location variable: If selected, then Ubidots will understand this variable to be containing the context of latitude and longitude coordinates.
Here’s an example of how this configuration could look like:
NOTE: For each synthetic variable, you can set the basic fields excluding allowed range and scaling function. Additionally, you will be able to set the following field:
Synthetic expression: The math or statistical expression used to compute new data based on one or more existing variables.
EXAMPLE: The variable name and variable API label can be the same or different. If the variable name is "Temperature" and the Variable API label is "temp", Ubidots will recognize the "temp" API label and update the corresponding variable, but display "Temperature" in the dashboard.
Step 5 (optional): Configure tasks
Tasks are actions that get executed once a device is created using a device type. In the previous steps we've gone through settings related to the device itself, but "tasks" allow you to go even further and automate the creation of dashboards and events, or assigning the newly created device to a device group.
Click on "+ add task" to add as many tasks as needed. You can choose between "assign to a device group", "create an event", or "create a dashboard". The last two options take an existing event/dashboard as template.
Type of task: Create an event
Whenever a new device of this type is created, a new event will be created with the same trigger conditions and actions found in the selected event. Clicking on "select event" will present you with a modal to select an existing event.
Type of task: Create a dashboard
Whenever a new device of this type is created, a new static dashboard will be created with the same widgets and variable labels found in the selected dashboard. Clicking on "select dashboard" will present you with a modal to select an existing dashboard.
Type of task: Assign to device group
Whenever a new device of this type is created, it will be assigned to the device group selected in the "select device group" drop-down.
3. Testing Device Types
To access the list of all Device Types in your account, select "types" in the Devices tab of the main navigation bar.
To test the device type, copy and paste the below sample request into your computer's terminal. Make sure to change the token and the ?type= parameter.
IMPORTANT NOTE: Device types are only applied when creating new devices. Sending the “?type=” parameter to an existing device will only update the data of the configured variables.
curl -X POST 'https://industrial.api.ubidots.com/api/v1.6/devices/device-type-test/?type=new-type' \
> -H 'Content-Type: application/json' \
> -H 'X-Auth-Token: YOUR-TOKEN‘ \
> -d '{"<Variable_API_Label>":""}'
If the device type has been created properly, a 201 response code will be returned in your computer's terminal.
{"Variable_API_Label": [{"status_code": 201}]}
Lastly, in your Ubidots account, you can see the results. Not only will you see the new device created and named according to the credentials established in the device type, but you will also see the device's pre-configured variables with names, icons and units of measurement already updating according to your device type:
Plus... The device properties are also added:
