LibOSDP: Open Supervised Device Protocol Implementation

While the core is written in C, LibOSDP provides bindings for several languages:

• C/C++: Uses a minimal API defined in include/osdp.h or include/osdp.hpp.
• Rust: Available via crates.io.
• Python: Available as a PyPI package.

In LibOSDP, commands and events are queued by reference. This means any object you submit to the library must remain alive and unmodified until the completion callback is triggered and returns ownership to you.

For resource-constrained environments without a heap, follow this pattern to avoid memory corruption:

1. Use a single static command/event object.
2. Use an in-flight flag to track the status.
3. Do not refill or modify the object while the flag is set.
4. Clear the in-flight flag only inside the completion callback.

For platforms with an allocator, you may alternatively use an 'allocate-per-submission' pattern as seen in the examples/c directory.

LibOSDP implements the OSDP protocol by managing communication between a Control Panel (CP) and one or more Peripheral Devices (PD). Your application interacts with the library through three primary constructs:

• Channel: The transport layer that enables communication between two OSDP devices.
• Commands: Actions initiated by a CP to a PD.
• Events: Actions or notifications initiated by a PD to a CP.

To use the library, you must:

1. Implement the osdp_channel interface.
2. Describe the device using osdp_pd_info_t.
3. Create an osdp_t context.
4. Call osdp_cp/pd_refresh() at least once every 50ms to satisfy protocol timing requirements.

LibOSDP uses a specific ownership model for commands and events: they are queued by reference. To prevent memory leaks or use-after-free errors, follow these rules:

1. Lifetime: A submitted object (command or event) must outlive the initial function call.
2. Handover: The object is handed back to the application exactly once via its completion callback.
3. Allocation Pattern: The safest pattern for production is to allocate the object per submission and free it inside the completion callback. This ensures the library no longer holds the object before it is destroyed.

The Python library is a high-level wrapper around the C library. It abstracts away several low-level requirements of the C API:

• Memory Management: Unlike the C library, which requires callers to keep objects alive manually, the Python library manages object lifecycles automatically.
• Thread Safety and Serialization: The C library requires calls against a device to be serialized against its refresh loop. The Python library handles this in the background by owning the refresh thread and serializing API calls against it. This makes every call safe to make from any thread.
• Non-blocking Status Checks: Status checks like is_online() and is_sc_active() are implemented to be lock-free, meaning polling these values will not wait on the serial bus.

As a result, commands and events are treated as ordinary Python objects that you can build, submit, and forget.

LibOSDP does not manage the physical transport layer. You must implement a subclass of osdp.Channel to bridge the library to your hardware (e.g., Serial, TCP/IP). Your implementation must provide read(max_bytes), write(data), and flush() methods.

import serial
from osdp import Channel

class SerialChannel(Channel):
    def __init__(self, device: str, speed: int = 115200):
        self.dev = serial.Serial(device, speed, timeout=0)

    def read(self, max_bytes: int) -> bytes:
        return self.dev.read(max_bytes)

    def write(self, data: bytes) -> int:
        return self.dev.write(data)

    def flush(self) -> None:
        self.dev.flush()

    def __del__(self):
        self.dev.close()

To use the libosdp Python bindings, you must install the libosdp package along with pyserial for serial communication support.

Run the following command to install the necessary dependencies:

python3 -m pip install pyserial libosdp

When using the TinyAES backend for Secure Channel, LibOSDP uses rand_u32(), which is backed by esp_random(). On ESP32, esp_random() provides true hardware entropy only when Wi-Fi, Bluetooth, or the SAR ADC entropy source is active.

If your application runs Secure Channel over TinyAES without using RF (Wi-Fi/BT), you must manually enable the entropy source to avoid using the predictable libc rand() fallback.

Important: The entropy source cannot be shared. You must call bootloader_random_enable() before osdp_pd_setup() and call bootloader_random_disable() before starting Wi-Fi or Bluetooth later.

// Example sequence for non-RF applications using TinyAES
bootloader_random_enable();
osdp_pd_setup(...);

// ... later, before starting Wi-Fi/BT
bootloader_random_disable();

To simulate communication between a CP and a PD on a single machine without physical hardware, use socat to create a pair of linked pseudo-terminal devices. This creates a virtual serial channel.

1. Create the linked pseudo-terminals:

socat pty,raw,echo=0,nonblock,link=/tmp/ttyS0 pty,raw,echo=0,nonblock,link=/tmp/ttyS1

2. In a separate terminal, start the CP application using the first device:

./examples/python/cp_app.py /tmp/ttyS0

3. Start the PD application using the second device:

./examples/python/pd_app.py /tmp/ttyS1