Python API Reference

Everything below is importable from the top-level osdp package:

from osdp import (
    ControlPanel, PeripheralDevice, PDInfo, PdId, PDCapabilities,
    KeyStore, Channel,
    Command, CommandLEDColor, CommandFileTxFlags, Event, Notification,
    CardFormat, Capability, LibFlag, LogLevel, StatusReportType,
    CompletionStatus, FileTxOutcome,
)

ControlPanel ​

Drives one or more PDs. Construct it with a list of PDInfo.

ControlPanel(
    pd_info_list: list[PDInfo],
    log_level: LogLevel = LogLevel.Info,
    event_handler: Callable[[int, dict], int] = None,
    command_completion_handler: Callable[[int, dict, int], None] = None,
)

Method	Description
start()	Start the background refresh thread.
stop() / teardown()	Stop the thread / fully tear the context down.
sc_wait_all(timeout=5)	Block until every PD has an active secure channel.
sc_wait(address, timeout=5)	Block until one PD's secure channel is active.
online_wait_all(timeout=10) / online_wait(address, timeout=8)	Block until PDs are online.
offline_wait(address, timeout=8)	Block until a PD goes offline.
send_command(address, cmd)	Queue a command dict for a PD.
submit_command(address, cmd)	Lower-level command submit.
flush_commands(address)	Drop pending commands for a PD.
get_event(address, timeout=5)	Pop the next event dict from a PD, or None.
set_event_handler(handler)	handler(address, event) -> int, called for every event.
set_command_completion_handler(handler)	handler(address, command, status); status is a CompletionStatus.
is_online(address) / get_num_online()	Online status helpers.
is_sc_active(address) / get_num_sc_active()	Secure-channel status helpers.
get_pd_id(address) -> PdId	Read a PD's reported identity.
check_capability(address, cap) -> (compliance, num_items)	Query a Capability.
set_flag(address, flag) / clear_flag(address, flag)	Toggle a LibFlag at runtime.
enable_pd(address) / disable_pd(address) / is_pd_enabled(address)	Enable/disable a PD.
register_file_ops(address, fops) / get_file_tx_status(address)	File-transfer hooks.
get_metrics(address)	Per-PD metrics.

set_event_handler and get_event() are two ways to consume the same events — register a handler for push delivery, or poll get_event(). The default handler feeds the internal queue that get_event() reads from.

PeripheralDevice ​

Acts as a single PD. Construct it with a PDInfo and a PDCapabilities.

PeripheralDevice(
    pd_info: PDInfo,
    pd_cap: PDCapabilities,
    log_level: LogLevel = LogLevel.Info,
    command_handler: Callable[[dict], Tuple[int, dict]] = None,
    event_completion_handler: Callable[[dict, int], None] = None,
)

Method	Description
start()	Start the background refresh thread.
stop() / teardown()	Stop the thread / fully tear the context down.
sc_wait(timeout=8)	Block until the secure channel is active.
notify_event(event) / submit_event(event)	Send an event dict to the CP.
get_command(timeout=5)	Pop the next command dict from the CP, or None.
set_command_handler(handler)	handler(command) -> (retcode, reply_dict), called for every command.
set_event_completion_handler(handler)	handler(event, status); status is a CompletionStatus.
is_online() / is_sc_active()	Status helpers.
register_file_ops(fops) / get_file_tx_status()	File-transfer hooks.
get_metrics()	PD metrics.

As with the CP, set_command_handler (push) and get_command() (poll) are two views of the same command stream.

PDInfo ​

Describes one PD to the library.

PDInfo(
    address: int,
    channel: Channel,
    scbk: bytes = None,        # 16-byte Secure Channel Base Key; None = install mode
    name: str = None,          # defaults to "PD-<address>"
    flags = [],                # list of LibFlag values
    id: PdId = None,           # defaults to a placeholder PdId
    baud_rate: int = 9600,
)

Pass scbk=KeyStore.gen_key() to provision a random key, or scbk=None to put the device in install mode. See Secure Channel.

PdId ​

The identity a PD reports to a CP (also returned by ControlPanel.get_pd_id).

PdId(
    version: int,
    model: int,
    vendor_code: int,
    serial_number: int,
    firmware_version: int,
)

PDCapabilities ​

Declares what a PD can do. Built from a list of (Capability, compliance_level, num_items) tuples:

PDCapabilities([
    (Capability.OutputControl, 1, 1),
    (Capability.LEDControl, 2, 1),
])

KeyStore ​

Helpers for managing Secure Channel Base Keys.

Method	Description
KeyStore.gen_key(key_len=16)(static)	Return a random key as bytes.
KeyStore(dir=None)	Open/create a keystore backed by a directory.
new_key(name, key_len=16, force=True)	Generate and stage a named key.
get_key(name) / load_key(name, key_len=16)	Read a named key.
update_key(name, key) / commit_key(name)	Replace / persist a key.

Channel ​

Abstract transport. Subclass it and implement the three methods:

from osdp import Channel

class MyChannel(Channel):
    def read(self, max_bytes: int) -> bytes: ...
    def write(self, buf: bytes) -> int: ...   # return bytes actually written
    def flush(self) -> None: ...

See Getting Started for a pyserial implementation.

Enumerations ​

These constant classes mirror the C enums in osdp.h.

Command ​

Output, Buzzer, LED, Comset, ComsetDone, Text, Manufacturer, Keyset, FileTransfer, Status, Notification. Used as the command key in command dicts.

Event ​

CardRead, KeyPress, ManufacturerReply, Status, Notification. Used as the event key in event dicts.

CommandLEDColor ​

Black, Red, Green, Amber, Blue, Magenta, Cyan, White.

CardFormat ​

Unspecified, Wiegand, ASCII. Used as the format key in a CardRead event.

Capability ​

Unused, ContactStatusMonitoring, OutputControl, CardDataFormat, LEDControl, AudibleControl, TextOutput, TimeKeeping, CheckCharacter, CommunicationSecurity, ReceiveBufferSize, CombinedMessageSize, SmartCard, Readers, Biometrics.

StatusReportType ​

Local, Input, Output, Remote. Used as the type key in Status commands/events.

LibFlag ​

EnforceSecure, InstallMode, IgnoreUnsolicited, EnableNotification, CapturePackets, AllowEmptyEncryptedDataBlock. Passed in PDInfo(flags=[...]) or toggled via ControlPanel.set_flag / clear_flag.

LogLevel ​

Emergency, Alert, Critical, Error, Warning, Notice, Info, Debug.

CompletionStatus ​

Ok, Failed, Flushed, Aborted. Delivered to the command/event completion handlers.

FileTxOutcome ​

Ok, OkRebooting, Aborted, Unrecognized, Invalid.

Notification ​

Command, SecureChannelStatus, PeripheralDeviceStatus, FileTransferDone.

CommandFileTxFlags ​

Cancel.