ble-light/components/ethermind/mesh/export/include/MS_generic_location_api.h

/**
 * \file MS_generic_location_api.h
 *
 * \brief This file defines the Mesh Generic Location Model Application Interface
 * - includes Data Structures and Methods for both Server and Client.
 */

/*
 * Copyright (C) 2017. Mindtree Ltd.
 * All rights reserved.
 */

#ifndef _H_MS_GENERIC_LOCATION_API_
#define _H_MS_GENERIC_LOCATION_API_


/* --------------------------------------------- Header File Inclusion */
#include "MS_access_api.h"


/* --------------------------------------------- Global Definitions */
/**
 * \defgroup generic_location_module GENERIC_LOCATION (Mesh Generic Location Model)
 * \{
 *  This section describes the interfaces & APIs offered by the EtherMind
 *  Mesh Generic OnOff Model (ONOFF) module to the Application.
 */



/* --------------------------------------------- Data Types/ Structures */
/**
 *  \defgroup generic_location_cb Application Callback
 *  \{
 *  This Section Describes the module Notification Callback interface offered
 *  to the application
 */

/**
 * Generic Location Server application Asynchronous Notification Callback.
 *
 * Generic Location Server calls the registered callback to indicate events occurred to the
 * application.
 *
 * \param [in] ctx           Context of the message received for a specific model instance.
 * \param [in] msg_raw       Uninterpreted/raw received message.
 * \param [in] req_type      Requested message type.
 * \param [in] state_params  Model specific state parameters.
 * \param [in] ext_params    Additional parameters.
 */
typedef API_RESULT (* MS_GENERIC_LOCATION_SERVER_CB)
        (
            MS_ACCESS_MODEL_REQ_MSG_CONTEXT    * ctx,
            MS_ACCESS_MODEL_REQ_MSG_RAW        * msg_raw,
            MS_ACCESS_MODEL_REQ_MSG_T          * req_type,
            MS_ACCESS_MODEL_STATE_PARAMS       * state_params,
            MS_ACCESS_MODEL_EXT_PARAMS         * ext_params

        ) DECL_REENTRANT;

/**
 * Generic Location Client application Asynchronous Notification Callback.
 *
 * Generic Location Client calls the registered callback to indicate events occurred to the
 * application.
 *
 * \param handle        Model Handle.
 * \param opcode        Opcode.
 * \param data_param    Data associated with the event if any or NULL.
 * \param data_len      Size of the event data. 0 if event data is NULL.
 */
typedef API_RESULT (* MS_GENERIC_LOCATION_CLIENT_CB)
        (
            MS_ACCESS_MODEL_HANDLE * handle,
            UINT32                   opcode,
            UCHAR                  * data_param,
            UINT16                   data_len
        ) DECL_REENTRANT;

/**
 * Generic Location Setup Server application Asynchronous Notification Callback.
 *
 * Generic Location Setup Server calls the registered callback to indicate events occurred to the
 * application.
 *
 * \param [in] ctx           Context of the message received for a specific model instance.
 * \param [in] msg_raw       Uninterpreted/raw received message.
 * \param [in] req_type      Requested message type.
 * \param [in] state_params  Model specific state parameters.
 * \param [in] ext_params    Additional parameters.
 */
typedef API_RESULT (* MS_GENERIC_LOCATION_SETUP_SERVER_CB)
        (
            MS_ACCESS_MODEL_REQ_MSG_CONTEXT    * ctx,
            MS_ACCESS_MODEL_REQ_MSG_RAW        * msg_raw,
            MS_ACCESS_MODEL_REQ_MSG_T          * req_type,
            MS_ACCESS_MODEL_STATE_PARAMS       * state_params,
            MS_ACCESS_MODEL_EXT_PARAMS         * ext_params

        ) DECL_REENTRANT;
/** \} */


/**
 *  \defgroup generic_location_structures Structures
 *  \{
 */

/**
 * Generic Location Global Set message parameters.
 */
typedef struct MS_generic_location_global_struct
{
    /**
     * Global Coordinates (Latitude).
     * The Global Latitude field describes the global WGS84 North coordinate of the element.
     */
    UINT32 global_latitude;

    /**
     * Global Coordinates (Longitude).
     * The Global Longitude field describes the global WGS84 East coordinate of the element.
     */
    UINT32 global_longitude;

    /**
     * Global Altitude.
     * The Global Altitude field determines the altitude of the device above the WGS84 datum.
     * It expresses the altitude beyond the WGS84 ellipsoid of the element that exposed its position.
     *
     * Value         | Description
     * --------------|------------
     * 0x7FFF        | Global Altitude is not configured.
     * 0x7FFE        | Global Altitude is greater than or equal to 32766 meters.
     * 0x8000-0x7FFD | Global Altitude is (field value) from -32768 meters through 32765 meters.
     */
    UINT16 global_altitude;

} MS_GENERIC_LOCATION_GLOBAL_STRUCT;

/**
 * Generic Location Local Set message parameters.
 */
typedef struct MS_generic_location_local_struct
{
    /**
     * Local Coordinates (North).
     * The Local North field describes the North coordinate of the device using a local coordinate system.
     * It is relative to the north orientation on a predefined map.
     *
     * The Local North value is encoded in decimeters and has a range of -32767 decimeters through 32767 decimeters.
     * The value 0x8000 means the Local North information is not configured.
     */
    UINT16 local_north;

    /**
     * Local Coordinates (East).
     * The Local East field describes the East coordinate of the device using a local coordinate system.
     * It is relative to the east orientation of a predefined map.
     *
     * The Local East value is encoded decimeters and it ranges from -32767 decimeters through 32767 decimeters.
     * The value 0x8000 means the Local East information is not configured.
     */
    UINT16 local_east;

    /**
     * Local Altitude.
     * The Local Altitude field determines the altitude of the device relative to the Generic Location Global Altitude.
     *
     * Value         | Description
     * --------------|------------
     * 0x7FFF        | Local Altitude is not configured.
     * 0x7FFE        | Local Altitude is greater than or equal to 32766 meters.
     * 0x8000-0x7FFD | Local Altitude is (field value) from -32768 meters through 32765 meters.
     */
    UINT16 local_altitude;

    /**
     * Floor Number.
     *
     * The Floor Number field describes the floor number where the element is installed.
     * The floor number, N, is encoded as X = N + 20, where X is the encoded floor number.
     * Floor number = -20 (X=0) has a special meaning, indicating the floor -20, and also any floor below that.
     * Floor number = 232 (X=252) has a special meaning, indicating the floor 232, and also any floor above that.
     *
     * Encoded Value X | Floor number N
     * ----------------|---------------
     * 0x00            | Floor -20 or any floor below -20.
     * 0x01-0xFB       | Floor number N, encoded as X = N + 20.
     * 0xFC            | Floor 232 or any floor above 232.
     * 0xFD            | Ground floor. Floor 0.
     * 0xFE            | Ground floor. Floor 1.
     * 0xFF            | Not configured
     *
     * Note: The reason for having two definitions of ground floor (0 or 1) is to allow for
     * different conventions applicable in different countries.
     */
    UCHAR  floor_number;

    /**
     * Uncertainty.
     * The Uncertainty field is a 16-bit bit field that describes the uncertainty of
     * the location information the element exposes.
     *
     * bits  | Field       | Description
     * ------|-------------|------------
     * 0     | Stationary  | This bit indicates whether the device broadcasting the location information
     *                       has a stationary location or is mobile. (0 = Stationary, 1 = Mobile)
     * 1-7   | RFU         | Reserved for Future Use
     * 8-11  | Update Time | This value (x) is a 4-bit value ranging from 0 through 15.
     *                       It represents the time (t) elapsed since the last update of the device's position,
     *                       measured in seconds using the following formula: t=2^(x-3)
     *                       The represented range is from 0.125 seconds through 4096 seconds.
     *                       Note: If 'stationary' is set, this value can be ignored.
     * 12-15 | Precision   | This value (y) is a 4-bit value ranging from 0 through 15.
     *                       It represents a location precision with the formula: Precision = 2^(y-3)
     *                       The represented range is from 0.125 meters through 4096 meters.
     */
    UINT16 uncertainty;

} MS_GENERIC_LOCATION_LOCAL_STRUCT;

/** \} */



/* --------------------------------------------- Function */
/**
 * \defgroup generic_location_api_defs API Definitions
 * \{
 * This section describes the EtherMind Mesh Generic Location Model APIs.
 */
/**
 * \defgroup generic_location_ser_api_defs Generic Location Server API Definitions
 * \{
 * This section describes the Generic Location Server APIs.
 */

/**
 *  \brief API to initialize Generic_Location Server model
 *
 *  \par Description
 *  This is to initialize Generic_Location Server model and to register with Acess layer.
 *
 *  \param [in] element_handle
 *              Element identifier to be associated with the model instance.
 *
 *  \param [in, out] model_handle
 *                   Model identifier associated with the model instance on successful initialization.
 *                   After power cycle of an already provisioned node, the model handle will have
 *                   valid value and the same will be reused for registration.
 *
 *  \param [in] appl_cb    Application Callback to be used by the Generic_Location Server.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_server_init
           (
               /* IN */    MS_ACCESS_ELEMENT_HANDLE    element_handle,
               /* INOUT */ MS_ACCESS_MODEL_HANDLE    * model_handle,
               /* IN */    MS_GENERIC_LOCATION_SERVER_CB appl_cb
           );

/**
 *  \brief API to send reply or to update state change
 *
 *  \par Description
 *  This is to send reply for a request or to inform change in state.
 *
 * \param [in] ctx                     Context of the message.
 * \param [in] current_state_params    Model specific current state parameters.
 * \param [in] target_state_params     Model specific target state parameters (NULL: to be ignored).
 * \param [in] remaining_time          Time from current state to target state (0: to be ignored).
 * \param [in] ext_params              Additional parameters (NULL: to be ignored).
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_server_state_update
           (
               /* IN */ MS_ACCESS_MODEL_REQ_MSG_CONTEXT    * ctx,
               /* IN */ MS_ACCESS_MODEL_STATE_PARAMS       * current_state_params,
               /* IN */ MS_ACCESS_MODEL_STATE_PARAMS       * target_state_params,
               /* IN */ UINT16                               remaining_time,
               /* IN */ MS_ACCESS_MODEL_EXT_PARAMS         * ext_params
           );

/**
 *  \brief API to initialize Generic_Location_Setup Server model
 *
 *  \par Description
 *  This is to initialize Generic_Location_Setup Server model and to register with Acess layer.
 *
 *  \param [in] element_handle
 *              Element identifier to be associated with the model instance.
 *
 *  \param [in, out] model_handle
 *                   Model identifier associated with the model instance on successful initialization.
 *                   After power cycle of an already provisioned node, the model handle will have
 *                   valid value and the same will be reused for registration.
 *
 *  \param [in] appl_cb    Application Callback to be used by the Generic_Location_Setup Server.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_setup_server_init
           (
               /* IN */    MS_ACCESS_ELEMENT_HANDLE    element_handle,
               /* INOUT */ MS_ACCESS_MODEL_HANDLE    * model_handle,
               /* IN */    MS_GENERIC_LOCATION_SETUP_SERVER_CB appl_cb
           );

/**
 *  \brief API to send reply or to update state change
 *
 *  \par Description
 *  This is to send reply for a request or to inform change in state.
 *
 * \param [in] ctx                     Context of the message.
 * \param [in] current_state_params    Model specific current state parameters.
 * \param [in] target_state_params     Model specific target state parameters (NULL: to be ignored).
 * \param [in] remaining_time          Time from current state to target state (0: to be ignored).
 * \param [in] ext_params              Additional parameters (NULL: to be ignored).
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_setup_server_state_update
           (
               /* IN */ MS_ACCESS_MODEL_REQ_MSG_CONTEXT    * ctx,
               /* IN */ MS_ACCESS_MODEL_STATE_PARAMS       * current_state_params,
               /* IN */ MS_ACCESS_MODEL_STATE_PARAMS       * target_state_params,
               /* IN */ UINT16                               remaining_time,
               /* IN */ MS_ACCESS_MODEL_EXT_PARAMS         * ext_params
           );
/** \} */

/**
 * \defgroup generic_location_cli_api_defs Generic Location Client API Definitions
 * \{
 * This section describes the Generic Location Client APIs.
 */

/**
 *  \brief API to initialize Generic_Location Client model
 *
 *  \par Description
 *  This is to initialize Generic_Location Client model and to register with Acess layer.
 *
 *  \param [in] element_handle
 *              Element identifier to be associated with the model instance.
 *
 *  \param [in, out] model_handle
 *                   Model identifier associated with the model instance on successful initialization.
 *                   After power cycle of an already provisioned node, the model handle will have
 *                   valid value and the same will be reused for registration.
 *
 *  \param [in] appl_cb    Application Callback to be used by the Generic_Location Client.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_client_init
           (
               /* IN */    MS_ACCESS_ELEMENT_HANDLE    element_handle,
               /* INOUT */ MS_ACCESS_MODEL_HANDLE    * model_handle,
               /* IN */    MS_GENERIC_LOCATION_CLIENT_CB appl_cb
           );

/**
 *  \brief API to get Generic_Location client model handle
 *
 *  \par Description
 *  This is to get the handle of Generic_Location client model.
 *
 *  \param [out] model_handle   Address of model handle to be filled/returned.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_client_get_model_handle
           (
               /* OUT */ MS_ACCESS_MODEL_HANDLE  * model_handle
           );

/**
 *  \brief API to send acknowledged commands
 *
 *  \par Description
 *  This is to initialize sending acknowledged commands.
 *
 *  \param [in] req_opcode    Request Opcode.
 *  \param [in] param         Parameter associated with Request Opcode.
 *  \param [in] rsp_opcode    Response Opcode.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
API_RESULT MS_generic_location_client_send_reliable_pdu
           (
               /* IN */ UINT32    req_opcode,
               /* IN */ void    * param,
               /* IN */ UINT32    rsp_opcode
           );

/**
 *  \brief API to get the selected fields of the Generic Location state of an element.
 *
 *  \par Description
 *  Generic Location Global Get message is an acknowledged message used to get the selected fields
 *  of the Generic Location state of an element.
 *  The response to the Generic Location Global Get message is a Generic Location Global Status message.
 *  There are no parameters for this message.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
#define MS_generic_location_global_get() \
        MS_generic_location_client_send_reliable_pdu \
        (\
            MS_ACCESS_GENERIC_LOCATION_GLOBAL_GET_OPCODE,\
            NULL,\
            MS_ACCESS_GENERIC_LOCATION_GLOBAL_STATUS_OPCODE\
        )

/**
 *  \brief API to set the selected fields of the Generic Location state of an element.
 *
 *  \par Description
 *  Generic Location Global Set is an acknowledged message used to set the selected fields of the Generic Location state of an element.
 *  The response to the Generic Location Global Set message is a Generic Location Global Status message.
 *
 *  \param [in] param Generic Location Global Set message
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
#define MS_generic_location_global_set(param) \
        MS_generic_location_client_send_reliable_pdu \
        (\
            MS_ACCESS_GENERIC_LOCATION_GLOBAL_SET_OPCODE,\
            param,\
            MS_ACCESS_GENERIC_LOCATION_GLOBAL_STATUS_OPCODE\
        )

/**
 *  \brief API to set the selected fields of the Generic Location state of an element.
 *
 *  \par Description
 *  Generic Location Global Set Unacknowledged is an unacknowledged message used to set the selected fields
 *  of the Generic Location state of an element.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
#define MS_generic_location_global_set_unacknowledged(param) \
        MS_generic_location_client_send_reliable_pdu \
        (\
            MS_ACCESS_GENERIC_LOCATION_GLOBAL_SET_UNACKNOWLEDGED_OPCODE,\
            param,\
            0xFFFFFFFF\
        )

/**
 *  \brief API to get the selected fields of the Generic Location state of an element.
 *
 *  \par Description
 *  Generic Location Local Get message is an acknowledged message used to get the selected fields
 *  of the Generic Location state of an element.
 *  The response to the Generic Location Local Get message is a Generic Location Local Status message.
 *  There are no parameters for this message.
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
#define MS_generic_location_local_get() \
        MS_generic_location_client_send_reliable_pdu \
        (\
            MS_ACCESS_GENERIC_LOCATION_LOCAL_GET_OPCODE,\
            NULL,\
            MS_ACCESS_GENERIC_LOCATION_LOCAL_STATUS_OPCODE\
        )

/**
 *  \brief API to set the selected fields of the Generic Location state of an element.
 *
 *  \par Description
 *  Generic Location Local Set is an acknowledged message used to set the selected fields
 *  of the Generic Location state of an element.
 *  The response to the Generic Location Local Set message is a Generic Location Local Status message.
 *
 * \param [in] param Generic Location Local Set message
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
#define MS_generic_location_local_set(param) \
        MS_generic_location_client_send_reliable_pdu \
        (\
            MS_ACCESS_GENERIC_LOCATION_LOCAL_SET_OPCODE,\
            param,\
            MS_ACCESS_GENERIC_LOCATION_LOCAL_STATUS_OPCODE\
        )

/**
 *  \brief API to set the selected fields of the Generic Location state of an element.
 *
 *  \par Description
 *  Generic Location Local Set Unacknowledged is an unacknowledged message used to set the selected fields
 *  of the Generic Location state of an element.
 *
 *  \param [in] param Generic Location Local Set message
 *
 *  \return API_SUCCESS or an error code indicating reason for failure
 */
#define MS_generic_location_local_set_unacknowledged(param) \
        MS_generic_location_client_send_reliable_pdu \
        (\
            MS_ACCESS_GENERIC_LOCATION_LOCAL_SET_UNACKNOWLEDGED_OPCODE,\
            param,\
            0xFFFFFFFF\
        )
/** \} */
/** \} */
/** \} */

#endif /*_H_MS_GENERIC_LOCATION_API_ */