Skip to main content

OSDP

The osdp adapter runs as an ACU (Access Control Unit), polling one or more PDs (readers, keypads, auxiliary devices) over RS-485. It parses card reads and keypad presses and exposes peripheral control.

What it does​

  • Polls each configured PD and parses card reads (RAW / FMT) and keypad presses (KEYPAD).
  • Exposes REST actions for LED / buzzer / text / output control, plus generic raw-frame injection.
  • Publishes parsed events to MQTT/webhooks.

Configuration​

Configure the PDs on the port:

osdp.pds: [
  { "address": 0, "name": "Front Door", "secure": false },
  { "address": 1, "name": "Back Door",  "secure": true, "scbk": "<32 hex chars>" }
]
  • address — the PD's OSDP address.
  • name — a label for the UI/events.
  • secure — enable Secure Channel for this PD (see below).
  • scbk — 32 hex characters; blank installs the default SCBK_D (all zeros).

Secure Channel (beta)​

OmniBus implements OSDP Secure Channel per SIA OSDP v2.2:

  • AES-CMAC validated against NIST RFC 4493 test vectors.
  • Session-key derivation, server/client cryptograms, and the CHLNG/CCRYPT/SCRYPT/RMAC_I handshake are verified end-to-end against a conformant peer (libosdp) over a hardware-free interop harness.
  • Plaintext operation (poll, ID/CAP, card reads) is fully working.
  • The Secure Channel control plane is working: encrypted inbound replies (SCS_18, e.g. encrypted card data) are decrypted and their MACs verified; a reply that fails MAC verification is dropped (no chain advance, no decrypt, no dispatch) so a forged frame can't pass as card data.

:::caution Validate Secure Channel against your reader before production SCS_17 (sending encrypted commands) and KEYSET (installing an SCBK) are scaffolded but not yet validated against real hardware. Do one pass against your actual reader before relying on them in production. :::

Outputs​

OutputBehavior
TCPRaw frame transport.
MQTTPublishes card reads / keypad events; control via subscribed topics.
RESTLED/buzzer/text/output control + raw-frame injection.
WebhooksFan out card-read / keypad events.