Bootstrap Service Fw Development Examples

1) Definition and Purpose

LwM2M Bootstrap is a provisioning phase where a Bootstrap Server configures the client before normal LwM2M registration begins.

It enables:

  • zero-touch provisioning
  • remote credential injection/rotation
  • late binding to deployment server
  • recovery through re-bootstrap

In practice, bootstrap provides the device with:

  • target LwM2M server URI(s)
  • security mode and credentials
  • server parameters (lifetime, binding, and related settings)

2) Scope and Assumptions

Assumptions for this guide:

  • Hardware: nRF9151
  • Connectivity: LTE-M and/or NB-IoT
  • Stack: Zephyr/Nordic LwM2M client flow
  • Bootstrap type: device-initiated bootstrap
  • Firmware has modem bring-up and persistent storage enabled

3) Architecture Overview

Bootstrap should be treated as a first-class runtime phase, not just a registration failure fallback.

Core layers:

  • application state machine
  • LwM2M client library
  • bootstrap/security handling
  • modem + IP + DTLS
  • persistent settings storage

4) Platform Requirements

4.1 Cellular and IP

  • modem init works
  • network registration works
  • IP transport is available

4.2 Persistence

The firmware must persist object data across reboot/power loss:

  • Security Object (Object 0)
  • Server Object (Object 1)
  • bootstrap completion related state

Typical Zephyr setup uses settings/flash-backed storage.

5) Bootstrap State Machine Design

Recommended high-level flow:

  1. STARTUP
  2. Load persisted LwM2M config
  3. Validate Security/Server object consistency
  4. If valid: register directly
  5. If invalid/missing: enter bootstrap mode

Bootstrap should also be re-entered on repeated unrecoverable registration/authentication failures.

6) Project-Specific Configuration (samples/lwm2m client)

When bootstrap is enabled in the project, the client starts with bootstrap credentials CONFIG_LWM2M_CLIENT_UTILS_BOOTSTRAP_TLS_TAG and then transitions to server credentials CONFIG_LWM2M_CLIENT_UTILS_SERVER_TLS_TAG.

Relevant config:

  • CONFIG_LWM2M_RD_CLIENT_SUPPORT_BOOTSTRAP=y
  • CONFIG_LWM2M_CLIENT_UTILS_SERVER="coap://bootstrap.iec.iot.telekom.de:5783"
  • CONFIG_LWM2M_CLIENT_UTILS_BOOTSTRAP_TLS_TAG=100
  • CONFIG_LWM2M_CLIENT_UTILS_SERVER_TLS_TAG=101

See:

  • overlay-leshan-bootstrap.conf
  • prj.conf

7) Startup and Bootstrap Decision (main.c + lwm2m_security.c)

7.1 Initialization Path

At startup, main() calls lwm2m_setup():

  1. lwm2m_init_sec(&client, endpoint_name, NULL)
  2. apn_obj11_init(CONFIG_PDN_DEFAULT_APN)
  3. apn_obj11_apply_modem(bootstrap_flags)

7.2 Bootstrap Decision

Bootstrap is determined by lwm2m_sec_needs_bootstrap().

Bootstrap is required if:

  • persistent keys/settings are missing
  • or server credentials for final server are missing in modem storage

If true, app uses:

  • LWM2M_RD_CLIENT_FLAG_BOOTSTRAP

8) Security Bootstrap Internals (lwm2m_security.c)

8.1 lwm2m_init_sec() behavior

With bootstrap support enabled, it:

  1. Registers create/delete callbacks for Objects 0 and 1
  2. Initializes and loads settings subtree
  3. Recreates object instances from persisted data as needed
  4. Removes conflicting default instances when persisted/bootstrap-managed data exists

8.2 Credentials to Modem

Credential loader selects TLS tag by mode:

  • bootstrap mode: bootstrap tag (100)
  • normal mode: server tag (101)

It avoids unnecessary rewrites, handles modem state transitions, and writes required credentials into modem key storage.

8.3 Persistence Callbacks

Post-write callbacks persist bootstrap writes:

  • Security object writes
  • Server object writes

During settings restore, object instances are recreated before resources are restored.

9) Runtime Event Flow (main.c)

State machine includes bootstrap-aware states:

  • START
  • CONNECTING
  • BOOTSTRAP
  • CONNECTED
  • APN_SWITCH
  • NETWORK_ERROR

Important events:

  • LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_REG_COMPLETE
  • LWM2M_RD_CLIENT_EVENT_BOOTSTRAP_TRANSFER_COMPLETE

After transfer complete, app enters APN_SWITCH, performs LTE offline/online transition, applies APN selection, then resumes registration path.

10) Custom Object 11 APN Behavior (lwm2m_obj11_apn.c)

This project uses custom Object 11 for APN profiles.

Highlights:

  • Object ID 11, multiple APN instances
  • values persisted via settings
  • bootstrap-time and post-bootstrap APN selection differ intentionally

Selection logic summary:

  • during bootstrap: force bootstrap APN path/default
  • after bootstrap: prefer Server Object APN link (/1/0/10) when valid
  • fallback to enabled APN profiles

11) End-to-End Sequences

11.1 First Boot

  1. Device starts and initializes modem/LwM2M
  2. Settings likely empty
  3. lwm2m_sec_needs_bootstrap() returns true
  4. RD client starts in bootstrap mode
  5. Device registers to bootstrap server
  6. Bootstrap server writes Object 0/Object 1
  7. Writes are persisted
  8. Credentials are stored in modem tags
  9. Bootstrap transfer completes
  10. APN switch logic runs
  11. Device registers to final server

11.2 Subsequent Boot

  1. Persisted objects are loaded
  2. Modem credential presence is checked
  3. If valid, bootstrap is skipped
  4. Device registers directly to final server

12) Re-Bootstrap and Failure Handling

Recommended triggers for re-bootstrap:

  • repeated DTLS/auth failures
  • repeated registration failures/timeouts
  • explicit local reset request

Project behavior includes delayed retries and guarded transitions during APN switch to avoid incorrect auto-restart behavior.

13) Common Pitfalls

  • treating bootstrap as normal registration
  • not persisting DELETE operations from bootstrap server
  • allowing registration before bootstrap finish
  • mismatched SSID between Security and Server objects
  • incomplete or non-atomic persistence during provisioning

14) Validation Checklist

  1. Bootstrap succeeds on blank device
  2. Reset during bootstrap does not brick configuration
  3. Provisioned data survives reboot/power cycle
  4. Re-bootstrap path works after credential breakage
  5. Registration never happens before bootstrap completion
  6. Logs show bootstrap complete then registration complete

15) Project Debugging Checklist

If bootstrap fails, verify:

  1. bootstrap URI/transport (coap:// vs coaps://) is correct
  2. bootstrap credentials exist under tag 100
  3. final server credentials exist under tag 101 after bootstrap
  4. settings backend is enabled in config
  5. endpoint format matches server expectation
  6. APN switching does not leave modem in wrong state

16) Bootstrap Portal Setup Guide

This section is the operator flow to configure the bootstrap server side.

16.1 Prerequisites

  • Access to:
    • Device Bootstrap Management
    • Bootstrap Target Profiles
    • Bootstrap IMEI Configurations
  • Target LwM2M server URI is known
  • Device onboarding data is available (IMEI, PSK ID, PSK Key)

16.2 Steps

  1. Add a new target profile Go to Device Bootstrap Management -> Bootstrap Target Profiles -> Add.
  2. Configure the target profile:
    • In Basic: set Tenant, Profile Name, optional Description.
    • In Target System: set Target System URI; optionally set APN/credentials.
    • In Bootstrap Operations: add custom operations only if needed.
    • Keep Base Bootstrap Operations (System-Generated) as-is (read-only).
  3. Save the target profile.
  4. Add a new device Go to Bootstrap IMEI Configurations -> Add.
  5. Add device mapping:
    • Select Profile
    • Enable Bootstrap allowed
    • Fill required fields:
      • IMEI
      • Target PSK Id (for PSK mode)
      • Target PSK Key (for PSK mode, correct format B64/HEX)
    • Optional: IMSI, ICCID, LwM2M Endpoint, Customer Device Id, Package Id
  6. Save configuration.

16.3 Firmware-Side Alignment

Ensure firmware values match portal onboarding data:

  • bootstrap enabled in build config
  • bootstrap URI set correctly
  • endpoint/PSK identity/key aligned with portal entries

16.4 Validation

After provisioning:

  1. reboot device
  2. confirm logs show bootstrap registration and transfer complete
  3. confirm final registration to target server