ZGP Command API

Zigbee Green Power (ZGP) commands related APIs for ESP Zigbee SDK.

API Reference

Header File

components/esp-zigbee-lib/include/zgp/esp_zigbee_zgp.h

Functions

void esp_zb_zgp_set_skip_gpdf(uint8_t skip)

Set whether skip the Green power device frame.

Parameters: skip – [in] Skip or not

uint8_t esp_zb_zgp_get_skip_gpdf(void)

Get the setting of skip the Green power device frame.

Returns

true: Skip
false: Not skip

void esp_zb_zgp_set_shared_security_key_type(esp_zb_zgp_security_key_type_t type)

Set shared security key type.

Parameters: type – [in] The type of security key

esp_err_t esp_zb_zgp_set_shared_security_key(uint8_t *key)

Set shared security key.

Parameters

key – [in] The 16-byte pointer will be set as the shared security keyof green power

Returns

ESP_OK: on success
ESP_ERR_INVALID_ARG: invalid argument

esp_err_t esp_zb_zgp_set_link_key(uint8_t *key)

Set shared security key.

Parameters

key – [in] The 16-byte pointer will be set as the link key of green power

Returns

ESP_OK: on success
ESP_ERR_INVALID_ARG: invalid argument

void esp_zb_zgp_set_proxy_functionality(uint32_t functionality, uint32_t active_functionality)

Set the ZGP proxy functionality.

Parameters

functionality – Functionality, refer to esp_zgp_gpp_functionality_t
active_functionality – Active functionality indicates which bits of functionality are active.

Unions

union esp_zb_zgpd_addr_u

#include <esp_zigbee_zgp.h>

ZGP device address.

Note

ZGPD is identified in network whether by SrcId or its IEEE address.

Public Members

uint32_t src_id: ZGPD source id

esp_zb_ieee_addr_t ieee_addr: ZGPD IEEE address

Structures

struct esp_zb_zgp_cluster_list_s

ZGP device Cluster List.

Public Members

uint8_t server_cl_num: Number of server ClusterIDs

uint8_t client_cl_num: Number of client ClusterIDs

uint16_t server_clusters[ZB_ZGP_MAX_PAIRED_CONF_CLUSTERS]: ClusterID List Server

uint16_t client_clusters[ZB_ZGP_MAX_PAIRED_CONF_CLUSTERS]: ClusterID List Client

struct esp_zb_zgpd_id_s

ZGP device identifier.

Public Members

uint8_t app_id: One of the esp_zb_zgp_app_id_t values

uint8_t endpoint: Identifier of the GPD endpoint, which jointly with the GPD IEEE address identifies a unique logical GPD device.

esp_zb_zgpd_addr_t addr: ZGPD SrcId or IEEE address

struct esp_zb_zgp_gpd_cmds_list_s

ZGP device CommandID list.

Public Members

uint8_t num: Number of GP commands

uint8_t cmds[ZB_ZGP_MAX_PAIRED_CONF_GPD_COMMANDS]: GPD CommandID list

struct esp_zb_zgps_mapping_entry_s

Mapping table entry structure for ZGP sink.

Public Members

uint8_t options: Options related to this table entry

esp_zb_zgpd_addr_t gpd_id: Identifier of the GPD

uint8_t gpd_endpoint: Endpoint

uint8_t gpd_command: The GPD command to be mapped

uint8_t endpoint: The EndPoint for which the mapping is valid

uint16_t profile: The Profile of the command after mapping

uint16_t cluster: The cluster of the Profile on the endpoint

uint8_t zcl_command: The Command ID of the Cluster into which GP Command is mapped

uint8_t zcl_payload_length: The payload length for the Zigbee Command, payload should be located in memory after this structure

struct esp_zb_zgp_raw_report_desc_s

Raw report descriptor received from the GPD.

Public Members

uint8_t len: total len, in octets, of the current report descriptor.

uint8_t data[ZB_ZGP_APP_DESCR_REPORT_DATA_SIZE]: array of not parsed zgp_data_point_desc_t

struct esp_zgp_pair_group_list_s

The structure for the paired group List.

Public Members

uint16_t sink_group: Sink group

uint16_t alias: Alias for the group communication

struct esp_zgp_tbl_ent_s

The structure for Green Power table entry.

Public Members

esp_zb_zgpd_addr_t zgpd_id: ID of the paired ZGPD

uint16_t options: The options for the reception from ZGPD

uint16_t zgpd_assigned_alias: The commissioned 16-bit ID to be used as alias for ZGPD

uint32_t security_counter: The incoming security frame counter for ZGPD

uint8_t zgpd_key[ESP_ZB_CCM_KEY_SIZE]: Security key for the GPD

uint8_t endpoint: Endpoint pair of IEEE:EP if App ID is 010.

uint8_t sec_options: Security options

uint8_t groupcast_radius: To limit the range of the groupcast

uint8_t is_sink: Sink or proxy

uint16_t ext_options: The tunneling options

uint8_t addr_ref: Address reference

struct esp_zgp_tbl_ent_s::[anonymous]::esp_zgp_proxy_tbl_ent_s::esp_zgp_lwsink_addr_list_s lwsaddr[ZB_ZGP_MAX_LW_UNICAST_ADDR_PER_GPD]: Sink address list

esp_zgp_pair_group_list_t sgrp[ZB_ZGP_MAX_SINK_GROUP_PER_GPD]: Sink group list

struct esp_zgp_tbl_ent_s::[anonymous]::esp_zgp_proxy_tbl_ent_s proxy: Proxy table

uint8_t device_id: ZGPD Device ID from Commissioning frame, refer to esp_zb_zgpd_dev_id_t

uint8_t match_dev_tbl_idx: index in matching table matched by device_id or app_info.manuf_model_id

esp_zb_ieee_addr_t ieee_addr: Extension to the table, Dest IEEE address to use in GPT to GPD packets even if GPD is identified by SrcID

struct esp_zgp_tbl_ent_s::[anonymous]::esp_zgp_sink_tbl_ent_s sink: Sink table

union esp_zgp_tbl_ent_s::[anonymous] u: ZGP table

Macros

ESP_ZB_ZGP_FILL_GPS_SECURITY_LEVEL(sec_level, with_link_key, involve_tc): Fill the security level for ZGP sink.

ESP_ZB_ZGPD_IDS_COMPARE(id1, id2): Compare the ZGP devive identifier.

ESP_ZB_GPDF_CMD_UNDEFINED

ESP_ZB_ZGP_ZCL_CMD_ID_UNDEFINED

ESP_ZB_ZGP_ZCL_CLUSTER_ID_UNDEFINED

ESP_ZB_ZGP_MAPPING_ENTRY_PARSED_PAYLOAD

ESP_ZB_GPDF_CMD_STORE_SCENE0

ESP_ZB_GPDF_CMD_STORE_SCENE1

ESP_ZB_GPDF_CMD_STORE_SCENE2

ESP_ZB_GPDF_CMD_STORE_SCENE3

ESP_ZB_GPDF_CMD_LVL_CTRL_STOP

ESP_ZB_GPDF_CMD_MOVE_UP_WITH_ON_OFF

ESP_ZB_GPDF_CMD_MOVE_DOWN_WITH_ON_OFF

ESP_ZB_GPDF_CMD_MOVE_STEP_ON

ESP_ZB_GPDF_CMD_MOVE_STEP_OFF

Type Definitions

typedef enum esp_zb_zgp_comm_status_e esp_zb_zgp_comm_status_t: Possible ZGP commissioning result.

typedef enum esp_zgp_gp_device_e esp_zgp_gp_device_t: possible types of GP device

typedef enum esp_zb_zgp_mode_change_reason_e esp_zb_zgp_mode_change_reason_t: ZGP Sink mode change reason.

typedef enum esp_zb_zgp_communication_mode_e esp_zb_zgp_communication_mode_t: ZGP communication mode.

typedef enum esp_zgp_commissioning_exit_mode_e esp_zgp_commissioning_exit_mode_t

typedef enum esp_zb_zgp_mode_e esp_zb_zgp_mode_t: Current mode of ZGP endpoint.

typedef enum esp_zb_zgp_app_id_e esp_zb_zgp_app_id_t: ZGP device application ID.

typedef enum esp_zgp_table_request_entries_type_e esp_zgp_table_request_entries_type_t: ZGP table request entries type.

typedef enum esp_zb_zgp_security_level_e esp_zb_zgp_security_level_t: ZGP security level type.

typedef enum esp_zb_zgp_security_key_type_e esp_zb_zgp_security_key_type_t: ZGP security key type.

typedef enum esp_zb_zgp_security_level_protection_with_gp_link_key_e esp_zb_zgp_security_level_protection_with_gp_link_key_t: ZGP gpsSecurityLevel attribute.

typedef enum esp_zb_zgp_security_level_involve_tc_e esp_zb_zgp_security_level_involve_tc_t: ZGP gpsSecurityLevel attribute.

typedef enum esp_zb_zgpd_commissioning_method_e esp_zb_zgpd_commissioning_method_t: ZGPD commissioning method.

typedef enum esp_zb_zgpd_dev_id_e esp_zb_zgpd_dev_id_t: Possible ZGPD device identifiers.

typedef enum esp_zgp_gpp_functionality_e esp_zgp_gpp_functionality_t: Green power proxy funtionality.

typedef enum esp_zgp_gps_functionality_e esp_zgp_gps_functionality_t: Green power sink funtionality.

typedef struct esp_zb_zgp_cluster_list_s esp_zb_zgp_cluster_list_t: ZGP device Cluster List.

typedef union esp_zb_zgpd_addr_u esp_zb_zgpd_addr_t: ZGP device address.

Note

ZGPD is identified in network whether by SrcId or its IEEE address.

typedef struct esp_zb_zgpd_id_s esp_zb_zgpd_id_t: ZGP device identifier.

typedef struct esp_zb_zgp_gpd_cmds_list_s esp_zb_zgp_gpd_cmds_list_t: ZGP device CommandID list.

typedef struct esp_zb_zgps_mapping_entry_s esp_zb_zgps_mapping_entry_t: Mapping table entry structure for ZGP sink.

typedef struct esp_zb_zgp_raw_report_desc_s esp_zb_zgp_raw_report_desc_t: Raw report descriptor received from the GPD.

typedef struct esp_zgp_pair_group_list_s esp_zgp_pair_group_list_t: The structure for the paired group List.

typedef struct esp_zgp_tbl_ent_s esp_zgp_tbl_ent_t: The structure for Green Power table entry.

typedef esp_zgp_tbl_ent_t esp_zb_zgp_sink_tbl_ent_t: Sink table structure.

typedef esp_zgp_tbl_ent_t esp_zb_zgp_proxy_tbl_ent_t: Proxy table structure.

Enumerations

enum esp_zb_zgp_comm_status_e

Possible ZGP commissioning result.

Values:

enumerator ESP_ZB_ZGP_COMMISSIONING_COMPLETED: Commissioning with some device completed successfully

enumerator ESP_ZB_ZGP_COMMISSIONING_FAILED: Commissioning failed.

enumerator ESP_ZB_ZGP_COMMISSIONING_TIMED_OUT: Commissioning failed, because of timeout

enumerator ESP_ZB_ZGP_COMMISSIONING_NO_MATCH_ERROR: No functionality match with commissioning device is found.

enumerator ESP_ZB_ZGP_COMMISSIONING_INTERNAL_ERROR: Commissioning failed, because some internal error occurred in stack.

enumerator ESP_ZB_ZGP_COMMISSIONING_EXTERNAL_ERROR: Commissioning failed, because some external error has occurred.

enumerator ESP_ZB_ZGP_COMMISSIONING_CANCELLED_BY_USER: User cancelled commissioning by calling esp_zb_zgps_stop_commissioning

enumerator ESP_ZB_ZGP_ZGPD_DECOMMISSIONED: ZGPD sent Decommissioning command

enum esp_zgp_gp_device_e

possible types of GP device

Values:

enumerator ESP_ZGP_DEVICE_PROXY: Proxy device

enumerator ESP_ZGP_DEVICE_PROXY_BASIC: Proxy basic device

enumerator ESP_ZGP_DEVICE_TARGET_PLUS: Target plus device

enumerator ESP_ZGP_DEVICE_TARGET: Target device

enumerator ESP_ZGP_DEVICE_COMMISSIONING_TOOL: Commissioning tool device

enumerator ESP_ZGP_DEVICE_COMBO: Combo device

enumerator ESP_ZGP_DEVICE_COMBO_BASIC: Combo basic device

enum esp_zb_zgp_mode_change_reason_e

ZGP Sink mode change reason.

Values:

enumerator ESP_ZB_ZGP_MODE_CHANGE_TRIGGERED_BY_COMMAND: GP Sink Commissioning Mode Command

enumerator ESP_ZB_ZGP_MODE_CHANGE_TRIGGERED_BY_USER: Application decided to change the mode

enumerator ESP_ZB_ZGP_MODE_CHANGE_ON_FIRST_PARING_EXIT: The device joined and the gpsCommissioningExitMode attribute has “On First Pairing success” bit seted

enumerator ESP_ZB_ZGP_MODE_CHANGE_TIMEOUT: It is possible if timeout is set and expired “On CommissioningWindow expiration” bit is set Timeout parameter to user API gps_commissioning_start().

enum esp_zb_zgp_communication_mode_e

ZGP communication mode.

Values:

enumerator ESP_ZB_ZGP_COMMUNICATION_MODE_FULL_UNICAST: Full unicast

enumerator ESP_ZB_ZGP_COMMUNICATION_MODE_GROUPCAST_DERIVED: Groupcast derived

enumerator ESP_ZB_ZGP_COMMUNICATION_MODE_GROUPCAST_PRECOMMISSIONED: Groupcast percommissioned

enumerator ESP_ZB_ZGP_COMMUNICATION_MODE_LIGHTWEIGHT_UNICAST: Light weight unicate

enum esp_zgp_commissioning_exit_mode_e

Values:

enumerator ESP_ZGP_COMMISSIONING_EXIT_MODE_ON_COMMISSIONING_WINDOW_EXPIRATION

enumerator ESP_ZGP_COMMISSIONING_EXIT_MODE_ON_PAIRING_SUCCESS

enumerator ESP_ZGP_COMMISSIONING_EXIT_MODE_ON_GP_PROXY_COMMISSIONING_MODE_EXIT

enumerator ESP_ZGP_COMMISSIONING_EXIT_MODE_ON_CWE_OR_PS

enumerator ESP_ZGP_COMMISSIONING_EXIT_MODE_ON_CWE_OR_PCM

enumerator ESP_ZGP_COMMISSIONING_EXIT_MODE_ALL

enum esp_zb_zgp_mode_e

Current mode of ZGP endpoint.

Values:

enumerator ESP_ZB_ZGP_OPERATIONAL_MODE: Operational mode

enumerator ESP_ZB_ZGP_COMMISSIONING_MODE: Commissioning mode

enum esp_zb_zgp_app_id_e

ZGP device application ID.

Values:

enumerator ESP_ZB_ZGP_APP_ID_0000: ApplicationID value 0b000 - usage of the SrcID

enumerator ESP_ZB_ZGP_APP_ID_0001: ApplicationID value 0b001 - LPED

enumerator ESP_ZB_ZGP_APP_ID_0010: ApplicationID value 0b010 - usage of the GPD IEEE address.

enumerator ESP_ZB_ZGP_APP_ID_INVALID: Invalid ApplicationID

enum esp_zgp_table_request_entries_type_e

ZGP table request entries type.

Values:

enumerator ESP_ZGP_REQUEST_TABLE_ENTRIES_BY_GPD_ID: GPD ID type

enumerator ESP_ZGP_REQUEST_TABLE_ENTRIES_BY_INDEX: Index type

enum esp_zb_zgp_security_level_e

ZGP security level type.

Values:

enumerator ESP_ZB_ZGP_SEC_LEVEL_NO_SECURITY: No security

enumerator ESP_ZB_ZGP_SEC_LEVEL_REDUCED: 1LSB of frame counter and short (2B) MIC

enumerator ESP_ZB_ZGP_SEC_LEVEL_FULL_NO_ENC: Full (4B) frame counter and full (4B) MIC

enumerator ESP_ZB_ZGP_SEC_LEVEL_FULL_WITH_ENC: Encryption & full (4B) frame counter and full (4B) MIC

enum esp_zb_zgp_security_key_type_e

ZGP security key type.

Values:

enumerator ESP_ZB_ZGP_SEC_KEY_TYPE_NO_KEY: No key

enumerator ESP_ZB_ZGP_SEC_KEY_TYPE_NWK: Zigbee NWK key

enumerator ESP_ZB_ZGP_SEC_KEY_TYPE_GROUP: ZGPD group key

enumerator ESP_ZB_ZGP_SEC_KEY_TYPE_GROUP_NWK_DERIVED: NWK-key derived ZGPD group key

enumerator ESP_ZB_ZGP_SEC_KEY_TYPE_ZGPD_INDIVIDUAL: (Individual) out-of-the-box ZGPD key

enumerator ESP_ZB_ZGP_SEC_KEY_TYPE_DERIVED_INDIVIDUAL: Derived individual ZGPD key

enum esp_zb_zgp_security_level_protection_with_gp_link_key_e

ZGP gpsSecurityLevel attribute.

Values:

enumerator ESP_ZB_ZGP_SEC_LEVEL_PROTECTION_WITHOUT_GP_LINK_KEY: Do not used GP link key

enumerator ESP_ZB_ZGP_SEC_LEVEL_PROTECTION_WITH_GP_LINK_KEY: Use GP link key

enum esp_zb_zgp_security_level_involve_tc_e

ZGP gpsSecurityLevel attribute.

Values:

enumerator ESP_ZB_ZGP_SEC_LEVEL_PROTECTION_DO_NOT_INVOLVE_TC: Do not involve TC

enumerator ESP_ZB_ZGP_SEC_LEVEL_PROTECTION_INVOLVE_TC: Involve TC

enum esp_zb_zgpd_commissioning_method_e

ZGPD commissioning method.

Values:

enumerator ESP_ZB_ZGPD_COMMISSIONING_BIDIR: Bidirectional commissioning

enumerator ESP_ZB_ZGPD_COMMISSIONING_UNIDIR: Unidirectional commissioning

enumerator ESP_ZB_ZGPD_COMMISSIONING_AUTO: Auto-commissioning

enum esp_zb_zgpd_dev_id_e

Possible ZGPD device identifiers.

Values:

enumerator ESP_ZB_ZGP_SIMPLE_GEN_1_STATE_SWITCH_DEV_ID: Simple Generic 1-state ZGP switch

enumerator ESP_ZB_ZGP_SIMPLE_GEN_2_STATE_SWITCH_DEV_ID: Simple Generic 2-state ZGP switch

enumerator ESP_ZB_ZGP_ON_OFF_SWITCH_DEV_ID: ZGP On/Off switch

enumerator ESP_ZB_ZGP_LEVEL_CONTROL_SWITCH_DEV_ID: ZGP Level Control Switch

enumerator ESP_ZB_ZGP_SIMPLE_SENSOR_DEV_ID: ZGP Simple Sensor

enumerator ESP_ZB_ZGP_ADVANCED_GEN_1_STATE_SWITCH_DEV_ID: Advanced Generic 1-state ZGP switch

enumerator ESP_ZB_ZGP_ADVANCED_GEN_2_STATE_SWITCH_DEV_ID: Advanced Generic 2-state ZGP switch

enumerator ESP_ZB_ZGP_GEN_8_CONT_SWITCH_DEV_ID: Generic 8-contact ZGP switch

enumerator ESP_ZB_ZGP_COLOR_DIMMER_SWITCH_DEV_ID: Color Dimmer ZGP Switch

enumerator ESP_ZB_ZGP_LIGHT_SENSOR_DEV_ID: ZGP Light Sensor

enumerator ESP_ZB_ZGP_OCCUPANCY_SENSOR_DEV_ID: ZGP Occupancy Sensor

enumerator ESP_ZB_ZGP_DOOR_LOCK_CONTROLLER_DEV_ID: ZGP Door Lock Controller

enumerator ESP_ZB_ZGP_TEMPERATURE_SENSOR_DEV_ID: ZGP temperature sensor

enumerator ESP_ZB_ZGP_PRESSURE_SENSOR_DEV_ID: ZGP Pressure Sensor

enumerator ESP_ZB_ZGP_FLOW_SENSOR_DEV_ID: ZGP Flow sensor

enumerator ESP_ZB_ZGP_ENVIRONMENT_SENSOR_DEV_ID: ZGP Temperature + Humidity sensor

enumerator ESP_ZB_ZGP_MANUF_SPECIFIC_DEV_ID: Manufactures-specific; more fields in the Commissioning frame. See 4.1

enumerator ESP_ZB_ZGP_UNDEFINED_DEV_ID: Undefined device type

enum esp_zgp_gpp_functionality_e

Green power proxy funtionality.

Values:

enumerator ESP_ZGP_GPP_GP_FEATURE

enumerator ESP_ZGP_GPP_DIRECT_COMMUNICATION

enumerator ESP_ZGP_GPP_DERIVED_GROUPCAST_COMMUNICATION

enumerator ESP_ZGP_GPP_PRECOMMISSIONED_GROUPCAST_COMMUNICATION

enumerator ESP_ZGP_GPP_FULL_UNICAST_COMMUNICATION

enumerator ESP_ZGP_GPP_LIGHTWEIGHT_UNICAST_COMMUNICATION

enumerator ESP_ZGP_GPP_RESERVED_B6

enumerator ESP_ZGP_GPP_BIDIRECTIONAL_OPERATION

enumerator ESP_ZGP_GPP_PROXY_TABLE_MAINTENANCE

enumerator ESP_ZGP_GPP_RESERVED_B9

enumerator ESP_ZGP_GPP_GP_COMMISSIONING

enumerator ESP_ZGP_GPP_CT_BASED_COMMISSIONING

enumerator ESP_ZGP_GPP_MAINTENANCE_OF_GPD

enumerator ESP_ZGP_GPP_SEC_LEVEL_NO_SECURITY

enumerator ESP_ZGP_GPP_SEC_LEVEL_REDUCED

enumerator ESP_ZGP_GPP_SEC_LEVEL_FULL_NO_ENC

enumerator ESP_ZGP_GPP_SEC_LEVEL_FULL_WITH_ENC

enumerator ESP_ZGP_GPP_RESERVED_B17

enumerator ESP_ZGP_GPP_RESERVED_B18

enumerator ESP_ZGP_GPP_GPD_IEEE_ADDRESS

enum esp_zgp_gps_functionality_e

Green power sink funtionality.

Values:

enumerator ESP_ZGP_GPS_GP_FEATURE

enumerator ESP_ZGP_GPS_DIRECT_COMMUNICATION

enumerator ESP_ZGP_GPS_DERIVED_GROUPCAST_COMMUNICATION

enumerator ESP_ZGP_GPS_PRECOMMISSIONED_GROUPCAST_COMMUNICATION

enumerator ESP_ZGP_GPS_FULL_UNICAST_COMMUNICATION

enumerator ESP_ZGP_GPS_LIGHTWEIGHT_UNICAST_COMMUNICATION

enumerator ESP_ZGP_GPS_PROXIMITY_BIDIRECTIONAL_OPERATION

enumerator ESP_ZGP_GPS_MULTIHOP_BIDIRECTIONAL_OPERATION

enumerator ESP_ZGP_GPS_PROXY_TABLE_MAINTENANCE

enumerator ESP_ZGP_GPS_PROXIMITY_COMMISSIONING

enumerator ESP_ZGP_GPS_MULTIHOP_COMMISSIONING

enumerator ESP_ZGP_GPS_CT_BASED_COMMISSIONING

enumerator ESP_ZGP_GPS_MAINTENANCE_OF_GPD

enumerator ESP_ZGP_GPS_SEC_LEVEL_NO_SECURITY

enumerator ESP_ZGP_GPS_SEC_LEVEL_REDUCED

enumerator ESP_ZGP_GPS_SEC_LEVEL_FULL_NO_ENC

enumerator ESP_ZGP_GPS_SEC_LEVEL_FULL_WITH_ENC

enumerator ESP_ZGP_GPS_SINK_TABLE_BASED_GROUPCAST_FORWARDING

enumerator ESP_ZGP_GPS_TRANSLATION_TABLE

enumerator ESP_ZGP_GPS_GPD_IEEE_ADDRESS