Line data    Source code

       1           1 : /** @file
       2             :  *  @brief Heartbeat APIs.
       3             :  */
       4             : 
       5             : /*
       6             :  * Copyright (c) 2020 Nordic Semiconductor ASA
       7             :  *
       8             :  * SPDX-License-Identifier: Apache-2.0
       9             :  */
      10             : #ifndef ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEARTBEAT_H_
      11             : #define ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEARTBEAT_H_
      12             : 
      13             : #include <stdint.h>
      14             : 
      15             : #include <zephyr/sys/iterable_sections.h>
      16             : #include <zephyr/sys/slist.h>
      17             : 
      18             : /**
      19             :  * @brief Heartbeat
      20             :  * @defgroup bt_mesh_heartbeat Heartbeat
      21             :  * @ingroup bt_mesh
      22             :  * @{
      23             :  */
      24             : 
      25             : #ifdef __cplusplus
      26             : extern "C" {
      27             : #endif
      28             : 
      29             : /** Heartbeat Publication parameters */
      30           1 : struct bt_mesh_hb_pub {
      31             :         /** Destination address. */
      32           1 :         uint16_t dst;
      33             :         /** Remaining publish count. */
      34           1 :         uint16_t count;
      35             :         /** Time To Live value. */
      36           1 :         uint8_t ttl;
      37             :         /**
      38             :          * Bitmap of features that trigger a Heartbeat publication if
      39             :          * they change. Legal values are @ref BT_MESH_FEAT_RELAY,
      40             :          * @ref BT_MESH_FEAT_PROXY, @ref BT_MESH_FEAT_FRIEND and
      41             :          * @ref BT_MESH_FEAT_LOW_POWER.
      42             :          */
      43           1 :         uint16_t feat;
      44             :         /** Network index used for publishing. */
      45           1 :         uint16_t net_idx;
      46             :         /** Publication period in seconds. */
      47           1 :         uint32_t period;
      48             : };
      49             : 
      50             : /** Heartbeat Subscription parameters. */
      51           1 : struct bt_mesh_hb_sub {
      52             :         /** Subscription period in seconds. */
      53           1 :         uint32_t period;
      54             :         /** Remaining subscription time in seconds. */
      55           1 :         uint32_t remaining;
      56             :         /** Source address to receive Heartbeats from. */
      57           1 :         uint16_t src;
      58             :         /** Destination address to received Heartbeats on. */
      59           1 :         uint16_t dst;
      60             :         /** The number of received Heartbeat messages so far. */
      61           1 :         uint16_t count;
      62             :         /**
      63             :          * Minimum hops in received messages, ie the shortest registered
      64             :          * path from the publishing node to the subscribing node. A
      65             :          * Heartbeat received from an immediate neighbor has hop
      66             :          * count = 1.
      67             :          */
      68           1 :         uint8_t min_hops;
      69             :         /**
      70             :          * Maximum hops in received messages, ie the longest registered
      71             :          * path from the publishing node to the subscribing node. A
      72             :          * Heartbeat received from an immediate neighbor has hop
      73             :          * count = 1.
      74             :          */
      75           1 :         uint8_t max_hops;
      76             : };
      77             : 
      78             : /** Heartbeat callback structure */
      79           1 : struct bt_mesh_hb_cb {
      80             :         /** @brief Receive callback for heartbeats.
      81             :          *
      82             :          *  Gets called on every received Heartbeat that matches the current
      83             :          *  Heartbeat subscription parameters.
      84             :          *
      85             :          *  @param sub  Current Heartbeat subscription parameters.
      86             :          *  @param hops The number of hops the Heartbeat was received
      87             :          *              with.
      88             :          *  @param feat The feature set of the publishing node. The
      89             :          *              value is a bitmap of @ref BT_MESH_FEAT_RELAY,
      90             :          *              @ref BT_MESH_FEAT_PROXY,
      91             :          *              @ref BT_MESH_FEAT_FRIEND and
      92             :          *              @ref BT_MESH_FEAT_LOW_POWER.
      93             :          */
      94           1 :         void (*recv)(const struct bt_mesh_hb_sub *sub, uint8_t hops,
      95             :                      uint16_t feat);
      96             : 
      97             :         /** @brief Subscription end callback for heartbeats.
      98             :          *
      99             :          *  Gets called when the subscription period ends, providing a summary
     100             :          *  of the received heartbeat messages.
     101             :          *
     102             :          *  @param sub Current Heartbeat subscription parameters.
     103             :          */
     104           1 :         void (*sub_end)(const struct bt_mesh_hb_sub *sub);
     105             : 
     106             :         /** @brief Publication sent callback for heartbeats.
     107             :          *
     108             :          *  Gets called when the heartbeat is successfully published.
     109             :          *
     110             :          *  @param pub Current Heartbeat publication parameters.
     111             :          */
     112           1 :         void (*pub_sent)(const struct bt_mesh_hb_pub *pub);
     113             : };
     114             : 
     115             : /**
     116             :  *  @brief Register a callback structure for Heartbeat events.
     117             :  *
     118             :  *  Registers a callback structure that will be called whenever Heartbeat
     119             :  *  events occur
     120             :  *
     121             :  *  @param _name Name of callback structure.
     122             :  */
     123           1 : #define BT_MESH_HB_CB_DEFINE(_name)                                            \
     124             :         static const STRUCT_SECTION_ITERABLE(bt_mesh_hb_cb, _name)
     125             : 
     126             : /** @brief Get the current Heartbeat publication parameters.
     127             :  *
     128             :  *  @param get Heartbeat publication parameters return buffer.
     129             :  */
     130           1 : void bt_mesh_hb_pub_get(struct bt_mesh_hb_pub *get);
     131             : 
     132             : /** @brief Get the current Heartbeat subscription parameters.
     133             :  *
     134             :  *  @param get Heartbeat subscription parameters return buffer.
     135             :  */
     136           1 : void bt_mesh_hb_sub_get(struct bt_mesh_hb_sub *get);
     137             : 
     138             : #ifdef __cplusplus
     139             : }
     140             : #endif
     141             : /**
     142             :  * @}
     143             :  */
     144             : 
     145             : #endif /* ZEPHYR_INCLUDE_BLUETOOTH_MESH_HEARTBEAT_H_ */