3. Gateway Discovery Control Events

To notify the developer about major events related to Gateway Discovery, the Amazon Sidewalk stack uses the SID_CONTROL_EVENT_LINK2_GW_DISCOVERY_STATUS control event. The event_data member contains information about the event.

By subscribing to control events, the developer will be notified of a gateway discovery timeout, as well as of a synchronization event or beacon loss. For example, in the case of a gateway discovery timeout, the developer can change the policy and retry discovery.

The following GW Discovery events are supported.

/**
 * The set of control events that are notified to the developer.
 * @see on_control_event_notify in #sid_event_callbacks.
 */
enum sid_control_event_type {
    /** Event indicating change in low latency
     *  configuration for #SID_LINK_TYPE_3
     */
    SID_CONTROL_EVENT_LOW_LATENCY_CONFIG_UPDATE = 0,
    /** Event indicating the device exceeded the traffic thresholds */
    SID_CONTROL_EVENT_TRAFFIC_THRESHOLD_RATE_EXCEEDED = 1,
    /** Indicating gateway discovery status events.
     *  The event_data contains information about the event.
     *  See enum sid_link_type_2_gw_discovery_event for details
     */
    SID_CONTROL_EVENT_LINK2_GW_DISCOVERY_STATUS = 2,
    /** Delimiter to enum sid_control_event_type */
    SID_CONTROL_EVENT_LAST,
};

/**
 * Describes the LINK2 GW Discovery events.
 * These events are notified to the developer through network control events
 */
enum sid_link_type_2_gw_discovery_event {
    /** Event indicating gateway under the
     *  selected discovered policy is not found
     */
    SID_LINK_TYPE_2_GW_DISCOVERY_EVENT_DISC_FAILED = 0,
    /** Event indicating the gateway is selected and beacon sync is done */
    SID_LINK_TYPE_2_GW_DISCOVERY_EVENT_BEACON_SYNC = 1,
    /** Event indicating the beacon sync was lost with the selected gateway */
    SID_LINK_TYPE_2_GW_DISCOVERY_EVENT_BEACON_SYNC_LOST = 2,
};

The following code example shows how to implement a user callback on_sidewalk_control_event() to handle network control events.

// Callback to invoke when the Sidewalk library notifies network control event
static void on_sidewalk_control_event(
    const struct sid_control_event_data *data, void *context)
{
    if (data->event_type == SID_CONTROL_EVENT_LINK2_GW_DISCOVERY_STATUS) {
        enum sid_link_type_2_gw_discovery_event *discovery_event =
            data->event_data;
        switch (*discovery_event) {
        case SID_LINK_TYPE_2_GW_DISCOVERY_EVENT_DISC_FAILED: {
            // An event indicating that a gateway was not found
            // within the scanning timeout
            break;
        }
        case SID_LINK_TYPE_2_GW_DISCOVERY_EVENT_BEACON_SYNC: {
            // The beacon sync was done with the selected gateway
            break;
        }
        case SID_LINK_TYPE_2_GW_DISCOVERY_EVENT_BEACON_SYNC_LOST: {
            // The beacon sync was lost
            break;
        }
        }
    }
}

// The set of user callbacks
struct sid_event_callbacks event_callbacks = {
    .context = &g_app_context,
    .on_event = on_sidewalk_event,
    .on_msg_received = on_sidewalk_msg_received,
    .on_msg_sent = on_sidewalk_msg_sent,
    .on_send_error = on_sidewalk_send_error,
    .on_status_changed = on_sidewalk_status_changed,
    .on_factory_reset = on_sidewalk_factory_reset,
    // Pass our callback to Sidewalk library
    .on_control_event_notify = on_sidewalk_control_event,
};

// The characteristics of the end device
struct sid_end_device_characteristics dev_ch = {
    .type = SID_END_DEVICE_TYPE_STATIC,
    .power_type = SID_END_DEVICE_POWERED_BY_BATTERY_AND_LINE_POWER,
    .qualification_id = 0x0001,
};

struct sid_config config = {
    .link_mask = SID_LINK_TYPE_2,
    .dev_ch = dev_ch,
    .callbacks = &event_callbacks,
    .link_config = app_get_ble_config(),
    .sub_ghz_link_config = app_get_sub_ghz_config(),  // update sub GHz config
};

static struct sid_handle *sidewalk_handle = NULL;
sid_error_t ret = sid_init(config, &sidewalk_handle);