dult: Add motion detector module

Jira: NCSDK-25429

Signed-off-by: Aleksander Strzebonski <aleksander.strzebonski@nordicsemi.no>

Author: alstrzebonski

include/dult.h

@@ -182,14 +182,21 @@ int dult_id_read_state_cb_register(const struct dult_user *user,
  */
 int dult_id_read_state_enter(const struct dult_user *user);
 
-/** Minimum duration in milliseconds for the DULT sound action. */
-#define DULT_SOUND_DURATION_MIN_MS (5000U)
+/** Minimum duration in milliseconds for the DULT sound action originating from the Bluetooth
+ *  accessory non-owner service (see @ref DULT_SOUND_SRC_BT_GATT).
+ */
+#define DULT_SOUND_DURATION_BT_GATT_MIN_MS (5000U)
 
 /** DULT sound source types. */
 enum dult_sound_src {
 	/** Sound source type originating from the Bluetooth accessory non-owner service. */
 	DULT_SOUND_SRC_BT_GATT,
 
+	/** Sound source type originating from the Motion detector.
+	 *  Used only when the @kconfig{CONFIG_DULT_MOTION_DETECTOR} is enabled.
+	 */
+	DULT_SOUND_SRC_MOTION_DETECTOR,
+
 	/** External source type originating from the unknown location to the DULT module. */
 	DULT_SOUND_SRC_EXTERNAL,
 };
@@ -204,7 +211,8 @@ struct dult_sound_cb {
 	 *  structure), it then calls the @ref dult_sound_state_update API.
 	 *
 	 *  @param src	Sound source type. Only the DULT internal sources are
-	 *              used in this callback: @ref DULT_SOUND_SRC_BT_GATT.
+	 *              used in this callback: @ref DULT_SOUND_SRC_BT_GATT,
+	 *              @ref DULT_SOUND_SRC_MOTION_DETECTOR.
 	 */
 	void (*sound_start)(enum dult_sound_src src);
 
@@ -215,8 +223,9 @@ struct dult_sound_cb {
 	 *  response to this request (as described by the @ref dult_sound_state_param
 	 *  structure), it then calls the @ref dult_sound_state_update API.
 	 *
-	 *  @param src	Sound source type. Only the DULT internal sources are
-	 *              used in this callback: @ref DULT_SOUND_SRC_BT_GATT.
+	 *  @param src	Sound source type. Only the DULT internal source originating
+	 *		from the Bluetooth accessory non-owner service
+	 *		(@ref DULT_SOUND_SRC_BT_GATT) is used in this callback.
 	 */
 	void (*sound_stop)(enum dult_sound_src src);
 };
@@ -279,6 +288,63 @@ struct dult_sound_state_param {
 int dult_sound_state_update(const struct dult_user *user,
 			    const struct dult_sound_state_param *param);
 
+/** @brief Motion detector callback structure.
+ *
+ *  Used only when the @kconfig{CONFIG_DULT_MOTION_DETECTOR} Kconfig option is enabled.
+ */
+struct dult_motion_detector_cb {
+	/** @brief Request the user to start the motion detector.
+	 *
+	 *  This callback is called to start the motion detector
+	 *  activity. From now on, the motion detector events are polled
+	 *  periodically with the @ref period_expired API.
+	 *  The motion detector activity stops when the
+	 *  @ref stop is called.
+	 */
+	void (*start)(void);
+
+	/** @brief Notify the user that the motion detector period has expired.
+	 *
+	 *  This callback is called at the end of each
+	 *  motion detector period. The @ref start function
+	 *  indicates the beginning of the first motion detector period.
+	 *  The next period is started as soon as the previous period expires.
+	 *  The user should notify the DULT module if motion was detected
+	 *  in the previous period. The return value of this callback
+	 *  is used to pass this information.
+	 *
+	 *  @return true to indicate detected motion in the last period,
+	 *  otherwise false.
+	 */
+	bool (*period_expired)(void);
+
+	/** @brief Notify the user that the motion detector can be stopped.
+	 *
+	 *  This callback is called to notify the user that the motion
+	 *  detector is no longer used by the DULT module. It concludes
+	 *  the motion detector activity that was started by the
+	 *  @ref start callback.
+	 */
+	void (*stop)(void);
+};
+
+/** @brief Register motion detector callbacks.
+ *
+ *  This function registers callbacks to handle motion detector activities defined
+ *  in the Motion detector feature from the DULT specification. This API can only
+ *  be used when the @kconfig{CONFIG_DULT_MOTION_DETECTOR} Kconfig option is
+ *  enabled. If this configuration is active, this function must be called after
+ *  registering the DULT user with @ref dult_user_register and before enabling
+ *  DULT with @ref dult_enable function.
+ *
+ *  @param user	User structure used to authenticate the user.
+ *  @param cb Motion detector callback structure.
+ *
+ *  @return 0 if the operation was successful. Otherwise, a (negative) error code is returned.
+ */
+int dult_motion_detector_cb_register(const struct dult_user *user,
+				     const struct dult_motion_detector_cb *cb);
+
 /** Modes of the DULT near-owner state. */
 enum dult_near_owner_state_mode {
 	/** Separated mode of the near-owner state. */

subsys/dult/CMakeLists.txt

@@ -11,6 +11,7 @@ zephyr_library_include_directories(include)
 zephyr_library_sources_ifdef(CONFIG_DULT_BATTERY battery.c)
 zephyr_library_sources_ifdef(CONFIG_DULT_BT_ANOS bt/anos.c)
 zephyr_library_sources_ifdef(CONFIG_DULT_ID id.c)
+zephyr_library_sources_ifdef(CONFIG_DULT_MOTION_DETECTOR motion_detector.c)
 zephyr_library_sources_ifdef(CONFIG_DULT_NEAR_OWNER_STATE near_owner_state.c)
 zephyr_library_sources_ifdef(CONFIG_DULT_SOUND sound.c)
 zephyr_library_sources_ifdef(CONFIG_DULT_USER user.c)

subsys/dult/Kconfig

@@ -148,6 +148,69 @@ config DULT_USER
 	help
 	  Add DULT user source files.
 
+config DULT_MOTION_DETECTOR
+	bool "Enable DULT Motion detector feature"
+	help
+	  The DULT Motion detector requests the device to ring if the accessory separated
+	  from owner is moving. For more details see
+	  https://www.ietf.org/archive/id/draft-detecting-unwanted-location-trackers-01.html#name-motion-detector.
+
+if DULT_MOTION_DETECTOR
+
+config DULT_MOTION_DETECTOR_TEST_MODE
+	bool "Enable DULT Motion detector test mode"
+	help
+	  The DULT Motion detector test mode allows to configure motion detector parameters
+	  for testing purposes. Those values are defined in the DULT specification and should
+	  not be changed in the production code.
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_SAMPLING_RATE1
+	int
+	default 10000
+	help
+	  Sampling rate in milliseconds when motion detector is enabled in separated state.
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_SAMPLING_RATE2
+	int
+	default 500
+	help
+	  Motion detector sampling rate in milliseconds when movement is detected in separated
+	  state.
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD
+	int "Period in minutes to disable motion detector if accessory is in separated state" if DULT_MOTION_DETECTOR_TEST_MODE
+	default 2 if DULT_MOTION_DETECTOR_TEST_MODE
+	default 360
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN
+	int "Minimum time span in minutes in separated state before enabling motion detector" if DULT_MOTION_DETECTOR_TEST_MODE
+	default 3 if DULT_MOTION_DETECTOR_TEST_MODE
+	default 480
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MAX
+	int "Maximum time span in minutes in separated state before enabling motion detector" if DULT_MOTION_DETECTOR_TEST_MODE
+	default DULT_MOTION_DETECTOR_SEPARATED_UT_TIMEOUT_PERIOD_MIN if DULT_MOTION_DETECTOR_TEST_MODE
+	default 1440
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_ACTIVE_POLL_DURATION
+	int
+	default 20
+	help
+	  Time span in seconds of motion detector active polling with
+	  CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_SAMPLING_RATE2 rate. After the timeout, the
+	  motion detector is disabled for CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD
+	  period.
+
+config DULT_MOTION_DETECTOR_SEPARATED_UT_MAX_SOUND_COUNT
+	int
+	default 10
+	help
+	  Maximum number of sound indications to be sent by motion detector before disabling it.
+	  After sending maximum number of sound indications, the motion detector is disabled for
+	  CONFIG_DULT_MOTION_DETECTOR_SEPARATED_UT_BACKOFF_PERIOD period."
+
+endif # DULT_MOTION_DETECTOR
+
 module = DULT
 module-str = DULT
 source "${ZEPHYR_BASE}/subsys/logging/Kconfig.template.log_config"

subsys/dult/include/dult_motion_detector.h

@@ -0,0 +1,72 @@
+/*
+ * Copyright (c) 2024 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
+ */
+
+#ifndef _DULT_MOTION_DETECTOR_H_
+#define _DULT_MOTION_DETECTOR_H_
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "dult.h"
+
+/**
+ * @defgroup dult_motion_detector Detecting Unwanted Location Trackers motion detector
+ * @brief Private API for DULT specification implementation of the motion detector module
+ *
+ * Used only when the CONFIG_DULT_MOTION_DETECTOR Kconfig option is enabled.
+ * @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief DULT motion detector sound callback structure. */
+struct dult_motion_detector_sound_cb {
+	/** @brief Start sound action.
+	 *
+	 *  This callback is called to notify the upper layer that the sound action shall be
+	 *  started due to the motion detector requirements.
+	 */
+	void (*sound_start)(void);
+};
+
+/** @brief Register DULT motion detector sound callback structure.
+ *
+ *  @param cb Sound callback structure.
+ */
+void dult_motion_detector_sound_cb_register(const struct dult_motion_detector_sound_cb *cb);
+
+/** @brief Notify the DULT motion detector module about the sound state change.
+ *
+ *  @param active True when the play sound action is in progress.
+ *                False: otherwise.
+ *  @param native True when the play sound action was triggered by this module.
+ *                False: otherwise.
+ */
+void dult_motion_detector_sound_state_change_notify(bool active, bool native);
+
+/** @brief Enable DULT motion detector.
+ *
+ *  @return 0 if the operation was successful. Otherwise, a (negative) error code is returned.
+ */
+int dult_motion_detector_enable(void);
+
+/** @brief Reset DULT motion detector.
+ *
+ *  @return 0 if the operation was successful. Otherwise, a (negative) error code is returned.
+ */
+int dult_motion_detector_reset(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**
+ * @}
+ */
+
+#endif /* _DULT_MOTION_DETECTOR_H_ */

subsys/dult/include/dult_near_owner_state.h

@@ -28,6 +28,26 @@ extern "C" {
  */
 enum dult_near_owner_state_mode dult_near_owner_state_get(void);
 
+/** @brief DULT near owner state callback structure. */
+struct dult_near_owner_state_cb {
+	/** @brief DULT near owner state changed.
+	 *
+	 *  This callback is called to notify that the near owner state has been changed.
+	 *
+	 *  @param mode Mode of the current DULT near owner state.
+	 */
+	void (*state_changed)(enum dult_near_owner_state_mode mode);
+
+	/** Internally used field for list handling. */
+	sys_snode_t node;
+};
+
+/** @brief Register DULT near owner state callback structure.
+ *
+ *  @param cb Near owner state callback structure.
+ */
+void dult_near_owner_state_cb_register(struct dult_near_owner_state_cb *cb);
+
 /** @brief Reset DULT near owner state.
  *
  *  Resets DULT near owner state to boot value which is equal to