BAS-IP Camdroid panels API interaction description

The following document outlines every API route available for the next models of BAS-IP Camdroid outdoor panels:

• Panels with only one direct call button, without display, and with camera:
  • av-01bd
  • av-01d
  • av-01ed
  • av-01md
  • av-01mfd
  • av-02d
  • av-03bd
  • av-03d
  • av-04fd
  • av-04sd
  • av-05fd
  • av-05sd
• Panels with only one direct call button, without display, and with keyboard:
  • av-01kd
• Panels with only one direct call button, without display, and without camera:
  • av-02idr
  • av-02fdr
  • av-04afd
  • av-04asd
• Panels with a few direct call buttons and without display:
  • ba-04bd
  • bi-08bd
  • bi-12bd
• Controllers and readers:
  • cr-02bd

Shortcomings

This document describes the requests and responses can be sent to and received from the devices, but does not describe device interaction with other structures, such as authorization or token refresh on the Link management server, identifiers validating on the 3d-party remote management servers etc. This information can be obtained upon request and will be added to the documentation in the future.

This document does not describe all the capabilities of the devices, but only the main parts and the key interaction between the components, to familiarize yourself with all the features, please refer to the API specification.

Authentication

Bearer Authentication

API offers bearer authentication without support of refresh tokens. Token storage time - 2 hours.

Device features

Getting basic information about the device

To get basic information about the device - its model, serial number and firmware version, you need to make a GET request to the /api/info endpoint.

In responce you will get similar values:

{
  "firmware_version": "2.3.0",
  "framework_version": "1.2.0",
  "frontend_version": "1.2.0",
  "api_version": "0.5.0",
  "device_name": "AV-03",
  "device_type": "panel",
  "device_serial_number": "203684c4-31d4-49c2-894c-832962f66690",
}

Link and 3d-party servers interaction

Interaction with Link and 3d-party servers servers occurs using REST API, this document describes requests to the device and device responses, requests from the device will be referenced in the document sections involve corresponding functionality.

Link server, device web interface and third-party servers use the same API to interact with the device, but there are some differences in how the Link and the web interface interact with the device table entities.

Device web interface allows you to work with table entities such as identifiers, apartments, forwards, and time profiles one at a time, as the user does. When creating an entity, it is created with a local uid, which is unique only within this device and which is used as a unique key for working with the entity.

For management from the server, the ability to use mass entity management is required, besides, a frequent task is to synchronize the same entities on different devices, which makes it impossible to use uid as a unique entity key.

To solve this problem, link_id is used, which is a unique number of the entity on the Link server or a third-party server.

Device auth on server

Device uses JWT for auth purpsoses.

Device authentication and authorization on the server, and subsequent interaction with requests are performed as follows:

1. Device sends login/password to the server.
2. In case of successful authentication, the server sends to the device access token and refresh token.
3. For each subsequent request, device uses access token in the header.
4. If server replies that access token's lifetime has expired, then device sends a refresh token to receive a new access token from server.
5. If server replies that refresh token's lifetime has expired, then device must authenticate with the login/password again to receive a new pair of tokens.

Heartbeat

On 3d-party server side it's possible to implement the panel's heath status using this feature

Panel can send a POST request to the server /devices/pong endpoint with its type, model name, and serial number as string resources once every 10 seconds, letting server know that it's still online.

{
  "type": "panel",
  "model": "AV-03",
  "serial_number": "203684c4-31d4-49c2-894c-832962f66690"
}

Feature can be enabled by the heartbeat parameter in the /network/management/remotes endpoint.

Table entities CRUD and other interaction

Device has the following entities, which are located in tables and user can interacts with them in a similar way:

• identifiers
• apartments
• forwards
• time profiles

Mass CRUD interaction notes

When requesting to the endpoints for the mass DELETE all requested existing entities will be removed from the list, nonexistent identifiers will be skipped. When requesting to the endpoints for the mass CRUD interaction you will receive status responce about every entity operation was performed - created, updated, deleted etc.

Identifiers

Identifier - an entity contains information about the type of identifier (card, code, face ID, QR code, etc.), its number, owner, number of the lock being opened, etc.

Following endpoints are available for basic CRUD operations:

• Create identifier - POST to the /access/identifier. In response you will get identifier local uid, which is used to interact with identifier in the panel.

  We don't use the identifier number as an ID for it in the panel memory to avoid collisions, because identifier numbers can be the same for different types of identifiers. The same identifier, but recorded in another device may have a different local uid, so if you need a unique identifier between several devices, please use link_id.

• Read information about identifier - GET to the /access/identifier/item/{identifierUid}. Device will return infomation about identifiers and connected to it other entities, such as apartments, time profiles, link_id etc.
• Update identifier - PATCH to the /access/identifier/item/{identifierUid}.
• Delete identifier - DELETE to the /access/identifier/item/{identifierUid}.

Following endpoints are available for mass CRUD operations:

• Create/Update multiple identifiers - POST to the /access/identifier/items/link. When adding or updating entities link_id must be used.
• Read identifiers list - GET to the /access/identifier/items. Device will return identifiers list according to the requested filters.
• Read identifiers list with link_id - GET to the /access/identifier/items/link. Device will return identifiers list according to the requested filters.
• Delete identifiers list by local uids - DELETE to the /access/identifier/items.
• Delete identifiers list by link_id - DELETE to the /access/identifier/items/link/.

Apartments

Apartment - an entity contains information about the address of the apartment owner within the existing logical addressing "building-unit-floor-apartment" and his name, this is the basic entity to which the other entities are attached - identifiers, and conditional forward rules.

Also the apartment onwers names and addresses in the apartments are used in the device address book, which optionally can be displayed on the screen.

Following endpoints are available for basic CRUD operations:

• Create apartment - POST to the /apartment. In response you will get apartment local uid, which is used to interact with apartment in the panel.
• Read information about apartment - GET to the /apartment/item/{apartmentUid}. Device will return infomation about apartment and connected to it other entities, such as identifiers uids, and conditional forward rules uids.
• Update apartment - PATCH to the /apartment​/item​/{apartmentUid}.
• Delete apartment - DELETE to the /apartment/item/{apartmentUid}.

Following endpoints are available for mass CRUD operations:

• Create/Update multiple apartments - POST to the /apartment/items/link. When adding or updating entities link_id must be used.
• Read apartments list - GET to the /apartment/items. Device will return apartments list according to the requested filters.
• Read apartments list with link_id - GET to the /apartment/items/link. Device will return apartments list according to the requested filters.
• Delete apartments list by local uids - DELETE to the /apartment/items.
• Delete apartments list by link_id - DELETE to the /apartment/items/link.

Forwards

Forward - an entity describing the conditional forwarding rule as "Full apartment number" - "Called SIP number". Each rule can contain up to 8 numbers, call to which can be performed simultaneously or in turn, changing the hop every 20 seconds, depending on the selected mode in the device settings.

Depending on the model, device can forward to the following types of numbers (a special prefix for the number is used):

• P2P SIP/SIP. Device automatically selects which protocol to call, depending on whether it's registered on the SIP server and whether the specified number is part of this SIP server.

Since device can call other devices/SIP phones using both the internal protocol and the forwarding rules, the call is made as follows:

1. User enter the required number on the keyboard and dial
2. Device send a broadcast request to the network to search for a BAS-IP response device
3. If there is no responce to broadcast within 1.5 seconds, then device checks the presence of such a number in the forwarding table and if it finds it, it calls the numbers recorded for this apartment.

User can combine different types of numbers in one rule. The exception is the simultaneous use of the SIP and the Vizit/Laskomex numbers when "All at once" mode is selected - calls to analog devices can only be made in turn.

Following endpoints are available for basic CRUD operations:

• Create/Update forward rule - POST to the /forward/item/{forwardUid}. Unlike other entities, you don't get uid in the response, because forwardUid is a unique identifier for this table.
• Delete forward rule - DELETE to the /forward/item/{forwardUid}.

Following endpoints are available for mass CRUD operations:

• Create/Update multiple forward rules with link_id - POST to the /forward/items/link.
• Read forward rules list - GET to the /forward/items. Device will return forward rules list according to the requested filters.
• Read forward rules list with link_id - GET to the /forward/items/link. Device will return forward rules list according to the requested filters.
• Delete forward rules list by link_id - DELETE to the /forward/items/link.

Time profiles

Time profile - an entity which can be bound to an identifier to restrict its use by date/time/number of passes with flexible repeated rules.

In the identifier settings there is also options for using some time limits and number of passes. If the identifier uses both its own time limits and the restrictions of the associated time profile, then both will be used, but the extreme limits of use will be set by the own identifier settings.

Following endpoints are available for basic CRUD operations:

• Create time profile - POST to the /access/timeprofile. In response you will get time profile local uid, which is used to interact with time profile in the panel.
• Read information about time profile - GET to the /access/timeprofile/item/{timeProfileUid}.
• Update time profile - PATCH to the /access/timeprofile/item/{timeProfileUid}.
• Delete time profile - DELETE to the /access​/timeprofile​/item​/{timeProfileUid}.

Following endpoints are available for mass CRUD operations:

• Create/Update multiple time profiles - POST to the /access/timeprofile/items/link. When adding or updating entities link_id must be used.
• Read time profiles list - GET to the /access/timeprofile/items. Device will return time profiles list according to the requested filters.
• Read time profiles list with link_id - GET to the /access/timeprofile/items/link. Device will return time profiles list according to the requested filters.
• Delete time profiles list by local uids - DELETE to the /access/timeprofile/items.
• Delete time profiles list by link_id - DELETE to the /access/timeprofile/items/link.

Connections between entities

Table entities can be interconnected, so when you receive data about the apartment entity, you can get additional information about identifiers and forward rules in this apartment, or in the logs you can know that the lock was opened by this or that user, a call was made by such a user and so on.

Entities have the following relationships:

• Time profiles can be connected to identifiers.
• Identifiers can be connected to apartments.

Making connections

Connections between entities are possible both by local uid and by link_id of these entities.

Making connection by uid:

• Connect time profile to identifier - POST to the /access/identifiers/item/{identifierUid}/timeProfile/{timeProfileUid}
• Connect identifier to apartment - POST to the /apartment/item/{apartmentUid}/identifier/{identifierUid}

Making connection between identifiers with time profiles, and identifers with apartments can be done by adding link_id of the time profiles and link_id of the apartment to the identifiers via /access/identifier/items/link/ endpoint.

Remove connections

Connections remove between entities are possible both by local uid and by link_id of these entities. Removing a connection does not delete the entity.

Removing connections by uid:

• Remove identifier from apartment - DELETE to the /apartment/item/unbind/identifier/{identifierUid}.
• Remove time profile from identifier - DELETE to the /access/identifiers/item/{identifierUid}/timeProfile/{timeProfileUid}.

Removing connection between identifiers with time profiles, and identifers with apartments can be done by removing link_id of the time profiles and link_id of the apartment from the identifiers via /access/identifier/items/link/ endpoint.

Pagination

Pagination works the same way for all the tables, available options are desribed in the PaginationOptions model.

Filtering in sections

General filtering mechanism is the same for all tables, but filtering parameters are different. Filtering mechanism and references to specific filters are described in ApartmentFilterGetOptions, ForwardFilterGetOptions, IdentifierFilterGetOptions, TimeProfileFilterGetOptions, and LogFilterGetOptions models.

Logs

Panels supports several modes of sending logs each of which is described below.

The device can store up to 10k records in the database. When the database is full, it clear the records that have already been sent to Link server. If the remaining memory is not enough for the operation, then device will delete the oldest 1k records.

Each event in the log has its own priority, category, and name. Currently available log records are presented in the table.

Event	Priority	Category	Initial firmware version
device_booted	Low	Info
incoming_call	Medium	Info
outgoing_call	Medium	Info
outgoing_call_missed	Medium	Info
access_granted_by_master_code	Medium	Access
access_granted_by_valid_identifier	Medium	Access
access_granted_by_api_call	Medium	Access
access_granted_by_remote_server_api_call	Medium	Access
access_granted_by_call_host	Medium	Access
lock_was_opened_by_exit_btn	Medium	Access
successful_login_api_call	Medium	System
sip_registration_lost	Medium	Info
door_was_closed	Medium	Access
door_was_opened	Medium	Access
door_sensor_was_opened	Medium	Access
door_sensor_was_closed	Medium	Acesss
emergency_lock_is_opened	Medium	Access
access_denied_by_not_valid_identifier	High	Access
access_denied_by_not_valid_input_code	High	Access
access_denied_by_remote_server_api_call	High	Access
access_denied_by_unknown_card	High	Access
access_denied_by_unknown_qr	High	Access
access_denied_by_web_api_call	High	Access
door_was_not_closed_too_long	High	Emergency
incorrect_login_api_call	High	System
emergency_start	Critical	Emergency
emergency_cancel	Critical	Emergency

Polling

By default, the device does not send logs anywhere, but you can use polling to get a log by the specified filter, device web interface does the same when you open the tab with the log.

To get the last 10 log entries you need to make a query to the /log/list endpoint in the followind kind:

/log/list?locale=en&limit=10&page_number=1

where

• locale - required locale
• limit - limiting the output of data in a request; available values: 10, 20, 30, 50
• page_number - chosen page number

In response you will receive information about the total number of records on all pages, the number of pages, all records for the specified page and a list of all other available filters.

You can also filter by time, priority, category and event name. The entire list of available filters is described in the endpoint specification.

Realtime

To send realtime logs to server this feature must be enabled in menu "Network" -> "Management system" of the device web interface or via /network/management/link endpoint.

When sending logs to Link or 3d-party server, device send logs during the origin of these events, but not more often than once per second. If device can't connect to the server then it use a buffer which is cleared when it's filled with 1k records, i.e. panel send the last 1k records to server, skip the rest of the records and Link or 3d-party server must pick them up later on its own, determining the difference by the synchronization timeout. The entire buffer is sent in one packet.

Device must authorize on the server before sending logs, process described in the relevant paragraph above.

Device send logs by the PUT requests to the /devices/logs endpont, the specification can be found in the corresponding document.

Access management

Access management includes:

• Common settings.
• Identifiers management.
• Access restrictions management.

Common settings

In the common setting you can:

• Read/set master card, which can be used by adding user cards by GET/POST to the /access/general/unlock/card/master endpoint. When administrator put this card to the reader, panel will wait 10 seconds for a new user card to be brought to the reader for adding. When a user card is brought, it will be written into memory and linked to the first apartment, therefore, this method of entering cards requires subsequent data management if you want the cards to have different owners.
• Enable/disable and read/set master code for panels with keyboards by GET/POST to the /access/general/unlock/input/code endpoint. Using this code the user can open the first lock connected to the panel. For better security it's recommended to use individual codes.

  Feature available only for panels with keyboard

• Read/set lock open time for both locks by GET/POST to the /access/general/lock/timeout/{lockNumber} endpoint.

  The panels have only one built-in relay for controlling the lock, the second lock is controlled by connecting the additional module SH-42.

• Read/set lock open delay time for both locks (after receiving a command to open the lock device will wait this time before open) by GET/POST to the /access/general/lock/delay/{lockNumber} endpoint.
• Read/set panel floor number by GET/POST to the /access/general/elevator/floor. If an elevator module EVRC-IP is installed in the system, then the response devices will be able to send the elevator to the panel floor when the lock is opened.
• Read/set status of security mode feature by GET/POST to the /access/general/security/monitor endpoint. If the feature is enabled, then when the card is brought to the panel reader, the security on the monitor in the apartment to which this card is linked will be turned off.
• Read status/change settings of help station feature by /device/feature/help-station. Feature allows to call the subscriber with a short press of the call button and at the same time close the relay, and with a long press of the call button - make a call normally.
• Read status/change settings of rescue service feature by /device/feature/rescue-service. Feature allows to close the relay when communication is established during a call and open it automatically when the door sensor contacts open.

Remote access

Remote access function can be used in projects in which it's undesirable to store data about identifiers in panels. When this function is enabled, the device sends any submitted identifier to the server and waits for a response from it for 10 seconds. Both Link and a third-party server can be used as a server. If the device has not received a response from the server within 10 seconds, then it checks for the presence of an identifier in its database and makes a decision on its own.

To control the function endpoint /access/general/remote/control/settings used.

Device sends identifiers to server for validation to the /identifiers/validate endpoint. More information about request available here.

After serrver have checked identifier and want to deny access, then server need to send GET requests to the /access/general/lock/open/remote/control/accepted/{lockNumber} endpoint. After receiving it, the device will play an error sound and show on the screen that access is denied.

Locks remote opening

You can open the first, second or both locks in the following ways:

• GET request to the /access/general/lock/open/remote/accepted/{lockNumber} endpoint.
• GET request to the /access/general/lock/open/remote/control/accepted/{lockNumber} endpoint.

The difference between this two endpoints is what the panel will write in its journal. When using the first endpoint, the panel will record that the door was opened by API (the same endpoint uses the web interface), when using the second - the door was opened from a remote server, which is convenient when using the feature above.

• Start/stop emergency mode by POST to the /access/general/lock/open/emergency and /access/general/lock/close/emergency, at which the device can open the specified locks for the time specified in the request, and close them on command or when the device is rebooted.

Modes of operation of the door sensor contacts

Device has a pair of dry contacts that can be used in different modes. Mode settings can be changed using /access/door/sensor endpoint.

• Door sensor mode. In this mode device detects the opening of contacts and sends information about this to the server after specified in the settings time, and repeats sending with the interval, which also specified in the settings. In addition, it's possibke to check the status of contacts using a GET request to the /access/door/status endpoint
• Concierge call mode. Device will call to the concierge when the contacts are closed. Feature can be used when connecting an additional button for people with limited mobility.

Conditional call forwarding

Interaction with entities in the forwarding table is described in one of the sections above.

Rules in the call forwarding table are needed if you want to make calls via P2P, SIP or analogue system (only for devices with installed hybrid module) to SIP or analogue device. The logic of device calls is as follows:

1. Device sent broadcast to the network with called device logical address consist of building # + unit # + floor # + apartment # and wait for the answer up to 1.5 seconds. If there is a response device in the network, then the device does not use the forwarding rules and call via internal protocol.
2. If device does not receive a response, then it looks for a rule inside the forwarding table and calls the list of numbers are specified for this rule.

The forwarding table consists of entries of the form "number entered on the keyboard" - "list of called P2P/SIP/analogue numbers".

Additional settings

RTSP feed

RTSP feed feature allows to change the video source when talking with the panel to one from the list by sending the corresponding DTMF codes.

To change the image source you need:

1. Specify a list of additional RTSP streams for device using /advanced/rtsp/feed endpoint.
2. Call from/to device, answer the call.
3. Press DTMF from 0 to 5, 0 - device own camera stream, 1-4 - additional RTSP streams.

Password change

There are 2 users in the panel, admin and manager. Admin has access to all settings, the manager does not have access control settings.

• Admin password can be changed by POST request to the /security/password/admin endpoint.
• Manager password can be changed by POST request to the /security/password/manager endpoint.

Backup/restore

System has 2 types of settings backups, which are performed separately:

• Tables data (identifiers, apartments, forwards, time profiles) backup/restore can be done using /system/settings/export/tables endpoint.
• Common data backup/restore can be done using /system/settings/backup/all endpoint.

System also makes an automatic backup when updating the firmware to a higher version. When rolling back the firmware to a previous version, if the database version has changed, the device will automatically restore the old data to ensure its operability, therefore it is always recommended to make backups of settings and user data when manually updating the firmware.

Default settings

Resetting the settings deletes all user data, set default settings for the common data and device automatically reboots.

You can restore default settings by the POST request to the /system/settings/default endpoint.

Firmware upgrade

Device can update the firmware from the BAS-IP server or from the user server, for example, if the user has custom features and does not want to receive general updates. It's also possible to manually update using the firmware file.

To update firmware from the server you need:

• Check update status one the server using GET request to the /system/firmware/check/status endpoint.
• To start the update send POST request to the /system/firmware/update/server endpoint.
• To get the updating status send GET request to the /system/firmware/update/status endpoint.

After finishing the update device reboot automatically.

To update firmware form the file you need:

• Upload firmware image using POST request to the /system/firmware/update/file endpoint.
• To start the update send POST request to the /system/firmware/update/server endpoint.

It is always recommended to make backups of settings and user data when updating the firmware.

Settings requiring device reboot

Device reboots automatically when performing the following operations:

• Backups import.
• Tables data import.
• Reset to default settings
• Firmware update.