Devices, variables, and Dots

The main entities in Ubidots are:

• Devices

• Variables

• Dots

Every time an Ubidots Device receives a sensor value in a variable, a data point, or "dot," is created. Ubidots stores the dots from your devices inside variables, and each stored dot has a corresponding timestamp:

An Ubidots Device is a virtual entity. This means you can map multiple physical devices to a single Ubidots Device, or map many variables from a single physical device to several Ubidots Devices. It is up to you how you want to organize your data in your Ubidots account.

We recommend mapping 1 Physical Device to 1 Ubidots Device.

The Dot

Each dot contains these items:

Item	Description	Mandatory	Size limit
value	A numerical value.	Yes	Up to 16-bit floating-point numbers.
timestamp	Unix Epoch time, in milliseconds. If not specified, our servers assign one upon reception.	No
context	An arbitrary collection of key-value pairs. Mostly used to store the latitude and longitude coordinates of GPS devices.	No	1 KB

You can find further details below.

Values

A numerical value. Ubidots accepts up to 16-bit floating-point numbers.

{"value" : 34.87654974}

Timestamps

A timestamp, as described here, tracks time as a running total of seconds. This count starts at the Unix Epoch on January 1, 1970, at UTC. Therefore, a Unix timestamp is simply the number of seconds between a particular date and the Unix Epoch.

Please keep in mind that Ubidots timestamps are in milliseconds.

Why do we use timestamps in milliseconds? This is common practice in APIs. It also lets us support many IoT applications where several data points are sent in the same second.

"timestamp" : 1537453824000

The above timestamp corresponds to Thursday, September 20, 2018 2:30:24 PM.

PRO-TIP: A useful tool for converting between Unix timestamps and human-readable dates is Epoch Converter.

Context

Numerical values are not the only supported data type. You can also store string or character data inside what we call context. The context is a key-value object that lets you store both numerical and string values. For example:

"context" : {"status" : "on", "weather" : "sunny"}

Context is commonly used to store your device's latitude and longitude for GPS or tracking use cases. All Ubidots maps use the lat and lng keys from a dot's context to extract your device's coordinates. This means you only need to send a single dot with the coordinate values in the variable context to plot it on a map, instead of sending latitude and longitude separately in two different variables. Below is a typical context with coordinate values:

"context" : {"lat":-6.2, "lng":75.4, "weather" : "sunny"}

You can mix both string and numerical values in the context. If your application is for geolocation, make sure the coordinates are set in decimal degrees.