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.
-
const char *name
-
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
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:
ctx – OSDP context
pd – PD offset (0-indexed) of this PD in
osdp_pd_info_t *
passed to osdp_cp_setup()
- 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.
-
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:
ctx – OSDP context
pd – PD offset (0-indexed) of this PD in
osdp_pd_info_t *
passed to osdp_cp_setup()cap – in/out; struct osdp_pd_cap pointer with osdp_pd_cap::function_code set to the function code to get data for.
- 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: clearflags
in ctx
- Return values:
0 – on success
-1 – on failure