mlmr.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file mlmr.h
5 *
6 * @brief Multi Link Multi Role Service API
7 *
8 *****************************************************************************************
9 * @attention
10 #####Copyright (c) 2019 GOODIX
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15 * Redistributions of source code must retain the above copyright
16 notice, this list of conditions and the following disclaimer.
17 * Redistributions in binary form must reproduce the above copyright
18 notice, this list of conditions and the following disclaimer in the
19 documentation and/or other materials provided with the distribution.
20 * Neither the name of GOODIX nor the names of its contributors may be used
21 to endorse or promote products derived from this software without
22 specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 POSSIBILITY OF SUCH DAMAGE.
35 *****************************************************************************************
36 */
37
38 /**
39 * @addtogroup BLE_SRV BLE Services
40 * @{
41 * @brief Definitions and prototypes for the BLE Service interface.
42 */
43
44 /**
45 * @defgroup BLE_SDK_MLMR Multi Link Multi Role Service (MLMR)
46 * @{
47 * @brief Definitions and prototypes for the MLMR interface.
48 *
49 * @details The Multi Link Multi Role Service is a customized GATT-based service with Tx, Rx and Flow Control
50 * characteristics. The application uses the service to send and receive data to and
51 * from the peer. The application data is sent to the peer as Handle Value Notification,
52 * and the data received from the peer is transmitted with GATT Write Command.
53 *
54 * After \ref mlmr_init_t variable is initialized , the application must call \ref mlmr_service_init()
55 * to add the Goodix Uart Service and Rx, Tx, Flow Control characteristics to the BLE Stack
56 * database. The application can send the data to the peer with \ref mlmr_tx_data_send() after
57 * \ref MLMR_EVT_TX_PORT_OPENED received. The application should copy the received data to its own buffer
58 * when handling \ref MLMR_EVT_RX_DATA_RECEIVED.
59 */
60
61 #ifndef __MLMR_H__
62 #define __MLMR_H__
63
64 #include "gr_includes.h"
65 #include "custom_config.h"
66
67 /**
68 * @defgroup MLMR_MACRO Defines
69 * @{
70 */
71 #define MLMR_CONNECTION_MAX 10 /**< Maximum number of Multi Link Multi Role Service connections. */
72 #define MLMR_MAX_DATA_LEN 247 /**< Maximum length of application data packet which is transmitted via MLMR. */
73 #define MLMR_FLOW_CTRL_LEN 1 /**< Maximum length of ble flow control data packet which is transmitted via MLMR. */
74 #define MLMR_SERVICE_UUID 0x1B, 0xD7, 0x90, 0xEC, 0xE8, 0xB9, 0x75, 0x80,\
75 0x0A, 0x46, 0x44, 0xD3, 0x01, 0x02, 0xED, 0xA6 /**< The UUID of Multi Link Multi Role Service for setting advertising data. */
76 /** @} */
77
78 /**
79 * @defgroup MLMR_ENUM Enumerations
80 * @{
81 */
82 /**@brief Multi Link Multi Role Service event types. */
83 typedef enum
84 {
85 MLMR_EVT_INVALID, /**< Invalid MLMR event. */
86 MLMR_EVT_RX_DATA_RECEIVED, /**< The data from the peer has been received. */
87 MLMR_EVT_TX_DATA_SENT, /**< The data from the application has been sent, and the service is ready to accept new data from the application. */
88 MLMR_EVT_TX_PORT_OPENED, /**< Tx port has been opened. */
89 MLMR_EVT_TX_PORT_CLOSED, /**< Tx port has been closed. */
90 MLMR_EVT_FLOW_CTRL_ENABLE, /**< MLMR flow control been enabled. */
91 MLMR_EVT_FLOW_CTRL_DISABLE, /**< MLMR flow control been disabled. */
92 MLMR_EVT_TX_FLOW_OFF, /**< Tx flow off control request. */
93 MLMR_EVT_TX_FLOW_ON, /**< Tx flow on control request. */
94 } mlmr_evt_type_t;
95
96 /**@brief Flow control state for MLMR service. */
97 enum mlmr_flow_ctrl_state
98 {
99 MLMR_FLOW_CTRL_STATE_OFF = 0, /**< Indicate that MLMR can not receive data from peer. */
100 MLMR_FLOW_CTRL_STATE_ON /**< Indicate that MLMR can receive data from peer. */
101 };
102 /**@brief Underlying type used for the MLMR flow control state. */
103 typedef uint8_t mlmr_flow_ctrl_state_t;
104 /** @} */
105
106 /**
107 * @defgroup MLMR_STRUCT Structures
108 * @{
109 */
110 /**@brief Multi Link Multi Role Service event. */
111 typedef struct
112 {
113 mlmr_evt_type_t evt_type; /**< The MLMR event. */
114 uint8_t conn_idx; /**< The index of the connection for the data transmission. */
115 uint8_t *p_data; /**< Pointer to the buffer within received data. */
116 uint16_t length; /**< Length of received data. */
117 } mlmr_evt_t;
118 /** @} */
119
120 /**
121 * @defgroup MLMR_TYPEDEF Typedefs
122 * @{
123 */
124 /**@brief Multi Link Multi Role Service event handler type. */
125 typedef void (*mlmr_evt_handler_t)(mlmr_evt_t *p_evt);
126 /** @} */
127
128 /**
129 * @addtogroup MLMR_STRUCT Structures
130 * @{
131 */
132 /**@brief Multi Link Multi Role Service init stucture. This contains all option and data needed for initialization of the service. */
133 typedef struct
134 {
135 mlmr_evt_handler_t evt_handler; /**< Multi Link Multi Role Service event handler which must be provided by the application to send and receive the data. */
136 } mlmr_init_t;
137 /** @} */
138
139 /**
140 * @defgroup MLMR_FUNCTION Functions
141 * @{
142 */
143 /**
144 *****************************************************************************************
145 * @brief Initialize a Multi Link Multi Role Service instance and add in the database.
146 *
147 * @param[in] p_mlmr_init: Pointer to Multi Link Multi Role Service initialization variables.
148 *
149 * @return Result of service initialization.
150 *****************************************************************************************
151 */
152 sdk_err_t mlmr_service_init(mlmr_init_t *p_mlmr_init);
153
154 /**
155 *****************************************************************************************
156 * @brief Send data to peer device.
157 *
158 * @param[in] conn_idx: Index of the connection.
159 * @param[in] p_data: Pointer to sent data.
160 * @param[in] length: Length of sent data.
161 *
162 * @return Result of sending data.
163 *****************************************************************************************
164 */
165 sdk_err_t mlmr_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length);
166
167 /**
168 *****************************************************************************************
169 * @brief Send MLMR Rx flow control state to peer device
170 *
171 * @param[in] conn_idx: Index of the connection.
172 * @param[in] flow_ctrl: MLMR Rx flow control state
173 *
174 * @return Result of sending MLMR Rx flow control state.
175 *****************************************************************************************
176 */
177 sdk_err_t mlmr_rx_flow_ctrl_set(uint8_t conn_idx, mlmr_flow_ctrl_state_t flow_ctrl);
178 /** @} */
179
180 #endif
181 /** @} */
182 /** @} */
mlmr_evt_t::p_data
uint8_t * p_data
Pointer to the buffer within received data.
Definition: mlmr.h:115
MLMR_EVT_TX_PORT_CLOSED
@ MLMR_EVT_TX_PORT_CLOSED
Tx port has been closed.
Definition: mlmr.h:89
MLMR_EVT_TX_FLOW_ON
@ MLMR_EVT_TX_FLOW_ON
Tx flow on control request.
Definition: mlmr.h:93
MLMR_EVT_TX_FLOW_OFF
@ MLMR_EVT_TX_FLOW_OFF
Tx flow off control request.
Definition: mlmr.h:92
mlmr_evt_t::evt_type
mlmr_evt_type_t evt_type
The MLMR event.
Definition: mlmr.h:113
MLMR_EVT_TX_DATA_SENT
@ MLMR_EVT_TX_DATA_SENT
The data from the application has been sent, and the service is ready to accept new data from the app...
Definition: mlmr.h:87
gr_includes.h
Include Files API.
mlmr_init_t
Multi Link Multi Role Service init stucture.
Definition: mlmr.h:134
mlmr_evt_t
Multi Link Multi Role Service event.
Definition: mlmr.h:112
MLMR_FLOW_CTRL_STATE_ON
@ MLMR_FLOW_CTRL_STATE_ON
Indicate that MLMR can receive data from peer.
Definition: mlmr.h:100
mlmr_flow_ctrl_state_t
uint8_t mlmr_flow_ctrl_state_t
Underlying type used for the MLMR flow control state.
Definition: mlmr.h:103
mlmr_rx_flow_ctrl_set
sdk_err_t mlmr_rx_flow_ctrl_set(uint8_t conn_idx, mlmr_flow_ctrl_state_t flow_ctrl)
Send MLMR Rx flow control state to peer device.
mlmr_evt_handler_t
void(* mlmr_evt_handler_t)(mlmr_evt_t *p_evt)
Multi Link Multi Role Service event handler type.
Definition: mlmr.h:125
mlmr_evt_type_t
mlmr_evt_type_t
Multi Link Multi Role Service event types.
Definition: mlmr.h:84
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:274
MLMR_EVT_INVALID
@ MLMR_EVT_INVALID
Invalid MLMR event.
Definition: mlmr.h:85
mlmr_flow_ctrl_state
mlmr_flow_ctrl_state
Flow control state for MLMR service.
Definition: mlmr.h:98
mlmr_service_init
sdk_err_t mlmr_service_init(mlmr_init_t *p_mlmr_init)
Initialize a Multi Link Multi Role Service instance and add in the database.
mlmr_init_t::evt_handler
mlmr_evt_handler_t evt_handler
Multi Link Multi Role Service event handler which must be provided by the application to send and rec...
Definition: mlmr.h:135
MLMR_EVT_FLOW_CTRL_ENABLE
@ MLMR_EVT_FLOW_CTRL_ENABLE
MLMR flow control been enabled.
Definition: mlmr.h:90
MLMR_FLOW_CTRL_STATE_OFF
@ MLMR_FLOW_CTRL_STATE_OFF
Indicate that MLMR can not receive data from peer.
Definition: mlmr.h:99
MLMR_EVT_RX_DATA_RECEIVED
@ MLMR_EVT_RX_DATA_RECEIVED
The data from the peer has been received.
Definition: mlmr.h:86
mlmr_tx_data_send
sdk_err_t mlmr_tx_data_send(uint8_t conn_idx, uint8_t *p_data, uint16_t length)
Send data to peer device.
mlmr_evt_t::length
uint16_t length
Length of received data.
Definition: mlmr.h:116
MLMR_EVT_FLOW_CTRL_DISABLE
@ MLMR_EVT_FLOW_CTRL_DISABLE
MLMR flow control been disabled.
Definition: mlmr.h:91
MLMR_EVT_TX_PORT_OPENED
@ MLMR_EVT_TX_PORT_OPENED
Tx port has been opened.
Definition: mlmr.h:88
mlmr_evt_t::conn_idx
uint8_t conn_idx
The index of the connection for the data transmission.
Definition: mlmr.h:114