ZGP Sink API

Data Structures
struct	zgp_to_zb_cmd_mapping_s
	Mapping of ZGPD command ID to Zigbee ZCL command ID. More...
struct	zb_zgps_mapping_entry_additional_info_option_selector_s
	Mapping table entry additional info option selector structure Figure 84 – Format of the Option selector field of the Option record field of the Translation Table entry. More...
struct	zb_zgps_mapping_entry_generic_switch_option_data_s
	Mapping table entry additional info generic switch option data structure Figure 85 – Format of the Option data of the Generic switch command execution option of the Translation Table entry. More...
struct	zb_zgps_mapping_entry_generic_switch_option_s
	Mapping table entry additional info generic switch option structure. More...
struct	zb_zgps_mapping_entry_additional_info_option_record_s
	Mapping table entry additional info option record structure A.3.6.2.2 GPD application functionality translation Figure 83 – Format of the Option record field of the Translation Table entry. More...
struct	zb_zgps_mapping_entry_additional_info_s
	Mapping table entry additional info structure Figure 82 – Format of the Additional information block field of the Translation Table entry. More...
struct	zb_zgps_mapping_entry_s
	Mapping table entry structure. More...

Macros
#define	ZB_ZGP_ZCL_CMD_ID_UNDEFINED   (0xff)
#define	ZB_ZGP_ZCL_CLUSTER_ID_UNDEFINED   (0xffff)
#define	ZB_GPDF_CMD_UNDEFINED   (0xff)
#define	ZB_ZGP_MAPPING_ENTRY_ENDPOINT_PASS_RAW_GPDF_TO_APP   (0xfc)
#define	ZB_ZGP_MAPPING_ENTRY_ENDPOINT_NO_PAIRS   (0xfd)
#define	ZB_ZGP_MAPPING_ENTRY_ENDPOINT_ALL_ARE_MATCHED   (0xff)
#define	ZB_ZGP_MAPPING_ENTRY_NO_PAYLOAD   (0x00)
#define	ZB_ZGP_MAPPING_ENTRY_GPDF_PAYLOAD   (0xff)
#define	ZB_ZGP_MAPPING_ENTRY_PARSED_PAYLOAD   (0xfe)
#define	ZB_ZGP_MAPPING_ENTRY_OPTIONS(app_id, add_info_present)   (((((add_info_present) & 0x01) << 3)) | ((app_id) & 0x07))
#define	ZB_ZGP_MAPPING_ENTRY_OPTIONS_IS_ADDITIONAL_INFO_PRESENT(options)   (((options) >> 3) & 0x01)
#define	ZB_ZGP_GET_MAPPING_ENTRY_ZCL_PAYLOAD_PTR(entry)   (&entry->zcl_payload_length+sizeof(entry->zcl_payload_length))
#define	ZB_ZGP_SET_MAPPING_TABLE(table_ptr, table_size_ptr)
	Set mapping table information that is used to fill ZGP command - ZCL cluster mapping 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 zb_zgps_mapping_entry_additional_info_option_selector_s	zb_zgps_mapping_entry_additional_info_option_selector_t
	Mapping table entry additional info option selector structure Figure 84 – Format of the Option selector field of the Option record field of the Translation Table entry.
typedef struct zb_zgps_mapping_entry_generic_switch_option_data_s	zb_zgps_mapping_entry_generic_switch_option_data_t
	Mapping table entry additional info generic switch option data structure Figure 85 – Format of the Option data of the Generic switch command execution option of the Translation Table entry.
typedef struct zb_zgps_mapping_entry_generic_switch_option_s	zb_zgps_mapping_entry_generic_switch_option_t
	Mapping table entry additional info generic switch option structure.
typedef struct zb_zgps_mapping_entry_additional_info_option_record_s	zb_zgps_mapping_entry_additional_info_option_record_t
	Mapping table entry additional info option record structure A.3.6.2.2 GPD application functionality translation Figure 83 – Format of the Option record field of the Translation Table entry.
typedef struct zb_zgps_mapping_entry_additional_info_s	zb_zgps_mapping_entry_additional_info_t
	Mapping table entry additional info structure Figure 82 – Format of the Additional information block field of the Translation Table entry.
typedef struct zb_zgps_mapping_entry_s	zb_zgps_mapping_entry_t
	Mapping table entry structure.
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...

Enumerations
enum	zb_zgps_mapping_entry_8bit_vector_option_ids_e { ZB_ZGPS_MAPPING_ENTRY_8BIT_VECTOR_OPTION_ID_GENERIC_SWITCH_COMMAND_EXECUTION = 0U }
	A.3.6.2.2.1.1 OptionIDs for GPD 8-bit vector commands.
enum	zb_zgps_mapping_entry_compact_attr_report_option_ids_e { ZB_ZGPS_MAPPING_ENTRY_COMPACT_ATTR_REPORT_REPORTABLE = 0U }
	A.3.6.2.2.1.2 OptionIDs for GPD Compact Attribute Reporting.

Functions
void	zb_zgps_start_commissioning (zb_time_t timeout)
	Put ZGPS into commissioning mode, the mode will be changed back to operational mode if: More...
void	zb_zgps_start_commissioning_on_ep (zb_uint8_t ep, zb_time_t timeout)
	Put ZGPS into commissioning mode on a specific endpoint. 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)
zb_uint8_t	zb_zgps_get_security_level (void)
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)
void	zb_zgp_gpdf_raw_indication (zb_bufid_t buf_ref)
	Application function to override allows custom handling incoming raw GPDF packet. More...
void	zb_zgp_set_skip_gpdf (zb_uint8_t skip)
zb_uint8_t	zb_zgp_get_skip_gpdf (void)
void	zb_zgp_sync_pib (zb_uint8_t param)

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_lvl	zb_zgp_security_level_e Minimal GPD Security Level sub-field contains the minimum gpdSecurityLevel this sink accepts
with_link_key	1 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_tc	always zero for the current GPPB specification

  /* set ZGP secur_level */
  zb_zgps_set_security_level(ZB_ZGP_FILL_GPS_SECURITY_LEVEL(
    ZB_ZGP_SEC_LEVEL_NO_SECURITY,
    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_MAPPING_TABLE

#define ZB_ZGP_SET_MAPPING_TABLE	(		table_ptr,
			table_size_ptr
	)

Value:

{ \
  zb_zgps_set_mapping_table((table_ptr), (table_size_ptr));   \
}

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

Parameters

[in]	table_ptr	Mapping information, pointer to array of type zb_zgps_mapping_entry_t
[in]	table_size_ptr	pointer to size of the table - max entry number what can be iterated

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

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_id	incoming command ID: press (0x69) or release(0x6a)
[in]	switch_type	switch type of the command's originator (see ZGP spec. A.4.2.1.1.10)
[in]	num_of_contacts	number of contacts command's originator provides
[in]	contact_status	contacts status from the payload of the received command
[out]	zgp_cmd_out	GPDF 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 */
#ifdef ZB_ZGP_SINK_SUPPORT_LEGACY_8BIT_VECTOR_HANDLING
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 deactivated 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;
}
#endif  /* ZB_ZGP_SINK_SUPPORT_LEGACY_8BIT_VECTOR_HANDLING */

zb_zgp_gpdf_raw_indication()

void zb_zgp_gpdf_raw_indication

(

zb_bufid_t

buf_ref

)

Application function to override allows custom handling incoming raw GPDF packet.

If this function is not implemented by the application, then ZBOSS drops the buffer without any additional handling.

If this function is implemented by the application, the application itself shall carry to free this resource.

Parameters

buf_ref

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

key	Security 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_type

Security key type to set (

See also

zb_zgp_security_key_type_e)

zb_zgp_set_skip_gpdf()

void zb_zgp_set_skip_gpdf

(

zb_uint8_t

skip

)

Set ZBOSS to skip all incoming GPDF.

To be used for testing only. Use that function with ZB_TRUE parameter to prevent Combo device from receiving GPDFS thus always working thru Proxy device.

Parameters

skip	if ZB_TRUE, skip incoming GP frames

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 signal ZB_ZGP_SIGNAL_APPROVE_COMMISSIONING or zb_zgp_comm_req_cb_t callback. 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_ref	reference to the free buffer
zgpd_id	identifier 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_get_security_level()

zb_uint8_t zb_zgps_get_security_level

(

void

)

Get gpsSecurityLevel GP cluster attribute of gpcb

Described in A.3.3.2.6 gpsSecurityLevel attribute.

Returns

value of gpsSecurityLevel aыруыруttribtue

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

cem	Commissioning 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

mode	zgp_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

level

Security level to set

  /* set ZGP secur_level */
  zb_zgps_set_security_level(ZB_ZGP_FILL_GPS_SECURITY_LEVEL(
    ZB_ZGP_SEC_LEVEL_NO_SECURITY,
    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, the mode will be changed back to operational mode if:

• "On first Pairing success" is set in gpsCommissioningModeExit attribute and a successful paring occurs. See ZB_ZGP_DEFAULT_COMMISSIONING_EXIT_MODE.
• The timeout parameter is different from 0 and a timeout occurs.
• GP Sink Commissioning Mode command with Action field set to 0x0 is received.

ZB_ZGP_SIGNAL_MODE_CHANGE is generated when sink changes mode from Operation Mode to Commissioning Mode and when it changes from Commissioning Mode to Operational Mode.

ZB_ZGP_SIGNAL_COMMISSIONING is generated if a successful commission happens or if a decommissioning happens

Parameters

timeout

Maximum commissioning time in beacon intervals, 0 means no timeout.

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

void start_comm(zb_uint8_t param)
{
  ZVUNUSED(param);
  TRACE_MSG(TRACE_APP1, "start commissioning", (FMT__0));
  zb_zgps_start_commissioning(60 * ZB_TIME_ONE_SECOND);
}

zb_zgps_start_commissioning_on_ep()

void zb_zgps_start_commissioning_on_ep	(	zb_uint8_t	ep,
		zb_time_t	timeout
	)

Put ZGPS into commissioning mode on a specific endpoint.

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

Parameters

[in]	ep	Endpoint to start a commissioning. Will be used for GPD command forwarding
[in]	timeout	Maximum commissioning time in beacon intervals. 0 means no timeout. If timeout occurs, then result of commissioning is ZB_ZGP_COMMISSIONING_TIMED_OUT

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_zgps_stop_commissioning();
}