From 5e4b2f1bc4a1d9d2ab3675d0d701e8b4aefe1a58 Mon Sep 17 00:00:00 2001 From: Leandro Lanzieri Date: Fri, 12 Mar 2021 19:07:39 +0100 Subject: [PATCH] pkg/wakaama: improve documentation --- pkg/wakaama/doc.txt | 133 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 1 deletion(-) diff --git a/pkg/wakaama/doc.txt b/pkg/wakaama/doc.txt index 800a07a68a4c0..696677f6550d2 100644 --- a/pkg/wakaama/doc.txt +++ b/pkg/wakaama/doc.txt @@ -3,7 +3,138 @@ * @ingroup pkg * @ingroup net * @brief LwM2M implementation based on the Wakaama package - * @see https://github.com/eclipse/wakaama + * + * Lightweight Machine to Machine is a device management protocol designed for sensor networks, + * designed for remote management of M2M devices and related service enablement. It defines an + * extensible resource and data model and builds top of CoAP. LwM2M has been specified by the + * OMA SpecWorks Device Management Working Group. The specification is freely available + * [here](http://openmobilealliance.org/wp/index.html). * * For a list of the supported objects see @ref lwm2m_objects. + * The client implementation is based on the Eclipse + * [Wakaama project](https://github.com/eclipse/wakaama) + * + * + * ## Usage + * A LwM2M Client organizes resources as object instances. The LwM2M engine is independent of the + * objects that the client exposes, but it needs at least 3 mandatory ones: + * @ref lwm2m_objects_device "Device object", @ref lwm2m_objects_security "Security object" and a + * Server object. + * + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c} + * #include "lwm2m_client.h" + * #include "lwm2m_client_objects.h" + * #include "objects/security.h" + * #include "objects/device.h" + * #include "net/credman.h" + * + * // hold references to object handles + * lwm2m_object_t *obj_list[3]; + * + * // LwM2M Client instance + * lwm2m_client_data_t client_data; + * + * // initiate the LwM2M Client + * lwm2m_client_init(&client_data); + * + * // arguments for instantiating a security object + * lwm2m_obj_security_args_t args = { + * .server_id = 1, + * .server_uri = "coap://[fd00:dead:beef::1]:5683", + * .security_mode = LWM2M_SECURITY_MODE_NONE, + * .cred = NULL, + * .is_bootstrap = false, + * .client_hold_off_time = 5, + * .bootstrap_account_timeout = 0 + * }; + * + * // get the Security object handle + * obj_list[0] = lwm2m_object_security_get(); + * + * // create a new Security object instance + * int res = lwm2m_object_security_instance_create(obj_list[0], 1, &args); + * if (res < 0) { + * puts("Could not instantiate the security object"); + * return; + * } + * + * // get the Server object handle (only single instance for now) + * obj_list[1] = lwm2m_client_get_server_object(&client_data, CONFIG_LWM2M_SERVER_SHORT_ID); + * + * // device object has a single instance. All the information for now is defined at compile-time + * obj_list[2] = lwm2m_object_device_get(); + * + * // run the LwM2M client + * lwm2m_client_run(&client_data, obj_list, ARRAY_SIZE(obj_list); + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * The LwM2M Client will connect to the specified LwM2M server and register itself. After that, the + * server will be able to perform Read, Write, Create, Delete, Execute and Observe operations on the + * resources. + * + * ### DTLS support + * With the configuration above plain CoAP is used. To secure the connection with the LwM2M Server, + * a credential is needed in the Security object instance. To enable DTLS support add the module + * `wakaama_client_dtls`. This uses the @ref net_sock_dtls, so you will need to select an + * implementation of it (e.g. `USEPKG += tinydtls`). For now only Pre-Shared Key mode is supported. + * First define a credential: + * + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c} + * static const uint8_t psk_id[] = "Client_Identity"; + * static const uint8_t psk_key[] = "ThisIsRIOT!"; + * + * static const credman_credential_t credential = { + * .type = CREDMAN_TYPE_PSK, + * .tag = CREDMAN_TAG_EMPTY, + * .params = { + * .psk = { + * .key = { .s = psk_key, .len = sizeof(psk_key) - 1, }, + * .id = { .s = psk_id, .len = sizeof(psk_id) - 1, }, + * } + * }, + * }; + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * Then, use that credential when instantiating the Security Object, and define the security mode + * to use (@ref LWM2M_SECURITY_MODE_PRE_SHARED_KEY). Probably the server URI will change to specify + * the CoAPS port: + * + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c} + * lwm2m_obj_security_args_t args = { + * .server_id = 1, + * .server_uri = "coaps://[fd00:dead:beef::1]:5684", + * .security_mode = LWM2M_SECURITY_MODE_PRE_SHARED_KEY, + * .cred = &credential, + * .is_bootstrap = false, + * .client_hold_off_time = 5, + * .bootstrap_account_timeout = 0 + * }; + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * ### Using a LwM2M Bootstrap Server + * A bootstrap server gives a LwM2M deployment more flexibility. Information on how to connect to the + * LwM2M bootstrap server is defined at compile-time in the client (including URI and potentially + * needed credentials). The client connects to the bootstrap server on boot, which installs on the + * node the information needed to connect to the LwM2M servers. + * + * To enable bootstrap support, set the `LWM2M_BOOTSTRAP` option on Kconfig or set the CFLAG + * `CONFIG_LWM2M_BOOTSTRAP=1`. You will also need to specify during the security object instantiation + * that the information corresponds to a bootstrap server. DTLS is also supported for the bootstrap + * server: + * + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.c} + * lwm2m_obj_security_args_t args = { + * .server_id = 1, + * .server_uri = "coaps://[fd00:dead:beef::1]:5684", + * .security_mode = LWM2M_SECURITY_MODE_PRE_SHARED_KEY, + * .cred = &credential, + * .is_bootstrap = true, + * .client_hold_off_time = 5, + * .bootstrap_account_timeout = 0 + * }; + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * Keep into account, that some Sock DTLS implementations may need some extra configuration to handle + * multiple connections. See the `example/wakaama` Makefile. + * */