How to Perform Graceful Shutdown and Recovery

This guide explains how to safely stop CBSD operations and recover after reboot, network loss, or relocation, following WINNF-TS-0016.

Overview

Graceful shutdown prevents "ghost grants" (active grants without heartbeats) that waste spectrum and hurt approval rates. Recovery restores operation quickly without re-registering unnecessarily.

Key Bridge SAS Note: Don't worry if you cannot shutdown gracefully (e.g., sudden power loss or crash). Everything will be automatically cleaned up by the SAS — there is no harm or penalty when your radio comes back online. Just perform a normal bootstrapping procedure to get back on air.

Shutdown Sequence

Step 1: Stop Transmission

• Cease RF immediately on all grants
• Log final state (active grants, last heartbeat times)

Step 2: Relinquish All Active Grants (When Possible)

Send RelinquishmentRequest for each grantId (can batch in array).

Example

{
  "relinquishmentRequest": [
    { "cbsdId": "SAS123/CBSD-001", "grantId": "GRANT-789" },
    { "cbsdId": "SAS123/CBSD-001", "grantId": "GRANT-790" }
  ]
}

Success: responseCode 0 (or 501 if already terminated — safe to ignore)

Step 3: Deregister CBSD

{
  "deregistrationRequest": [
    { "cbsdId": "SAS123/CBSD-001" }
  ]
}

Key Bridge SAS Optimization:

• If time is short (e.g., low battery, imminent power loss), skip relinquishment and send only the DeregistrationRequest.
• Our SAS is smart enough to detect the sudden loss of heartbeats and automatically clean up any remaining grants.

Tip: Prioritize deregistration in low-power scenarios — it ensures the cleanest state for fastest recovery.

Step 4: Persist State

Store to non-volatile memory:

• cbsdId (most critical — enables skip registration)
• fccId, serialNumber, userId
• installationParam (if unchanged)
• groupingParam
• Last known grants (for diagnostics)

Recovery Sequence (After Reboot/Network Loss)

Step 1: Restore State

Load persisted data. Keep cbsdId — valid ~30-60 days post-deregistration.

Step 2: Certificate/Health Check

Test TLS with health endpoint:

curl -v --cert cert.pem --key key.pem --cacert root.pem https://sas.cbrs.keybridgewireless.com/cbsd/api/v1.2/health

Step 3: Conditional Re-Registration

• If cbsdId valid + installation unchanged: Skip registration → directly Spectrum Inquiry
• If location moved or params changed: Full re-registration required

Quick Recovery Registration (same params):

{
  "registrationRequest": [{
    "cbsdId": "SAS123/CBSD-001",  // Reuse!
    "fccId": "ABC123",
    "cbsdSerialNumber": "SN456789",
    // ... same installationParam, groupingParam, measCapability
  }]
}

Success: SAS recognizes → immediate spectrum inquiry

Step 4: Resume Multi-Grant Flow

• Spectrum Inquiry (include fresh measurements)
• Request grants (up to 15, 10 MHz blocks)
• Heartbeat to activate

Best Practices & Tips

• Shutdown Timer: On SIGTERM/SIGINT: 30s window → relinquish → deregister (or just deregister if low battery)
• Watchdog: If heartbeat fails 2x → auto-shutdown sequence
• State File: JSON format, checksummed, stored in /persist/cbsd-state.json
• DPA Neighborhood: Maintain upper 50 MHz (3650-3700 MHz) grant as recovery anchor
• Network Loss: On reconnect → check if grants still valid via heartbeat → relinquish dead ones
• Key Bridge SAS: Persisted cbsdId skips 80% of recovery time

Common Issues & Troubleshooting

Pseudocode Example

# Shutdown
def graceful_shutdown():
    stop_rf()
    if time_available():
        for grant in active_grants:
            relinquish(grant)
    deregister()  # Always send this
    persist_state()
    sys.exit(0)

# Recovery
def recovery():
    state = load_state()
    if health_check():
        if state.cbsdId and params_unchanged():
            spectrum_inquiry(state.cbsdId)
        else:
            register(state)  # Returns new cbsdId
        request_multi_grants()  # Full band + upper 50 MHz

Next Steps

• Add shutdown hooks to your main loop
• Test full cycle: run → shutdown → reboot → recovery