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 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_pd_setup(const osdp_pd_info_t *info)
This method is used to setup a device in PD mode. Application must store the returned context pointer and pass it back to all OSDP functions intact.
- Parameters:
info – Pointer to info struct populated by application.
- Return values:
OSDP – Context on success
NULL – on errors
PD Capabilities
-
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
-
uint8_t function_code
-
void osdp_pd_set_capabilities(osdp_t *ctx, const 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_command_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.- Param arg:
pointer that will was passed to the arg param of
osdp_pd_set_command_callback
.- Param cmd:
pointer to the received command.
- Retval 0:
if LibOSDP must send a
osdp_ACK
response- Retval -ve:
if LibOSDP must send a
osdp_NAK
response- Retval +ve:
and modify the passed
struct osdp_cmd *cmd
if LibOSDP must send a specific response. This is useful for sending manufacturer specific replyosdp_MFGREP
.
-
void osdp_pd_set_command_callback(osdp_t *ctx, pd_command_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.
- 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 the
cmd
structure is framed.
Events
When a PD app has some event (card read, key press, etc.,) to be reported to the
CP, it creates the corresponding event structure and calls
osdp_pd_notify_event
to deliver it to the CP on the next osdp_POLL command.
-
int osdp_pd_notify_event(osdp_t *ctx, const 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.
- Return values:
0 – on success
-1 – on failure
-
int osdp_pd_flush_events(osdp_t *ctx)
Deletes all events from the PD’s event queue.
- Parameters:
ctx – OSDP context
- Returns:
int Count of events dequeued.
Refer to the event structure document for more information on how to
populate the event
structure for these function.