pkg/wakaama: improve documentation

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.
+ *
  */