bleSDK_expansion_board/mesh/api/mm_itf.h

/**
 ****************************************************************************************
 *
 * @file mm_itf.h
 *
 * @brief Header file for Mesh Model Message Interface Definitions
 *
 ****************************************************************************************
 */

#ifndef _MM_ITF_H_
#define _MM_ITF_H_

/*
 * INCLUDE FILES
 ****************************************************************************************
 */

#include <stdint.h>
#include "string.h"
#include "mesh.h"
#include "mm_def.h"


/*
 * DEFINES
 ****************************************************************************************
 */

/// define the static keyword for this compiler
#ifndef __STATIC
    #define __STATIC                static
#endif

/// define the force inlining attribute for this compiler
#ifndef __INLINE__
    #define __INLINE__              __forceinline static
#endif


/*
 * ENUMERATIONS
 ****************************************************************************************
 */


/*
 * TYPE DEFINTIONS
 ****************************************************************************************
 */

typedef struct mm_mdl_env           mm_mdl_env_t;

typedef struct mm_route_env         mm_route_env_t;

/**
 ****************************************************************************************
 * @brief Inform model about reception of a mesh message with a supported opcode
 ****************************************************************************************
 */
typedef void (*mm_rx_cb)(mm_mdl_env_t *p_env, mesh_buf_t *p_buf, mm_route_env_t *p_route_env);

/**
 ****************************************************************************************
 * @brief Check if an opcode is handled by the model
 ****************************************************************************************
 */
typedef uint8_t (*mm_opcode_check_cb)(mm_mdl_env_t *p_env, uint32_t opcode);

/**
 ****************************************************************************************
 * @brief Set state value of a local Server Model
 ****************************************************************************************
 */
typedef uint8_t (*mm_srv_set_cb)(mm_mdl_env_t *p_env, uint16_t state_id, uint32_t state);

/**
 ****************************************************************************************
 * @brief Get state value using a Client Model
 ****************************************************************************************
 */
typedef uint8_t (*mm_cli_get_cb)(mm_mdl_env_t *p_env, m_lid_t app_key_lid, uint16_t dst,
                                    uint16_t get_info);

/**
 ****************************************************************************************
 * @brief Get state value using a Client Model
 ****************************************************************************************
 */
typedef uint8_t (*mm_cli_set_cb)(mm_mdl_env_t *p_env, m_lid_t app_key_lid, uint16_t dst,
                                    uint32_t state_1, uint32_t state_2, uint16_t set_info);

/**
 ****************************************************************************************
 * @brief Initiate transition to a new state value using a Client Model
 ****************************************************************************************
 */
typedef uint8_t (*mm_cli_trans_cb)(mm_mdl_env_t *p_env, m_lid_t app_key_lid, uint16_t dst,
                                    uint32_t state_1, uint32_t state_2,
                                    uint32_t trans_time_ms, uint16_t delay_ms,
                                    uint16_t trans_info);

/**
 ****************************************************************************************
 * @brief Definition of callback function called by the Binding Manager to inform the main model
 * when one of the model composing a model group has requested transition to a new state.
 *
 * @param[in] main_mdl_lid      Main model local index
 * @param[in] req_model_id      Model ID of model that has requested the transition
 * @param[in] trans_type        Transition type
 * @param[in] state_delta       State value or delta value
 ****************************************************************************************
 */
typedef void (*mm_bind_trans_req_cb) (m_lid_t main_mdl_lid, uint32_t req_model_id, 
                                    uint8_t trans_type, uint32_t state_delta);

/**
 ****************************************************************************************
 * @brief Definition of callback function called by the Binding Manager to inform a model about
 * transition or publication event
 *
 * @param[in] mdl_lid           Model local index
 * @param[in] event             Event (@see enum mesh_mdl_grp_event)
 ****************************************************************************************
 */
typedef void (*mm_bind_grp_event_cb) (m_lid_t mdl_lid, uint8_t event, uint8_t info);

/**
 ****************************************************************************************
 * @brief Definition of callback function by the Binding Manager to inform a model about
 * state value to be set
 *
 * @param[in] mdl_lid       Model local index
 * @param[in] type          State type (@see mm_state_type)
 * @param[in] state         State value
 ****************************************************************************************
 */
typedef void (*mm_bind_set_state_cb) (m_lid_t mdl_lid, uint8_t type, uint32_t state);


/*
 * STRUCTURES DEFINTIONS
 ****************************************************************************************
 */

/// Structure containing specific callback functions for a Server Model
typedef struct mm_srv_cb
{
    /// Set state value of a local Server Model
    mm_srv_set_cb       cb_set;
} mm_srv_cb_t;

/// Structure containing specific callback functions for a Client Model
typedef struct mm_cli_cb
{
    /// Get state value using a Client Model
    mm_cli_get_cb       cb_get;
    /// Set state value using a Client Model
    mm_cli_set_cb       cb_set;
    /// Initiate transition to a new state value using a Client Model
    mm_cli_trans_cb     cb_trans;
} mm_cli_cb_t;

/// Model Callback Structure
typedef struct mm_mdl_cb
{
    /// Inform model about reception of a mesh message with a supported opcode
    mm_rx_cb                cb_rx;
    /// Check if an opcode is handled by the model
    mm_opcode_check_cb      cb_opcode_check;
    /// Pointer to either callback functions for Server Model or Client Model
    union
    {
        /// Set state value of a local Server Model
        mm_srv_set_cb       cb_srv_set;
        /// Pointer to callback functions for Client Model
        const mm_cli_cb_t  *p_cb_cli;
    };
} mm_mdl_cb_t;

/// Basic structure for model information
struct mm_mdl_env
{
    /// Model ID
    uint32_t            model_id;
    /// Model callback functions
    mm_mdl_cb_t         mdl_cb;
    /// Information bit field (@see enum mm_info)
    uint8_t             info;
    /// Model Local Index
    m_lid_t             mdl_lid;
    /// Group Local Index - filled by Binding Manager
    m_lid_t             grp_lid;
    /// Element Index
    uint8_t             elmt_idx;
};

/// Basic structure for model information when sending of publications is supported
typedef struct mm_mdl_publi_env
{
    /// Basic model environment - Must be first element in the structure - DO NOT MOVE
    mm_mdl_env_t        env;
    /// Timer for sending of publications
    mesh_timer_t        tmr_publi;
    /// Publication period in milliseconds
    uint32_t            publi_period_ms;
} mm_mdl_publi_env_t;

/// Structure to allocate as part of model environment for replay protection
typedef struct mm_replay_env
{
    /// List of replay elements
    list_t              list_replay;
    /// Timer for replay protection
    mesh_timer_t        tmr_replay;
    /// Validity delay in milliseconds for replay elements inserted in the list
    uint16_t            delay_ms;
    /// Sum of delays of elements placed after the first replay element in the list
    uint16_t            delay_total_ms;
} mm_replay_env_t;

/// Buffer environment when handled by models
struct mm_route_env
{
    /// Opcode
    uint32_t            opcode;
    /// Information bitfield (@see enum mm_route_info)
    uint16_t            info;
    union
    {
        /// Source address (for RX)
        uint16_t        src;
        /// Destination address (for TX)
        uint16_t        dst;
    } u_addr;
    /// Application key local index
    m_lid_t             app_key_lid;
    /// Model local index
    m_lid_t             mdl_lid;
};


/*
 * FUNCTION DECLARATIONS
 ****************************************************************************************
 */

/****************************************************************************************
 * APIs - Mesh Stack for Models
 ****************************************************************************************/

/**
 ****************************************************************************************
 * @brief Register a model instance.
 *
 * @param[in] model_id          Model ID.
 * @param[in] elmt_idx          Index of the element the model belongs to
 * @param[in] config            Configuration (@see mesh_mdl_config)
 *
 * @return The allocated Model LID if model instance has been registered
 *         MESH_INVALID_LID if it was not possible to register the model instance.
 ****************************************************************************************
 */
m_lid_t ms_register_model(uint32_t model_id, uint8_t elmt_idx, uint8_t config);

/**
 ****************************************************************************************
 * @brief Inform the Model State Manager about registration of a new model
 *
 * @param[in] model_id      Model Identifier
 * @param[in] elmt_idx      Index of element the model belongs to
 * @param[in] mdl_lid       Local index allocated by the mesh profile for the model
 * @param[in] mdl_role      Model Role
 * @param[in] env_size      Size of environment to allocate for this model
 *
 * @return Pointer to the new environment or NULL
 ****************************************************************************************
 */
mm_mdl_env_t* mm_state_register(uint8_t elmt_idx, uint32_t model_id, m_lid_t mdl_lid,
                              uint8_t mdl_role, uint16_t env_size);

/**
 ****************************************************************************************
 * @brief Get pointer to environment allocated for a given model
 *
 * @param[in] mdl_lid       Model local index
 *
 * @return Pointer to the environment
 ****************************************************************************************
 */
mm_mdl_env_t *mm_state_get_env(m_lid_t mdl_lid);

/**
 ****************************************************************************************
 * @brief Get local index allocated for a given model on a given element
 *
 * @param[in] elmt_idx      Element Index
 * @param[in] model_id      Model Identifier
 *
 * @return Model local index or MESH_INVALID_LID if not found.
 ****************************************************************************************
 */
m_lid_t mm_state_get_lid(uint8_t elmt_idx, uint32_t model_id);

/**
 ****************************************************************************************
 * @brief Convert a transition time value in milliseconds in its packed format
 *
 * @param[in] trans_time_ms       Transition time in milliseconds
 *
 * @return Packed transition time
 ****************************************************************************************
 */
uint8_t mm_get_trans_time(uint32_t trans_time_ms);

/**
 ****************************************************************************************
 * @brief Convert a transition time value in its packed format into a millisecond value
 *
 * @param[in] time_tt       Transition time (packed format)
 *
 * @return Transition time in milliseconds
 ****************************************************************************************
 */
uint32_t mm_get_trans_time_ms(uint8_t time_tt);

/**
 ****************************************************************************************
 * @brief Add a group of bound models
 *
 * @param[in] nb_mdl            Number of models bound with the main model
 * @param[in] elmt_idx          Index of element the models belong to
 * @param[out] p_grp_lid        Pointer to variable in which group local index will be returned
 * @param[in] main_mdl_lid      Local index of the main model
 * @param[in] cb_grp_event      Callback function for communication with the model when a group
 * event occurs
 * @param[in] cb_trans_req      Callback function used to inform the main model about a transition
 * request received by one of its bound model
 *
 * @return An error status
 ****************************************************************************************
 */
m_lid_t mm_bind_add_group(uint8_t nb_mdl, uint8_t elmt_idx, m_lid_t main_mdl_lid,
                              mm_bind_grp_event_cb cb_grp_event,
                              mm_bind_trans_req_cb cb_trans_req);

/**
 ****************************************************************************************
 * @brief Add a model to a group of bound models
 *
 * @param[in] grp_lid           Group local index
 * @param[in] mdl_lid           Local index of the model
 * @param[in] model_id          Model ID of the model
 * @param[in] cb_grp_event      Callback function for communication with the model when a group
 * event occurs
 *
 * @return An error status
 ****************************************************************************************
 */
uint8_t mm_bind_group_add_mdl(m_lid_t grp_lid, m_lid_t mdl_lid, uint32_t model_id,
                                  mm_bind_grp_event_cb cb_grp_event,
                                  mm_bind_set_state_cb cb_set_state);

/**
 ****************************************************************************************
 * @brief Set default transition time value for groups belonging to a given element
 *
 * @param[in] elmt_idx          Element index
 * @param[in] dft_trans_time    Default transition time value
 ****************************************************************************************
 */
void mm_bind_set_dft_trans_time(uint8_t elmt_idx, uint8_t dft_trans_time);

/**
 ****************************************************************************************
 * @brief Function used by a bound model to set state
 *
 * @param[in] grp_lid        Group local index
 * @param[in] type           State type (@see enum mm_state_type)
 * @param[in] model_id       Model ID of the model
 * @param[in] state          State value
 *
 * @return An error status (@see mesh_err)
 ****************************************************************************************
 */
uint8_t mm_bind_set_state(m_lid_t grp_lid, uint8_t type, uint32_t model_id, uint32_t state);

/**
 ****************************************************************************************
 * @brief Function used by a bound model to request a new transition.
 *
 * @param[in] grp_lid        Group local index
 * @param[in] mdl_lid        Model local index of model that requires a transition
 * @param[in] trans_type     Transition Type (@see enum mm_trans_type)
 * @param[in] state_delta    Either new state value or delta value to be applied
 * @param[in] trans_time     Transition Time (packed format)
 * @param[in] delay          Delay
 *
 * @return An error status (@see mesh_err)
 ****************************************************************************************
 */
uint8_t mm_bind_trans_req(m_lid_t grp_lid, m_lid_t mdl_lid,
                              uint8_t trans_type, uint32_t state_delta,  uint8_t trans_time,
                              uint8_t delay);

/**
 ****************************************************************************************
 * @brief Function called by a main model in order to initiate a new transition
 *
 * @param[in] grp_lid       Group local index
 * @param[in] trans_time    Transition time
 * @param[in] delay         Delay duration in multiple of 5ms
 *
 * @return An error status
 ****************************************************************************************
 */
uint8_t mm_bind_trans_new(m_lid_t grp_lid, uint8_t trans_type, uint8_t trans_time, uint8_t delay);

/**
 ****************************************************************************************
 * @brief Function called by a main model in order to reject a transition required by one of its
 * bound models
 *
 * @param[in] grp_lid       Group local index
 ****************************************************************************************
 */
void mm_bind_trans_reject(m_lid_t grp_lid);

/**
 ****************************************************************************************
 * @brief Function called by a main model once all target states have been set in order to start
 * the transition
 *
 * @param[in] grp_lid       Group local index
 *
 * @return An error status
 ****************************************************************************************
 */
uint8_t mm_bind_trans_start(m_lid_t grp_lid);

/**
 ****************************************************************************************
 * @brief Check if transition is currently in progress for a group and retrieve the remaining
 * transition time if needed
 *
 * @param[in] grp_lid       Group local index
 * @param[in] p_rem_time    Pointer to the variable in which remaining time will be written
 * if a transition is in progress
 *
 * @return true if transition is in progress else false
 ****************************************************************************************
 */
uint8_t mm_bind_get_trans_info(m_lid_t grp_lid, uint8_t *p_trans_type, uint8_t *p_rem_time);

/**
 ****************************************************************************************
 * @brief
 *
 * @param[in] p_mdl_env     
 * @param[in] src           Source addr
 * @param[in] tid           TID value
 *
 * @return
 ****************************************************************************************
 */
bool mm_replay_is_retx(mm_replay_env_t *p_mdl_env, uint16_t src, uint8_t tid);

/**
 ****************************************************************************************
 * @brief Allocate a buffer for transmission of a message
 *
 * @param[in] data_len   Requested data length
 ****************************************************************************************
 */
__INLINE__ mesh_buf_t* mm_route_buf_alloc(uint16_t data_len)
{
    // Allocate buffer and return the status
    return (mesh_buf_alloc(2, data_len, 0));
}

/**
 ****************************************************************************************
 * @brief Allocate a buffer for transmission of a status message sent as a direct answer.
 *
 * @param[in] data_len      Requested data length
 * @param[in] p_route_env   Pointer at which address of allocated buffer must be written
 ****************************************************************************************
 */
mesh_buf_t* mm_route_buf_alloc_status(uint16_t data_len, mm_route_env_t *p_route_env);

/**
 ****************************************************************************************
 * @brief Provide a buffer to the Access Layer of the Mesh Profile for transmission
 *
 * @param[in] p_buf     Pointer to buffer containing the message to send
 ****************************************************************************************
 */
void mm_route_send(mesh_buf_t *p_buf);


/****************************************************************************************
 * APIs - Send Messages to application
 ****************************************************************************************/

/**
 ****************************************************************************************
 * @brief Inform upper application about registered model
 *        Send a MESH_MDL_IND message with MM_REGISTER_IND indication code.
 *
 * @param[in] model_id      Model Identifier
 * @param[in] elmt_idx      Element Index
 * @param[in] mdl_lid       Allocated model local index
 ****************************************************************************************
 */
//void mm_register_ind_send(uint32_t model_id, uint8_t elmt_idx, m_lid_t mdl_lid);
#define mm_register_ind_send(model_id, elmt_idx, mdl_lid)

/**
 ****************************************************************************************
 * @brief Inform application about a local model state update
 *        Send a MESH_MDL_IND message with MM_SRV_STATE_UPD_IND indication code.
 *
 * @param[in] state_id      State identifier (@see mm_state_idx)
 * @param[in] elmt_idx      Element Index
 * @param[in] state         New state value or targeted state value depending on
 * transition time
 * @param[in] trans_time_ms Transition time in milliseconds
 ****************************************************************************************
 */
void mm_srv_state_upd_ind_send(uint16_t state_id, uint8_t elmt_idx, uint32_t state,
                                   uint32_t trans_time_ms);

/**
 ****************************************************************************************
 * @brief Inform upper application about set global part of Generic Location state value
 *        Send a MESH_MDL_IND message with MM_SRV_LOCG_UPD_IND indication code.
 *
 * @param[in] elmt_idx      Element Index
 * @param[in] latitude      Global Latitude
 * @param[in] longitude     Global Longitude
 * @param[in] altitude      Global Altitude
 ****************************************************************************************
 */
void mm_srv_locg_upd_ind_send(uint8_t elmt_idx, int32_t latitude, int32_t longitude,
                                    int16_t altitude);

/**
 ****************************************************************************************
 * @brief Inform upper application about set local part of Generic Location state value
 *        Send a MESH_MDL_IND message with MM_SRV_LOCL_UPD_IND indication code.
 *
 * @param[in] elmt_idx      Element Index
 * @param[in] north         Local North
 * @param[in] east          Local East
 * @param[in] altitude      Local Altitude
 * @param[in] floor         Floor Number
 * @param[in] uncertainty   Uncertainty
 ****************************************************************************************
 */
void mm_srv_locl_upd_ind_send(uint8_t elmt_idx, int16_t north, int16_t east, int16_t altitude,
                                   uint8_t floor, uint16_t uncertainty);

/**
 ****************************************************************************************
 * @brief Send a MESH_MDL_REQ_IND message to upper application in order to retrieve 
 *        a state value not stored locally
 *
 * @param[in] req_code      Request indication code (@see mm_req_code)
 * @param[in] elmt_dix      Element Index
 ****************************************************************************************
 */
void mm_srv_state_req_ind_send(uint16_t req_code, uint8_t elmt_idx);

/**
 ****************************************************************************************
 * @brief Send a MESH_MDL_REQ_IND message with MM_SRV_PROP_GET_REQ_IND to Inform application
 *        about received get request for a Generic User/Admin/Manufacturer Property.
 *        A confirmation is expected from the application.
 *
 * @param[in] elmt_idx      Index of element for which get request has been received
 * @param[in] prop_type     Property type (@see enum mm_prop_type)
 * @param[in] prop_id       Property ID
 ****************************************************************************************
 */
void mm_srv_prop_get_send(uint8_t elmt_idx, uint8_t prop_type, uint16_t prop_id);

/**
 ****************************************************************************************
 * @brief Send a MESH_MDL_REQ_IND message with MM_SRV_PROP_SET_REQ_IND to Inform application 
 *        about received set request for a Generic User/Admin/Manufacturer Property.
 *        A confirmation is expected from the application.
 *
 * @param[in] elmt_idx      Index of element for which set request has been received
 * @param[in] prop_type     Property type (@see enum mm_prop_type)
 * @param[in] prop_id       Property ID
 * @param[in] length        Property value length
 * @param[in] p_val         Pointer to the received property value
 ****************************************************************************************
 */
void mm_srv_prop_set_send(uint8_t elmt_idx, uint8_t prop_type, uint16_t prop_id,
                              uint16_t length, uint8_t *p_val);

/**
 ****************************************************************************************
 * @brief Inform application about received state value from an element
 *        Send a MESH_MDL_IND message with MM_CLI_STATE_IND indication code.
 *
 * @param[in] src           Address of element for which state value has been received
 * @param[in] state_id      State Identifier
 * @param[in] state_1       State value 1
 * @param[in] state_2       State value 2
 * @param[in] rem_time_ms   Remaining time in milliseconds
 ****************************************************************************************
 */
void mm_cli_state_ind_send(uint16_t src, uint16_t state_id, uint32_t state_1,
                               uint32_t state_2, uint32_t rem_time_ms);

/**
 ****************************************************************************************
 * @brief Inform application about received Generic Battery state value from an element
 *        Send a MESH_MDL_IND message with MM_CLI_BAT_IND indication code.
 *
 * @param[in] src           Address of node's element that has reported its Generic Battery state
 * @param[in] bat_lvl       Battery level value
 * @param[in] time_dischrg  Time to discharge
 * @param[in] time_chrg     Time to charge
 * @param[in] flags         Flags
 ****************************************************************************************
 */
void mm_cli_bat_ind_send(uint16_t src, uint8_t bat_lvl, uint32_t time_dischrg,
                             uint32_t time_chrg, uint8_t flags);

/**
 ****************************************************************************************
 * @brief Inform application about received Generic Location Global state value from an element
 *        Send a MESH_MDL_IND message with a MM_CLI_LOCG_IND indication code.
 *
 * @param[in] src           Address of node's element that has reported its Generic Location state
 * @param[in] latitude      Global Latitude
 * @param[in] longitude     Global Longitude
 * @param[in] altitude      Global Altitude
 ****************************************************************************************
 */
void mm_cli_locg_ind_send(uint16_t src, int32_t latitude, int32_t longitude, int16_t altitude);

/**
 ****************************************************************************************
 * @brief Inform application about received Generic Location Local state value from an element
 *        Send a MESH_MDL_IND message with a MM_CLI_LOCL_IND indication code.
 *
 * @param[in] src           Address of node's element that has reported its Generic Location state
 * @param[in] north         Local North
 * @param[in] East          Local East
 * @param[in] altitude      Local Altitude
 * @param[in] floor         Floor
 * @param[in] uncertainty   Uncertainty
 ****************************************************************************************
 */
void mm_cli_locl_ind_send(uint16_t src, int16_t north, int16_t east, int16_t altitude,
                               uint8_t floor, uint16_t uncertainty);

/**
 ****************************************************************************************
 * @brief Inform application about reception of a Generic User/Admin/Manufacturer Property value.
 *        Send a MESH_MDL_IND message with a MM_CLI_PROP_IND indication code.
 *
 * @param[in] src           Address of element for which property value has been received
 * @param[in] prop_id       Property ID
 * @param[in] user_access   User access
 * @param[in] length        Property value length
 * @param[in] p_val         Pointer to the property value
 ****************************************************************************************
 */
void mm_cli_prop_ind_send(uint16_t src, uint16_t prop_id, uint8_t user_access, uint16_t length,
                              uint8_t *p_val);

/**
 ****************************************************************************************
 * @brief Inform application about reception of list of Generic User/Admin/Manufacturer/Client
 *        Properties supported by an element. 
 *        Send a MESH_MDL_IND message with a MM_CLI_PROP_IND indication code.
 *
 * @param[in] src           Address of element for which list of properties has been received
 * @param[in] prop_type     Property type (@see enum mm_prop_type)
 * @param[in] nb_prop       Number of Properties
 * @param[in] p_prop_ids    Pointer to received list of Property IDs
 ****************************************************************************************
 */
void mm_cli_prop_list_ind_send(uint16_t src, uint8_t prop_type, uint16_t nb_prop,
                                   uint16_t *p_prop_ids);


#endif // _MM_ITF_H_