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 strucutres from polluting the exposed headers, they are typedefed to void before sending them to the upper layers. This level of abstaction looked reasonable as technically no one should attempt to modify it outside fo 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.

param baud_rate

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

param 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

param flags

Used to modify the way the context is setup. See OSDP_FLAG_XXX

param id

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

param 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

param channel

Communication channel ops structure, containing send/recv function pointers.

param 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 instead of using the Master Key (in case of CP).

osdp_t *osdp_pd_setup(osdp_pd_info_t *info)

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

Parameters

info – Pointer to iinfo struct populated by application.

Returns

  • 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.

param function_code

One of enum osdp_pd_cap_function_code_e.

param compliance_level

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

param num_items

Number of such capability entities in PD.

void osdp_pd_set_capabilities(osdp_t *ctx, 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_commnand_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.

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

  • cmd – pointer to the received command.

Returns

  • 0 – if LibOSDP must send a osdp_ACK response

  • -ve – if LibOSDP must send a osdp_NAK response

  • +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_commnand_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. This function must return:

  • 0 if LibOSDP must send a osdp_ACK response

  • -ve if LibOSDP must send a osdp_NAK response

  • +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.

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 to populate the cmd structure for these function.

Events

struct osdp_event

OSDP Event structure.

param id

used to select specific event in union. See: enum osdp_event_type

param keypress

keypress event structure

param cardread

cardread event structure

param mfgrep

mfgrep event structure

int osdp_pd_notify_event(osdp_t *ctx, 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.

Returns

  • 0 – on success

  • -1 – on failure