1.. zephyr:code-sample:: lwm2m-client
2   :name: LwM2M client
3   :relevant-api: lwm2m_api
4
5   Implement a LwM2M client that connects to a LwM2M server.
6
7Overview
8********
9
10Lightweight Machine to Machine (LwM2M) is an application layer protocol
11based on CoAP/UDP, and is designed to expose various resources for reading,
12writing and executing via an LwM2M server in a very lightweight environment.
13
14This LwM2M client sample application for Zephyr implements the LwM2M library
15and establishes a connection to an LwM2M server using the
16`Open Mobile Alliance Lightweight Machine to Machine Technical Specification`_
17(Section 5.3: Client Registration Interface).
18
19.. _Open Mobile Alliance Lightweight Machine to Machine Technical Specification:
20    http://www.openmobilealliance.org/release/LightweightM2M/V1_0-20170208-A/OMA-TS-LightweightM2M-V1_0-20170208-A.pdf
21
22The source code for this sample application can be found at:
23:zephyr_file:`samples/net/lwm2m_client`.
24
25Requirements
26************
27
28- :ref:`networking_with_eth_qemu`, :ref:`networking_with_qemu` or :ref:`networking_with_native_sim`
29- Linux machine
30- Leshan Demo Server (https://eclipse.org/leshan/)
31
32Building and Running
33********************
34
35There are configuration files for various setups in the
36samples/net/lwm2m_client directory:
37
38.. list-table::
39
40    * - :file:`prj.conf`
41      - This is the standard default config.
42
43    * - :file:`overlay-bootstrap.conf`
44      - This overlay config can be added to enable LWM2M Bootstrap support.
45
46    * - :file:`overlay-ot.conf`
47      - This overlay config can be added for OpenThread support.
48
49    * - :file:`overlay-dtls.conf`
50      - This overlay config can be added for DTLS support via MBEDTLS.
51
52    * - :file:`overlay-queue.conf`
53      - This overlay config can be added to enable LWM2M Queue Mode support.
54
55    * - :file:`overlay-tickless.conf`
56      - This overlay config can be used to stop LwM2M engine for periodically interrupting socket polls. It can have significant effect on power usage on certain devices.
57
58Build the lwm2m-client sample application like this:
59
60.. zephyr-app-commands::
61   :zephyr-app: samples/net/lwm2m_client
62   :board: <board to use>
63   :conf: <config file to use>
64   :goals: build
65   :compact:
66
67The easiest way to setup this sample application is to build and run it
68as a native_sim application or as a QEMU target using the default configuration :file:`prj.conf`.
69This requires a small amount of setup described in :ref:`networking_with_eth_qemu`, :ref:`networking_with_qemu` and :ref:`networking_with_native_sim`.
70
71Download and run the latest build of the Leshan Demo Server:
72
73.. code-block:: console
74
75    $ wget https://ci.eclipse.org/leshan/job/leshan/lastSuccessfulBuild/artifact/leshan-server-demo.jar
76    $ java -jar ./leshan-server-demo.jar -wp 8080
77
78You can now open a web browser to: http://localhost:8080 This is where you
79can watch and manage connected LwM2M devices.
80
81Build the lwm2m-client sample application for QEMU like this:
82
83.. zephyr-app-commands::
84   :zephyr-app: samples/net/lwm2m_client
85   :host-os: unix
86   :board: qemu_x86
87   :goals: run
88   :compact:
89
90The sample will start and automatically connect to the Leshan Demo Server with
91an IPv6 client endpoint "qemu_x86".
92
93To change the sample to use IPv4, disable IPv6 by changing these two
94configurations in ``prj.conf``::
95
96    CONFIG_NET_IPV6=n
97    CONFIG_NET_CONFIG_NEED_IPV6=n
98
99DTLS Support
100============
101
102To build the lwm2m-client sample for QEMU with DTLS support do the following:
103
104.. zephyr-app-commands::
105   :zephyr-app: samples/net/lwm2m_client
106   :host-os: unix
107   :board: qemu_x86
108   :conf: "prj.conf overlay-dtls.conf"
109   :goals: run
110   :compact:
111
112Setup DTLS security in Leshan Demo Server:
113
1141. Open up the Leshan Demo Server web UI
115#. Click on "Security"
116#. Click on "Add new client security configuration"
117#. Enter the following data:
118
119    * Client endpoint: qemu_x86
120    * Security mode: Pre-Shared Key
121    * Identity: Client_identity
122    * Key: 000102030405060708090a0b0c0d0e0f
123
124#. Start the Zephyr sample
125
126Bootstrap Support
127=================
128
129In order to run Bootstrap procedure with the sample, you need to download and
130run the Leshan Demo Bootstrap Server:
131
132.. code-block:: console
133
134    $ wget https://ci.eclipse.org/leshan/job/leshan/lastSuccessfulBuild/artifact/leshan-bsserver-demo.jar
135    $ java -jar ./leshan-bsserver-demo.jar -wp 8888 -lp 5783 -slp 5784
136
137
138You can now open a web browser to: http://localhost:8888 The Demo Bootstrap
139Server web UI will open, this is where you can configure your device for
140bootstrap.
141
142Configure the lwm2m-client sample in the Demo Bootstrap Server:
143
1441. Click on "Add new client bootstrap configuration"
145#. Enter the following data:
146
147    * Client endpoint: qemu_x86
148
149#. In the ``LWM2M Server`` tab, enter the following data:
150
151    * LWM2M Server URL: coap://[2001:db8::2]:5683 (or coap://192.0.2.2:5683 if IPv4 is used)
152    * Security mode: No Security
153
154#. The ``LWM2M Bootstrap Server`` tab can be left intact in the default
155   configuration (No Security).
156
157To build the lwm2m-client sample for QEMU with Bootstrap enabled do the
158following:
159
160.. zephyr-app-commands::
161   :zephyr-app: samples/net/lwm2m_client
162   :host-os: unix
163   :board: qemu_x86
164   :conf: "prj.conf overlay-bootstrap.conf"
165   :goals: run
166   :compact:
167
168The sample will start and automatically connect to the Leshan Demo Bootstrap
169Server to obtain the LwM2M Server information. After that, the sample will
170automatically connect to the Leshan Demo Sever, as it was indicated in the
171Bootstrap Server configuration.
172
173It is possible to combine overlay files, to enable DTLS and Bootstrap for
174instance. In that case, the user should make sure to update the port number in
175the overlay file for Bootstrap over DTLS (5784 in case of Leshan Demo Bootstrap
176Server) and to configure correct security mode in the ``LWM2M Bootstrap Server``
177tab in the web UI (Pre-shared Key).
178
179OpenThread Support
180==================
181
182To build the lwm2m-client sample for hardware requiring OpenThread for
183networking do the following:
184
185.. zephyr-app-commands::
186   :zephyr-app: samples/net/lwm2m_client
187   :host-os: unix
188   :board: <board to use>
189   :conf: "prj.conf overlay-ot.conf"
190   :goals: build
191   :compact:
192
193Note: If not provisioned (fully erased before flash), device will form
194new OpenThread network and promote itself to leader (Current role: leader).
195To join into already existing OT network, either enable CONFIG_OPENTHREAD_JOINER=y
196and CONFIG_OPENTHREAD_JOINER_AUTOSTART=y and send join request from other
197already joined device with joiner capabilities, or provision it manually
198from console:
199
200.. code-block:: console
201
202   ot thread stop
203   ot channel <channel>
204   ot networkname <network name>
205   ot masterkey <key>
206   ot panid <panid>
207   ot extpanid <extpanid>
208   ot thread start
209
210You could get all parameters for existing OT network from your OTBR with
211the following command:
212
213.. code-block:: console
214
215    wpanctl get Thread:ActiveDataset
216
217Queue Mode Support
218==================
219
220To build the lwm2m-client sample with LWM2M Queue Mode support do the following:
221
222.. zephyr-app-commands::
223   :zephyr-app: samples/net/lwm2m_client
224   :host-os: unix
225   :board: <board to use>
226   :conf: "prj.conf overlay-queue.conf"
227   :goals: build
228   :compact:
229
230With Queue Mode enabled, the LWM2M client will register with "UDP with Queue
231Mode" binding. The LWM2M engine will notify the application with
232``LWM2M_RD_CLIENT_EVENT_QUEUE_MODE_RX_OFF`` event when the RX window
233is closed so it can e. g. turn the radio off. The next RX window will be open
234with consecutive ``LWM2M_RD_CLIENT_EVENT_REG_UPDATE_COMPLETE`` event.
235
236WNC-M14A2A LTE-M Modem Support
237==============================
238
239To build the lwm2m-client sample for use with the WNC-M14A2A LTE-M modem
240shield do the following:
241
242.. zephyr-app-commands::
243   :zephyr-app: samples/net/lwm2m_client
244   :host-os: unix
245   :board: <board to use>
246   :conf: "prj.conf overlay-wncm14a2a.conf"
247   :goals: build
248   :compact:
249
250Sample output without DTLS enabled
251==================================
252
253The following is sample output from the QEMU console.  First, LwM2M engine is
254initialized.  Then, several LwM2M Smart Objects register themselves with the
255engine.  The sample app then sets some client values so that they can be seen
256in the Leshan Demo Server interface, and finally, the registration request is
257sent to the server where the endpoint is initialized.
258
259.. code-block:: console
260
261    To exit from QEMU enter: 'CTRL+a, x'
262    [QEMU] CPU: qemu32,+nx,+pae
263    qemu-system-i386: warning: Unknown firmware file in legacy mode: genroms/multiboot.bin
264
265    shell> [lib/lwm2m_engine] [DBG] lwm2m_engine_init: LWM2M engine thread started
266    [lwm2m_obj_security] [DBG] security_create: Create LWM2M security instance: 0
267    [lwm2m_obj_server] [DBG] server_create: Create LWM2M server instance: 0
268    [lwm2m_obj_device] [DBG] device_create: Create LWM2M device instance: 0
269    [lwm2m_obj_firmware] [DBG] firmware_create: Create LWM2M firmware instance: 0
270    [lwm2m-client] [INF] main: Run LWM2M client
271    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/0, value:0x0001c99e, len:6
272    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/1, value:0x0001c9ab, len:23
273    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/2, value:0x0001c9c9, len:9
274    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/3, value:0x0001c9d9, len:3
275    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/9, value:0x0041a3a4, len:1
276    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/10, value:0x0041a3b4, len:4
277    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/17, value:0x0001c9fc, len:16
278    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/18, value:0x0001ca14, len:5
279    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/20, value:0x0041a3a4, len:1
280    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3/0/21, value:0x0041a3b4, len:4
281    [lib/lwm2m_engine] [DBG] lwm2m_engine_create_obj_inst: path:3303/0
282    [ipso_temp_sensor] [DBG] temp_sensor_create: Create IPSO Temperature Sensor instance: 0
283    [lib/lwm2m_engine] [DBG] lwm2m_engine_set: path:3303/0/5700, value:0x0041a3b8, len:8
284    [lib/lwm2m_rd_client] [INF] lwm2m_rd_client_start: LWM2M Client: qemu_x86
285    [lib/lwm2m_rd_client] [INF] sm_do_init: RD Client started with endpoint 'qemu_x86' and client lifetime 0
286    [lib/lwm2m_rd_client] [DBG] sm_send_registration: registration sent [2001:db8::2]
287    [lib/lwm2m_engine] [DBG] lwm2m_udp_receive: checking for reply from [2001:db8::2]
288    [lib/lwm2m_rd_client] [DBG] do_registration_reply_cb: Registration callback (code:2.1)
289    [lwm2m-client] [DBG] rd_client_event: Registration complete
290    [lib/lwm2m_rd_client] [INF] do_registration_reply_cb: Registration Done (EP='EZd501ZF26')
291    [lib/lwm2m_engine] [DBG] lwm2m_udp_receive: reply 0x004001ec handled and removed
292