4 End devices

Unlike a gateway, an end device does not determine its own region. The region is supplied to it, and an end device is therefore the case in which the region can be set incorrectly, set late, or set to a value the device cannot support. The remainder of this section is what an application developer is responsible for on an end device.

As with a gateway, regional support is compiled in: an end device can only be provisioned to a region its firmware includes. Build end-device firmware with REGION_LITE, which compiles in both North America and Europe; provisioning a device to a region its build omits is refused as described in §4.4. Use REGION_LITE on its own: the single-region options REGION_US915 and REGION_EU868 are alternatives to it, not additions, and defining REGION_EU868 alongside it changes the default region described in §4.3 from North America to Europe.

4.1 The region values

An end device’s region is one of the values of enum sid_device_region, defined in the Amazon Sidewalk API guide (§2.16.1). The current build supports SID_DEVICE_REGION_NORTH_AMERICA and SID_DEVICE_REGION_EUROPE; SID_DEVICE_REGION_UNSET means no region has been set. The radio region passed at platform initialisation (§4.2) uses the same numeric value for each region, so a single stored value can supply both.

4.2 Configuring the radio and reporting the region

An end device uses its region in two separate places, and the application supplies both:

Radio region. The sub-GHz radio is configured from the region the application passes to sid_platform_init(), in the platform_init_parameters.region and platform_init_parameters.iso_country fields of platform_parameters_t. This value sets the band, spreading factor, transmit power and channel-access rules. Platform initialisation runs once per boot.
Reported region. The stack writes and reads the provisioned region through the set_info and get_info callbacks in struct sid_device_info_callbacks, with information type SID_DEVICE_INFO_TYPE_REGION. It uses this value to report the region during setup, to allow or block network registration, and to decide whether to start the sub-GHz links (§4.3). It does not configure the radio.

The stack does not connect the two, so the application must keep them consistent by deriving both from one stored value:

In set_info, store the provisioned region persistently before returning success.
In get_info, return the stored value as an enum sid_device_region, or SID_DEVICE_REGION_UNSET if none is stored.
At every boot, pass the stored region to sid_platform_init(), rather than a fixed compile-time value. Because platform initialisation runs once per boot, a newly provisioned region reaches the radio after the next reboot.
If no region is stored, pass a region the build includes, for example North America. The device still reports SID_DEVICE_REGION_UNSET, so the sub-GHz links stay off until the region is provisioned.
On factory reset, clear the stored region.

If the two values differ, the device reports one region while its radio operates on the parameters of another.

For the field definitions and integration steps, see the Amazon Sidewalk API guide §3.1 (platform_init_parameters) and §2.16.3 (integration steps).

4.3 When no region is reported

What the stack does when get_info reports no region depends on whether the device is already registered:

Not yet registered. Network registration is blocked, and sid_start() starts only Bluetooth Low Energy; the sub-GHz links are not started, and a request to start only sub-GHz links returns SID_ERROR_INVALID_STATE. Bluetooth Low Energy remains available so that the region can be provisioned over it during setup. This is the normal state of a new device; treat it as a start-up state, not an error.
Already registered. A device built with REGION_LITE is treated as North America for registration and reporting. This covers a device registered before region support was available, for example one that later receives a firmware update adding it. Initialise its radio for North America as well, so that the two values agree.

If the application does not report a region at all — get_info does not handle SID_DEVICE_INFO_TYPE_REGION — none of the above applies: registration is not gated and no default is applied. This is the behaviour of firmware without region support.

Because the application clears the stored region on factory reset (§4.2), a reset device returns to the first case above.

4.4 An unsupported region

If setup provisions a region the device firmware does not support — for the current build, any region other than North America or Europe (§4) — the stack rejects the request with a not-supported error and does not pass the region to the application. The device keeps its previous region, or remains without one.

The error is definitive. Setup should stop rather than retry: the request is rejected every time until the device runs firmware that supports the region.