Control Panel

The following functions are used when OSDP is to be used in CP mode.

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_cp_setup(int num_pd, osdp_pd_info_t *info, uint8_t *master_key) __attribute__((deprecated("Use osdp_cp_setup2 instead!")))

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

Note: Master key based SCBK derivation is discouraged. Pass SCBK for each connected PD in osdp_pd_info_t::scbk.

  • num_pd – Number of PDs connected to this CP. The osdp_pd_info_t * is treated as an array of length num_pd.

  • info – Pointer to info struct populated by application.

  • master_key – 16 byte Master Key from which the SCBK (Secure Channel Base KEY) is generated. If this field is NULL, then secure channel is disabled.


  • OSDP – Context on success

  • NULL – on errors

void osdp_cp_refresh(osdp_t *ctx)

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


ctx – OSDP context

void osdp_cp_teardown(osdp_t *ctx)

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


ctx – OSDP context


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

typedef int (*cp_event_callback_t)(void *arg, int pd, struct osdp_event *ev)

Callback for CP event notifications. After is has been registered with osdp_cp_set_event_callback, this method is invoked when the CP receives an event from the PD.

Param arg

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

Param pd

PD offset number as in pd_info_t *.

Param ev

pointer to osdp_event struct (filled by libosdp).

  • 0 – on handling the event successfully.

  • -ve – on errors.

void osdp_cp_set_event_callback(osdp_t *ctx, cp_event_callback_t cb, void *arg)

Set callback method for CP event notification. This callback is invoked when the CP receives an event from the PD.

  • ctx – OSDP context

  • cb – The callback function’s pointer

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


For the CP application, it’s connected PDs are referenced by the offset number. This offset corresponds to the order in which the osdp_pd_info_t was populated when passed to osdp_cp_setup.

int osdp_cp_send_command(osdp_t *ctx, int pd, struct osdp_cmd *cmd)

Generic command enqueue API.


This method only adds the command on to a particular PD’s command queue. The command itself can fail due to various reasons.

  • ctx – OSDP context

  • pd – PD offset number as in pd_info_t *.

  • cmd – command pointer. Must be filled by application.


  • 0 – on success

  • -1 – on failure

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

Get PD capability

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.

int osdp_cp_get_capability(osdp_t *ctx, int pd, struct osdp_pd_cap *cap)

Get capability associated to a function_code that the PD reports in response to osdp_CAP(0x62) command. Calling this method before the CP has had a the chance to get this information will return invalid/stale results.

  • ctx – OSDP context

  • pd – PD offset number as in pd_info_t *.

  • cap – in/out; struct osdp_pd_cap pointer with osdp_pd_cap::function_code set to the function code to get data for.


  • 0 – on success

  • -1 – on failure


int osdp_cp_get_pd_id(osdp_t *ctx, int pd, struct osdp_pd_id *id)

Get PD ID information as reported by the PD. Calling this method before the CP has had a the chance to get this information will return invalid/stale results.

  • ctx – OSDP context

  • pd – PD offset number as in pd_info_t *.

  • id – A pointer to struct osdp_pd_id that will be filled with the PD ID information that the PD last returned.


  • 0 – on success

  • -1 – on failure