Documentation

Control Panel

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

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

Device Lifecycle Management ​

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

functionosdp_cp_setup
osdp_t * osdp_cp_setup(const struct osdp_channel *channel, 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
channelPointer to shared channel ops used for this CP context.
num_pdNumber of PDs connected to this CP. The osdp_pd_info_t * is treated as an array of length num_pd.
infoPointer to info struct populated by application.
Returns
OSDPContext on success
NULLon errors
functionosdp_cp_add_pd
int osdp_cp_add_pd(osdp_t *ctx, int num_pd, const osdp_pd_info_t *info)

Adds more PD devices in the CP control list.

Parameters
ctxOSDP context
num_pdNumber of PDs connected to this CP. The osdp_pd_info_t * is treated as an array of length num_pd.
infoPointer to info struct populated by application.
Returns
0on success
-1on failure
functionosdp_cp_refresh
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
ctxOSDP context
functionosdp_cp_teardown
void osdp_cp_teardown(osdp_t *ctx)

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

Parameters
ctxOSDP context

Enabling and Disabling PDs ​

A PD can be temporarily taken off the polling loop without tearing down the CP context — useful when a device is known to be offline or under maintenance.

functionosdp_cp_disable_pd
int osdp_cp_disable_pd(osdp_t *ctx, int pd)

Disable a PD managed by the CP. Disabled PDs are brought to a safe state and will not process commands or generate events.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
Returns
0on success
-1on failure
functionosdp_cp_enable_pd
int osdp_cp_enable_pd(osdp_t *ctx, int pd)

Enable a previously disabled PD. The PD will start up as it would during initial setup.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
Returns
0on success
-1on failure
functionosdp_cp_is_pd_enabled
bool osdp_cp_is_pd_enabled(const osdp_t *ctx, int pd)

Check if a PD is currently enabled.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
Returns
trueif PD is enabled
falseif PD is disabled or on error

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 be notified of events.

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

Parameters
argOpaque pointer provided by the application during callback registration.
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
evpointer to osdp_event struct (filled by libosdp).
Returns
0on handling the event successfully.
-veon errors.
functionosdp_cp_set_event_callback
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
ctxOSDP context
cbThe callback function's pointer
argA 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 creates a command struct and calls osdp_cp_submit_command to enqueue it to a particular PD.

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

Submit CP commands to PD. These commands are queued to be sent to the PD at the next available opportunity. A successful return does not mean PD received it, it only means LibOSDP accepted this submission.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
cmdcommand pointer. Must be filled by application.
Returns
0on success
-1on failure
Command lifetime — queued by reference

An accepted command is queued by reference; LibOSDP does not copy it. The cmd you pass must stay alive and unmodified from a successful submission until the library is done with it. A command that lives on the stack of a function that returns, or one reused for a second submission while the first is still queued, corrupts the queue.

Ownership returns to your application when the command completion callback fires for that pointer (register it with osdp_cp_set_command_completion_callback). Every accepted command is reported exactly once — including those dropped by osdp_cp_flush_commands (OSDP_COMPLETION_FLUSHED) and osdp_cp_teardown (OSDP_COMPLETION_ABORTED) — so a heap-allocated command should be freed in that callback. On a -1 return the command was never queued and is yours to reuse at once.

functionosdp_cp_flush_commands
int osdp_cp_flush_commands(osdp_t *ctx, int pd)

Deletes all commands queued for a give PD.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
Returns
intint Count of events dequeued

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

Command Completion ​

Register a completion callback to learn when each submitted command leaves your ownership. The callback reports the outcome as an osdp_completion_status.

typedefcp_command_completion_callback_t
typedef void(* cp_command_completion_callback_t) (void *arg, int pd, const struct osdp_cmd *cmd, enum osdp_completion_status status)

Callback for CP command completion notifications.

functionosdp_cp_set_command_completion_callback
void osdp_cp_set_command_completion_callback(osdp_t *ctx, cp_command_completion_callback_t cb, void *arg)

Set callback method for CP command completion.

Parameters
ctxOSDP context
cbCallback function pointer
argOpaque pointer passed as first callback argument
enumosdp_completion_status

Terminal status of a submitted command/event object.

Values
OSDP_COMPLETION_OK
Successfully completed
OSDP_COMPLETION_FAILED
Transport/protocol failure
OSDP_COMPLETION_FLUSHED
Removed by flush API
OSDP_COMPLETION_ABORTED
Removed during teardown

Deprecated ​

osdp_cp_send_command is retained for backward compatibility; new code should use osdp_cp_submit_command instead.

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

Generic command enqueue API.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
cmdcommand pointer. Must be filled by application.
Returns
0on success
-1on failure

Get PD Capability ​

See PD capabilities for the function codes a PD can advertise and their compliance levels.

structosdp_pd_cap

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

Members
enum osdp_pd_cap_function_code_e 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
functionosdp_cp_get_capability
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
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
capin/out; struct osdp_pd_cap pointer with osdp_pd_cap::function_code set to the function code to get data for.
Returns
0on success
-1on failure

Others ​

osdp_cp_get_pd_id fills an osdp_pd_id with the identity a PD reported during setup.

structosdp_pd_id

PD ID information advertised by the PD.

Members
int version
1-Byte Manufacturer's version number
int model
1-byte Manufacturer's model number
uint32_t vendor_code
3-bytes IEEE assigned OUI
uint32_t serial_number
4-byte serial number for the PD
uint32_t firmware_version
3-byte version (major, minor, build)
functionosdp_cp_get_pd_id
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
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
idA pointer to struct osdp_pd_id that will be filled with the PD ID information that the PD last returned.
Returns
0on success
-1on failure
functionosdp_cp_modify_flag
int osdp_cp_modify_flag(osdp_t *ctx, int pd, uint32_t flags, bool do_set)

Set or clear OSDP public flags.

Parameters
ctxOSDP context
pdPD offset (0-indexed) of this PD in osdp_pd_info_t * passed to osdp_cp_setup()
flagsOne or more of the public flags (OSDP_FLAG_XXX) exported from osdp.h. Any other bits will cause this method to fail.
do_setwhen true: set flags in ctx; when false: clear flags in ctx
Returns
0on success
-1on failure