Documentation

Application Commands

LibOSDP exposes the following structures through osdp.h. All commands are carried in a single union wrapper:

structosdp_cmd

OSDP Command Structure. This is a wrapper for all individual OSDP commands.

Members
osdp_queue_node_t _node
Reserved: internal queue linkage
enum osdp_cmd_e id
Command ID. Used to select specific commands in union
uint32_t flags
Flags; see OSDP_CMD_FLAG_* flags for possibilities
struct osdp_cmd_led led
LED command structure
struct osdp_cmd_buzzer buzzer
Buzzer command structure
struct osdp_cmd_text text
Text command structure
struct osdp_cmd_output output
Output command structure
struct osdp_cmd_comset comset
Comset command structure
struct osdp_cmd_keyset keyset
Keyset command structure
struct osdp_cmd_mfg mfg
Manufacturer specific command structure
struct osdp_cmd_file_tx file_tx
File transfer command structure
struct osdp_status_report status
Status report command structure
struct osdp_notification notif
LibOSDP notification (PD mode)
struct osdp_cmd_bioread bioread
Biometric read command structure
struct osdp_cmd_biomatch biomatch
Biometric match command structure
struct osdp_cmd_tdset tdset
Time and date set command structure
struct osdp_cmd_pivdata pivdata
PIV data retrieval command structure
struct osdp_cmd_auth auth
GENAUTH/CRAUTH command structure
union osdp_cmd::@2 @3
Command

The id field selects the active union member and is one of osdp_cmd_e:

enumosdp_cmd_e

OSDP application exposed commands.

Values
OSDP_CMD_OUTPUT
Output control command
OSDP_CMD_LED
Reader LED control command
OSDP_CMD_BUZZER
Reader buzzer control command
OSDP_CMD_TEXT
Reader text output command
OSDP_CMD_KEYSET
Encryption Key Set Command
OSDP_CMD_COMSET
PD communication configuration command
OSDP_CMD_MFG
Manufacturer specific command
OSDP_CMD_FILE_TX
File transfer command
OSDP_CMD_STATUS
Status report command
OSDP_CMD_COMSET_DONE
Comset completed; Alias for OSDP_CMD_COMSET
OSDP_CMD_NOTIFICATION
LibOSDP notification (PD mode, synthesized)
OSDP_CMD_BIOREAD
Scan and send biometric data command
OSDP_CMD_BIOMATCH
Scan and match biometric template command
OSDP_CMD_TDSET
Time and date set command
OSDP_CMD_PIVDATA
Retrieve PIV object data command
OSDP_CMD_GENAUTH
General authenticate command
OSDP_CMD_CRAUTH
Challenge/response authenticate command
OSDP_CMD_SENTINEL
Max command value
defineOSDP_CMD_FLAG_BROADCAST
0x000000001

When set (struct osdp_cmd::flags), the command is sent out with the OSDP packet broadcast flag to the PD.

Below are the structures for each command type. They are submitted to a PD with osdp_cp_submit_command.

LED Command ​

structosdp_cmd_led_params

LED params sub-structure. Part of LED command. See osdp_cmd_led.

Members
uint8_t control_code
Control code. The block this struct is used as decides which enumeration applies: osdp_cmd_led_temporary_control_code_e for osdp_cmd_led::temporary, osdp_cmd_led_permanent_control_code_e for osdp_cmd_led::permanent. They do not agree numerically, so the two cannot share a type.
uint8_t on_count
The ON duration of the flash, in units of 100 ms.
uint8_t off_count
The OFF duration of the flash, in units of 100 ms.
enum osdp_led_color_e on_color
Color to set during the ON timer (see osdp_led_color_e).
enum osdp_led_color_e off_color
Color to set during the OFF timer (see osdp_led_color_e).
uint16_t timer_count
Time in units of 100 ms (only for temporary mode).
structosdp_cmd_led

Sent from CP to PD to control the behaviour of it's on-board LEDs.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
uint8_t led_number
LED number. 0 = first LED, 1 = second LED, etc.
struct osdp_cmd_led_params temporary
Ephemeral LED status descriptor.
struct osdp_cmd_led_params permanent
Permanent LED status descriptor.
enumosdp_led_color_e

LED Colors as specified in OSDP for the on_color/off_color parameters.

Values
OSDP_LED_COLOR_NONE
No color
OSDP_LED_COLOR_RED
Red
OSDP_LED_COLOR_GREEN
Green
OSDP_LED_COLOR_AMBER
Amber
OSDP_LED_COLOR_BLUE
Blue
OSDP_LED_COLOR_MAGENTA
Magenta
OSDP_LED_COLOR_CYAN
Cyan
OSDP_LED_COLOR_WHITE
White
OSDP_LED_COLOR_SENTINEL
Max value
enumosdp_cmd_led_temporary_control_code_e

What the temporary block of an LED command does.

Values
OSDP_CMD_LED_TEMPORARY_CC_NOP
Do not alter this LED's temporary settings
OSDP_CMD_LED_TEMPORARY_CC_CANCEL
Cancel any temporary operation and display this LED's permanent state immediately
OSDP_CMD_LED_TEMPORARY_CC_SET
Set the temporary state as given and start timer immediately
OSDP_CMD_LED_TEMPORARY_CC_SENTINEL
Max value
enumosdp_cmd_led_permanent_control_code_e

What the permanent block of an LED command does.

Values
OSDP_CMD_LED_PERMANENT_CC_NOP
Do not alter this LED's permanent settings
OSDP_CMD_LED_PERMANENT_CC_SET
Set the permanent state as given
OSDP_CMD_LED_PERMANENT_CC_SENTINEL
Max value

Buzzer Command ​

structosdp_cmd_buzzer

Sent from CP to control the behaviour of a buzzer in the PD.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_cmd_buzzer_control_code_e control_code
What the buzzer should do.
uint8_t on_count
The ON duration of the sound, in units of 100 ms.
uint8_t off_count
The OFF duration of the sound, in units of 100 ms.
uint8_t rep_count
The number of times to repeat the ON/OFF cycle; 0: forever.
enumosdp_cmd_buzzer_control_code_e

What a buzzer command does.

Values
OSDP_CMD_BUZZER_CC_NO_TONE
No tone
OSDP_CMD_BUZZER_CC_OFF
Silence the buzzer
OSDP_CMD_BUZZER_CC_DEFAULT_TONE
Sound the reader's default tone
OSDP_CMD_BUZZER_CC_SENTINEL
Max value

Text Command ​

structosdp_cmd_text

Command to manipulate any display units that the PD supports.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_cmd_text_control_code_e control_code
How the message should be displayed.
uint8_t temp_time
Duration to display temporary text, in seconds
uint8_t offset_row
Row to display the first character (1-indexed)
uint8_t offset_col
Column to display the first character (1-indexed)
uint8_t length
Number of characters in the string
uint8_t data
The string to display
enumosdp_cmd_text_control_code_e

How a text command displays its message.

Values
OSDP_CMD_TEXT_CC_PERMANENT_NO_WRAP
Permanent text, no wrap
OSDP_CMD_TEXT_CC_PERMANENT_WRAP
Permanent text, with wrap
OSDP_CMD_TEXT_CC_TEMPORARY_NO_WRAP
Temporary text, no wrap; reverts after osdp_cmd_text::temp_time
OSDP_CMD_TEXT_CC_TEMPORARY_WRAP
Temporary text, with wrap; reverts after osdp_cmd_text::temp_time
OSDP_CMD_TEXT_CC_SENTINEL
Max value
defineOSDP_CMD_TEXT_MAX_LEN
32

Max text, in bytes, that a text command can carry to a PD's display.

Output Command ​

structosdp_cmd_output

Command sent from CP to Control digital output of PD.

Members
uint8_t output_no
0 = First Output, 1 = Second Output, etc.
enum osdp_cmd_output_control_code_e control_code
What to do to the output line.
uint16_t timer_count
Time in units of 100 ms
enumosdp_cmd_output_control_code_e

What an output command does to the output line.

Values
OSDP_CMD_OUTPUT_CC_NOP
Do not alter this output
OSDP_CMD_OUTPUT_CC_PERMANENT_OFF
Set the permanent state to OFF, abort timed operation (if any)
OSDP_CMD_OUTPUT_CC_PERMANENT_ON
Set the permanent state to ON, abort timed operation (if any)
OSDP_CMD_OUTPUT_CC_PERMANENT_OFF_ALLOW_TIMED
Set the permanent state to OFF, allow timed operation to complete
OSDP_CMD_OUTPUT_CC_PERMANENT_ON_ALLOW_TIMED
Set the permanent state to ON, allow timed operation to complete
OSDP_CMD_OUTPUT_CC_TEMPORARY_ON
Set the temporary state to ON, resume perm state on timeout
OSDP_CMD_OUTPUT_CC_TEMPORARY_OFF
Set the temporary state to OFF, resume perm state on timeout
OSDP_CMD_OUTPUT_CC_SENTINEL
Max value

Comset Command ​

structosdp_cmd_comset

Sent in response to a COMSET command. Set communication parameters to PD. Must be stored in PD non-volatile memory.

Members
uint8_t address
Unit ID to which this PD will respond after the change takes effect.
uint32_t baud_rate
Baud rate. Valid values: 9600, 19200, 38400, 115200, 230400.

Keyset Command ​

This command sets the SCBK on a PD; see Secure Channel for how keying and install mode work.

structosdp_cmd_keyset

This command transfers an encryption key from the CP to a PD.

Members
uint8_t type
Type of keys: - 0x01 – Secure Channel Base Key
uint8_t length
Number of bytes of key data - (Key Length in bits + 7) / 8
uint8_t data
Key data
defineOSDP_CMD_KEYSET_KEY_MAX_LEN
32

Max key length, in bytes, that a keyset command can carry. Not overridable: it must stay large enough to hold the 16-byte SCBK that secure channel is built on.

Manufacturer Specific Command ​

structosdp_cmd_mfg

Manufacturer Specific Commands.

Members
uint32_t vendor_code
3-byte IEEE assigned OUI. Most Significant 8-bits are unused
uint8_t data
Command data
uint8_t length
Length of the data (internal use)
defineOSDP_CMD_MFG_MAX_DATALEN
64

Max vendor defined data, in bytes, that a manufacturer specific command can carry.

Biometric Commands ​

structosdp_cmd_bioread

Command sent from CP to instruct the PD to perform a biometric scan and return the scan data in an OSDP_EVENT_BIOREADR event.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_biometric_type_e type
Body part to scan. See osdp_biometric_type_e
enum osdp_biometric_format_e format
Format of the data to be returned. See osdp_biometric_format_e
uint8_t quality
Normalised scan quality
structosdp_cmd_biomatch

Command sent from CP to instruct the PD to perform a biometric scan and match it against data, returning the result in an OSDP_EVENT_BIOMATCHR event.

Members
uint8_t reader
Target reader: 0 is this PD, 1 the first attached reader, and so on. Must fit within the PD's OSDP_PD_CAP_READERS capability.
enum osdp_biometric_type_e type
Body part to scan. See osdp_biometric_type_e
enum osdp_biometric_format_e format
Format of the attached template. See osdp_biometric_format_e
uint8_t quality
Normalised threshold required for accepting the match
uint16_t length
Length of the template in data
uint8_t data
Template to match the scan against
defineOSDP_CMD_BIOMATCH_MAX_TEMPLATE_LEN
128

Max biometric template that fits in a single OSDP packet.

enumosdp_biometric_type_e

Biometric type; the body part to scan. See OSDP spec Table 24.

Values
OSDP_BIO_TYPE_NOT_SPECIFIED
0x00 Default
OSDP_BIO_TYPE_RIGHT_THUMB_PRINT
0x01
OSDP_BIO_TYPE_RIGHT_INDEX_FINGER_PRINT
0x02
OSDP_BIO_TYPE_RIGHT_MIDDLE_FINGER_PRINT
0x03
OSDP_BIO_TYPE_RIGHT_RING_FINGER_PRINT
0x04
OSDP_BIO_TYPE_RIGHT_LITTLE_FINGER_PRINT
0x05
OSDP_BIO_TYPE_LEFT_THUMB_PRINT
0x06
OSDP_BIO_TYPE_LEFT_INDEX_FINGER_PRINT
0x07
OSDP_BIO_TYPE_LEFT_MIDDLE_FINGER_PRINT
0x08
OSDP_BIO_TYPE_LEFT_RING_FINGER_PRINT
0x09
OSDP_BIO_TYPE_LEFT_LITTLE_FINGER_PRINT
0x0A
OSDP_BIO_TYPE_RIGHT_IRIS_SCAN
0x0B
OSDP_BIO_TYPE_RIGHT_RETINA_SCAN
0x0C
OSDP_BIO_TYPE_LEFT_IRIS_SCAN
0x0D
OSDP_BIO_TYPE_LEFT_RETINA_SCAN
0x0E
OSDP_BIO_TYPE_FULL_FACE_IMAGE
0x0F
OSDP_BIO_TYPE_RIGHT_HAND_GEOMETRY
0x10
OSDP_BIO_TYPE_LEFT_HAND_GEOMETRY
0x11
OSDP_BIO_TYPE_SENTINEL
Max biometric type value
enumosdp_biometric_format_e

Biometric data format. See OSDP spec Table 25.

Values
OSDP_BIO_FMT_NOT_SPECIFIED
0x00 Not specified; the PD scans using its default method and reports the format it used.
OSDP_BIO_FMT_RAW_PGM
0x01 Raw fingerprint data as a PGM
OSDP_BIO_FMT_ANSI_INCITS_378
0x02 ANSI/INCITS 378 fingerprint template
OSDP_BIO_FMT_SENTINEL
Max biometric format value
enumosdp_biometric_status_e

Outcome of a biometric scan, as reported by the PD.

Values
OSDP_BIO_STATUS_SUCCESS
Rest of the fields are valid
OSDP_BIO_STATUS_TIMEOUT
The scan timed out
OSDP_BIO_STATUS_UNKNOWN_ERROR
Unknown error

File Transfer Command ​

structosdp_cmd_file_tx

File transfer start command.

Members
int id
Pre-agreed file ID between CP and PD
uint32_t flags
Reserved and set to zero by OSDP spec. Note: : The upper bits are used by libosdp internally (IOW, not sent over the OSDP bus). Currently the following flags are defined: - OSDP_CMD_FILE_TX_FLAG_CANCEL
defineOSDP_CMD_FILE_TX_FLAG_CANCEL
(1UL << 31)

A CP only flag that can be used by the application to cancel an in-flight file transfer.

Status Report Command ​

structosdp_status_report

Status report structure. Used by OSDP_CMD_STATUS and OSDP_EVENT_STATUS. In case of command, it is used to send a query to the PD while in the case of events, the PD responds back with this structure.

Members
enum osdp_status_report_type type
The kind of event to report see enum osdp_event_status_type_e
int nr_entries
Number of valid entries in report
uint8_t report
Status report; one byte per entry
enumosdp_status_report_type

OSDP Status report types.

Values
OSDP_STATUS_REPORT_INPUT
Status report of the inputs attached the PD.
OSDP_STATUS_REPORT_OUTPUT
Status report of the output attached the PD.
OSDP_STATUS_REPORT_LOCAL
Local tamper and power status report.
OSDP_STATUS_REPORT_READER
Reader tamper status report.
defineOSDP_STATUS_REPORT_MAX_LEN
64

Maximum number of status entries an osdp_status_report can carry; i.e., the size of its report[] array. Each entry is one status byte, one per tracked entity (input, output, tamper/power, or reader).

NAK Codes ​

When a PD declines a command it replies with a NAK carrying one of these reason codes.

enumosdp_pd_nak_code_e

OSDP specified NAK codes.

Values
OSDP_PD_NAK_NONE
No error
OSDP_PD_NAK_MSG_CHK
Message check character(s) error (bad cksum/crc)
OSDP_PD_NAK_CMD_LEN
Command length error
OSDP_PD_NAK_CMD_UNKNOWN
Unknown Command Code – Command not implemented by PD
OSDP_PD_NAK_SEQ_NUM
Sequence number error
OSDP_PD_NAK_SC_UNSUP
Secure Channel is not supported by PD
OSDP_PD_NAK_SC_COND
unsupported security block or security conditions not met
OSDP_PD_NAK_BIO_TYPE
BIO_TYPE not supported
OSDP_PD_NAK_BIO_FMT
BIO_FORMAT not supported
OSDP_PD_NAK_RECORD
Unable to process command record
OSDP_PD_NAK_SENTINEL
NAK codes max value