7. Observability and troubleshooting
A GSK transition drives the device out of SID_STATE_READY and back. On a sub-GHz-only product, every establishment, expiry and fallback drives on_status_changed to SID_STATE_NOT_READY (1) and back on SubG-CSS, unless the application selected MDR (§2.1); on SubG-FSK a GSK transition does not itself leave network synchronization, so state does not change. On SubG-CSS the re-initialization can report SID_STATUS_NO_TIME (1) transiently. Neither is a fault. Gate sends on SID_STATE_READY (0), which requires network synchronization (Glossary), but drive product state machines on a state sustained longer than the several minutes a transition can take.
| Symptom | Likely cause | Action |
|---|---|---|
| No GSK activity, with registration, sub-GHz network synchronization or GSK enablement unconfirmed | Not registered; or radio-connected but not network-synchronized; or the network has not enabled GSK for this device; or the link in use is Bluetooth LE | Confirm that registration_status and time_sync_status report network synchronization (Glossary), and that a sub-GHz link is in use. If all hold, GSK is not enabled for this device (§8, step 0). |
| No GSK activity, with all three confirmed | The quiet window never elapses: on a busy device idle_timeout_sec exceeds the routine gap between sub-GHz messages; on a quiet device the effective keep-alive interval is at or below idle_timeout_sec — most often a LoRa Profile B device at a 2 or 3 min network-sync interval against the 240 s default window, including one set by passing nwsync_time = 0 with is_set = true (§4). Shortly after bring-up, expect minutes of delay before the first establishment | Lower idle_timeout_sec below the shortest routine inter-message gap; the minimum is 10 s. Read the effective keep-alive interval (§4) and apply Figure 6.1: raise nwsync_time to at least idle_timeout_sec / 45, in minutes, never to 0 (§6). |
| LoRa link never establishes a session in this region | MDR is not available in this region — never in the EU (§2.1); a rejected attempt changes no data rate and costs no link bounce | None. The device operates normally at LDR (§2.1), at 5000 ms separation only. |
Device stuck with time_sync_status == SID_STATUS_NO_TIME (1) persistently | No network time, so establishment cannot start | Resolve time synchronization first — coverage, registration, Gateway reachability. A transient NO_TIME during a LoRa PHY change is expected (above). |
SubG-FSK link drops and returns; state cycles NOT_READY then READY | Not an establishment signature. A successful FSK establishment does not leave network synchronization, so it changes nothing in state (the Amazon Sidewalk Sid API Developer Guide). A visible FSK bounce is a join that never completed — a GSK establishment that could not re-join, or an ordinary FSK link outage | Re-send what failed during the bounce. If it repeats, treat it as FSK coverage, not GSK. |
| The SubG-CSS link bounces once after a reboot, or cycles — bounce, quiet, bounce again — with no reboot | The stored session was not accepted when the link returned, so a fresh establishment ran (§2.2) — usually a reboot out of coverage or near a different Gateway | None if it correlates with poor coverage at boot. If it happens on every reboot in good coverage, capture the reboot-to-first-uplink sequence and raise it as in §8, step 0. |
| LoRa throughput, range or downlink latency changes without an application request | Activation moved the link to MDR; a fallback moved it back to LDR and reset the live window (unless the application selected MDR, §2.1) | Size coverage, airtime and latency for both data rates (§2.1). A required MDR separation is re-applied by the stack and needs no action (§4). |
A run of ack-requested uplinks fails with SID_ERROR_TIMEOUT (-2), then traffic succeeds again | The detector reached app_ack_miss_threshold and discarded the session (§2.2). Those messages were not retransmitted. | Re-send the payloads you cannot lose, as above. If this recurs in good RF, raise the threshold toward 6 or 8; expect non-GSK mode until the next establishment retry (retry_interval_sec, §3) or a reboot. |
The LoRa link bounces twice per retry_interval_sec — at the same time each day at the default — and no session ever appears | Each establishment retry is failing: one bounce into MDR on the way in, one back to LDR on the way out (§2.1) | No application-side fix. Confirm GSK enablement as in §8, step 0, and verify MDR coverage at the device’s location (§2.1). |
Table 7.1: GSK observability and troubleshooting.