ABB Developer Portal

API definition

GetDeviceList

Get the list of all Smart Access Points.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{SystemWIP{dtId}}

dtId - [String] select single object by ID (if not specified all objects of that type are considered)

Response

{
  "data": {
    "SystemWIP": [
      {
        "dtId": "318df790-fd89-4a6e-9ed3-b8edfe4c8836"
      },
      {
        "dtId": "057b18c6-6666-40c1-a84a-9e13e9527c19"
      },
      {
        "dtId": "b39552c9-9b87-42b8-9930-069355e37291"
      },
      {
        "dtId": "c376b842-8f78-4b69-ae31-f815f24d5b90"
      }
    ]
  }
}

dtId - [String] ID used to identify this object inside of this API

RequestGetAll

Request the SmartAP to send a complete getAll (current model state) to the cloud.

It is important that this is not required to get the data-model. It is just exposed as "fallback”in case the model is not in sync. Otherwise it might be that the API-User is causing unnecessary load.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{SystemWIP(dtId:"c376b842-8f78-4b69-ae31-f815f24d5b90"){DeviceManagement{RequestGetAll{callMethod }}}}

Response

Success

{
  "data": {
    "SystemWIP": [
      {
        "DeviceManagement": {
          "RequestGetAll": {
            "callMethod": true
          }
        }
      }
    ]
  }
}

Failed

{
  "data": {
    "SystemWIP": [
      {
        "DeviceManagement": {
          "RequestGetAll": {
            "callMethod": false
          }
        }
      }
    ]
  }
}

GetConfiguration

Get configuration for the Smart Access Point, this includes the schema for all devices, channels and data points, the building structure and current user information.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{SystemWIP(dtId:"592c91f0-8d9b-44bf-88da-23fd1ef6d994"){Assets{__typename dtId label nameId } Locations{dtId Sublocations{dtId}} Users{userName credentials{value{displayName}} deviceAccessList{key}}}}

dtId - [String] select single object by ID (if not specified all objects of that type are considered)
label - [String] Human readable name of the object

Response

{
  "data": {
    "SystemWIP": [
      {
        "Assets": [
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_101807A7F02809C",
            "label": "OS 002-01",
            "nameId": "WIP_0801"
          },
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_142807A7F030B4F",
            "label": "RF/IP gateway",
            "nameId": "WIP_0666"
          },
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_105807A7F02977C",
            "label": "Smart Access Point",
            "nameId": "WIP_FFCA"
          },
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_107807A7F0321AE",
            "label": "EC 066-01",
            "nameId": "WIP_0827"
          },
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_102807A7F046CCB",
            "label": "IS 032-0101-01",
            "nameId": "WIP_0802"
          },
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_107807A7F0321CC",
            "label": "EC 001-01",
            "nameId": "WIP_0827"
          },
          {
            "__typename": "DeviceWIP",
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Device_201647E000000E4",
            "label": "Cylinder",
            "nameId": "WIP_0562"
          }
        ],
        "Locations": [
          {
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Building_1",
            "Sublocations": [
              {
                "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Floor_1_1"
              }
            ]
          },
          {
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Building_6",
            "Sublocations": [
              {
                "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Floor_6_1"
              }
            ]
          },
          {
            "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Building_7",
            "Sublocations": [
              {
                "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994_Floor_7_1"
              }
            ]
          }
        ],
        "Users": [
          {
            "userName": "admin585",
            "credentials": [
              {
                "value": {
                  "displayName": "1234"
                }
              },
              {
                "value": {
                  "displayName": "1213"
                }
              },
              {
                "value": {
                  "displayName": "11111"
                }
              },
              {
                "value": {
                  "displayName": "809"
                }
              },
              {
                "value": {
                  "displayName": "1112"
                }
              },
              {
                "value": {
                  "displayName": "121212"
                }
              }
            ],
            "deviceAccessList": [
              {
                "key": "101807A7F02809C"
              },
              {
                "key": "201647E000000E4"
              }
            ]
          },
          {
            "userName": "clouduser",
            "credentials": null,
            "deviceAccessList": null
          },
          {
            "userName": "0040101",
            "credentials": [
              {
                "value": {
                  "displayName": "ookk"
                }
              }
            ],
            "deviceAccessList": [
              {
                "key": "201647E000000E4"
              }
            ]
          }
        ]
      }
    ]
  }
}

dtId - [String] ID used to identify this object inside of this API

CreateUserWithPermissionsMethod

Create a new user in the SmartAP with permissions defined by scope names. The created users represents a service or entity in the cloud that wants to direct further calls towards the SmartAP through IoTHub. The user on the SmartAP is disabled by default and must be enabled manually by the customer to express consent to use the cloud service. This behavior is based on the protocol for other ISPf services that require manual confirmation as well. The call returns a success if the user already exists.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{
  ISystem(dtId: "c376b842-8f78-4b69-ae31-f815f24d5b90") {
    DeviceManagement {
      RPCCreateUserWithPermissionsMethod {
        callMethod(
          displayName: "friendlyname"
          user: "clouduser"
          scopes: "permissionRequestTargets"
        ) {
          code
      }
    }
  }
}
}

The user account format only supports lowercase letters and numbers, with a length of 1-40.

Response

{
  "data": {
    "ISystem": [
      {
        "DeviceManagement": {
          "RPCCreateUserWithPermissionsMethod": {
            "callMethod": {
              "code": 204
            }
          }
        }
      }
    ]
  }
}

CreateBackup

Trigger the upload of a backup from the SmartAP to the cloud.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{ISystem(dtId:"c376b842-8f78-4b69-ae31-f815f24d5b90"){BackupService{CreateBackup{callMethod(name: "backup") }}}}

name - [String] backup name

Response

Success

{
  "data": {
    "ISystem": [
      {
        "BackupService": {
          "CreateBackup": {
            "callMethod": true
          }
        }
      }
    ]
  }
}

Failed

{
  "data": {
    "ISystem": [
      {
        "BackupService": {
          "CreateBackup": {
            "callMethod": false
          }
        }
      }
    ]
  }
}

RestoreBackup

Download of a backup from the cloud. This call does not apply the backup, it just downloads it to the SmartAP so that it can be applied manually. Automaticly applying a backup is not supported by welcome IP because it might require manual interaction with the UI for device conflict resolution.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

ISystem(dtId:"c376b842-8f78-4b69-ae31-f815f24d5b90"){BackupService{RestoreBackup{callMethod(name: "0001-backup.tar") }}}}

name - [String] backup name

Response

Success

{
  "data": {
    "ISystem": [
      {
        "BackupService": {
          "RestoreBackup": {
            "callMethod": true
          }
        }
      }
    ]
  }
}

Failed

{
  "data": {
    "ISystem": [
      {
        "BackupService": {
          "RestoreBackup": {
            "callMethod": false
          }
        }
      }
    ]
  }
}

SetDataPointMethod

Set the value of one or multiple input datapoints. Each datapoint in the welcome IP installation is addressed by the device serial number, the persistent id of the channel (hex format) and the id of the datapoint inside the channel. The value is always formatted as string, even for numbers. Datapoint values will be applied in the order they are given in the payload.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{
  ChannelWIP(
    dtId: "c376b842-8f78-4b69-ae31-f815f24d5b90_Device_105807A7F02977C_Channel_6"
  ) {
    outputs(key: "0") {
      value {
        DataPointService {
          SetDataPointMethod {
            callMethod(value:"1")
            {code}
          }
        }
      }
    }
  }
}

dtId - [String] uuid_Device_Serialnum_Channel_Channelnum
key - [String] data point
value - [String] specify value to set datapoint to

Response

{
  "data": {
    "ChannelWIP": [
      {
        "outputs": [
          {
            "value": {
              "DataPointService": {
                "SetDataPointMethod": {
                  "callMethod": {
                    "code": 204
                  }
                }
              }
            }
          }
        ]
      }
    ]
  }
}

RPCCreateCredentialMethod

Create QR/Pin code

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{ISystemWIP(dtId:"c376b842-8f78-4b69-ae31-f815f24d5b90"){DeviceManagementWIP{RPCCreateCredentialMethod{callMethod(password:"234113",to:1,from:1,max:1,timeprofile:0,name:"ookk",type:2,block:4,floor:1,room:1){code} }}}}

password - [String] If creating a PIN-Code, this filed is need, the password need provide by the cloud side. If creating a QR-Code, this filed is not need, the device will automatically generate a password
max - [Float] duration limit, how much time usable
to - [Float] the number of seconds from Jan 1, 1970
from - [Float] the number of seconds from Jan 1, 1970
timeprofile -[Float] whether there is a time limit. 0 means no a time limit, 1 means a time limit
name - [Float] custom name
block,floor,room - [Float] Physical address

Response

Success

{
  "data": {
    "ISystemWIP": [
      {
        "DeviceManagementWIP": {
          "RPCCreateCredentialMethod": {
            "callMethod": {
              "code": 200
            }
          }
        }
      }
    ]
  }
}

Failed

{
  "data": {
    "ISystemWIP": [
      {
        "DeviceManagementWIP": {
          "RPCCreateCredentialMethod": {
            "callMethod": {
              "code": 409
            }
          }
        }
      }
    ]
  }
}

RPCQueryCredentialMethod

Query QR/Pin code

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{
ISystemWIP(dtId: "c376b842-8f78-4b69-ae31-f815f24d5b90") {
DeviceManagementWIP {
RPCQueryCredentialMethod {
callMethod(block:4,floor:1,room:1) {
code
payload {
index
name
password
}
}
}
}
}

Response

{
  "data": {
    "ISystemWIP": [
      {
        "DeviceManagementWIP": {
          "RPCQueryCredentialMethod": {
            "callMethod": {
              "code": 200,
              "payload": [
                {
                  "index": 7,
                  "name": "ookk1",
                  "password": "11C4BB28DC27D475"
                }
              ]
            }
          }
        }
      }
    ]
  }
}

RPCDeleteCredentialMethod

Delete QR/Pin code.

Request

Request URL

https://apim.eu.mybuildings.abb.com/adtg-api/v1/graphql

Request headers

Field	type	description
Authorization	string	OAuth 2.0 access token obtained from eu.mybuildings.abb.com.

Request body

{
ISystemWIP(dtId: "318df790-fd89-4a6e-9ed3-b8edfe4c8836") {
DeviceManagementWIP {
RPCDeleteCredentialMethod {
callMethod(data:["1","2"])
{
code
details
payload{
result
i
}}}}}}

data - [String array] the index of the PIN-Code or QR-Code will be deleted

Response

{
  "data": {
    "ISystemWIP": [
      {
        "DeviceManagementWIP": {
          "RPCDeleteCredentialMethod": {
            "callMethod": {
              "code": 200,
              "details": null,
              "payload": [
                {
                  "result": 0,
                  "i": 7
                }
              ]
            }
          }
        }
      }
    ]
  }
}

Telemetry

The welcome IP cloud API provides a websocket endpoint to enable the API user to get immediately informed about changes to datapoints or the configuration without polling.

In order to open a websocket, you require a websocket implementation that:

Supports providing headers to the connection request.
Supports HTTP redirect responses (NOTE: Take special care of this. Not all implementations support this out of the box, sometime is must be enabled in the configuration, sometimes it is not supported at all).

Note in particular that opening from a browser in javascript is therefore not possible with default javascript websocket implementations.

When these requirements are ensured, simply open a websocket with the correct authentication headers (see the samples for details), including a valid OAuth2 token on the websocket url (using the usual websocket schema wss:// instead of https://):

wss://apps.eu.mybuildings.abb.com/adtg-ws/graphql

After this, you can receive websocket events on the opened websocket connection.

All queries inside the “subscription {…}” query are sent via WS directly – in such cases no REST API is used (in the playground it just looks like the same as the REST calls)
There is a graphql-ws-protocol: https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md

A typical query looks like follows (could also be done using the ws-integration in Postman):

Init

{"type":"connection_init","payload":{"authorization":"Bearer [TOKEN]"}}

Start query #1 (multiple queries are possible over one websocket)

{
    "id": "1",
    "type": "subscribe",
    "payload": {
        "variables": {},
        "extensions": {},
        "operationName": null,
        "query": "subscription {\n  DataPointSubscription (dtId:\"9a829d2e-c21a-4be4-ac64-548099a786b7\") { value serialNumber timestamp}\n}\n"    
        }
}

End query #1

{
     "id": "1",
        "type": "complete"
}

DataPointSubscription

Subscription

subscription{DataPointSubscription (dtId:"592c91f0-8d9b-44bf-88da-23fd1ef6d994"){dtId  serialNumber channelNumber value}}

Response

{
  "DataPointSubscription": {
    "dtId": "592c91f0-8d9b-44bf-88da-23fd1ef6d994",
    "serialNumber": "105807A7F02977C",
    "channelNumber": "1",
    "value": "0"
  }
}