Assets

Assets are the first of the native object types. An asset is the digital twin of a thing in the real world: it has properties and metadata, sensor values and a location.

Object type	Plural form
asset	assets

Assets support every generic endpoint: get, create, update, delete and rename, history, values, aggregates and the object type schema.

Sensors

An asset carries the values of its sensors. They come from Undagrid supported hardware devices and range from temperature and movement to inclination and battery status. To couple a device to an asset, the device is commissioned onto it; see Commissioning.

sensors.metadata lists the asset's virtual sensors and the devices that feed them, sensors.latestEvents holds the latest value of each sensor, and sensors.values holds the same values keyed by sensor name. The value of a sensor is specific to its type; every sensor and the form of its value are described under Sensor values.

Location

A device can also deliver the location of the asset, once its location sensor is commissioned. The location is held in location:

• position: a GeoJSON point, with coordinates in the order longitude, latitude;
• accuracy: the horizontal accuracy in metres;
• source: the source of the fix;
• floor: the floor;
• stationary: whether the asset is stationary;
• geoFeatures: the names of the geofences the position matches.

Asset schema

Asset

Definition of the Asset object

Includes every field of Base object.

Field	Type	Required	Description
sensors	Sensors
location	Location

Sensors

Sensors defines two things: the metadata describing the virtual sensor, and the current values of the configured virtual sensors

Field	Type	Required	Description
metadata	array of object		An array of active virtual sensors on the asset with commissioned nodes. It defines the source of the virtual sensor information
latestEvents	array of object		An array of virtual sensor values representing the current state of these sensors

Location

Describes the logical location of an asset in various degrees of precision. Note that all fields are optional.

Field	Type	Required	Description
locationTime	string (date-time)		The moment the asset was at this location
updateTime	string (date-time)		The moment the location information was updated
stationary	boolean		True if asset is stationary. In that case locationTime points to the moment the asset became stationary
valid	boolean		Show if the system is sure the asset is currently still at the given position. For instance, when moving, it will show invalid because the asset will not be at the shown location anymore. When stationary a location can be invalid when for instance there was not enough information to comprise a new location. In that case the previous location is retained
source	string		The source of the location, for example GPS, cell, hybrid, UBLN or MANUAL for a manually assigned position
namedLocation	string		A string that can identify a location
potentialField	object		A GeoJSON multi-polygon describing one or multiple areas of where the asset could be
accuracy	number		The horizontal accuracy in meters
position	object		A GeoJSON point describing a single point location of the asset
correctedPosition	array of number		A corrected position based on snapping configuration on one of the matching geos
floor	string		Floor level inside of a building
geoFeatures	array of string		Names of the matched geos for this location
altitude	number		height above sea level

Commissioning

To assign sensors to an asset, the devices that provide them are commissioned onto it. This is a largely automated process that:

• checks that the devices are in working order;
• sets up the communication paths to the tenant;
• assigns the devices' sensors to the asset.

Commissioning has two parts:

1. Checking that the devices are in working order: prepare.
2. Performing the actual commissioning: commission.

The first is optional, since the second performs the same checks. It is useful as a dry run: it changes nothing.

Operation: COMMISSION

Prepare

POST /v1/{tenant}/asset/prepare/{deviceA}/{deviceB}/...

Any number of devices can be given.

Commission

POST /v1/{tenant}/asset/{assetNameOrId}/commission/{deviceA}/{deviceB}/...

Any number of devices can be given. The list replaces all devices currently commissioned onto the asset; an empty list removes them all.

Result

Both calls return the same result:

Commission Prepare Result

The result of a commissioning prepare or commission call.

Field	Type	Required	Description
status	passed | warning | failed	yes	The status of the commissioning call
statusText	array of string		A human readable text describing the status. Generally used to display error messages
devices	array of object	yes	A list of devices commissioned or prepared
location	object		The last known location of the sensor
location.lat	number		Sensor location latitude
location.lon	number		Sensor location longitude
location.timestamp	string (date-time)		Sensor location timestamp