Control Panel

The following functions are used when OSDP is to be used in CP 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.

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

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_cp_setup(int num_pd, const osdp_pd_info_t *info)

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

Parameters:

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

Return values:

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

Parameters:

ctx – OSDP context

void osdp_cp_teardown(osdp_t *ctx)

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

Parameters:

ctx – OSDP context

Events

Events are generated by the PD and sent to the CP. The CP app can register a callback using osdp_cp_set_event_callback to get notified of events.

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

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

Param arg:

Opaque pointer provided by the application during callback registration.

Param pd:

PD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()

Param ev:

pointer to osdp_event struct (filled by libosdp).

Retval 0:

on handling the event successfully.

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

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 event structure document for more information on how the event structure is framed.

Commands

Commands are sent from the CP to the PD to perform various actions. The CP app has to create a command struct and then call osdp_cp_send_command to enqueue the command to a particular PD.

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

Generic command enqueue API.

Note

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

Parameters:

  • ctx – OSDP context

  • pd – PD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()

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

Return values:

  • 0 – on success

  • -1 – on failure

int osdp_cp_flush_commands(osdp_t *ctx, int pd)

Deletes all commands queued for a give PD.

Parameters:
Returns:

int Count of events dequeued

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.

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

int osdp_cp_get_capability(const 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.

Parameters:
Return values:

  • 0 – on success

  • -1 – on failure

Others

int osdp_cp_get_pd_id(const 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.

Parameters:

  • ctx – OSDP context

  • pd – PD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()

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

Return values:

  • 0 – on success

  • -1 – on failure

int osdp_cp_modify_flag(osdp_t *ctx, int pd, uint32_t flags, bool do_set)

Set or clear OSDP public flags.

Note

It doesn’t make sense to call some initialization time flags during runtime. This method is for dynamic flags that can be turned on/off at runtime.

Parameters:

  • ctx – OSDP context

  • pd – PD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()

  • flags – One or more of the public flags (OSDP_FLAG_XXX) exported from osdp.h. Any other bits will cause this method to fail.

  • do_set – when true: set flags in ctx; when false: clear flags in ctx

Return values:

  • 0 – on success

  • -1 – on failure