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