BAS-IP devices API via MQTT 1.0.0 documentation

Default content type: application/json

The following document describes the concept of interaction with BAS-IP devices API through the MQTT protocol.

Starting from firmware versions mentioned below, BAS-IP devices supporting connection to the MQTT brokers v.3

3.15.0 for Android panels
5.6.0 for Android monitors
3.3.0 for Camdroid panels
1.11.0 for Camdroid monitors

Encryption

All devices supports:

TLSv1,TLSv1.1,TLSv1.2
CA signed certificates
Ability to upload and use self-signed SSL ceritificates in PEM format
Operation without encryption

Basic concepts

Interaction between device and server is carried out in 5 topics specified in this documentation, concept is the next:

Device is authorized on the MQTT broker
Device subscribes to messages from the server in the topic device/request/v0/{serial_number}
- Server can perform requests to the device API by sending appropriate commands to this topic
Device responds to the server requests in the topic device/response/v0/{serial_number}
- Server subscribes to this topic and receives answers to requests
Server subscribes to messages from the device in the topic server/request/v0/{serial_number}
- Device can perform requests to the server API by sending appropriate commands to this topic
- Mainly used by the devices to send logs
Server responds to the device requests in the topic server/request/v0/{serial_number}
- Device subscribes to this topic and receives answers to requests
Device send online/offline status messages in the topic device/status/v0/{serial_number}

The payload of the message is formed in such a way as to allow the use of headers and request bodies familiar to HTTP requests. The client and the server exchange the same JSON objects, make requests to the same URIs and use HTTP methods as in REST API, but using the MQTT message payload for this.

"Content-Type: application/json" header is mandatory when sending requests.

Examples

Server authorization on a device, and opening the device lock by the server

Server sends a request for authorization on the device to the device/request/v0/{serial_number} topic and starts a waiting timer (similar to connection timeout) for a response with a 202 status, for example 3 seconds. If in 3 seconds it does not receive a response with status 202, it will consider that the request was completed with an error.
```
{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "headers": ["Content-Type: application/json"],
  "method": "GET",
  "uri": "/api/login?username=admin&password=E10ADC3949BA59ABBE56E057F20F883E",
  "data": null
}
```
Device receives this message, parses it, and if the message is parsed, publishes a message without a response body with status 202 to the device/response/v0/{serial_number} topic, this will mean that the device has accepted the request and started processing it.
```
{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "status": 202,
  "data": null                                                    
}
```
Server receives a response with a 202 status, stops the wait timer for 202 and starts a new timer (similar to request timeout), for example for 600 seconds. If it does not receive a response 200, 400, 404, 422, 500 etc. then it will consider that the request was completed with an error.

Device finishes processing the request and publishes a response message with a 200 status and a JSON object containing the token and account_type to the device/response/v0/{serial_number} topic.

{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "status": 200,
  "data": {
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss",
            "account_type": "admin"
          }                                                    
}

Server receives a response, parses, considers that the request was successful.

Server sends a message with a lock opening request to device/request/v0/{serial_number}, adding token "Authorization: Bearer eb1e0846-0d66-4cef-a29f-8f7d58086f8f" to the header array, because the specified endpoint requires authorization on the device.

{
  "request_id": "5665a873-5072-465f-aa1c-a955f00e5985",
  "headers": [
                "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss",
                "Content-Type: application/json"
              ],
  "method": "GET",
  "uri": "/api/v1/access/general/lock/open/remote/accepted/1",
  "data": null
}

Device receives this message, parses it, and if the message is parsed, publishes a message without a response body with status 202 to the device/response/v0/{serial_number} topic, this will mean that the device has accepted the request and started processing it.
```
{
  "request_id": "5665a873-5072-465f-aa1c-a955f00e5985",
  "status": 202,
  "data": null                                                    
}
```
Server receives a response with a 202 status, stops the wait timer for 202 and starts a new timer (similar to request timeout), for example for 600 seconds. If it does not receive a response 200, 400, 404, 422, 500 etc. then it will consider that the request was completed with an error.

Device finishes processing the request and publishes a response message with a 200 status to the device/response/v0/{serial_number} topic.

{
  "request_id": "5665a873-5072-465f-aa1c-a955f00e5985",
  "status": 200,
  "data": null                                                  
}

Server receives a response, parses, considers that the request was successful.

Device authorization on a server, and sending log about opening the device lock by the server

Device sends a request for authorization on the server to the server/request/v0/{serial_number} topic and starts a waiting timer (similar to connection timeout) for a response with a 202 status, for example 3 seconds. If in 3 seconds it does not receive a response with status 202, it will consider that the request was completed with an error.
```
{
  "request_id": "4e0b354c-d288-426c-872d-e86f3bf739ae",
  "headers": ["Content-Type: application/json"],
  "method": "POST",
  "uri": "/api/v0/devices/login",
  "data": {
            "login": "admin",
            "password": "123456"
          }
}
```
Server receives this message, parses it, and if the message is parsed, publishes a message without a response body with status 202 to the server/response/v0/{serial_number} topic, this will mean that the server has accepted the request and started processing it.
```
{
  "request_id": "4e0b354c-d288-426c-872d-e86f3bf739ae",
  "status": 202,
  "data": null                                                    
}
```
Device receives a response with a 202 status, stops the wait timer for 202 and starts a new timer (similar to request timeout), for example for 600 seconds. If it does not receive a response 200, 400, 404, 422, 500 etc. then it will consider that the request was completed with an error.

Server finishes processing the request and publishes a response message with a 200 status and a JSON object containing the token and refresh token to the server/response/v0/{serial_number} topic.

{
  "request_id": "4e0b354c-d288-426c-872d-e86f3bf739ae",
  "status": 200,
  "data": {
            "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss",
            "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss"
          }                                                    
}

Device receives a response, parses, considers that the request was successful.

Device sends a message with a lock opening log to server/request/v0/{serial_number}, adding token "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss" to the header array, because the specified endpoint requires authorization on the server.

{
  "request_id": "427a1ae0-b733-4bb7-a2b4-e86e56410bbf",
  "headers": [
                "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss",
                "Content-Type: application/json"
              ],
  "method": "PUT",
  "uri": "/api/v0/devices/logs",
  "data": {
            "events": [
              {
                "created_at": 1653561910116,
                "category": "access",
                "priority": "medium",
                "code": "access_granted_by_api_call",
                "info": {
                          "lock":  1
                        }
              }
            ]
          }
}

Server receives this message, parses it, and if the message is parsed, publishes a message without a response body with status 202 to the server/response/v0/{serial_number} topic, this will mean that the device has accepted the request and started processing it.
```
{
  "request_id": "427a1ae0-b733-4bb7-a2b4-e86e56410bbf",
  "status": 202,
  "data": null                                                    
}
```
Device receives a response with a 202 status, stops the wait timer for 202 and starts a new timer (similar to request timeout), for example for 600 seconds. If it does not receive a response 200, 400, 404, 422, 500 etc. then it will consider that the request was completed with an error.

Server finishes processing the request and publishes a response message with a 200 status to the server/response/v0/{serial_number} topic.

{
  "request_id": "427a1ae0-b733-4bb7-a2b4-e86e56410bbf",
  "status": 200,
  "data": null                                                  
}

Device receives a response, parses, considers that the request was successful.

Useful links

http://developers.bas-ip.com
- Devices API
https://app.swaggerhub.com/apis-docs/basip/galaxy-link-devices-interaction/1.2.0
- Server API examples with which devices interact

Servers
- production
Operations

Servers

`production` Server

URL: example.com:{port}
Protocol: mqtt

Test broker

URL Variables

Name	Description	Default value	Allowed values
port	Secure connection (TLS) is available through port 8883. By default connection between Link and intercoms secured by self-signed preinstalled certificate	`8883`	`1883`, `8883`

Security

Security Requirement 1

Type: User/Password Provide device serial number as username, and password

Operations

PUB `device/request/v0/{serial_number}` Operation

Topic for requests to the device API

Operation ID: device_request

Topic for requests to device API

Parameters

Name	Type	Description	Value	Constraints	Notes
serial_number	string	Device serial number (UUID)	-	-	required

Message Request to the device API `deviceRequest`

Content type: application/json

Devices API documentation available at https://developers.bas-ip.com

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are allowed
request_id	string	Unique request ID, UUID	-	-	-
headers	string	[] string same as HTTP headers	-	-	-
method	string	Same as HTTP request methods - GET, POST etc.	allowed (`"GET"`, `"POST"`, `"PUT"`, `"DELETE"`)	-	-
uri	string	Request URI to the device API	-	-	-
data	string	Null, string or JSON object, same as request body in HTTP requests	-	-	-

Examples of payload (generated)

{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "headers": [
    "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss",
    "Content-Type: application/json"
  ],
  "method": "GET",
  "uri": "/api/info",
  "data": "null"
}

SUB `device/response/v0/{serial_number}` Operation

Device response to the made requests

Operation ID: device_response

Topic to which device sends responses to API requests

Parameters

Name	Type	Description	Value	Constraints	Notes
serial_number	string	Device serial number (UUID)	-	-	required

`mqtt` Operation specific information

Name	Type	Description	Value	Constraints	Notes
qos	-	-	`"2"`	-	-
retain	-	-	`"true"`	-	-

Message Device response for the sent request `deviceResponse`

Content type: application/json

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are allowed
request_id	string	Unique request ID, UUID	-	-	-
status	integer	Same as HTTP response status	allowed (`200`, `202`, `400`, `404`, `422`, `500`)	-	-
data	object	Null, string or JSON object, same as request body in HTTP requests	-	-	additional properties are allowed

Examples of payload (generated)

{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "status": 200,
  "data": {
    "model": "aa12fb"
  }
}

PUB `server/request/v0/{serial_number}` Operation

Topic for requests to the server API and logs from device

Operation ID: server_request

Topic for requests to server API

Parameters

Name	Type	Description	Value	Constraints	Notes
serial_number	string	Device serial number (UUID)	-	-	required

Message Request to the server API `serverRequest`

Content type: application/json

Server API examples with which devices interact available at https://app.swaggerhub.com/apis-docs/basip/galaxy-link-devices-interaction/1.0.0

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are allowed
request_id	string	Unique request ID, UUID	-	-	-
headers	string	[] string same as HTTP headers	-	-	-
method	string	Same as HTTP request methods - GET, POST etc.	allowed (`"GET"`, `"POST"`, `"PUT"`, `"DELETE"`)	-	-
uri	string	Request URI to the server API	-	-	-
data	object	Null, string or JSON object, same as request body in HTTP requests	-	-	additional properties are allowed

Examples of payload (generated)

{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "headers": [
    "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiZXhwIjoxNjM1OTYwODA4fQ.-oSdDxGL7AWL80XS9msxdAyzSh1rfj_hpmbagu5nFss",
    "Content-Type: application/json"
  ],
  "method": "PUT",
  "uri": "/devices/logs",
  "data": {
    "events": [
      {
        "created_at": 1548836752282,
        "category": "access",
        "priority": "high",
        "code": "high",
        "info": null
      }
    ]
  }
}

SUB `server/response/v0/{serial_number}` Operation

Server response to the made request

Operation ID: server_response

Topic to which server sends responses to API requests

Parameters

Name	Type	Description	Value	Constraints	Notes
serial_number	string	Device serial number (UUID)	-	-	required

`mqtt` Operation specific information

Name	Type	Description	Value	Constraints	Notes
qos	-	-	`"2"`	-	-
retain	-	-	`"true"`	-	-

Message Server response for the sent request `serverResponse`

Content type: application/json

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are allowed
request_id	string	Unique request ID, UUID	-	-	-
status	integer	Same as HTTP response status	allowed (`200`, `202`, `400`, `401`, `403`, `404`, `422`, `500`)	-	-
data	object	Null, string or JSON object, same as request body in HTTP requests	-	-	additional properties are allowed

Examples of payload (generated)

{
  "request_id": "e912e4de-5838-4717-af20-37c4512dafcc",
  "status": 401,
  "data": {
    "message": "method_not_allowed"
  }
}

SUB `device/status/v0/{serial_number}` Operation

LWT enabled by default

Operation ID: device_status

Topic for device online/offline status

Parameters

Name	Type	Description	Value	Constraints	Notes
serial_number	string	Device serial number (UUID)	-	-	required

`mqtt` Operation specific information

Name	Type	Description	Value	Constraints	Notes
qos	-	-	`"2"`	-	-
retain	-	-	`"true"`	-	-

Message Device connection status `deviceStatus`

Content type: application/json

Payload

Name	Type	Description	Value	Constraints	Notes
(root)	object	-	-	-	additional properties are allowed
serial_number	string	Device serial number (UUID)	-	-	-
type	string	Device type	allowed (`"panel"`, `"monitor"`, `"accesscontroller"`, `"liftcontroller"`)	-	-
model	string	Device model	-	-	-
status	string	Device status	allowed (`"online"`, `"offline"`)	-	additional properties are allowed

Examples of payload (generated)

{
  "serial_number": "e912e4de-5838-4717-af20-37c4512dafcc",
  "type": "panel",
  "model": "aa14fb",
  "status": "online"
}

BAS-IP devices API via MQTT 1.0.0 documentation

Encryption​

Basic concepts​

Examples​

Server authorization on a device, and opening the device lock by the server​

Device authorization on a server, and sending log about opening the device lock by the server​

Useful links​

Table of Contents​

Servers​

production Server​

URL Variables​

Security​

Security Requirement 1​

Operations​

PUB device/request/v0/{serial_number} Operation​

Parameters​

Message Request to the device API deviceRequest​

Payload​

SUB device/response/v0/{serial_number} Operation​

Parameters​

mqtt Operation specific information​

Message Device response for the sent request deviceResponse​

Payload​

PUB server/request/v0/{serial_number} Operation​

Parameters​

Message Request to the server API serverRequest​

Payload​

SUB server/response/v0/{serial_number} Operation​

Parameters​

mqtt Operation specific information​

Message Server response for the sent request serverResponse​

Payload​

SUB device/status/v0/{serial_number} Operation​

Parameters​

mqtt Operation specific information​

Message Device connection status deviceStatus​

Payload​

Encryption

Basic concepts

Examples

Server authorization on a device, and opening the device lock by the server

Device authorization on a server, and sending log about opening the device lock by the server

Useful links

Table of Contents

Servers

`production` Server

URL Variables

Security

Security Requirement 1

Operations

PUB `device/request/v0/{serial_number}` Operation

Parameters

Message Request to the device API `deviceRequest`

Payload

SUB `device/response/v0/{serial_number}` Operation

Parameters

`mqtt` Operation specific information

Message Device response for the sent request `deviceResponse`

Payload

PUB `server/request/v0/{serial_number}` Operation

Parameters

Message Request to the server API `serverRequest`

Payload

SUB `server/response/v0/{serial_number}` Operation

Parameters

`mqtt` Operation specific information

Message Server response for the sent request `serverResponse`

Payload

SUB `device/status/v0/{serial_number}` Operation

Parameters

`mqtt` Operation specific information

Message Device connection status `deviceStatus`

Payload