pkg/wakaama/objects: add Humidity Sensor

pkg/wakaama/Makefile.dep

@@ -21,6 +21,10 @@ ifneq (,$(filter wakaama_objects_current,$(USEMODULE)))
     USEMODULE += wakaama_objects_ipso_sensor_base
 endif
 
+ifneq (,$(filter wakaama_objects_humidity,$(USEMODULE)))
+    USEMODULE += wakaama_objects_ipso_sensor_base
+endif
+
 USEMODULE += ztimer
 USEMODULE += ztimer_sec
 USEPKG += tlsf

pkg/wakaama/contrib/objects/Kconfig.ipso

@@ -23,4 +23,13 @@ config LWM2M_CURRENT_INSTANCES_MAX
 
 endmenu
 
+menu "IPSO humidity object"
+    depends on USEMODULE_WAKAAMA_OBJECTS_HUMIDITY
+
+config LWM2M_HUMIDITY_INSTANCES_MAX
+    int "Maximum number of humidity object instances"
+    default 1
+
+endmenu
+
 endmenu # "IPSO objects"

pkg/wakaama/contrib/objects/humidity.c

@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2024 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+/**
+ * @{
+ * @ingroup     lwm2m_objects_humidity
+ *
+ * @file
+ * @brief       Humidity Sensor object implementation for LwM2M client using Wakaama
+ *
+ * @author      Leandro Lanzieri <leandro.lanzieri@haw-hamburg.de>
+ * @}
+ */
+
+#include "mutex.h"
+#include "liblwm2m.h"
+#include "lwm2m_client.h"
+#include "objects/humidity.h"
+#include "objects/ipso_sensor_base.h"
+
+#define ENABLE_DEBUG 1
+#include "debug.h"
+
+/**
+ * @brief Humidity Sensor object implementation descriptor.
+ */
+static lwm2m_obj_ipso_sensor_base_t _humidity_object;
+
+/**
+ * @brief Pool of object instances.
+ */
+static lwm2m_obj_ipso_sensor_base_inst_t _instances[CONFIG_LWM2M_HUMIDITY_INSTANCES_MAX];
+
+lwm2m_object_t *lwm2m_object_humidity_init(lwm2m_client_data_t *client_data)
+{
+    assert(client_data);
+    int res = lwm2m_object_ipso_sensor_base_init_derived(client_data, &_humidity_object,
+                                                         LWM2M_HUMIDITY_OBJECT_ID,
+                                                         _instances,
+                                                         CONFIG_LWM2M_HUMIDITY_INSTANCES_MAX);
+
+    if (res) {
+        DEBUG("[lwm2m:humidity]: failed to create object\n");
+        return NULL;
+    }
+
+    return &_humidity_object.object;
+}
+
+int32_t lwm2m_object_humidity_instance_create(const lwm2m_obj_humidity_args_t *args)
+{
+    int32_t result = lwm2m_object_ipso_sensor_base_instance_create(&_humidity_object, args);
+
+    if (result) {
+        DEBUG("[lwm2m:humidity]: failed to create instance\n");
+    }
+
+    return result;
+}
+
+void lwm2m_object_humidity_update_value(const lwm2m_client_data_t *client_data,
+                                        uint16_t instance_id, int16_t value)
+{
+    lwm2m_object_ipso_sensor_base_update_value(client_data, &_humidity_object, instance_id, value);
+}

pkg/wakaama/include/objects/humidity.h

@@ -0,0 +1,162 @@
+/*
+ * Copyright (C) 2024 HAW Hamburg
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     lwm2m_objects
+ * @defgroup    lwm2m_objects_humidity Humidity
+ * @brief       Humidity Sensor object implementation for LwM2M client using Wakaama
+ *
+ * @experimental
+ *
+ * This implements the LwM2M Humidity Sensor object (ID 3304) as specified in the LwM2M registry.
+ * This IPSO object should be used with a humidity sensor to report a humidity measurement.
+ * It also provides resources for minimum/maximum measured values and the minimum/maximum range that
+ * can be measured by the humidity sensor. An example measurement unit is relative humidity as a
+ * percentage.
+ *
+ * The sensor value can be updated by the application using the
+ * @ref lwm2m_object_humidity_update_value function, or polled when required if a callback is
+ * registered upon object instantiation via @ref lwm2m_obj_humidity_args_t::read_cb.
+ *
+ * To use this object add `USEMODULE += wakaama_objects_humidity` to the application Makefile.
+ *
+ * ## Resources
+ *
+ * For an XML description of the object see
+ * https://raw.githubusercontent.com/OpenMobileAlliance/lwm2m-registry/prod/version_history/3304-1_0.xml
+ *
+ * This object is based on the @ref lwm2m_objects_ipso_sensor_base, therefore it shares the same
+ * resources.
+ *
+ * ## Usage
+ *
+ * 1. Initialize the LwM2M object with an initialized client pointer.
+ *
+ * ~~~~~~~~~~~~~~~{.c}
+ * lwm2m_object_t *obj = lwm2m_object_humidity_init(&client_data);
+ * ~~~~~~~~~~~~~~~
+ *
+ * 2. Create a new instance of the object with a given configuration (@ref lwm2m_obj_humidity_args_t).
+ *    Here, you can decide the way of updating the sensor values: polling or pushing. In this case,
+ *    we register a callback function that is called whenever the sensor value is read.
+ *
+ * ~~~~~~~~~~~~~~~{.c}
+ *
+ * // callback function to read the sensor value
+ * int _read_cb(void *arg, int16_t *value)
+ * {
+ *     (void)arg;
+ *
+ *     // generate new value
+ *     *value = 100;
+ *
+ *     return 0;
+ * }
+ *
+ * // initialize an instance of humidity sensor object
+ * const lwm2m_obj_humidity_args_t humidity_args = {
+ *     .min_range_value = 0.0,
+ *     .max_range_value = 100.0,
+ *     .units = "RH",
+ *     .units_len = sizeof("RH") - 1,
+ *     .instance_id = 0,
+ *     .read_cb = _read_cb,
+ *     .read_cb_arg = NULL
+ * };
+ *
+ * int32_t res = lwm2m_object_humidity_instance_create(&humidity_args);
+ *
+ * if (res < 0) {
+ *     puts("Could not create humidity object instance");
+ * }
+ * ~~~~~~~~~~~~~~~
+ *
+ * 3. You can now update the sensor values using the @ref lwm2m_object_humidity_update_value function.
+ *
+ * ~~~~~~~~~~~~~~~{.c}
+ * uint16_t instance_id = (uint16_t)res;
+ * lwm2m_object_humidity_update_value(&client_data, instance_id, new_value);
+ * ~~~~~~~~~~~~~~~
+ * @{
+ *
+ * @file
+ *
+ * @author      Leandro Lanzieri <leandro.lanzieri@haw-hamburg.de>
+ */
+
+#ifndef OBJECTS_HUMIDITY_H
+#define OBJECTS_HUMIDITY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "liblwm2m.h"
+#include "lwm2m_client.h"
+#include "objects/ipso_sensor_base.h"
+
+/**
+ * @defgroup lwm2m_objects_humidity_config LwM2M Humidity Sensor object compile configurations
+ * @ingroup lwm2m_client_config
+ * @{
+ */
+/**
+ * @brief Maximum number of instances of the object
+ */
+#ifndef CONFIG_LWM2M_HUMIDITY_INSTANCES_MAX
+#define CONFIG_LWM2M_HUMIDITY_INSTANCES_MAX (1U)
+#endif
+/** @} */
+
+/**
+ * @brief LwM2M Humidity Sensor object ID
+ */
+#define LWM2M_HUMIDITY_OBJECT_ID 3304
+
+/**
+ * @brief Arguments for the creation of a Humidity Sensor object instance.
+ */
+typedef lwm2m_obj_ipso_base_sensor_args_t lwm2m_obj_humidity_args_t;
+
+/**
+ * @brief   Initialize the Humidity Sensor object handle
+ *
+ * @param[in] client_data   Pointer to the LwM2M client data.
+ *
+ * @return Pointer to the global handle of the Humidity Sensor object.
+ */
+lwm2m_object_t *lwm2m_object_humidity_init(lwm2m_client_data_t *client_data);
+
+/**
+ * @brief   Create a new Humidity Sensor instance.
+ *
+ * @param[in]      args             Initialize structure with the parameter for the instance. Must
+ *                                  not be NULL.
+ *
+ * @return > 0 value representing the instance ID if the instance was created successfully.
+ * @return <0 otherwise
+ */
+int32_t lwm2m_object_humidity_instance_create(const lwm2m_obj_humidity_args_t *args);
+
+/**
+ * @brief Update the value of the humidity sensor and trigger a notification
+ *        to the observing servers, if any.
+ *
+ * @param[in] client_data   Pointer to the LwM2M client.
+ * @param[in] instance_id   ID of the instance to update.
+ * @param[in] value         New value for the sensor.
+ */
+void lwm2m_object_humidity_update_value(const lwm2m_client_data_t *client_data,
+                                        uint16_t instance_id, int16_t value);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* OBJECTS_HUMIDITY_H */
+/** @} */