# Devices

When thinking about the IIoT Platform, one of its pillars are the connected "things", which we can most often refer to as devices. It is important to understand that we can have two kinds of devices:

Directly Connected
Indirectly Connected

Directly connected devices communicate with the ABB Ability™ Platform directly via the platform's communication interface (Azure IoT Hub), without any brokers in-between. Sometimes those devices are also called Native Ability Platform Devices.

Indirectly connected devices do not communicate with the Ability Platform directly. They do it through an intermediary device.

Edge Device

If you need to have a device acting as a broker for an indirectly connected device, it is recommended to make use of the Ability Edge: a reference implementation of Edge device software provided by the Ability Engineering Team.

This section describes the devices that connect to the ABB Ability™ Platform directly. The provided information will help you to understand the communication protocol that the devices must adhere to.

Code Example

Take a look at an example of directly connected device implementation on Codebits.

# Requirements for a Directly Connected Device

A device must have a type registered in the Type Definition Registry.
All device communication with IoT Hub must be secured via TLS with X.509 certificate based authentication.
The device hardware must support Verified boot (ex. UEFI Secure Boot) to assure software integrity and Secure key storage backed by a Hardware root of trust (Ex. TPM 2.0).
The device must support the isolation of an internet-facing network interface. If the device communicates with other on-premise equipment, then on-premise communication should occur on a separate network interface rather than on the internet-facing network interface.
The device must be configured with:
- the URL of the Device Provisioning Service (DPS)
- the URL of the Certificate Authority (CA)
- the hash of the CA's certificate
- the URL of the Global ID Generator Service (GIG)
The device must satisfy the Minimum Cyber Security Requirements from:
- MCSR for Products
- MCSR for Internet facing Products (Section 4)

# Communication with the cloud

Directly Connected Devices communicate with the Ability Platform using the Device API. The platform supports two versions of this API: V1 and V2. Although both of them are supported, it is recommended to design your devices to use the Device API V2. V1 is an older communication interface, has limited functionality, and is about to be deprecated in one of the future releases of the Ability Platform.

TIP

To learn more about operations that are supported by the Device API (both V1 and V2), go to the Device API section.

# Type Definition

Each device must have an associated type that is registered in the type definition registry before the device is connected. The device type must be under a model definition such as abb.ability.device. This type must declare all:

properties that describe the characteristics of your device
variables, alarms, and events that your device shall emit
supported methods and their signatures

The following properties are mandatory in the type definition:

deviceId string, must be mandatory, enforced by the device model definition
hubName string, must be mandatory, enforced by the device model definition

Both of these properties should be declared as unique - these properties identify your device as directly connected and addressable by the Ability Platform. Here's an example of how those would look like in a type definition:

"properties": {
  "hubName": {
    "description": "IoT Hub host name",
    "dataType": "string",
    "isMandatory": true
  },
  "deviceId": {
    "description": "IoT Hub device identifier",
    "dataType": "string",
    "isMandatory": true
  }
}

If your device can be configured (i.e. if it supports changing the frequency of the telemetry that is being emitted), then you also must create a type under a model definition abb.ability.configuration. Every time this model is updated in the cloud, a C2D message will be sent to your device, allowing you to act on configuration changes accordingly. If you want your configuration model to be created automatically when your device is registered, create a relatedModels link in the device type as mentioned above. For more, see the Information Modeling article and the Codebits repository, which contains some examples of directly connected devices' type definitions.

PKI Overview →