ZGP Sink API

Macros
#define	ZB_COMMON_SIGNAL_CAN_SLEEP   22U
#define	ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY   23U
#define	ZB_NWK_SIGNAL_NO_ACTIVE_LINKS_LEFT   24U
#define	ZB_SIGNAL_SUBGHZ_SUSPEND   41U
#define	ZB_SIGNAL_SUBGHZ_RESUME   42U
#define	ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED   47U
#define	ZB_ZDO_SIGNAL_DEVICE_UPDATE   48U
#define	ZB_NWK_SIGNAL_PANID_CONFLICT_DETECTED   49U
#define	ZB_NLME_STATUS_INDICATION   50U
#define	ZB_ZGP_FILL_GPS_SECURITY_LEVEL(sec_lvl, with_link_key, involve_tc)   (((sec_lvl) & 3U) | ((!!(with_link_key)) << 2U) | ((!!(involve_tc)) << 3U))

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_contacs, zb_uint8_t contact_status, zb_uint8_t *zgp_cmd_out)

Signals passed to zboss_signal_handler()
Note If an application requires the parameters to be passed to the zboss_signal_handler, it is recommended to introduce the structure according to the pattern below: typedef struct zb_zdo_app_my_custom_signal_s { zb_zdo_app_signal_type_t super; zb_my_custom_data_type_t my_custom_data; }
#define	ZB_ZGP_SIGNAL_COMMISSIONING   21U

Detailed Description

Macro Definition Documentation

ZB_COMMON_SIGNAL_CAN_SLEEP

#define ZB_COMMON_SIGNAL_CAN_SLEEP   22U

Notifies the application that the MCU can sleep for the specified period of time.

Note

Signal will not be generated if the sleep interval is less than sleep threshold ZB_SCHED_SLEEP_THRESHOLD_MS. To change the sleep threshold see zb_ret_t zb_sleep_set_threshold().

When generated:

• ZBOSS scheduler detects that the sleep mode can be enabled on the device.

Status codes:

• RET_OK: The sleep mode can be enabled on the device.
• Does not return error status.

Signal parameters:

• zb_zdo_signal_can_sleep_params_t

      case ZB_COMMON_SIGNAL_CAN_SLEEP:
      {
        /* zb_zdo_signal_can_sleep_params_t *can_sleep_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zdo_signal_can_sleep_params_t); */
#ifdef ZB_USE_SLEEP
        zb_sleep_now();
#endif
        break;
      }

ZB_NLME_STATUS_INDICATION

#define ZB_NLME_STATUS_INDICATION   50U

NLME status indication. Application may implement additional logic based on receiving some statuses.

Signal parameter

zb_zdo_signal_nlme_status_indication_params_t

See also

zb_nwk_command_status_t is the full list of NLME statuses

ZB_NWK_SIGNAL_NO_ACTIVE_LINKS_LEFT

#define ZB_NWK_SIGNAL_NO_ACTIVE_LINKS_LEFT   24U

Notifies the application about the Neighbor Table expiration. It means that the neighbor devices did not send the Link Status messages for ZB_NWK_ROUTER_AGE_LIMIT * ZB_NWK_LINK_STATUS_PERIOD seconds.

When generated:

• All routes expired (usually when the link is down).

Status codes:

• RET_OK: All routers expired.
• Does not return error status.

Signal parameters:

• none

ZB_NWK_SIGNAL_PANID_CONFLICT_DETECTED

#define ZB_NWK_SIGNAL_PANID_CONFLICT_DETECTED   49U

PAN ID conflict has been detected. Application has to decide whether to initiate its resolution or not.

Signal parameter

See also

zb_start_pan_id_conflict_resolution

ZB_SIGNAL_SUBGHZ_RESUME

#define ZB_SIGNAL_SUBGHZ_RESUME   42U

ZC resumed our device tx (sub-ghz only)

ZB_SIGNAL_SUBGHZ_SUSPEND

#define ZB_SIGNAL_SUBGHZ_SUSPEND   41U

ZC / our MAC suspended our device tx: out of Duty cycle (sub-ghz only)

Signal parameter - number of minutes to suspend, -1 if unknown

ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED

#define ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED   47U

Notifies the Zigbee Trust center application about a new device is authorized in the network. For Zigbee R21 devices it means that the TCLK exchange procedure was finished, for the legacy devices it means that the Transport key was send to the device.

When generated:

• Authorization success
• Authorization failed
• Authorization timeout

Status codes:

• RET_OK: Device information updated.
• Does not return error status. Signal parameters:
• zb_zdo_signal_device_authorized_params_t

ZB_ZDO_SIGNAL_DEVICE_UPDATE

#define ZB_ZDO_SIGNAL_DEVICE_UPDATE   48U

Notifies the Zigbee Trust center or parent router application about a new device joined, rejoined or left the network.

When generated:

• Standard device secured rejoin
• Standard device unsecured join
• Device left
• Standard device trust center rejoin

Status codes:

• RET_OK: Device information updated.
• Does not return error status.

Signal parameters:

• zb_zdo_signal_device_update_params_t

ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY

#define ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY   23U

Notifies the application that the application specific part of the production configuration was found and restored and provides the application with this data.

When generated:

• After restoring the production configuration.

Status codes:

• RET_OK: The application specific part of the production configuration exists.
• RET_ERROR: An error of any type.

Signal parameters:

• Passed up with application specific data from production configuration.

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_SIGNAL_COMMISSIONING

#define ZB_ZGP_SIGNAL_COMMISSIONING   21U

ZGP commissioning complete signal.

When generated:

• GPCB left the commissioning mode.

Status codes:

• RET_OK: commissioning complete.
• RET_ERROR: An error of any type.

Signal parameters:

• zb_zgp_signal_commissioning_params_s

      case ZB_ZGP_SIGNAL_COMMISSIONING:
      {
        zb_zgp_signal_commissioning_params_t *comm_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zgp_signal_commissioning_params_t);
        comm_done_cb(comm_params->zgpd_id, comm_params->result);
      }
      break;

Function Documentation

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

timeout

[in] 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.

After commissioning is cancelled, user is notified with zb_zgp_comm_completed_cb_t with ZB_ZGP_COMMISSIONING_CANCELLED_BY_USER status.

void stop_comm(zb_uint8_t param)
{
  ZVUNUSED(param);
  TRACE_MSG(TRACE_APP1, "stop commissioning", (FMT__0));
  zb_zgps_stop_commissioning();
}