Peripheral Device

The following functions are used when OSDP is to be used in pd mode. The library returns a single opaque pointer of type osdp_t where it maintains all it’s internal data. All applications consuming this library must pass this context pointer all API calls.

Device lifecycle management

typedef void osdp_t

To keep the OSDP internal data structures from polluting the exposed headers, they are typedefed to void before sending them to the upper layers. This level of abstraction looked reasonable as technically no one should attempt to modify it outside of the LibOSDP and their definition may change at any time.

struct osdp_pd_info_t

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

Public Members

const char *name

User provided name for this PD (log messages include this name)

int baud_rate

Can be one of 9600/19200/38400/57600/115200/230400

int address

7 bit PD address. the rest of the bits are ignored. The special address 0x7F is used for broadcast. So there can be 2^7-1 devices on a multi-drop channel

int flags

Used to modify the way the context is setup. See OSDP_FLAG_* macros.

struct osdp_pd_id id

Static information that the PD reports to the CP when it received a CMD_ID. These information must be populated by a PD application.

const struct osdp_pd_cap *cap

This is a pointer to an array of structures containing the PD’ capabilities. Use { -1, 0, 0 } to terminate the array. This is used only PD mode of operation

struct osdp_channel channel

Communication channel ops structure, containing send/recv function pointers

const uint8_t *scbk

Pointer to 16 bytes of Secure Channel Base Key for the PD. If non-null, this is used to set-up the secure channel.

osdp_t *osdp_pd_setup(const osdp_pd_info_t *info)

This method is used to setup a device in PD mode. Application must store the returned context pointer and pass it back to all OSDP functions intact.

Parameters:

info – Pointer to info struct populated by application.

Return values:

  • OSDP – Context on success

  • NULL – on errors

void osdp_pd_refresh(osdp_t *ctx)

Periodic refresh method. Must be called by the application at least once every 50ms to meet OSDP timing requirements.

Parameters:

ctx – OSDP context

void osdp_pd_teardown(osdp_t *ctx)

Cleanup all osdp resources. The context pointer is no longer valid after this call.

Parameters:

ctx – OSDP context

PD Capabilities

struct osdp_pd_cap

PD capability structure. Each PD capability has a 3 byte representation.

Public Members

uint8_t function_code

Capability function code. See osdp_pd_cap_function_code_e

uint8_t compliance_level

A function_code dependent number that indicates what the PD can do with this capability.

uint8_t num_items

Number of such capability entities in PD

void osdp_pd_set_capabilities(osdp_t *ctx, const struct osdp_pd_cap *cap)

Set PD’s capabilities.

Parameters:

  • ctx – OSDP context

  • cap – pointer to array of cap (struct osdp_pd_cap) terminated by a capability with cap->function_code set to 0.

Commands

typedef int (*pd_command_callback_t)(void *arg, struct osdp_cmd *cmd)

Callback for PD command notifications. After it has been registered with osdp_pd_set_command_callback, this method is invoked when the PD receives a command from the CP.

Param arg:

pointer that will was passed to the arg param of osdp_pd_set_command_callback.

Param cmd:

pointer to the received command.

Retval 0:

if LibOSDP must send a osdp_ACK response

Retval -ve:

if LibOSDP must send a osdp_NAK response

Retval +ve:

and modify the passed struct osdp_cmd *cmd if LibOSDP must send a specific response. This is useful for sending manufacturer specific reply osdp_MFGREP.

void osdp_pd_set_command_callback(osdp_t *ctx, pd_command_callback_t cb, void *arg)

Set callback method for PD command notification. This callback is invoked when the PD receives a command from the CP.

Parameters:

  • ctx – OSDP context

  • cb – The callback function’s pointer

  • arg – A pointer that will be passed as the first argument of cb

Refer to the command structure document for more information on how the cmd structure is framed.

Events

When a PD app has some event (card read, key press, etc.,) to be reported to the CP, it creates the corresponding event structure and calls osdp_pd_notify_event to deliver it to the CP on the next osdp_POLL command.

int osdp_pd_notify_event(osdp_t *ctx, const struct osdp_event *event)

API to notify PD events to CP. These events are sent to the CP as an alternate response to a POLL command.

Parameters:

  • ctx – OSDP context

  • event – pointer to event struct. Must be filled by application.

Return values:

  • 0 – on success

  • -1 – on failure

int osdp_pd_flush_events(osdp_t *ctx)

Deletes all events from the PD’s event queue.

Parameters:

ctx – OSDP context

Returns:

int Count of events dequeued.

Refer to the event structure document for more information on how to populate the event structure for these function.