ZBOSS commissioning signals handler

Device started for the first time after the NVRAM erase.

When generated:

• Upon completing the typical device startup (network formation for ZC or rejoin/discovery/association for ZR and ZED).
• This signal is exclusive to ZB_BDB_SIGNAL_DEVICE_REBOOT

Note

No ZB_BDB_SIGNAL_STEERING or ZB_BDB_SIGNAL_FORMATION signals will be generated.

Status codes:

• RET_OK: Device started after the NVRAM erase
• RET_ERROR: An error of any type.

Signal parameters:

• none

      case ZB_BDB_SIGNAL_DEVICE_FIRST_START:
        TRACE_MSG(TRACE_APP1, "Device STARTED OK", (FMT__0));
        bdb_start_top_level_commissioning(ZB_BDB_NETWORK_STEERING);
#ifdef TEST_APS_FRAGMENTATION
        ZB_SCHEDULE_APP_ALARM(send_frag_data, 0, ZB_TIME_ONE_SECOND / 2);
#endif
        break;

Device started using the NVRAM contents.

When generated:

• Upon the device joining/rejoining Zigbee network using restored parameters.
• This signal is exclusive to ZB_BDB_SIGNAL_DEVICE_FIRST_START

Note

No ZB_BDB_SIGNAL_STEERING or ZB_BDB_SIGNAL_FORMATION signals will be generated.

Status codes:

• RET_OK: Device started using configuration stored in NVRAM
• RET_ERROR: An error of any type.

Signal parameters:

• none

      case ZB_BDB_SIGNAL_DEVICE_REBOOT:
        TRACE_MSG(TRACE_APP1, "Device RESTARTED OK", (FMT__0));
#ifndef ZB_USE_BUTTONS
        /* Do not have buttons in simulator - just start periodic on/off sending */
        cmd_in_progress = ZB_FALSE;
        ZB_SCHEDULE_APP_ALARM_CANCEL(button_press_handler, ZB_ALARM_ANY_PARAM);
        ZB_SCHEDULE_APP_ALARM(button_press_handler, 0, 7 * ZB_TIME_ONE_SECOND);
#endif
        break;

BDB finding and binding for an initiator endpoint completed.

When generated:

• F&B with a Target succeeded or F&B initiator timeout expired or cancelled.

Status codes:

• zdo_fb_initiator_finished_status

Signal parameters:

• zb_zdo_signal_fb_initiator_finished_params_t

BDB finding and binding for a target endpoint completed.

When generated:

• F&B target timeout expires.

Status codes:

• RET_OK: F&B completed successfully.
• RET_ERROR: An error of any type.

Signal parameters:

• none

BDB network formation completed (Network formation only).

When generated:

• Upon completing Network formation initiated by bdb_start_top_level_commissioning(ZB_BDB_NETWORK_FORMATION).

Status codes:

• RET_OK: Network formation completed.
• RET_INTERRUPTED: was cancelled with bdb_cancel_formation()

Signal parameters:

• none

BDB formation cancel request processed

When generated:

• after the cancel request called with bdb_cancel_formation() is processed

Status codes:

• RET_INVALID_STATE: formation is not in progress
• RET_PENDING: it is too late to cancel a formation, it will be completed soon
• RET_IGNORE: cancellation was already requested
• RET_OK: formation is cancelled successfully

Signal parameters:

• none

BDB network steering completed (Network steering only).

When generated:

• Upon completing Network steering initiated by bdb_start_top_level_commissioning(ZB_BDB_NETWORK_STEERING).

Status codes:

• RET_OK: Network steering completed.
• RET_INTERRUPTED: was cancelled with bdb_cancel_joining()

Has additional data of type zb_zdo_signal_leave_indication_params_t.

Signal parameters:

• none

BDB steering cancel request processed

When generated:

• after the cancel request called with bdb_cancel_steering() is processed

Status codes:

• RET_ILLEGAL_REQUEST: device is a ZC
• RET_INVALID_STATE: steering for a node not a network is not in progress
• RET_PENDING: it is too late to cancel a steering, it will be completed soon
• RET_IGNORE: cancellation was already requested
• RET_OK: steering is cancelled successfully

Signal parameters:

• none

TC rejoin is completed

When generated:

• Device completes TC rejoin procedure.

Status codes:

• RET_OK: TC rejoin completed successful
• RET_ERROR: An error of any type.

Signal parameters:

• none

      case ZB_BDB_SIGNAL_TC_REJOIN_DONE:
        TRACE_MSG(TRACE_APP1, "TC rejoin failed, so try it again with interval", (FMT__0));
        ZB_SCHEDULE_APP_ALARM(zb_bdb_initiate_tc_rejoin, 0, 3 * ZB_TIME_ONE_SECOND);
        break; /* ZB_BDB_SIGNAL_TC_REJOIN_DONE */

WWAH Rejoin start indication.

When generated:

• Device lost communication with the parent and started WWAH Rejoin procedure.

Status codes:

• RET_OK: Leave command received from the child device.
• Does not return error status.

Signal parameters: no

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;
      }

Device left

Get status from the application signal.

Parameters

param

- buffer reference

Returns

status zb_ret_t

Device rejoin with high security

Device join without high security

Device rejoin without high security

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

Obsolete signal, used for pre-R21 ZBOSS API compatibility. Use ZB_ZDO_SIGNAL_DEVICE_ANNCE signal instead!

When generated:

• Indicates that there is a new device associated with Zigbee Coordinator or router.

Status codes:

• RET_OK: New device associated.
• Does not return error status.

Signal parameters:

• zb_nwk_signal_device_associated_params_t

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

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

Notifies the Zigbee Trust center or router application about permit join status changed.

When generated:

• Network was just open
• Network was just closed

Status codes:

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

Signal parameters:

• zb_uint8_t - Open time or zero if network closed. Value of zb_zdo_mgmt_permit_joining_req_param_t::permit_duration

Signal handling:

      case ZB_NWK_SIGNAL_PERMIT_JOIN_STATUS:
      {
        zb_uint8_t *permit_duration = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_uint8_t);
        TRACE_MSG(TRACE_APP1, "Permit Join Received. Duration: %hd", (FMT__D, (*permit_duration)));
        break; /* ZB_NWK_SIGNAL_PERMIT_JOIN_STATUS */
      }

Signal generation:

• To self:

  void permit_join_request_local(zb_uint8_t buf, zb_uint16_t time)
  {
    TRACE_MSG(TRACE_APP3, ">> permit_join_request_local : param %hd", (FMT__D, buf));
    if (buf == 0U)
    {
      zb_buf_get_out_delayed_ext(permit_join_request_local, time, 0U);
    }
    else
    {
      zb_zdo_mgmt_permit_joining_req_param_t *req_param
          = ZB_BUF_GET_PARAM(buf, zb_zdo_mgmt_permit_joining_req_param_t);
      TRACE_MSG(TRACE_APP1, "permit_join_request_local_cb: requesting permit join", (FMT__0));
      req_param->dest_addr = zb_get_short_address();
      req_param->permit_duration = (zb_uint8_t) time;
      req_param->tc_significance = ZB_TRUE;
      zb_zdo_mgmt_permit_joining_req(buf, &permit_join_request_local_cb);
    }
  }
  void permit_join_request_local_cb(zb_uint8_t param)
  {
    if (param != 0U)
    {
      zb_buf_free(param);
    }
    TRACE_MSG(TRACE_APP1, "permit_join_request_local_cb: callback called", (FMT__0));
    return;
  }

• To other devices:

  void permit_join_request_broadcast(zb_uint8_t buf, zb_uint16_t time)
  {
    TRACE_MSG(TRACE_APP3, ">> permit_join_request_broadcast : param %hd", (FMT__D, buf));
    if (buf == 0U)
    {
      zb_buf_get_out_delayed_ext(permit_join_request_broadcast, time, 0U);
    }
    else
    {
      zb_zdo_mgmt_permit_joining_req_param_t *req_param
          = ZB_BUF_GET_PARAM(buf, zb_zdo_mgmt_permit_joining_req_param_t);
      TRACE_MSG(TRACE_APP1, "permit_join_request_broadcast_cb: requesting permit join", (FMT__0));
      req_param->dest_addr = ZB_NWK_BROADCAST_ROUTER_COORDINATOR;
      req_param->permit_duration = (zb_uint8_t) time;
      req_param->tc_significance = ZB_TRUE;
      zb_zdo_mgmt_permit_joining_req(buf, &permit_join_request_broadcast_cb);
    }
  }
  void permit_join_request_broadcast_cb(zb_uint8_t param)
  {
    if (param != 0U)
    {
      zb_buf_free(param);
    }
    TRACE_MSG(TRACE_APP1, "permit_join_request_broadcast_confirm_cb: callback called", (FMT__0));
    return;
  }

ZBOSS is ready to shutdown signal

When generated:

• after ZBOSS preparations to shutdown initiated by zboss_start_shut() is done

After receiving that signal application MUST complete ZBOSS shutdown by calling zboss_complete_shut(). It is impossible to continue ZBOSS work without a restart after calling zboss_start_shut().

Signal parameters:

• none

Device rejoin with standard security

Device join without security

Device rejoin without standard security

authorize device

deby authorization - msend Remove device

ignore Update Device - that meay lead to authorization deny

Authorization type for legacy devices ( < r21)

Authorization type for r21 device through TCLK

Authorization type for SE through CBKE

Authorization success

F&B on the Initiator side is finished by timeout

F&B on the Initiator side is canceled

F&B on the Initiator side is failure finished

F&B with a Target on the Initiator side is success completed

Authorization failed

Authorization success

Cuts ZBOSS signal headers while keeping the signal parameter (if it was in the buffer).

Parameters

buf	- pointer to a zb_buf_t structure. The buffer must be the one passed into zboss_signal_handler.

Obsolete signal, used for pre-R21 ZBOSS API compatibility. Not recommended to use.

When generated:

• After the device has been started and the non-BDB commissioning completed.
• In case of the commissioning error.

Status codes:

• RET_OK: Device has started and joined the network.
• RET_ERROR: An error of any type.

Signal parameters:

• none

Notifies the application about the new device appearance.

When generated:

• Upon receiving the Device_annce command.

Status codes:

• RET_OK: Device_annce command was received.
• Does not return error status.

Signal parameters:

• zb_zdo_signal_device_annce_params_t

      case ZB_ZDO_SIGNAL_DEVICE_ANNCE:
      {
        zb_zdo_signal_device_annce_params_t *dev_annce_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zdo_signal_device_annce_params_t);
        simple_gw_dev_annce_cb(dev_annce_params->device_short_addr);
      }
      break;

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

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

Corrupted or incorrect signal information.

When generated:

• Incorrect buffer length detected by zb_get_app_signal (less then zb_zdo_app_signal_hdr_t)

Status codes:

• none

Signal parameters:

• none

Obtains pointer to parameters passed with application signal.

Parameters

[in]	sg_p	- pointer to application signal
[in]	type	- parameter type

Returns

pointer to signal parameters

Example

      case ZB_ZDO_SIGNAL_LEAVE:
      {
        zb_zdo_signal_leave_params_t *leave_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zdo_signal_leave_params_t);
        erl_interface_leave_handler(leave_params->leave_type);
      }
      break;

Notifies the application that the device itself has left the network.

When generated:

• Upon sending the "Leave" command.

Status codes:

• RET_OK: Device has sent the "Leave" command.
• Does not return error status.

Signal parameters:

• zb_zdo_signal_leave_params_t

      case ZB_ZDO_SIGNAL_LEAVE:
      {
        zb_zdo_signal_leave_params_t *leave_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zdo_signal_leave_params_t);
        light_control_retry_join(leave_params->leave_type);
      }
      break;

Network leave indication.

When generated:

• The child device has left the network.

Status codes:

• RET_OK: Leave command received from the child device.
• RET_ERROR: An error of any type.

Signal parameters:

• zb_zdo_signal_leave_indication_params_t

      case ZB_ZDO_SIGNAL_LEAVE_INDICATION:
      {
        zb_zdo_signal_leave_indication_params_t *leave_ind_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zdo_signal_leave_indication_params_t);
        if (!leave_ind_params->rejoin)
        {
          simple_gw_leave_indication(leave_ind_params->device_addr);
        }
      }
      break;

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.

Notifies the application that ZBOSS framework (scheduler, buffer pool, etc.) has started, but no join/rejoin/formation/BDB initialization has been done yet.

When generated:

• When the application calls zboss_start_no_autostart() instead of zboss_start() before the zboss_main_loop(). Used when some hardware must be initialized before the Zigbee commissioning, but already has ZBOSS scheduler running. Example: sensor connected through UART.

Status codes:

• RET_OK: Only ZBOSS framework has been initialized.
• Does not return error status.

Signal parameters:

• none

      case ZB_ZDO_SIGNAL_SKIP_STARTUP:
#ifndef ZB_MACSPLIT_HOST
        TRACE_MSG(TRACE_APP1, "ZB_ZDO_SIGNAL_SKIP_STARTUP: start commissioning", (FMT__0));
        if (zb_bdb_is_factory_new())
        {
          ZB_SCHEDULE_APP_ALARM_CANCEL(sp_com_button_pressed_reset_fd, ZB_ALARM_ANY_PARAM);
        }
        /* NVRAM is loaded, init relay state */
        {
          zb_zcl_attr_t *attr_desc_on_off = zb_zcl_get_attr_desc_a(SP_ENDPOINT,ZB_ZCL_CLUSTER_ID_ON_OFF,
                                                                   ZB_ZCL_CLUSTER_SERVER_ROLE,
                                                                   ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID);
          sp_relay_on_off((zb_bool_t )ZB_ZCL_GET_ATTRIBUTE_VAL_8(attr_desc_on_off));
#ifdef SP_CONTROL4_COMPATIBLE
          if (!zb_bdb_is_factory_new())
          {
            /* Increment BOOT_COUNT attribute */
            g_dev_ctx.c4_attr.boot_count++;
            ZB_SCHEDULE_APP_CALLBACK(sp_write_app_data, 0);
          }
#endif /* SP_CONTROL4_COMPATIBLE */
        }
        /* Have zb_bdb_is_factory_new() check inside */
        ZB_SCHEDULE_APP_CALLBACK(sp_start_join, SP_FIRST_JOIN_ATTEMPT);
#endif /* ZB_MACSPLIT_HOST */
        break;
#ifdef ZB_MACSPLIT_HOST
      case ZB_MACSPLIT_DEVICE_BOOT:
        TRACE_MSG(TRACE_APP1, "ZB_MACSPLIT_DEVICE_BOOT: start commissioning", (FMT__0));
        if (zb_bdb_is_factory_new())
        {
          ZB_SCHEDULE_APP_ALARM_CANCEL(sp_com_button_pressed_reset_fd, ZB_ALARM_ANY_PARAM);
        }
        /* NVRAM is loaded, init relay state */
        {
          zb_zcl_attr_t *attr_desc_on_off = zb_zcl_get_attr_desc_a(SP_ENDPOINT,ZB_ZCL_CLUSTER_ID_ON_OFF,
                                                                   ZB_ZCL_CLUSTER_SERVER_ROLE,
                                                                   ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID);
          sp_relay_on_off((zb_bool_t )ZB_ZCL_GET_ATTRIBUTE_VAL_8(attr_desc_on_off));
#ifdef SP_CONTROL4_COMPATIBLE
          if (!zb_bdb_is_factory_new())
          {
            /* Increment BOOT_COUNT attribute */
            g_dev_ctx.c4_attr.boot_count++;
            ZB_SCHEDULE_APP_CALLBACK(sp_write_app_data, 0);
          }
#endif /* SP_CONTROL4_COMPATIBLE */
        }
        /* Have zb_bdb_is_factory_new() check inside */
        ZB_SCHEDULE_APP_CALLBACK(sp_start_join, SP_FIRST_JOIN_ATTEMPT);
        break;
#endif /* ZB_MACSPLIT_HOST */

Authorization failed

Authorization success

Authorization timeout

The supplied endpoint was equal to 0x00 or between 0xf1 and 0xff.

The device is not in the proper state to support the requested operation.

The requested device did not exist on a device following a child descriptor request to a parent.

The requested endpoint is not described by simple descriptor.

Custom internal statuses.

The device does not have storage space to support the requested operation.

A child descriptor was not available following a discovery request to a parent.

The unbind request was unsuccessful due to the coordinator or source device not having an entry in its binding table to unbind.

The requested optional feature is not supported on the target device.

The index in the received command is out of bounds.

The device does not have table space to support the operation.

A timeout has occurred with the requested operation.

The requested operation or transmission was completed successfully. The supplied request type was invalid.

The permissions configuration table on the target indicates that the request is not authorized from this device.

The end device bind request was unsuccessful due to a failure to match any suitable clusters.

Association parameters.

Stack passes this parameter to application when some device associates to that.

Application signal header

Type for signals passed to zboss_signal_handler().

Holds one of zdo_app_signal_type. Previously it was defined as enum but was converted to a set of defines due to MISRA violations.

Type for Authorization types for ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED.

Type for Status codes for F&B Initiator Finished signal.

Holds one of zdo_fb_initiator_finished_status. Kept only for backward compatibility as zdo_fb_initiator_finished_status were declared previously as enum. Can be removed in future releases.

Type for Authorization statuses for ZB_ZDO_AUTHORIZATION_TYPE_LEGACY value of zdo_authorization_type type.

Sleep signal parameters.

Stack passes this parameter to application when device ready to sleep.

Association parameters.

Stack passes this parameter to application when some device joins/rejoins to network.

Leave Indication parameters.

Stack passes this parameter to application upon receipt of leave indication primitive.

Leave parameters.

Stack passes this parameter to application when device leave the network.

Macsplit device boot parameters.

Macsplit passes this parameter to application when device is booted.

NLME status indication parameters.

Stack passes this parameter to application when NLME status indication is generated.

Type for Authorization types for ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED.

Type for ZDP status values.

Holds one of zdp_status. Kept for backward compatibility as zdp_status were declared previously as enum.

Unpack application signal buffer in zboss_signal_handler()

Parameters

param	- parameter of zboss_signal_handler()
sg_p	- pointer to the extended signal info, if application wants it. Can be NULL.

Returns

Application signal

ZBOSS application signal handler.

Mandatory for all applications implemented on the top of ZBOSS stack. See zdo_app_signal_type.

Parameters

param

- reference to the buffer which contains signal. See zb_get_app_signal.