Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Type Definitions

Before you send any piece of data to the ABB Ability™ Platform, that data needs to be modeled.

There are three levels of information modeling available in the ABB Ability™ Platform. This article describes how to model a device with a Type Definition.

Type Definitions in the ABB Ability™ Platform store data modeling logic built on top of semantic areas defined in Model Definitions.

# Know Your Device

The bottom line for data modeling in the ABB Ability™ Platform is knowing the device containing the information you want to expose. Depending on the device, there is information you should consider:

  • The current state of the device
  • Telemetry to send
  • Device functionality
  • How the device is associated with other devices/systems;

Before focusing on details, you should always start by creating the Type Definition by providing three pieces of required, basic information:

  • The domain (Model Definition) you are building your type definition on
  • The name (unique id) of your Type Definition
  • The version of your Type Definition

Let's assume that our domain is a device. We will use an ABB Ability™-provided Model Definition - abb.ability.device. In this case, the initial version of our Type Definition could look as follows:

{
    "model": "abb.ability.device",
    "typeId": "abb.myDevice",
    "version": "1.0.0"
}

# Versioning

A version of a type definition consists of three parts:

  • major
  • minor
  • patch

An example: 2.5.3. The MAJOR part is 2; the MINOR part is 5, and the PATCH part is 3.

Normally, you would start versioning from 1.0.0 - MAJOR part is 1, and the rest is 0. Anytime you want to update the type, you need to raise up the version, following the rules:

  • If the change is breaking (i.e., removal of some property), you need to raise the MAJOR.
  • If the change is not "critical", but still could impact solutions that use the type (i.e., change of some default property value), you need to raise the MINOR part.
  • In other cases (i.e., change of some description), you should raise the PATCH part.

The Type Definition API will return an error if you update the type significantly while raising just the less significant part of the version. The error will contain the suggestion about the part of the version that you should raise.

Type Definitions Semantic Versioning

To learn more about semantic versioning and version changes in particular cases, see the article Type Definitions Semantic Versioning.

# Find Your Properties

The starting point should always be technical documentation of your device. Let's assume that your device rating plate looks as follows:

  • Name: myDevice
  • Model: XY123
  • Type: Bluetooth device
  • Serial Number: myDevice123-456-789
  • Owner: ABB
  • Date Of Manufacture: 2018-02-18

When you look at the attributes, you can split them into attributes that are unique (e.g. serial number), ones that are likely to be changed during the lifetime of the device (e.g. name, owner), and others. The set of such information provides the current state of your device. Now you need to decide which information is required to identify your device and which information about your information state you may need in the future. For example:

  • Unique device information:
    • Serial Number
  • Mandatory device information:
    • Serial Number
    • Type
    • Owner
  • Other device information:
    • Model
    • Date of Manufacture

In the ABB Ability™ Platform, such information is defined as type definition properties. For example, the above device's definition would look as follows:

{
    "unique": ["SerialNumber"],
    "properties": {
        "SerialNumber": {
            "dataType": "string",
            "isMandatory": true
        },
        "DeviceType": {
            "dataType": "string",
            "isMandatory": true
        },
        "Owner": {
            "dataType": "string",
            "isMandatory": true
        },
        "DeviceModel": {
            "dataType": "string"
        },
        "DateOfManufacture": {
            "dataType": "string"
        }
    }
}

TIP

In the example above, you can see that each property has a dataType assigned to it. All supported data types can be found here: Supported Data Types

In the ABB Ability™ Platform, information modeling properties are defined by:

  • Providing the Properties section in Type Definition JSON
  • Providing the name of the property
  • Providing the data type of the property
  • Optional: providing default value (not for unique properties), description, other predefined attributes (see following chapters of this manual)

The ABB Ability™ Platform currently supports three levels of nesting. If you want to mark properties that are nested as unique, you need to follow this naming convention:

{
    "unique":["categoryName.firstLevelOfNesting.secondLevelOfNesting"]
}

# Find Your Variables

If you are interested in exposing the telemetry from your device, you probably have a dedicated API available in a given language. Using this API, you can reach the data from a particular device sensor. In your device API documentation, you will find the list of methods, properties, and events associated with telemetry data exposure. Let's assume that this is a subsection of such documentation:

//to create a connection to your device, use the following code:
MyDevice myDevice = new MyDevice("http://localhost/myDevice:8364");

//to retrieve a current value of your device surface temperature, use the following code:
public double GetSurfaceTemperature()
{
    return myDevice.GetSurfaceTemperature();
}

//to get notifications about your device's surface temperature change, use the inbuild event:
double currentSurfaceTemperature;
myDevice.SurfaceTemperatureChanged += MyDevice_SurfaceTemperatureChanged;

private void MyDevice_SurfaceTemperatureChanged(object sender, EventArgs e, double value)
{
     currentSurfaceTemperature = value;
}

//to retrieve a current value of your device's internal temperature, use the following code:
public double GetInternalTemperature()
{
    return myDevice.GetInternalTemperature();
}

//to retrieve a current value of your device's rpm, use the following code:
int double GetRPM()
{
    return myDevice.GetRpm();
}

...

From the example above, you can see that your device exposes at least three telemetry signals in various ways. The most important things here are the names of the signals and what data types those signals are associated with. A very similar approach is present with ABB Ability™ Platform information modeling. For signals extracted from the above piece of API documentation (those signals in the platform are named variables), the Type Definition entry will look as follows:

{
    "variables": {
        "surfaceTemperature": {
            "dataType": "number"
        },
        "internalTemperature": {
            "dataType": "number"
        },
        "RPM": {
            "dataType": "integer"
        }
    }
}

For variables, as for properties, you can use nesting. It can be useful for introducing variables/properties categories. For example, the preceding could look as follows:

{
    "variables": {
        "temperature": {
            "surfaceTemperature": {
                "dataType": "number"
            },
            "internalTemperature": {
                "dataType": "number"
            }
        },
        "RPM": {
            "dataType": "integer"
        }
    }
}

To know more about querying variables go to Query Variables

TIP

Type definitions allow you also to include alarms and events. Learn more here.

# Find Your Methods

The same technical documentation you've used for retrieving the information about the telemetry your device is able to expose can be very useful for extracting information about the additional functionality of your device. By additional functionality, you should consider any action that the device can perform on-demand, e.g.:

  • Automatic device update
  • Automatic restart/restart scheduling
  • Push information on demand
  • etc.

Let's imagine another subsection of our API documentation as follows:

//To perform device restart, use the following code:
public void Restart()
{
    myDevice.Restart();
}

//To schedule a restart, use the following code:
public void ScheduledRestart(DateTime time)
{
    myDevice.Restart(time);
}

//To update a device, use the following code:
public bool Update(DateTime when, double importantDoublePropertyValue, string engineerEmail, string[] someOptionalParameterValues)
{
    Dictionary<string, object> parameters = new Dictionary<string, object>();
    parameters.Add("Time", when);
    parameters.Add("ImportantDoubleProperty", importantDoublePropertyValue);
    parameters.Add("ResponibleForUpdate", engineerEmail);
    parameters.Add("Optional", someOptionalParameterValues);

    return myDevice.Update(parameters);
}

From the example above, we can extract information about three methods exposed by your device API. Using ABB Ability™ information modeling to declare a method in the type definition, you need to provide:

  • Name of the method
  • Name and data type of the input parameters (optional)
  • Name and data type of the output parameters (optional)

The JSON representation of the methods mentioned in the Type Definition can look as follows:

{
    "methods": {
        "Restart": {},
        "ScheduledRestart": {
            "input": {
                "time": {
                    "dataType": "string"
                }
            }
        },
        "Update": {
            "input": {
                "time": {
                    "dataType": "string"
                },
                "importantDoubleProperty": {
                    "dataType": "number"
                },
                "responsibleForUpdate": {
                    "dataType": "string"
                },
                "optional": {
                    "dataType": "array",
                    "items": "string"
                }
            },
            "output": {
                "done": {
                    "dataType": "boolean"
                }
            }
        }
    }
}

TIP

Please be aware that the Platform is responsible for providing the information about authorized method invocation to a target directly connected device or an Edge module responsible for a target device. The invocation logic needs to be implemented in the device or an Edge module.

# Define Your References

Sometimes you may need information about the connection of your devices with other devices. For connections, you should consider a relation loosely coupled between the objects in the same domain, e.g.:

  • Robot arm is currently connected to a specific robot controller
  • SmartSensor is currently attached to a specific electrical engine
  • etc.

Before setting such a relation, such information needs to be added to our device type definition. Let's assume that our device can be set paired with other devices of the same type. The JSON entry in the type definition will look as follows:

{
    "references": {
        "paired": {
            "isHierarchical": true,
            "to": [{
                "type": "abb.myDevice@1"
            }]

        }
    }
}

The general algorithm for adding a reference is as follows:

{
    "references": {
        "name_of_the_reference": {
            "isHierarchical": true / false,
            "to": [{
                "type": "typeDefinitionId@majorVersionNumber"
            }]

        }
    }
}

In the example above, when setting the isHierarchical parameter as true, the platform will check the references chain for potential loops.

The references can be set only between the objects in the same domain. This means that if the type definition you are building refers to the abb.abbility.device domain, the type definition you are referring to in the reference section also needs to be built on top of the same domain.

# References to Any Type

The Ability Platform users to create type definitions that have references to any type without the normal type restrictions discussed above.

  • Not all types of objects that will be created must be known in advance.

  • This flexibility allows:

    • early general modeling of structures.

    • defining attachment types that can be used in arbitrary places (e.g. smart sensor tag).

# Functionality

  1. The type definition allows creating a references section containing a reference to type abb.ability.ObjectModel@1:
{
    "model": "abb.ability.some",
    "type": "abb.ability.type",
    "version": "1.0.0",
    "references": {
        "connected": {
            "isHierarchical": true,
            "isContainment": true,
            "to": [
                {
                    "type": "abb.ability.ObjectModel@1"
                }
            ]
        }
    }
}

  1. The information model validates the reference to any type during reference creation.

    • Check if the referenced object model has the same model as the referencing one.

  2. The abstract root type abb.ability.ObjectModel is introduced with the following behavior. Note that the type:

    • is platform-defined and cannot be created or updated by the user.

    • cannot define any tokens.

    • always has version 1.

    • is a root type of all types, allowing for an overriding of references in base types as described in the Covariance section of Type Definition Inheritance.

The developer must not create an object model for the abstract root type abb.ability.ObjectModel. Any request for the creation of such an object model will be rejected with a 'BadRequest' exception.

NOTE

The root type cannot be present in baseTypes in any type definition. The root type preserves inheritance behavior in the case of reference covariance and can thus be seen as implicitly inherited by all types.

# System Attributes

# Overview

Attributes in ABB Ability™ Platform information modeling are the additional meta-information that can be used with a detailed description of variables, properties, and method parameters. System attributes are more precisely those attributes that govern how the platform functions, independent of attributes defined by a user for a local solution. Thus, any attributes defined by a user are automatically subordinate to attributes defined within the platform.

For all system attributes (SA) we understand that:

  • Keywords are reserved for platform special needs.

  • Attributes can be used among components (IM + TDR).

  • All components treat attributes in one defined way.

Note that:

  • There is no need to define platform attributes as there is a common definition for them across the platform.

  • Definitions are strict. See descriptions below.

  • Platform attributes cannot be defined or redefined by the user. Any user-defined attribute cannot clash with a platform attribute.

NOTE

Currently, the ABB Ability™ Platform does not introduce any additional logic associated with platform or with custom (user-defined) attributes. It is up to you to add specific handling for specific situations, e.g. where internal temperature telemetry data is higher than defined in the max attribute threshold (push an event).

There are two types of system-reserved tokens that may not be redefined by the user, reserved validation keywords and platform-defined attributes, as described below.

# Reserved Validation Keywords

Currently, the following keywords are reserved and cannot be redefined by the user. They can, however, be used in payloads only, according to specification.

  • dataType - string. Applicable to properties, variables, attributes.

  • description - string. Applicable to all elements (properties, variables, but also type definitions). MUST be one of the six primitive types ("boolean", "array", "map", "number", or "string"), or "integer".

  • tags - An array of strings. Applicable to top-level elements (excludes properties or variables) in a textual, human-readable form.

  • items - Defines the set of possible values of an array. Mandatory if“dataType” is an array. Values must be one of the following: “string”,“number”, integer”, or “boolean”.

  • enum - array. Defines the set of possible values of a property or variable. Applicable to properties, variables, and attributes.

  • values - MUST be either a valid property definition or a string (implicit dataType keyword). Defines the allowed values of keys inside a map-valued property or variable. Applicable to properties and variables.

  • value - Defined by the dataType keyword. Applicable to properties.

  • isMandatory - boolean. Applicable to properties. If this keyword has the boolean value false, the instance validates successfully. If it has the boolean value true, the instance validates successfully if it has a value.

  • isHierarchical - boolean. Applicable to references. Defines whether a reference is considered to be part of a tree structure. If there is only one incoming reference per object model, then 'isHierarchical' is set to true and there are no loops in the sequence of hierarchical references.

    • Type definition minor version value is updated if this value is changed.

  • isContainment - boolean. Only applicable to references and in combination with isHierarchical : true. Defines whether an ObjectModel is tied to the life-cycle of its hierarchical parent.

    • Type definition minor version value is updated if this value is changed

# Platform-defined Attributes

# max

  • Defines a maximum possible number of the value of a property or variable.

  • Applicable to properties and variables.

  • This attribute can be applied to integer and number dataTypes properties and variables only.

# min

  • Defines a minimum possible number of the value of a property or variable.

  • Applicable to properties and variables.

  • This attribute can be applied to integer and number dataTypes properties and variables only.

# unit

  • Defines a string value of the engineering unit that the value of the property or variable is measured in. For example "C" or "kW".

  • Applicable to properties and variables.

  • This attribute can be applied to integer and number dataTypes properties and variables only.

  • Can be used for UI representation and calculation based on convertible units.

NOTE

min/max/unit attributes can't be declared by the user in the 'attributes' section, but they can be used in properties/variable if they are consistent with defined common rules.

Sample platform-defined attributes rules payload (see System Attributes, Overview, above):

{
 "attributes": {
   "unit": {
     "appliesTo": [
       "number",
       "integer"
     ],
     "dataType": "string"
   },
   "min": {
     "appliesTo": [
       "number",
       "integer"
     ],
     "dataType": "number"
   },
   "max": {
     "appliesTo": [
       "number",
       "integer"
     ],
     "dataType": "number"
   }
 }
}

# System Attributes in the HolisticView

The holistic view is a representation of all related definitions defined in the type definition and the object model. System attributes will not appear in the holistic view, despite their use.

# Example Use Case

Let's assume that in the technical documentation of our device there is the following information:

WARNING

Device safe temperature range: The device safe range for internal temperature is from 0 °C to 100 °C.

Platform defined attributes can be used to enrich the type definition with this information.

After using platform attributes, your variable section would look as follows:

{
    "variables": {
        "temperature": {
            "surfaceTemperature": {
                "dataType": "number"
            },
            "internalTemperature": {
                "dataType": "number",
                "min": 0,
                "max": 100,
                "unit": "°C"
            }
        },
        "RPM": {
            "dataType": "integer"
        }
    }
}
Last updated: 2/11/2022, 10:32:55 AM

← Status Lifecycle →

Feedback