8. Appendix — Bring-up checklist
Follow these steps in order on a qualified development kit. Do not proceed past a step until you see its observable result.
| Step | What you do | What you should observe |
|---|---|---|
| 0 | Confirm that GSK is enabled for your devices, and on which link. No API reports it: ask your Amazon Sidewalk contact, or open an AWS Support case against your AWS IoT Core for Amazon Sidewalk resources, supplying the device identifier, the AWS Region and the regulatory region, the link type and device profile, and the SDK version. | Confirmation of the links GSK is enabled for. |
| 1 | Include sid_gsk_config.h, then initialize with an explicit struct sid_gsk_config. Register on_status_changed, and on_control_event_notify for SID_CONTROL_EVENT_KA_ACK_STATUS (6), which delivers a struct sid_ka_ack_status whose ack_received = false marks a missed keep-alive acknowledgement. | The §5 compile-time assertions compile, and sid_init() returns SID_ERROR_NONE (0). |
| 2 | Read the effective keep-alive interval with SID_OPTION_DL_ROUTE_VALIDITY (19), is_set = false, and check idle_timeout_sec against it (§6). | nwsync_time × 60 s > idle_timeout_sec (§4). §6’s 4/3 term is margin on top of that inequality: at the LoRa Profile B default, 5 × 60 s = 300 s clears the 240 s default window, so a session still establishes, but its 60 s of slack for application traffic is short of the 25 % Figure 6.1 asks for. |
| 3 | Register the device and bring up a sub-GHz link, with a Gateway in range. | sid_get_status() reports state == SID_STATE_READY (0) and the link network-synchronized (Glossary). |
| 4 | Stop application traffic on the sub-GHz link for longer than idle_timeout_sec, in Gateway range. | SubG-CSS: a transition out of SID_STATE_READY and back, within several minutes of the lull — the idle window first, then the establishment itself (§2.1, §7) — unless the application selected MDR (§2.1), which leaves the reported status unchanged. SubG-FSK: no change in the reported status, so a working session is not visible at this step. On a SubG-CSS device that shows nothing, apply Figure 6.1, lower idle_timeout_sec and repeat from step 2; if that changes nothing, return to step 0. |
Table 8.1: GSK bring-up checklist.
References
- Gateway Session Key (GSK) Application Note
- Keep-Alive (KA) Application Note
- Amazon Sidewalk Registration over Wire — Application Note
- Gateway Discovery and Selection Application Note
- Sidewalk Internationalization Application Note
- Amazon Sidewalk Location Library Developer Guide
- Amazon Sidewalk Specification — https://docs.sidewalk.amazon/specifications/
- Amazon Sidewalk Sid API Developer Guide — https://docs.sidewalk.amazon/sid-api-dg/
Glossary
| Term | Definition |
|---|---|
| Ack-requested uplink | An uplink the stack transmitted having asked for an end-to-end response — your request_ack = true messages and several the stack sends on its own. Not GSK-specific; what the desync detector counts while a session is active (§2.2). |
| Desync fallback | Discarding the session after app_ack_miss_threshold consecutive ack-requested uplinks went unacknowledged, and running in non-GSK mode until the next establishment retry (§2.2) |
| GSK | Gateway Session Key: a symmetric session key an Endpoint and a Gateway share, used in place of Cloud-supplied authentication material to authenticate the sender of the Endpoint’s sub-GHz uplinks at the Gateway. The network key stays in use, and end-to-end protection of the application payload is unchanged. |
| Idle timeout | The quiet window required before an establishment starts (§2.2); sid_gsk_config.idle_timeout_sec |
| Keep-alive (KA) | A periodic, always ack-requested uplink the stack sends on a network-synchronized sub-GHz link to keep the downlink route valid; its interval is application-settable (§4). |
| LDR | Low data rate (SID_LINK3_DATA_RATE_LDR). The lower-data-rate, longer-range sub-GHz LoRa mode; its parameters are per-region. The Amazon Sidewalk Sid API Developer Guide calls it the default data rate. |
| MDR | Medium data rate (SID_LINK3_DATA_RATE_MDR), which the Amazon Sidewalk Sid API Developer Guide calls the higher data rate. The higher-data-rate, shorter-range sub-GHz LoRa mode, and the only LoRa mode that carries a GSK session. Not available in the EU. |
| Network synchronization | A link has joined the Amazon Sidewalk network and holds network time: SID_STATUS_REGISTERED (0), SID_STATUS_TIME_SYNCED (0) and the link’s bit set in link_status_mask |
| Non-GSK mode | Operation without a Gateway Session Key. Your traffic is carried normally: the same keys, the same sid_get_mtu() value and the same APIs. On SubG-CSS the link runs the region’s low data rate unless the application selected MDR, with link-layer acknowledgement and retries off (§2.1). No public API reports whether a session is in use. |
| Session | The period during which a single Gateway Session Key is in use |