Safety: door locks and egress hardware affect life safety. Do not leave a door in a state where people cannot leave. Mains and lock power wiring in Australia must be done by a licensed electrician. Keep commissioning on a bench or with the door held open and a plan B.
1. Wiring
- RS-485 data on a twisted pair (labelled A/B or +/- depending on vendor), with the shield or signal ground as the manufacturer instructs. Reader power is separate (check the voltage on the reader datasheet).
- A/B labelling is inconsistent between vendors. If a reader is silent, swapping the pair is a common fix, but check the datasheet first.
- Daisy-chain multiple readers. Follow the controller vendor's advice on termination and the maximum number of readers per bus.
- OSDP uses 8 data bits, 1 stop bit and no parity. The baud rate must be one of 9600, 19200, 38400, 57600, 115200 or 230400. Many commissioning problems are simply a baud mismatch, so start with the rate the reader is documented to ship with and the one the controller expects.
- Set a unique address for each reader on the bus.
- Power the reader and check that the controller sees it online. Check the reader's identity and capabilities in the controller UI if it shows them.
- Test the basics: card read, beep, LED colour changes. These confirm two-way comms.
From the LibOSDP notes on how OSDP Secure Channel works:
- Secure Channel uses AES with a 128-bit key. The CP starts a session with a short handshake in which each side proves it holds the same Secure Channel Base Key (SCBK).
- A new reader in install mode uses a default key that is hardcoded and published in the OSDP spec. This is deliberately insecure and meant for provisioning. The controller then sends a new SCBK and the reader leaves install mode automatically.
- Do the keying on a controlled point-to-point link, not on a shared bus where someone could be listening or could impersonate a reader. The LibOSDP notes point out that some designs enter install mode with a button press at boot, which is weak against anyone with physical access, so think about reader tamper protection and mounting.
- Use a unique SCBK for each reader, as the specification recommends. Do not reuse one key for the whole site.
- Record who holds the keys and where they are stored. If the controller loses keys, you will need to re-provision the reader.
- After keying, confirm that the controller reports a secure session. A reader that falls back to plain text silently is a security hole, so look for a controller setting that refuses unsecured readers, if it has one.
- Reader flaps online and offline: baud, A/B swap, missing shield or ground, long unterminated runs, or two readers with the same address.
- Reader online but Secure Channel fails: mismatched SCBK, or the reader is no longer in install mode and has a different key from the controller. Re-provisioning is needed.
- Slow response: OSDP expects replies within 200 ms, and some converters add delay.
- Reader works with one controller but not another: check the version of OSDP and capabilities supported, and ask the vendors.
LibOSDP (Apache-2.0) has C code and Python bindings (pip install libosdp). The project's examples include a control panel app and a peripheral device app in Python (see examples/python on GitHub), and the PyPI page includes a quick start that creates a serial channel such as /dev/ttyUSB0 and a control panel. The LibOSDP docs describe a flag called OSDP_FLAG_ENFORCE_SECURE that makes secure channel mandatory and disallows install mode. This is the library's own behaviour for software built on it, not something you can set on a commercial reader.
With a USB to RS-485 adapter you can act as a CP on a bench to talk to a single reader. I have not tested this against any specific commercial reader, and the compatibility page says its results are community-sourced, so read it before assuming a model works. Do not connect a bench setup to a live door controller bus.
7. Handover
- Document reader addresses, baud, cable routes, and where keys are stored.
- Test fire alarm release and request-to-exit with the installer responsible for the doors.
- Do not leave default keys or install mode enabled on a reader that is in service.
Question for the group: what is the most common OSDP commissioning problem you have run into (baud, addressing, keying, wiring), and how did you track it down?