Developing with ZBOSS for Zigbee
ZGP Sink API

Data Structures

struct  zgp_to_zb_cmd_mapping_s
 Mapping of ZGPD command ID to Zigbee ZCL command ID. More...
 
struct  zgps_cluster_rec_s
 
struct  zb_zgps_match_info_s
 Necessary information for filling translation table for any ZGPD during commissioning. More...
 

Macros

#define ZB_ZGP_SET_MATCH_INFO(info)
 Set matching information that is used to fill ZGP command - ZCL cluster translation table. More...
 
#define ZB_ZGP_REGISTER_COMM_REQ_CB(cb)
 Register commissioning request callback. More...
 
#define ZB_ZGP_REGISTER_APP_CIC_CB(cb)
 Register application commissioning indication callback. More...
 
#define ZB_ZGP_FILL_GPS_SECURITY_LEVEL(sec_lvl, with_link_key, involve_tc)   (((sec_lvl) & 3U) | ((!!(with_link_key)) << 2U) | ((!!(involve_tc)) << 3U))
 

Typedefs

typedef struct zgp_to_zb_cmd_mapping_s zgp_to_zb_cmd_mapping_t
 Mapping of ZGPD command ID to Zigbee ZCL command ID.
 
typedef struct zgps_cluster_rec_s zgps_dev_cluster_rec_t
 
typedef struct zb_zgps_match_info_s zb_zgps_match_info_t
 Necessary information for filling translation table for any ZGPD during commissioning. More...
 
typedef void(* zb_zgp_app_comm_ind_cb_t) (zb_zgpd_id_t *zgpd_id, zb_uint8_t param)
 Application callback, indication of the attempted commissioning in GPS operational mode. More...
 

Functions

void zb_zgps_start_commissioning (zb_time_t timeout)
 Put ZGPS into commissioning mode. More...
 
void zb_zgps_stop_commissioning (void)
 Switch ZGPS back to operational mode from commissioning. More...
 
void zb_zgps_accept_commissioning (zb_bool_t accept)
 Accept/reject ZGPD commissioning attempt. More...
 
void zb_zgps_delete_zgpd (zb_uint8_t buf_ref, zb_zgpd_id_t *zgpd_id)
 Remove all the information about ZGPD from stack. More...
 
void zb_zgps_delete_all_zgpd (void)
 Remove all the information about ALL ZGPD from stack. More...
 
void zb_zgps_get_diag_data (zb_zgpd_id_t *zgpd_id, zb_uint8_t *lqi, zb_int8_t *rssi)
 
void zb_zgps_set_security_level (zb_uint_t level)
 
void zb_zgp_set_shared_security_key_type (zb_uint_t key_type)
 
void zb_zgp_set_shared_security_key (zb_uint8_t *key)
 
void zb_zgps_set_commissioning_exit_mode (zb_uint_t cem)
 
void zb_zgps_set_communication_mode (zgp_communication_mode_t mode)
 
zb_ret_t zb_zgp_convert_8bit_vector (zb_uint8_t vector_8bit_cmd_id, zb_uint8_t switch_type, zb_uint8_t num_of_contacts, zb_uint8_t contact_status, zb_uint8_t *zgp_cmd_out)
 

Detailed Description

Macro Definition Documentation

◆ ZB_ZGP_FILL_GPS_SECURITY_LEVEL

#define ZB_ZGP_FILL_GPS_SECURITY_LEVEL (   sec_lvl,
  with_link_key,
  involve_tc 
)    (((sec_lvl) & 3U) | ((!!(with_link_key)) << 2U) | ((!!(involve_tc)) << 3U))

Fill security level constant to be passed to zb_zgps_set_security_level()

Described in A.3.3.2.6 gpsSecurityLevel attribute.

Parameters
sec_lvlzb_zgp_security_level_e Minimal GPD Security Level sub-field contains the minimum gpdSecurityLevel this sink accepts
with_link_key1 bit - Protection with the gpLinkKey sub-field, indicates if the GPDs attempting the pairing are required to support protecting the over-the-air exchange of the GPD Key
involve_tcalways zero for the current GPPB specification
/* set ZGP secur_level */
ZB_ZGP_DEFAULT_SEC_LEVEL_PROTECTION_WITH_GP_LINK_KEY,
ZB_ZGP_DEFAULT_SEC_LEVEL_INVOLVE_TC));

◆ ZB_ZGP_REGISTER_APP_CIC_CB

#define ZB_ZGP_REGISTER_APP_CIC_CB (   cb)
Value:
{ \
zb_zgps_register_app_cic_cb((cb)); \
}

Register application commissioning indication callback.

Parameters
cb[in] Application commissioning indication callback (zb_zgp_app_comm_ind_cb_t)

◆ ZB_ZGP_REGISTER_COMM_REQ_CB

#define ZB_ZGP_REGISTER_COMM_REQ_CB (   cb)
Value:
{ \
zb_zgps_register_comm_req_cb((cb)); \
}

Register commissioning request callback.

Parameters
cb[in] Commissioning request callback (zb_zgp_comm_req_cb_t)

◆ ZB_ZGP_SET_MATCH_INFO

#define ZB_ZGP_SET_MATCH_INFO (   info)
Value:
{ \
zb_zgps_set_match_info((info)); \
}

Set matching information that is used to fill ZGP command - ZCL cluster translation table.

Parameters
[in]infoMatching information of type zb_zgps_match_info_t

Typedef Documentation

◆ zb_zgp_app_comm_ind_cb_t

typedef void( * zb_zgp_app_comm_ind_cb_t) (zb_zgpd_id_t *zgpd_id, zb_uint8_t param)

Application callback, indication of the attempted commissioning in GPS operational mode.

Application commissioning indication callback notifies application about commissioning attempt from ZGPD. Callback is called when commissioning frame or notification is received from ZGPD. Callback provides to zgpd_id and full incoming packet's data. Based on these parameters user application should decide further actions.

Application commissioning indication callback should be set during ZGP initialization using ZB_ZGP_REGISTER_APP_CIC_CB macro.

Parameters
zgpd_id[in] ZGPD ID
param[in] buffer index, containing GPDF

◆ zb_zgps_match_info_t

Necessary information for filling translation table for any ZGPD during commissioning.

Includes matching table and command ID mappings. Given some ZGPD device ID it is possible to fill translation table entry with help of this structure.

Function Documentation

◆ zb_zgp_convert_8bit_vector()

zb_ret_t zb_zgp_convert_8bit_vector ( zb_uint8_t  vector_8bit_cmd_id,
zb_uint8_t  switch_type,
zb_uint8_t  num_of_contacts,
zb_uint8_t  contact_status,
zb_uint8_t zgp_cmd_out 
)

Application function to override translation of 8-bit vector command (generic switch)

If this function is not implemented in the application, then ZBOSS performs a default translation as recommended by ZGP spec (see Green Power Basic specification v1.1.1, tables 51, 52). If there is no default translation found, then the received command is dropped.

If this function is implemented by the the application, then application is fully responsible for a translation of GPD 8-bit vector commands. For any return code but RET_OK, ZBOSS will stop command processing and drop it.

Note: The translation is done to GPDF command ID, not to ZCL command ID.

Parameters
[in]vector_8bit_cmd_idincoming command ID: press (0x69) or release(0x6a)
[in]switch_typeswitch type of the command's originator (see ZGP spec. A.4.2.1.1.10)
[in]num_of_contactsnumber of contacts command's originator provides
[in]contact_statuscontacts status from the payload of the received command
[out]zgp_cmd_outGPDF command ID to which incoming command should be translated
Returns
RET_OK if translation is successful.

See Green Power Basic specification v1.1.1, chapters A.3.6.2.2.2, A.4.2.2.1 for more information.

/*
* "Contact status" possible values for GPD 8-bit vector incoming command
* Every bit in contact_status is for a specific contact:
* - 0b1 indicates a closed contact
* - 0b0 indicates an open contact
* This sample supports a button switch which works like a rocker switch. Only
* one contact can be closed, the first contact means "Off", the second contact
* means "On".
*/
#define CONTACT_STATUS_SWITCH_OFF 0x01 /* 0b01 */
#define CONTACT_STATUS_SWITCH_ON 0x02 /* 0b10 */
zb_ret_t zb_zgp_convert_8bit_vector(zb_uint8_t vector_8bit_cmd_id, /* press or release cmd */
zb_uint8_t switch_type, /* see zb_zgpd_switch_type_e */
zb_uint8_t num_of_contacts,
zb_uint8_t contact_status,
zb_uint8_t *zgp_cmd_out)
{
zb_ret_t ret = RET_ERROR;
TRACE_MSG(TRACE_APP1, ">> zb_zgp_convert_8bit_vector", (FMT__0));
if ((vector_8bit_cmd_id == ZB_GPDF_CMD_8BIT_VECTOR_PRESS) &&
(num_of_contacts == 2) &&
(switch_type == ZB_GPD_SWITCH_TYPE_BUTTON))
{
if (contact_status == CONTACT_STATUS_SWITCH_ON)
{
*zgp_cmd_out = ZB_GPDF_CMD_ON;
ret = RET_OK;
}
else if (contact_status == CONTACT_STATUS_SWITCH_OFF)
{
*zgp_cmd_out = ZB_GPDF_CMD_OFF;
ret = RET_OK;
}
/* Switch could be a blinds controller with separate "Up" and "Down"
* contacts which can't be closed together. The desactivated code is left
* for demonstration purposes.
*/
#if 0
if (contact_status == 0x02)
{
*zgp_cmd_out = ZB_GPDF_CMD_MOVE_UP;
ret = RET_OK;
}
else if (contact_status == 0x01)
{
*zgp_cmd_out = ZB_GPDF_CMD_MOVE_DOWN;
ret = RET_OK;
}
#endif
}
TRACE_MSG(TRACE_APP1, "<< zb_zgp_convert_8bit_vector, ret %hd", (FMT__H, ret));
return ret;
}

◆ zb_zgp_set_shared_security_key()

void zb_zgp_set_shared_security_key ( zb_uint8_t key)

Set gpSharedSecurityKey GP cluster attribute

Described in A.3.3.3.1 gpSharedSecurityKey attribute.

Parameters
keySecurity key to set

◆ zb_zgp_set_shared_security_key_type()

void zb_zgp_set_shared_security_key_type ( zb_uint_t  key_type)

Set gpSharedSecurityKeyType GP cluster attribute

Described in A.3.3.3.1 gpSharedSecurityKeyType attribute.

Parameters
key_typeSecurity key type to set (
See also
zb_zgp_security_key_type_e)

◆ zb_zgps_accept_commissioning()

void zb_zgps_accept_commissioning ( zb_bool_t  accept)

Accept/reject ZGPD commissioning attempt.

This function should be called as an answer to commissioning request made by stack via zb_zgp_comm_req_cb_t. Also, it can be called from zb_zgp_comm_req_cb_t callback as well as outside it.

Parameters
[in]accept- If ZB_TRUE, then stack will continue ongoing commissioning process with ZGPD
Otherwise ongoing commissioning process will be terminated

◆ zb_zgps_delete_all_zgpd()

void zb_zgps_delete_all_zgpd ( void  )

Remove all the information about ALL ZGPD from stack.

◆ zb_zgps_delete_zgpd()

void zb_zgps_delete_zgpd ( zb_uint8_t  buf_ref,
zb_zgpd_id_t zgpd_id 
)

Remove all the information about ZGPD from stack.

In ZGP there is no way to say ZGPD to leave the network. ZGPD can leave network by itself using "Decommissioning" command, but ZGPS can miss this command if it was not in commissioning state.

This function removes all the information related to specified ZGPD from stack.

Parameters
buf_refreference to the free buffer
zgpd_ididentifier of ZGPD to be removed
Note
It is safe to free or overwrite memory pointed by zgpd_id after call

◆ zb_zgps_get_diag_data()

void zb_zgps_get_diag_data ( zb_zgpd_id_t zgpd_id,
zb_uint8_t lqi,
zb_int8_t rssi 
)

Get LQI and RSSI last time received from that ZGPD.

◆ zb_zgps_set_commissioning_exit_mode()

void zb_zgps_set_commissioning_exit_mode ( zb_uint_t  cem)

Set gpsCommissioningExitMode GP cluster attribute

Described in A.3.3.2.4 gpsCommissioningExitMode attribute.

Parameters
cemCommissioning exit mode to set (
See also
zgp_commissioning_exit_mode_t)

◆ zb_zgps_set_communication_mode()

void zb_zgps_set_communication_mode ( zgp_communication_mode_t  mode)

Set gpsCommunicationMode GP cluster attribute of gpcb

Described in A.3.3.2.3 gpsCommunicationMode attribute

Parameters
modezgp_communication_mode_t communication mode
/* set ZGP commissioning mode */
zb_zgps_set_communication_mode(ZGP_COMMUNICATION_MODE_LIGHTWEIGHT_UNICAST);

◆ zb_zgps_set_security_level()

void zb_zgps_set_security_level ( zb_uint_t  level)

Set gpsSecurityLevel GP cluster attribute of gpcb

Described in A.3.3.2.6 gpsSecurityLevel attribute.

Parameters
levelSecurity level to set
/* set ZGP secur_level */
ZB_ZGP_DEFAULT_SEC_LEVEL_PROTECTION_WITH_GP_LINK_KEY,
ZB_ZGP_DEFAULT_SEC_LEVEL_INVOLVE_TC));

◆ zb_zgps_start_commissioning()

void zb_zgps_start_commissioning ( zb_time_t  timeout)

Put ZGPS into commissioning mode.

It is safe to call this function when device is already in commissioning mode. In this case function does nothing.

Parameters
[in]timeoutMaximum commissioning time in beacon intervals.
0 means no timeout.
If timeout occurs, then result of commissioning is ZB_ZGP_COMMISSIONING_TIMED_OUT
void start_comm(zb_uint8_t param)
{
ZVUNUSED(param);
TRACE_MSG(TRACE_APP1, "start commissioning", (FMT__0));
}

◆ zb_zgps_stop_commissioning()

void zb_zgps_stop_commissioning ( void  )

Switch ZGPS back to operational mode from commissioning.

void stop_comm(zb_uint8_t param)
{
ZVUNUSED(param);
TRACE_MSG(TRACE_APP1, "stop commissioning", (FMT__0));
}
zb_uint8_t
unsigned char zb_uint8_t
Project-local 1-byte unsigned int type.
Definition: zb_types.h:149
TRACE_MSG
#define TRACE_MSG(lm, fmts, args)
Put trace output.
Definition: zb_trace.h:348
ZB_ZGP_SEC_LEVEL_NO_SECURITY
@ ZB_ZGP_SEC_LEVEL_NO_SECURITY
Definition: zboss_api_zgp.h:195
zb_zgps_stop_commissioning
void zb_zgps_stop_commissioning(void)
Switch ZGPS back to operational mode from commissioning.
zb_zgp_convert_8bit_vector
zb_ret_t zb_zgp_convert_8bit_vector(zb_uint8_t vector_8bit_cmd_id, zb_uint8_t switch_type, zb_uint8_t num_of_contacts, zb_uint8_t contact_status, zb_uint8_t *zgp_cmd_out)
zb_ret_t
zb_int32_t zb_ret_t
Return type for ZB functions returning execution status.
Definition: zb_errors.h:33
zb_zgps_set_communication_mode
void zb_zgps_set_communication_mode(zgp_communication_mode_t mode)
RET_OK
#define RET_OK
Error codes for non-void stack functions. In general, function can return OK, BLOCKED or some error....
Definition: zb_errors.h:78
ZB_TIME_ONE_SECOND
#define ZB_TIME_ONE_SECOND
Definition: zboss_api_core.h:172
zb_zgps_set_security_level
void zb_zgps_set_security_level(zb_uint_t level)
zb_zgps_start_commissioning
void zb_zgps_start_commissioning(zb_time_t timeout)
Put ZGPS into commissioning mode.
ZB_ZGP_FILL_GPS_SECURITY_LEVEL
#define ZB_ZGP_FILL_GPS_SECURITY_LEVEL(sec_lvl, with_link_key, involve_tc)
Definition: zboss_api_zgp.h:1425