OSDP Zephyr SDK

The OSDP Zephyr SDK is an access control SDK for teams building their own controllers (ACUs), readers and peripheral devices (PDs) on Zephyr RTOS. It starts from LibOSDP, the open-source OSDP library we maintain, and adds everything a shipping access control device needs around the protocol: hardware integration, Wiegand, NFC, key and settings persistence, file transfer, firmware update, sample applications and tests.

Everything in it is wired up the Zephyr way. Hardware is described in devicetree, features are switched on in Kconfig, and the SDK builds on Zephyr's own drivers and subsystems instead of working around them. Your firmware ends up looking like any well-structured Zephyr application, with no vendor framework, glue layer or second build system for your team to learn and carry.

You don't need custom hardware to start. The SDK runs out of the box on widely available Nordic and ST development kits, sold by every major electronics distributor. A complete ACU and PD setup, with NFC and Wiegand, can be on your bench within days. You prove your product's behaviour end to end before you commit to a board design, and your hardware team can design against a setup that already works.

This page describes what the SDK covers and what to expect when you adopt it. Integration guides, API reference and sample walkthroughs come with the SDK itself.

Who it is for ​

The SDK is written for embedded teams who:

• are building an OSDP controller, reader, keypad, I/O module or Wiegand-to-OSDP converter
• want to ship on Zephyr RTOS, or are already doing so
• need their device to pass SIA OSDP Verified testing without a long debug loop at the lab
• would rather spend their engineering time on product features than on bus drivers and protocol edge cases

If your product is a single device type today but may become a family, the SDK serves both roles from one codebase, so a controller and a reader can share the same foundation.

What the SDK covers ​

OSDP in both roles ​

• Controller (ACU) and peripheral (PD) roles on the same stack. A bus can be restarted in the other role at runtime.
• Secure Channel, including key changes from the controller and the default installation key.
• Multi-drop buses with several peripherals behind one controller, and several buses on one device.
• The standard command and reply set, delivered to your application as events, with non-blocking submission of commands and events and a report of how each one completed.
• Link and Secure Channel state reported to the application, so it can show, log or act on a peripheral going on or off the bus.

Settings and keys that persist ​

A device that loses its address, baud rate or keys after a power cut fails in the field and fails in verification. The SDK keeps them for you:

• Communication settings changed by the controller (address and baud rate) are saved and take effect on the next start.
• Secure Channel keys are saved, and on platforms with protected storage or a secure element they are kept there instead of in plain flash.
• Key changes are staged and only committed after the new key has been proven by a Secure Channel session, on both sides of the link. An interrupted key change falls back to the previous key instead of leaving the device unreachable.
• The application can read, change and clear the stored values, and is notified when they change.

Wiegand ​

Many installations mix OSDP and Wiegand hardware, and many migrations to OSDP happen one door at a time. The SDK includes a Wiegand driver written for Zephyr, independent of OSDP, so a device can do both:

• receive frames from Wiegand readers and transmit frames to Wiegand panels
• run receive and transmit ports side by side on the same device
• report malformed frames with the reason, rather than silently dropping them
• leave card formats to your application, with helpers for building and parsing them, and samples that handle common formats

That makes it straightforward to build controllers that accept OSDP and Wiegand readers on one panel, readers that offer both outputs, and converters that bridge between the two.

NFC card reading ​

The SDK integrates an NFC reader front end, so a reader product can be built on it directly:

• card detection, activation and identification of the card type
• smart-card (ISO-DEP) exchanges for cards that need them
• an NFC reader supported out of the box on the recommended development kits, for evaluation before your own reader board exists

Transparent reader support (TRS) ​

High-assurance credentials such as PIV and other smart-card based cards need more than a card number. The controller has to hold a secure conversation with the card itself. OSDP's Transparent Reader Support makes that possible over the reader bus, and few stacks implement it end to end.

The SDK does, on both sides of the link:

• As a PD, your reader passes card sessions straight through to the controller, so credential logic and keys stay in the panel and the reader stays simple.
• As an ACU, your controller drives those card sessions through any TRS-capable reader on the bus.
• Both roles run on the same Zephyr foundation, over Secure Channel, alongside the rest of the OSDP feature set.

That makes PIV-class card support a feature you configure rather than a protocol project you start.

File transfer and firmware update over OSDP ​

• Files move between controller and peripheral over the OSDP link that is already wired, with the transfer flow and error handling handled by the SDK.
• Firmware updates use that same transfer: the controller sends an image, and the peripheral applies it through Zephyr's native device firmware update path. Readers and modules in the field are updated over the bus, without opening a housing or attaching a programmer.
• The same mechanism carries your own files, such as configuration, display assets or credential data.

Manufacturer-specific commands ​

OSDP leaves room for vendor-defined commands and replies. The SDK lets your application add its own alongside the standard ones, on either side of the link, without touching the protocol layer. That is where most products put the features that set them apart.

Transports and hardware ​

• RS-485 with transceiver direction control, on DMA-capable and interrupt-driven UARTs.
• OSDP over other byte streams, such as USB, for tooling, bridges and test setups.
• Bus wiring, Wiegand lines and the NFC reader are described in devicetree, so bringing up a new board is a configuration change rather than a port.

Zephyr-native, so your code base stays clean ​

Many embedded SDKs bring their own world with them: a framework of their own, a parallel configuration system, glue code that only their authors understand. This one doesn't. The SDK is a regular Zephyr module, wired into Zephyr the way Zephyr's own drivers are:

• Devicetree describes your OSDP buses, transceivers, Wiegand ports and NFC reader. A board change is a devicetree change.
• Kconfig turns features on and off. Anything you don't use isn't compiled in.
• Zephyr's own subsystems handle settings, cryptography, secure storage, messaging and firmware update, so the SDK fits in with the rest of your firmware instead of standing apart from it.
• West delivers it. Your application lives in its own repository and imports the SDK at a release tag, which also pins the Zephyr version and dependencies that release was tested against.

The result is a product code base your team can read, review and maintain years from now, and one that any engineer who knows Zephyr can work on from day one.

Evaluate on off-the-shelf hardware ​

You don't need custom hardware to start. Our recommended evaluation setup uses popular Nordic and ST development kits and a standard NFC expansion board, all sold by the major electronics distributors. On that setup the SDK works out of the box.

• Build a complete controller and reader pair, with NFC and Wiegand, before a single schematic is drawn.
• Validate your product behaviour, card handling and conformance on the bench, then commit to a board design with confidence.
• Hand your hardware team a working reference to design against.

You are not tied to our recommendation. Because the SDK is Zephyr-native, it can be brought up on any Zephyr-supported board, including a development kit you already own or a board your team has designed in-house. We can help with that bring-up if you want it.

The SDK ships with sample applications for controllers, peripherals, Wiegand, NFC and transparent reader flows, ready to build on the recommended kits and to grow into your own firmware.

Quality and testing ​

• The SDK's test suites run without hardware, on Zephyr's native simulator over emulated buses.
• A real controller and a real peripheral are run against each other over cross-wired buses, on each supported UART backend.
• Every sample builds as part of the test run.
• The test suites ship with the SDK, so you can run them in your own CI against your configuration.

For device-level testing, Conformance Workspace on Osprio Mini runs structured OSDP conformance tests against your finished controller or reader.

Preparing for OSDP Verified ​

SIA's OSDP Verified program tests your finished product, and no SDK can certify a device on its own. The SDK is built to remove the usual reasons a device fails:

• key changes that are applied, persisted and recovered as the specification requires
• communication setting changes that survive a restart
• busy and error replies where the specification expects them
• Secure Channel behaviour aligned with the specification

Combined with your own conformance runs before submission, that keeps surprises at the test lab to a minimum.

Security ​

• Secure Channel cryptography uses Zephyr's PSA Crypto support.
• Secure key storage: keys go to the platform's protected storage where it exists, never left in plain flash.
• Secure element integration: for products that keep keys in dedicated security hardware, the SDK can work with a secure element so key material never leaves it.
• Card data is treated as a credential and is not written to logs at normal log levels.
• Reported vulnerabilities are handled under committed response times, and security fixes to LibOSDP are published upstream for everyone.

What comes with a licence ​

• SDK source, delivered through a private Git repository with tagged releases and release notes
• integration guides, API reference, devicetree binding reference and sample walkthroughs
• the supported Zephyr versions and boards for every release
• a list of the open-source components in each release with their versions and licence texts
• a year of updates and support, renewable yearly, with maintained release lines for security and interoperability fixes

The licence is perpetual and royalty-free. Licensing, support terms and optional engineering help are described on the OSDP Zephyr SDK product page.

Getting the SDK ​

Tell us what you are building, and we will send a quote and the licence terms. If you are not sure the SDK fits your product, ask us; the questions go to the engineers who maintain it. Both options are on the product page.