Crate libosdp

LibOSDP - Open Supervised Device Protocol Library

This is a cross-platform open source implementation of IEC 60839-11-5 Open Supervised Device Protocol (OSDP). The protocol is intended to improve interoperability among access control and security products. It supports Secure Channel (SC) for encrypted and authenticated communication between configured devices.

OSDP describes the communication protocol for interfacing one or more Peripheral Devices (PD) to a Control Panel (CP) over a two-wire RS-485 multi-drop serial communication channel. Nevertheless, this protocol can be used to transfer secure data over any stream based physical channel. Read more about OSDP here.

This protocol is developed and maintained by Security Industry Association (SIA).

Getting started

A device complying with OSDP can either be a CP or a PD. There can be only one CP on a bus which can talk to multiple PDs. LibOSDP allows your application to work either as a CP or a PD so depending on what you want to do you have to do some things differently.

LibOSDP creates the following constructs which allow interactions between devices on the OSDP bus. These should not be confused with the protocol specified terminologies that may use the same names. They are:

• Channel - Something that allows two OSDP devices to talk to each other
• Commands - A call for action from a control panel (CP) to peripheral device (PD)
• Events - A call for action from peripheral device (PD) to control panel (CP)

The app starts by defining a type that implements the Channel trait; this allows your devices to communicate with other osdp devices on the bus. Then you describe the PD you are

• talking to on the bus (in case of CP mode of operation) or,
• going to behave as on the bus (in case of PD mode of operation) by using the PdInfo struct.

You can use the PdInfo (or a vector of PdInfo structs in case of CP mode) to create a ControlPanel or PeripheralDevice context. Both these contexts have a non-blocking method refresh() that needs to called as frequently as your app can permit. To meet the OSDP specified timing requirements, your app must call this method at least once every 50ms.

After this point, the CP context can,

• send commands to any one of the PDs (to control LEDs, Buzzers, Input/Output pins, etc.,)
• register a closure for events that are sent from a PD

and the PD context can,

• notify it’s controlling CP about an event (card read, key press, tamper, etc.,)
• register a closure for commands issued by the CP

You can find a template implementation for CP app here and PD app here.

Structs

ControlPanel

OSDP CP device context.

OsdpComSet

Command to set the communication parameters for the PD. The effects of this command is expected to be be stored in PD’s non-volatile memory as the CP will expect the PD to be in this state moving forward.

OsdpCommandBuzzer

Command to control the behavior of a buzzer in the PD

OsdpCommandFileTx

Command to kick-off a file transfer to the PD.

OsdpCommandKeyset

Command to set secure channel keys to the PD.

OsdpCommandLed

Command to control the behavior of it’s on-board LEDs

OsdpCommandMfg

Command to to act as a wrapper for manufacturer specific commands

OsdpCommandOutput

Command to control digital output exposed by the PD.

OsdpCommandText

Command to manipulate the on-board display unit (Can be LED, LCD, 7-Segment, etc.,) on the PD.

OsdpEventCardRead

Event that describes card read activity on the PD

OsdpEventKeyPress

Event to describe a key press activity on the PD

OsdpEventMfgReply

Event to transport a Manufacturer specific command’s response.

OsdpFlag

OSDP setup flags

OsdpLedParams

LED params sub-structure. Part of LED command: OsdpCommandLed

OsdpStatusReport

Event to describe various status changes on PD

PdCapEntity

PD capability entity to be used inside PdCapability

PdId

PD ID information advertised by the PD.

PdInfo

OSDP PD Information. This struct is used to describe a PD to LibOSDP

PdInfoBuilder

OSDP PD Info Builder

PeripheralDevice

OSDP Peripheral Device (PD) context

Enums

ChannelError

OSDP channel errors

OsdpCardFormats

Various card formats that a PD can support. This is sent to CP when a PD must report a card read

OsdpCommand

CP interacts with and controls PDs by sending commands to it. The commands in this enum are specified by OSDP specification.

OsdpError

OSDP public errors

OsdpEvent

CP to intimate it about various events that originate there (such as key press, card reads, etc.,). They do this by creating an “event” and sending it to the CP. This module is responsible to handling such events though OsdpEvent.

OsdpLedColor

LED Colors as specified in OSDP for the on_color/off_color parameters.

OsdpStatusReportType

Status report type

PdCapability

OSDP defined PD capabilities. PDs expose/advertise features they support to the CP by means of “capabilities”.

Traits

Channel

The Channel trait acts as an interface for all channel implementors. See module description for the definition of a “channel” in LibOSDP.

ConvertEndian

Trait to convert between BigEndian and LittleEndian types

OsdpFileOps

File operations handler trait. Any type that implements this trait can be registered with crate::ControlPanel::register_file_ops or crate::PeripheralDevice::register_file_ops.

Functions

get_source_info

Get LibOSDP source info string

get_version

Get LibOSDP version