APIs for the Comms Hub Function Sub Ghz plugin.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code. 

/***************************************************************************/
#ifndef COMMS_HUB_FUNCTION_SUB_GHZ_H_INCLUDED
#define COMMS_HUB_FUNCTION_SUB_GHZ_H_INCLUDED

#include "app/framework//include/af-types.h"            // sl_802154_short_addr_t, sl_zigbee_af_cluster_id_t, etc.
#include "../comms-hub-function/comms-hub-function.h"   // sl_zigbee_af_plugin_comms_hub_function_status_t
#include "comms-hub-function-sub-ghz-types.h"
sl_zigbee_af_plugin_comms_hub_function_status_t sl_zigbee_af_comms_hub_function_sub_ghz_start_channel_change_sequence(void);

sl_zigbee_af_plugin_comms_hub_function_status_t sl_zigbee_af_comms_hub_function_sub_ghz_complete_channel_change_sequence(uint32_t pageChannelMask);
 // end of name APIs // end of comms-hub-function-sub-ghz

//------------------------------------------------------------------------------
// Application Framework Internal Functions
//
// The functions below are non-public internal function used by the application
// framework. They are NOT to be used by the application.

void sli_zigbee_af_comms_hub_function_sub_ghz_read_attribute_notification(sl_802154_short_addr_t source,
                                                                          sl_zigbee_af_cluster_id_t clusterId,
                                                                          uint16_t attrId);

void sl_zigbee_af_comms_hub_function_sub_ghz_channel_change_cb(sl_zigbee_af_plugin_comms_hub_function_sub_ghz_channel_change_outcome_t outcome,
                                                               sl_zigbee_af_status_t status);
#endif // COMMS_HUB_FUNCTION_SUB_GHZ_H_INCLUDED

API#

Functions#

void
sli_zigbee_af_comms_hub_function_sub_ghz_read_attribute_notification(sl_802154_short_addr_t source, sl_zigbee_af_cluster_id_t clusterId, uint16_t attrId)

An incoming ReadAttributes message handler.

void
sl_zigbee_af_comms_hub_function_sub_ghz_channel_change_cb(sl_zigbee_af_plugin_comms_hub_function_sub_ghz_channel_change_outcome_t outcome, sl_zigbee_af_status_t status)

Sub-GHz channel change request outcome callback.

API Documentation#

sl_zigbee_af_comms_hub_function_sub_ghz_start_channel_change_sequence#

sl_zigbee_af_plugin_comms_hub_function_status_t sl_zigbee_af_comms_hub_function_sub_ghz_start_channel_change_sequence (void )

Trigger the sub-GHz channel change sequence.

Parameters
N/A

The sub-GHz CHF channel change comprises several steps:

  1. Set the EnergyScanPending Functional Notification flag.

  2. Wait until the GSME reads that flag or one GSME wake up period, whichever comes first.

  3. Perform an energy scan and determine the new page and channel.

  4. Set the ChannelChangePending Functional Notification flag and the ChannelChange attribute.

  5. Wait until the GSME reads that attribute or two GSME wake up periods, whichever comes first.

  6. Change the channel.

Note 1: The GSME must have completed the registration and allocated a mirror before this function is called.

Note 2: sl_zigbee_af_comms_hub_function_sub_ghz_channel_change_cb() is called at steps 3 and 6 in the above sequence. After step 3, the application must call sl_zigbee_af_comms_hub_function_sub_ghz_complete_channel_change_sequence() to advance to steps 4 and and beyond.


Definition at line 65 of file app/framework/plugin/comms-hub-function-sub-ghz/comms-hub-function-sub-ghz.h

sl_zigbee_af_comms_hub_function_sub_ghz_complete_channel_change_sequence#

sl_zigbee_af_plugin_comms_hub_function_status_t sl_zigbee_af_comms_hub_function_sub_ghz_complete_channel_change_sequence (uint32_t pageChannelMask)

Complete the sub-GHz channel change sequence.

Parameters
N/ApageChannelMask

Requested new page and channel as a 32-bit mask (Top 5 bits denote the page, bottom 27 bits the channel. Only one of the bottom 27 bits can be set to 1.)

The application may call this function following an energy scan (step 3 in the sequence described above).

If the mask is 0, the sequence is terminated immediately and the channel is not changed.


Definition at line 79 of file app/framework/plugin/comms-hub-function-sub-ghz/comms-hub-function-sub-ghz.h

Function Documentation#

sli_zigbee_af_comms_hub_function_sub_ghz_read_attribute_notification#

void sli_zigbee_af_comms_hub_function_sub_ghz_read_attribute_notification (sl_802154_short_addr_t source, sl_zigbee_af_cluster_id_t clusterId, uint16_t attrId)

An incoming ReadAttributes message handler.

Parameters
N/Asource
N/AclusterId
N/AattrId

As described above, the sub-GHz channel change sequence involves setting notification flags and waiting for the remote client to read them. This function lets the the CHF know when the ReadAttributes command arrives.


Definition at line 96 of file app/framework/plugin/comms-hub-function-sub-ghz/comms-hub-function-sub-ghz.h

sl_zigbee_af_comms_hub_function_sub_ghz_channel_change_cb#

void sl_zigbee_af_comms_hub_function_sub_ghz_channel_change_cb (sl_zigbee_af_plugin_comms_hub_function_sub_ghz_channel_change_outcome_t outcome, sl_zigbee_af_status_t status)

Sub-GHz channel change request outcome callback.

Parameters
N/Aoutcome

Channel change request outcome

N/Astatus

Ember status code if the outcome is negative

This callback is called by the Comms Hub Function (Sub-GHz) plugin to report the outcome of the channel change request.


Definition at line 108 of file app/framework/plugin/comms-hub-function-sub-ghz/comms-hub-function-sub-ghz.h