/**
* \file MS_brr_api.h
*
* \brief This file defines the Mesh Bearer Application Interface - includes
* Data Structures and Methods.
*/
/*
* Copyright (C) 2017. Mindtree Ltd.
* All rights reserved.
*/
#ifndef _H_MS_BRR_API_
#define _H_MS_BRR_API_
/* --------------------------------------------- Header File Inclusion */
#include "MS_common.h"
/* --------------------------------------------- Global Definitions */
/**
* \defgroup brr_module BEARER (Mesh Bearer Layer)
* \{
* This section describes the interfaces & APIs offered by the EtherMind
* Mesh Bearer (BEARER) module to the Application and other upper
* layers of the stack.
*/
/**
* \defgroup brr_defines Defines
* \{
* Describes defines for the module.
*/
/**
* \defgroup brr_constants Constants
* \{
* Describes Constants defined by the module.
*/
/** Invalid Bearer handle identifier */
#define BRR_HANDLE_INVALID 0xFF
/** Bearer Interface events to the above layer */
#define BRR_IFACE_DOWN 0x00
#define BRR_IFACE_UP 0x01
#define BRR_IFACE_DATA 0x02
#define BRR_IFACE_PROXY_DATA 0x03
/** Bearer beacon types - Connectable (Active) and Non-Connectable (Passive) */
#define BRR_BCON_PASSIVE 0x00
#define BRR_BCON_ACTIVE 0x01
/** Bearer Beacon Operations - Broadcast/Observe */
#define BRR_BROADCAST 0x00
#define BRR_OBSERVE 0x01
/** Bearer Beacon Actions - Enable/Disable */
#define BRR_DISABLE 0x00
#define BRR_ENABLE 0x01
/** Maximum PDU size for data received over bearer */
#define BRR_MAX_PDU_SIZE 65
/** Bearer Server Client Roles */
#define BRR_CLIENT_ROLE 0x00
#define BRR_SERVER_ROLE 0x01
#define BRR_INVALID_ROLE 0xFF
/** Bearer Transmit and Receive operation modes */
#define BRR_TX 0x01
#define BRR_RX 0x02
/** \} */
/** \} */
/**
* \defgroup brr_events Events
* \{
* This section lists the Asynchronous Events notified to Application by the
* Module.
*/
/**
* \defgroup brr_marcos Utility Macros
* \{
* Initialization and other Utility Macros offered by the module.
*/
/** \} */
/** \} */
/* --------------------------------------------- Data Types/ Structures */
/**
* \addtogroup brr_defines Defines
* \{
*/
/** Bearer handle identifier */
typedef UCHAR BRR_HANDLE;
/** Bearer Type definitions */
typedef enum _BRR_TYPE
{
/** Beacon Bearer */
BRR_TYPE_BCON,
/** Advertising Bearer */
BRR_TYPE_ADV,
/** Provisioning Advertising Bearer */
BRR_TYPE_PB_ADV,
/** GATT Bearer */
BRR_TYPE_GATT,
/** Provisioning GATT Bearer */
BRR_TYPE_PB_GATT,
/** Number of bearers supported */
BRR_COUNT
} BRR_TYPE;
/* GATT Bearer Message Type Masks */
#define BRR_SUBTYPE_GATT_T_MASK_BIT_OFFSET 6
#define BRR_SUBTYPE_GATT_T_MASK (0xC0)
#define BRR_SUBTYPE_GATT_NETWORK_T_MASK ((MESH_GATT_TYPE_NETWORK << BRR_SUBTYPE_GATT_T_MASK_BIT_OFFSET) & (BRR_SUBTYPE_GATT_T_MASK))
#define BRR_SUBTYPE_GATT_BEACON_T_MASK ((MESH_GATT_TYPE_BEACON << BRR_SUBTYPE_GATT_T_MASK_BIT_OFFSET) & (BRR_SUBTYPE_GATT_T_MASK))
#define BRR_SUBTYPE_GATT_PROXY_T_MASK ((MESH_GATT_TYPE_PROXY << BRR_SUBTYPE_GATT_T_MASK_BIT_OFFSET) & (BRR_SUBTYPE_GATT_T_MASK))
#define BRR_SUBTYPE_GATT_PROV_T_MASK ((MESH_GATT_TYPE_PROV << BRR_SUBTYPE_GATT_T_MASK_BIT_OFFSET) & (BRR_SUBTYPE_GATT_T_MASK))
/** Bearer Beacon type definitions */
typedef enum _BRR_BCON_TYPE
{
/* Unprovisioned Device Beacon */
BRR_BCON_TYPE_UNPROV_DEVICE,
/* Secure Network Beacon */
BRR_BCON_TYPE_SECURE_NET,
/* Proxy beacon with Network ID */
BRR_BCON_TYPE_PROXY_NETID,
/* Proxy beacon with Node Identity */
BRR_BCON_TYPE_PROXY_NODEID,
/** Number of Beacon types */
BRR_BCON_COUNT
} BRR_BCON_TTYPE;
/**
* \addtogroup brr_structures Structures
* \{
*/
/** Bearer information to register */
typedef struct _BRR_BEARER_INFO
{
/** Bearer Information */
MS_BUFFER * binfo;
/** Data Send routine */
API_RESULT (*bearer_send)(BRR_HANDLE *, UCHAR, void *, UINT16);
/** Data Receive routine */
void (*bearer_recv)(BRR_HANDLE *, UCHAR *, UINT16, MS_BUFFER * info);
/** Bearer Sleep Interface */
void (*bearer_sleep)(BRR_HANDLE *);
/** Bearer Wakeup Interface */
void (*bearer_wakeup)(BRR_HANDLE *, UINT8 mode);
} BRR_BEARER_INFO;
/** Bearer Beacon type data structure */
typedef struct _BRR_BEACON_INFO
{
/**
* Beacon Action
* - Lower Nibble:
* > BRR_OBSERVE
* > BRR_BROADCAST
*
* - Higher Nibble:
* > BRR_ENABLE
* > BRR_DISABLE
*/
UCHAR action;
/**
* Beacon type
* - Lower Nibble:
* > BRR_BCON_PASSIVE - Non Connectable beacon
* > BRR_BCON_ACTIVE - Connectable beacon
*
* - Higher Nibble (Valid only when Passive)
* > BRR_BCON_TYPE_UNPROV_DEVICE
* > BRR_BCON_TYPE_SECURE_NET
*/
UCHAR type;
/** Beacon Broadcast Data */
UCHAR * bcon_data;
/** Beacon Broadcast Data length */
UINT16 bcon_datalen;
/** URI information in case of Unprovisioned Beacons */
MS_BUFFER * uri;
} BRR_BEACON_INFO;
/** Bearer GATT Channel informartion related data structure */
typedef struct _BRR_BEARER_CH_INFO
{
/** Identifies the MTU for the Bearer Channel */
UINT16 mtu;
/** Identifies the role for the Bearer channel */
UCHAR role;
}BRR_BEARER_CH_INFO;
/** \} */
/** \} */
/**
* \defgroup brr_cb Application Callback
* \{
* This Section Describes the module Notification Callback interface offered
* to the application
*/
/**
* BEARER Application Asynchronous Notification Callback.
*
* BEARER calls the registered callback to indicate events occurred to the
* application.
*
* \param brr_type Bearer Type.
* \param data 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 (*BRR_NTF_CB)
(
BRR_HANDLE * brr_handle,
UCHAR brr_event,
UCHAR * data_param,
UINT16 data_len
) DECL_REENTRANT;
/**
* BEARER Application Asynchronous Notification Callback for Beacons.
*
* Application registers callback for beacon notification with bearer.
*
* \param brr_type Bearer Type.
* \param data Data associated with the event if any or NULL.
* \param data_len Size of the event data. 0 if event data is NULL.
*/
typedef void (*BRR_BCON_CB)
(
UCHAR * data_param,
UINT16 data_len
) DECL_REENTRANT;
/** \} */
/**
* \addtogroup brr_defines Defines
* \{
*/
/**
* \addtogroup brr_structures Structures
* \{
*/
/** \} */
/** \} */
/* --------------------------------------------- Function */
/**
* \defgroup brr_api_defs API Definitions
* \{
* This section describes the EtherMind Mesh Bearer Layer APIs.
*/
#ifdef __cplusplus
extern "C" {
#endif
/**
* \brief Register Interface with Bearer Layer
*
* \par Description
* This routine registers interface with the Bearer Layer.
* Bearer Layer supports single Application, hence this rouine shall be called once.
*
* \param [in] brr_type
* Bearer Type
*
* \param [in] brr_cb
* Details describing Application Notification Callback
*
* \return API_SUCCESS or an error code indicating reason for failure
*
*/
API_RESULT MS_brr_register
(
/* IN */ BRR_TYPE brr_type,
/* IN */ BRR_NTF_CB brr_cb
);
/**
* \brief Register Beacon Interface with Bearer Layer
*
* \par Description
* This routine registers interface with the Bearer Layer to process Beacons.
* Bearer Layer supports single Application, hence this rouine shall be called once.
*1
* \param [in] bcon_type
* Beacon type - Unprovisioned Device or Secure Network.
*
* \param [in] bcon_handler
* Callback handler to be registered for the given beacon type.
*
* \return API_SUCCESS or an error code indicating reason for failure
*
*/
API_RESULT MS_brr_register_beacon_handler
(
/* IN */ UCHAR bcon_type,
/* IN */ void (*bcon_handler) (UCHAR * data, UINT16 datalen)
);
/**
* \brief Add a bearer to Bearer Layer
*
* \par Description
* This routine adds a bearer that is setup by the application
* for use by the Mesh Stack. Bearer Layer supports single Application,
* hence this rouine shall be called once.
*
* \param [in] brr_type
* Bearer Type
*
* \param [in] brr_info
* Details describing the Bearer being added
*
* \param [out] brr_handle
* Handle to the bearer that is added. Used in data APIs.
*
* \return API_SUCCESS or an error code indicating reason for failure
*
*/
API_RESULT MS_brr_add_bearer
(
/* IN */ BRR_TYPE brr_type,
/* IN */ BRR_BEARER_INFO * brr_info,
/* OUT */ BRR_HANDLE * brr_handle
);
/**
* \brief Remove a bearer from Bearer Layer
*
* \par Description
* This routine removes a bearer from the Mesh Stack. Bearer Layer
* supports single Application, hence this rouine shall be called once.
*
* \param [in] brr_type
* Bearer Type
*
* \param [out] brr_handle
* Handle to the bearer that is added. Used in data APIs.
*
* \return API_SUCCESS or an error code indicating reason for failure
*
*/
API_RESULT MS_brr_remove_bearer
(
/* IN */ BRR_TYPE brr_type,
/* IN */ BRR_HANDLE * brr_handle
);
/**
* \brief Observe ON/OFF for the beacon type
*
* \par Description
* This routine sends enables/disables the observation procedure
* for the given beacon type.
*
* \param [in] bcon_type
* Type of beacon to observe - Active/Passive.
*
* \param [in] enable
* Enable or Disable the observation procedure.
*
* \return API_SUCCESS or an error code indicating reason for failure
*
*/
API_RESULT MS_brr_observe_beacon
(
/* IN */ UCHAR bcon_type,
/* IN */ UCHAR enable
);
/**
* \brief API to send Unprovisioned Device Beacon
*
* \par Description
* This routine sends Unprovisioned Device Beacon
*
* \param [in] type
* Active or Passive Broadcast type.
*
* \param [in] dev_uuid
* Device UUID uniquely identifying this device.
*
* \param [in] oob_info
* OOB Information
*
* \param [in] uri
* Optional Parameter. NULL if not present.
* Points to the length and payload pointer of the URI string to be
* advertised interleaving with the unprovisioned beacon.
*
* \return API_SUCCESS or an error code indicating reason for failure
*/
API_RESULT MS_brr_bcast_unprovisioned_beacon
(
/* IN */ UCHAR type,
/* IN */ UCHAR * dev_uuid,
/* IN */ UINT16 oob_info,
/* IN */ MS_BUFFER * uri
);
/**
* \brief API to broadcast a beacon
*
* \par Description
* This routine sends the beacon of given type on Adv and GATT bearers
*
* \param [in] type
* The type of beacon
*
* \param [in] packet
* Beacon data
*
* \param [in] length
* Beacon data length
*
* \return API_SUCCESS or an error code indicating reason for failure
*/
API_RESULT MS_brr_broadcast_beacon
(
/* IN */ UCHAR type,
/* IN */ UCHAR * packet,
/* IN */ UINT16 length
);
/**
* \brief API to send Proxy Device ADV
*
* \par Description
* This routine sends Proxy Device ADV
*
* \param [in] type
* Proxy ADV Type:
* 0x00 - Network ID
* 0x01 - Node Identity
*
* \param [in] data
* Data to be advertised by Proxy.
* If the "type" is:
* 0x00 - Network ID - 8 Bytes of Network ID
* 0x01 - Node Identity - 8 Bytes Hash, 8 Bytes Random num
*
* \param [in] datalen
* Length of the data to be advertised by Proxy.
* If the "type" is:
* 0x00 - Network ID - 8 Bytes of Network ID
* 0x01 - Node Identity - 8 Bytes Hash, 8 Bytes Random num
*
* \return API_SUCCESS or an error code indicating reason for failure
*/
API_RESULT MS_brr_start_proxy_adv
(
/* IN */ UCHAR type,
/* IN */ UCHAR * data,
/* IN */ UINT16 datalen
);
/**
* \brief API to disable broadcast of given beacon type
*
* \par Description
* This routine stops advertising of given beacon type.
*
* \param [in] bcon
* The Bearer Beacon (Unprovisioned/Secure Network).
*
* \param [in] type
* The type of braodcast beacon (Active/Passive).
*
* \return API_SUCCESS or an error code indicating reason for failure
*/
API_RESULT MS_brr_bcast_end
(
/* IN */ UCHAR bcon,
/* IN */ UCHAR type
);
/**
* \brief Send a bearer PDU
*
* \par Description
* This routine sends a PDU from the Mesh stack to over the bearer
* indicated by the bearer handle.
*
* \param [in] brr_handle
* Bearer handle on which PDU is to be sent.
*
* \param [in] brr_type
* Type of Bearer as in \ref BRR_TYPE.
*
* \param [in] buffer
* PDU data to be sent.
*
* \return API_SUCCESS or an error code indicating reason for failure
*
*/
API_RESULT MS_brr_send_pdu
(
/* IN */ BRR_HANDLE * brr_handle,
/* IN */ BRR_TYPE brr_type,
/* IN */ MS_BUFFER * buffer
);
/**
* \brief Get the RSSI of current received packet being processed.
*
* \par Description
* This routine returns the RSSI value of the received packet in its
* context when called from the Mesh stack.
*
* \return RSSI value of the current packet in context.
*
* \note This applies only when the packet is received over ADV bearer
*
*/
UCHAR MS_brr_get_packet_rssi(void);
/**
* \brief Put the bearer to sleep.
*
* \par Description
* This routine requests the underlying bearer interface to sleep.
* Default bearer interface is that of advertising bearer.
*
* \return API_SUCCESS
*
*/
API_RESULT MS_brr_sleep(void);
/**
* \brief Wakeup the bearer.
*
* \par Description
* This routine requests the underlying bearer interface to wakeup.
* Default bearer interface is that of advertising bearer.
*
* \param mode
* Identifies the mode (BRR_TX/BRR_RX) for which bearer is requested
* for wakeup.
*
* \return API_SUCCESS
*
*/
API_RESULT MS_brr_wakeup(UINT8 mode);
#ifdef __cplusplus
};
#endif
/** \} */
/** \} */
#endif /* _H_MS_BRR_API_ */