Getting Started

LwM2M (Lightweight M2M) is a device management protocol designed for constrained devices. Unlike HTTP or MQTT, LwM2M defines a rich Object and Resource Registry — a standardized library of data structures for telemetry, configuration, and OTA updates. ThingsBoard acts as a full LwM2M Server and Bootstrap Server over plain UDP and DTLS.

Every piece of data on an LwM2M device is identified by a path: /{ObjectId}/{ObjectInstance}/{ResourceId}.

For example, /3/0/9 always means Device Object → Instance 0 → Battery Level.

Object versions are tracked separately. Use /{ObjectId}_{version}/{instance}/{resource} syntax when a specific version is required — e.g., /3_1.2/0/9 targets Object 3 at version 1.2.

ThingsBoard ships with a built-in set of standard LwM2M object models, so most devices work out of the box. However, the OMA LwM2M registry is updated regularly with new objects and revised versions. If your device uses a recently added or updated object that is not yet included in ThingsBoard, upload the latest model XML files:

1. Download the required model XML files from the official OMA registry on GitHub.
2. Log in as a System or Tenant administrator.
3. Go to Resources → Resource library and click +.
4. Upload the XML files. Models whose Object IDs match existing entries will be updated; new Object IDs will be added.

1. Go to Profiles → Device profiles and click +.
2. Enter a profile name and go to the Transport configuration tab.
3. Select LwM2M as the transport type.
4. Add the LwM2M objects your devices support (e.g., Device #3, Connectivity #4, Firmware Update #5, Location #6).
5. For each object resource, check Attribute to store it as a ThingsBoard attribute, or Telemetry + Observe to stream it as time-series data.
6. Save the profile.

For each resource marked as Attribute or Telemetry, you can customize the key name used in ThingsBoard. ThingsBoard reads attribute values at device registration and observes telemetry resources for ongoing updates.

1. Go to Entities → Devices and click +.
2. Name the device and select the LwM2M profile created above.
3. Go to the Credentials tab and choose a credential type (see below).
4. Save.

No Security connects over plain UDP on port 5685 — suitable for development and trusted networks only.

PSK is the most resource-efficient DTLS mode for constrained devices. Configure three values:

Endpoint Client Name:  MyClientPsk
PSK Identity:          myIdentity
PSK Key (hex):         01020304050607080A0B0C0D0F010203

RPK uses DTLS with raw asymmetric keys — lighter than X.509 because no certificate chain is involved. Generate an EC key pair and extract the public key in DER format:

openssl ecparam -out rpk_key.pem -name secp256r1 -genkey
openssl ec -in rpk_key.pem -pubout -outform DER | base64 > rpk_pub.b64

Paste the base64-encoded contents of rpk_pub.b64 into the Client Public Key field in Manage credentials.

X.509 uses mutual DTLS. Generate a self-signed EC certificate:

openssl ecparam -out key.pem -name secp256r1 -genkey
openssl req -new -key key.pem -x509 -nodes -days 365 -out cert.pem

Paste the contents of cert.pem into the Client certificate field in Manage credentials.

Use the ThingsBoard LwM2M Demo Client to test connectivity:

No Security (plain UDP):

java -jar thingsboard-lwm2m-demo-client-{version}.jar -u coap://$THINGSBOARD_HOST:5685 -n $ENDPOINT_NAME

Docker:

docker run --rm -it thingsboard/tb-lwm2m-demo-client:latest -u coap://$THINGSBOARD_HOST:5685 -n $ENDPOINT_NAME

PSK (DTLS port 5686):

java -jar thingsboard-lwm2m-demo-client-{version}.jar -u coaps://$THINGSBOARD_HOST:5686 -n MyClientPsk --psk-identity myIdentity --psk-key 01020304050607080A0B0C0D0F010203

Once connected, the device registers with ThingsBoard and begins sending telemetry. Communication logs appear under the transportLog key in Latest telemetry.

To enable DTLS on the ThingsBoard server, set these environment variables:

LWM2M_SERVER_CREDENTIALS_ENABLED=true
LWM2M_SERVER_CREDENTIALS_TYPE=PEM
LWM2M_SERVER_PEM_CERT=server.pem
LWM2M_SERVER_PEM_KEY=server_key.pem
LWM2M_SERVER_PEM_KEY_PASSWORD=secret

To also enable the Bootstrap Server over DTLS:

LWM2M_ENABLED_BS=true
LWM2M_BS_CREDENTIALS_ENABLED=true
LWM2M_BS_CREDENTIALS_TYPE=PEM
LWM2M_BS_PEM_CERT=server.pem
LWM2M_BS_PEM_KEY=server_key.pem
LWM2M_BS_PEM_KEY_PASSWORD=secret

Restart the ThingsBoard server after changing these variables.

Additional tuning variables:

• LWM2M_SECURITY_BIND_ADDRESS — bind address for the DTLS LwM2M server (default: 0.0.0.0)
• LWM2M_SECURITY_BIND_PORT — bind port for the DTLS LwM2M server (default: 5686)
• LWM2M_BS_SECURITY_BIND_ADDRESS — bind address for the DTLS Bootstrap server (default: 0.0.0.0)
• LWM2M_BS_SECURITY_BIND_PORT — bind port for the DTLS Bootstrap server (default: 5688)
• TB_LWM2M_SERVER_SECURITY_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT — skip validity check for client certificates (default: false)