OSDP specification
Open Supervised Device Protocol (OSDP)call_made is an access control communications standard maintained by the Security Industry Association (SIA)call_made. This page describes how we've implemented the official OSDP specificationcall_made in our reader firmware. Currently, we support version 2.1.7. Make sure you're familiar with the specification as the below documentation refers to it.
Supported hardware
OSDP is supported by BALTECH ACCESS2xx readers. They include the following components:
- Tamper switch
The firmware monitors the tamper switch and sends tamper change notifications as osdp_ACK replies. - Brownout detection
The firmware provides brownout monitoring and sends notifications as osdp_ACK replies. - Relay
It is controlled by output 0. - 1 bi-color LED (red/green)
- 1 beeper
Operation mode
OSDP requires our readers to run in Autoread mode. All other operation modes are not supported.
Supported commands
Command | Value | Meaning | Data |
---|---|---|---|
osdp_POLL | 0x60 | Poll | None |
osdp_ID | 0x61 | ID Report Request | ID type |
osdp_CAP | 0x62 | PD Capabilities Request | Reply type |
osdp_LSTAT | 0x64 | Local Status Report Request | None |
osdp_OSTAT | 0x66 | Output Status Report Request | None |
osdp_RSTAT | 0x67 | Reader Status Report Request | None |
osdp_OUT | 0x68 | Output Control Command | Output settings |
osdp_LED | 0x69 | Reader Led Control Command | LED settings |
osdp_BUZ | 0x6A | Reader Buzzer Control Command | Buzzer settings |
osdp_COMSET | 0x6E | PD Communication Configuration Command | Com settings |
osdp_KEYSET | 0x75 | Encryption Key Set Command | Encryption key |
osdp_CHLNG | 0x76 | Challenge and Secure Session Initialization Request | Challenge data |
osdp_SCRYPT | 0x77 | Server Cryptogram | Encryption data |
osdp_MFG | 0x80 | Manufacturer Specific Command | Any |
Supported Replies
Reply | Value | Meaning | Data |
---|---|---|---|
osdp_ACK | 0x40 | Command accepted, nothing else to report | None |
osdp_NACK | 0x41 | Command not processed | Reason for rejecting command |
osdp_PDID | 0x45 | PD ID Report | Report data |
osdp_PDCAP | 0x46 | PD Capabilities Report | Report data |
osdp_LSTATR | 0x48 | Local Status Report | Report data |
osdp_OSTATR | 0x4A | Output Status Report | Report data |
osdp_RSTATR | 0x4B | Reader Status Report | Report data |
osdp_RAW | 0x50 | Reader Data - Raw bit image of card data | Card data |
osdp_FMT | 0x51 | Reader Data - Formatted character stream | Card data |
osdp_KEYPAD | 0x53 | Keypad Data | Keypad data |
osdp_COM | 0x54 | PD Communications Configuration Report | Comm data |
osdp_CCRYPT | 0x76 | Client's ID, Random Number, and Cryptogram | Encryption data |
osdp_RMAC_I | 0x78 | Initial R-MAC | Encryption data |
osdp_BUSY | 0x79 | PD is Busy reply | None |
osdp_MFGREP | 0x90 | Manufacturer Specific Reply | Any |
Exchange BRP frames
You can send BRP commands to the reader using the manufacturer specific command osdp_MFG (see chapter 3.20 in the OSDP specification). The BRP command frame is transmitted as command specific data (bytes 4-n). The reader will respond with an osdp_MFGREP reply. The BRP response frame is transmitted as reply specific data (bytes 4-n).
For BRP security, you can implement AES encryption with strongly scalable access conditions. To send secured OSDP messages, you have to authenticate via security level 1 by default. Unsecured OSDP messages will be sent via an unencrypted connection.
Assign bus address
By default, ACCESS2xx readers have Wiegand enabled. To switch from Wiegand to OSDP, set a bus address on each reader. You can use BALTECH AdrCard to set a bus address between 0 and 16 or delete an assigned address. For security reasons, this only works when the tamper switch is open.
Alternatively, you can set a bus address via the reader configuration.
Configuration
Below, you'll find a description of the configuration values and their default settings. To make changes, you have the following possibilities:
- Create your own device settings
via the form in BALTECH ConfigEditor.
Where this is possible, the corresponding option in the form is indicated. - Order a custom configuration.
- Change the value via the OSDP controller if you create your own one.
Bus address
If you don't want to use BALTECH AdrCard to assign a bus address to each reader, you can set a fixed bus address via the configuration. All readers will receive this address and won't accept AdrCards anymore.
-
Configuration value: Addresscall_made
This value corresponds to the Bus address option in the device settings form of BALTECH ConfigEditor. -
Default: 0
Baud rate
-
Configuration value: BaudRatecall_made
This value corresponds to the Baud rate option in the device settings form of BALTECH ConfigEditor. -
Default: 9600
Inter-character timeout
- Configuration value: CharTimeOutcall_made
- Default: 20 ms
OSDP message type
-
Configuration value: DataModecall_made
-
Default: BitstreamRaw (corresponds to the OSDP message type OSDP_raw)
Host message format
The reader converts data read from the card to ASCII decimal. If the host expects a different format, the reader reconverts the ASCII data to that format (learn more).
- Configuration value: HostMsgFormatTemplatecall_made
- Default: Binary
This default setting matches the default message type osdp_RAW (i.e. DataModecall_made set to BitstreamRaw or BitstreamWiegand). It's automatically set when OSDP device settings are deployed or when a bus address has been assigned with BALTECH AdrCard.
If the message type is changed to osdp_FMT (i.e. DataModecall_made is set to Ascii), HostMsgFormatTemplatecall_made must be disabled.
Protocol encryption
This configuration value is needed to enable encryption as described in Appendix D of the OSDP specification. You can use it to enable install and/or secure mode.
-
Configuration value: SecureInstallModecall_made (reflects version 2 of the OSDP specification)
This value corresponds to the Spec compliance option in the device settings form of BALTECH ConfigEditor. -
Default: Communication without security (reflects version 1 of the OSDP specification)
Default Secure Channel Base Key (SDBK-D)
-
Configuration value: SCBKeyDefaultcall_made
-
Default: 0x30..0x3F
The value is read protected and is applied in conjunction with OSDP protocol encryption. You can change this value to a different SDBK-D. To do so, you can specify a diversified or non-diversified key. In the latter case, set the parameter DiversifyFlag to WillBeDiversified. The reader will then diversify the key according to Appendix D.4.1 of the OSDP specification (v2.1.7) and delete the non-diversified key afterwards.
Secure Channel Base Key (SDBK)
- Configuration value: SCBKeycall_made
- Default: none; communication is unencrypted
This configuration value stores the SDBK key once you've deployed it. The value is read protected and is applied in conjunction with OSDP protocol encryption.
To deploy the SDBK, you have 2 options:
- OSDP install mode
Enable install mode, authenticate with the SDBK-D and deploy the (diversified) SDBK. After the SDBK has been deployed, install mode is automatically terminated. - BALTECH ConfigCard
Alternatively, you can use a BALTECH ConfigCard to deploy an SCBK. If you want the SCBK to be diversified, set the parameter DiversifyFlag to WillBeDiversified. The reader will then diversify the key according to Appendix D.4.1 of the OSDP specification (v2.1.7) and delete the non-diversified key afterwards.
Firmware upgrades
When upgrading the reader firmware via the OSDP controller, you need to deploy the new firmware version in BF3SEC format.
Do not use a BF2 or BF3 file: Deploying these files will require you to do a factory reset first, which deletes the reader's bus address and makes any further communication with the reader impossible.