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_translation_payload_s
struct	zb_zgps_translation_entry_s
	Translation table entry structure. More...

Macros
#define	ZB_ZGP_TRANSLATION_ENTRY_ENDPOINT_PASS_RAW_GPDF_TO_APP   (0xfc)
#define	ZB_ZGP_TRANSLATION_ENTRY_ENDPOINT_NO_PAIRS   (0xfd)
#define	ZB_ZGP_TRANSLATION_ENTRY_ENDPOINT_ALL_ARE_MATCHED   (0xff)
#define	ZB_ZGP_TRANSLATION_ENTRY_NO_PAYLOAD   (0x00)
#define	ZB_ZGP_TRANSLATION_ENTRY_GPDF_PAYLOAD   (0xff)
#define	ZB_ZGP_TRANSLATION_ENTRY_PARSED_PAYLOAD   (0xfe)
#define	ZB_ZGP_SET_TRANSLATION_TABLE(table, table_size)
	Set translation table 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 zb_zgps_translation_payload_s	zb_zgps_translation_payload_t
typedef struct zb_zgps_translation_entry_s	zb_zgps_translation_entry_t
	Translation 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...

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)
void	zb_zgp_gpdf_raw_indication (zb_bufid_t buf_ref)
	Application function to override allows custom handling incoming raw GPDF packet. More...

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_TRANSLATION_TABLE

#define ZB_ZGP_SET_TRANSLATION_TABLE	(		table,
			table_size
	)

Value:

{ \
  zb_zgps_set_translation_table((table), (table_size));     \
}

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

Parameters

[in]	table	Translation information, array of type zb_zgps_translation_entry_t
[in]	table_size	Size if the table in count of entries that 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 */
 
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;
}

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 os 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_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_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_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.

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

Parameters

[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

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