Nordic stack and drivers for the mbed BLE API
Fork of nRF51822 by
Embed:
(wiki syntax)
Show/hide line numbers
app_uart.h
Go to the documentation of this file.
00001 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved. 00002 * 00003 * The information contained herein is property of Nordic Semiconductor ASA. 00004 * Terms and conditions of usage are described in detail in NORDIC 00005 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. 00006 * 00007 * Licensees are granted free, non-transferable use of the information. NO 00008 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from 00009 * the file. 00010 * 00011 */ 00012 00013 /**@file 00014 * 00015 * @defgroup app_uart UART module 00016 * @{ 00017 * @ingroup app_common 00018 * 00019 * @brief UART module interface. 00020 */ 00021 00022 #ifndef APP_UART_H__ 00023 #define APP_UART_H__ 00024 00025 #include <stdint.h> 00026 #include <stdbool.h> 00027 #include "app_util_platform.h " 00028 00029 #define UART_PIN_DISCONNECTED 0xFFFFFFFF /**< Value indicating that no pin is connected to this UART register. */ 00030 00031 /**@brief UART Flow Control modes for the peripheral. 00032 */ 00033 typedef enum 00034 { 00035 APP_UART_FLOW_CONTROL_DISABLED, /**< UART Hw Flow Control is disabled. */ 00036 APP_UART_FLOW_CONTROL_ENABLED, /**< Standard UART Hw Flow Control is enabled. */ 00037 APP_UART_FLOW_CONTROL_LOW_POWER /**< Specialized UART Hw Flow Control is used. The Low Power setting allows the nRF51 to Power Off the UART module when CTS is in-active, and re-enabling the UART when the CTS signal becomes active. This allows the nRF51 to safe power by only using the UART module when it is needed by the remote site. */ 00038 } app_uart_flow_control_t; 00039 00040 /**@brief UART communication structure holding configuration settings for the peripheral. 00041 */ 00042 typedef struct 00043 { 00044 uint8_t rx_pin_no; /**< RX pin number. */ 00045 uint8_t tx_pin_no; /**< TX pin number. */ 00046 uint8_t rts_pin_no; /**< RTS pin number, only used if flow control is enabled. */ 00047 uint8_t cts_pin_no; /**< CTS pin number, only used if flow control is enabled. */ 00048 app_uart_flow_control_t flow_control; /**< Flow control setting, if flow control is used, the system will use low power UART mode, based on CTS signal. */ 00049 bool use_parity; /**< Even parity if TRUE, no parity if FALSE. */ 00050 uint32_t baud_rate; /**< Baud rate configuration. */ 00051 } app_uart_comm_params_t; 00052 00053 /**@brief UART buffer for transmitting/receiving data. 00054 */ 00055 typedef struct 00056 { 00057 uint8_t * rx_buf; /**< Pointer to the RX buffer. */ 00058 uint32_t rx_buf_size; /**< Size of the RX buffer. */ 00059 uint8_t * tx_buf; /**< Pointer to the TX buffer. */ 00060 uint32_t tx_buf_size; /**< Size of the TX buffer. */ 00061 } app_uart_buffers_t; 00062 00063 /**@brief Enumeration describing current state of the UART. 00064 * 00065 * @details The connection state can be fetched by the application using the function call 00066 * @ref app_uart_get_connection_state. 00067 * When hardware flow control is used 00068 * - APP_UART_CONNECTED: Communication is ongoing. 00069 * - APP_UART_DISCONNECTED: No communication is ongoing. 00070 * 00071 * When no hardware flow control is used 00072 * - APP_UART_CONNECTED: Always returned as bytes can always be received/transmitted. 00073 */ 00074 typedef enum 00075 { 00076 APP_UART_DISCONNECTED, /**< State indicating that the UART is disconnected and cannot receive or transmit bytes. */ 00077 APP_UART_CONNECTED /**< State indicating that the UART is connected and ready to receive or transmit bytes. If flow control is disabled, the state will always be connected. */ 00078 } app_uart_connection_state_t; 00079 00080 /**@brief Enumeration which defines events used by the UART module upon data reception or error. 00081 * 00082 * @details The event type is used to indicate the type of additional information in the event 00083 * @ref app_uart_evt_t. 00084 */ 00085 typedef enum 00086 { 00087 APP_UART_DATA_READY, /**< An event indicating that UART data has been received. The data is available in the FIFO and can be fetched using @ref app_uart_get. */ 00088 APP_UART_FIFO_ERROR, /**< An error in the FIFO module used by the app_uart module has occured. The FIFO error code is stored in app_uart_evt_t.data.error_code field. */ 00089 APP_UART_COMMUNICATION_ERROR, /**< An communication error has occured during reception. The error is stored in app_uart_evt_t.data.error_communication field. */ 00090 APP_UART_TX_EMPTY, /**< An event indicating that UART has completed transmission of all available data in the TX FIFO. */ 00091 APP_UART_DATA, /**< An event indicating that UART data has been received, and data is present in data field. This event is only used when no FIFO is configured. */ 00092 } app_uart_evt_type_t; 00093 00094 /**@brief Struct containing events from the UART module. 00095 * 00096 * @details The app_uart_evt_t is used to notify the application of asynchronous events when data 00097 * are received on the UART peripheral or in case an error occured during data reception. 00098 */ 00099 typedef struct 00100 { 00101 app_uart_evt_type_t evt_type; /**< Type of event. */ 00102 union 00103 { 00104 uint32_t error_communication; /**< Field used if evt_type is: APP_UART_COMMUNICATION_ERROR. This field contains the value in the ERRORSRC register for the UART peripheral. The UART_ERRORSRC_x defines from @ref nrf51_bitfields.h can be used to parse the error code. See also the nRF51 Series Reference Manual for specification. */ 00105 uint32_t error_code; /**< Field used if evt_type is: NRF_ERROR_x. Additional status/error code if the error event type is APP_UART_FIFO_ERROR. This error code refer to errors defined in nrf_error.h. */ 00106 uint8_t value; /**< Field used if evt_type is: NRF_ERROR_x. Additional status/error code if the error event type is APP_UART_FIFO_ERROR. This error code refer to errors defined in nrf_error.h. */ 00107 } data; 00108 } app_uart_evt_t; 00109 00110 /**@brief Function for handling app_uart event callback. 00111 * 00112 * @details Upon an event in the app_uart module this callback function will be called to notify 00113 * the applicatioon about the event. 00114 * 00115 * @param[in] p_app_uart_event Pointer to UART event. 00116 */ 00117 00118 00119 typedef void (* app_uart_event_handler_t) (app_uart_evt_t * p_app_uart_event); 00120 00121 /**@brief Macro for safe initialization of the UART module in a single user instance when using 00122 * a FIFO together with UART. 00123 * 00124 * @param[in] P_COMM_PARAMS Pointer to a UART communication structure: app_uart_comm_params_t 00125 * @param[in] RX_BUF_SIZE Size of desired RX buffer, must be a power of 2 or ZERO (No FIFO). 00126 * @param[in] TX_BUF_SIZE Size of desired TX buffer, must be a power of 2 or ZERO (No FIFO). 00127 * @param[in] EVENT_HANDLER Event handler function to be called when an event occurs in the 00128 * UART module. 00129 * @param[in] IRQ_PRIO IRQ priority, app_irq_priority_t, for the UART module irq handler. 00130 * @param[out] ERR_CODE The return value of the UART initialization function will be 00131 * written to this parameter. 00132 * 00133 * @note Since this macro allocates a buffer and registers the module as a GPIOTE user when flow 00134 * control is enabled, it must only be called once. 00135 */ 00136 #define APP_UART_FIFO_INIT(P_COMM_PARAMS, RX_BUF_SIZE, TX_BUF_SIZE, EVT_HANDLER, IRQ_PRIO, ERR_CODE) \ 00137 do \ 00138 { \ 00139 uint16_t APP_UART_UID = 0; \ 00140 app_uart_buffers_t buffers; \ 00141 static uint8_t rx_buf[RX_BUF_SIZE]; \ 00142 static uint8_t tx_buf[TX_BUF_SIZE]; \ 00143 \ 00144 buffers.rx_buf = rx_buf; \ 00145 buffers.rx_buf_size = sizeof (rx_buf); \ 00146 buffers.tx_buf = tx_buf; \ 00147 buffers.tx_buf_size = sizeof (tx_buf); \ 00148 ERR_CODE = app_uart_init(P_COMM_PARAMS, &buffers, EVT_HANDLER, IRQ_PRIO, &APP_UART_UID); \ 00149 } while (0) 00150 00151 /**@brief Macro for safe initialization of the UART module in a single user instance. 00152 * 00153 * @param[in] P_COMM_PARAMS Pointer to a UART communication structure: app_uart_comm_params_t 00154 * @param[in] EVENT_HANDLER Event handler function to be called when an event occurs in the 00155 * UART module. 00156 * @param[in] IRQ_PRIO IRQ priority, app_irq_priority_t, for the UART module irq handler. 00157 * @param[out] ERR_CODE The return value of the UART initialization function will be 00158 * written to this parameter. 00159 * 00160 * @note Since this macro allocates registers the module as a GPIOTE user when flow control is 00161 * enabled, it must only be called once. 00162 */ 00163 #define APP_UART_INIT(P_COMM_PARAMS, EVT_HANDLER, IRQ_PRIO, ERR_CODE) \ 00164 do \ 00165 { \ 00166 uint16_t APP_UART_UID = 0; \ 00167 ERR_CODE = app_uart_init(P_COMM_PARAMS, NULL, EVT_HANDLER, IRQ_PRIO, &APP_UART_UID); \ 00168 } while (0) 00169 00170 /**@brief Function for initializing the UART module. Use this initialization when several instances of the UART 00171 * module are needed. 00172 * 00173 * @details This initialization will return a UART user id for the caller. The UART user id must be 00174 * used upon re-initialization of the UART or closing of the module for the user. 00175 * If single instance usage is needed, the APP_UART_INIT() macro should be used instead. 00176 * 00177 * @note Normally single instance initialization should be done using the APP_UART_INIT() or 00178 * APP_UART_INIT_FIFO() macro depending on whether the FIFO should be used by the UART, as 00179 * that will allocate the buffers needed by the UART module (including aligning the buffer 00180 * correctly). 00181 00182 * @param[in] p_comm_params Pin and communication parameters. 00183 * @param[in] p_buffers RX and TX buffers, NULL is FIFO is not used. 00184 * @param[in] error_handler Function to be called in case of an error. 00185 * @param[in] app_irq_priority Interrupt priority level. 00186 * @param[in,out] p_uart_uid User id for the UART module. The p_uart_uid must be used if 00187 * re-initialization and/or closing of the UART module is needed. 00188 * If the value pointed to by p_uart_uid is zero, this is 00189 * considdered a first time initialization. Otherwise this is 00190 * considered a re-initialization for the user with id *p_uart_uid. 00191 * 00192 * @retval NRF_SUCCESS If successful initialization. 00193 * @retval NRF_ERROR_INVALID_LENGTH If a provided buffer is not a power of two. 00194 * @retval NRF_ERROR_NULL If one of the provided buffers is a NULL pointer. 00195 * 00196 * Those errors are propagated by the UART module to the caller upon registration when Hardware Flow 00197 * Control is enabled. When Hardware Flow Control is not used, those errors cannot occur. 00198 * @retval NRF_ERROR_INVALID_STATE The GPIOTE module is not in a valid state when registering 00199 * the UART module as a user. 00200 * @retval NRF_ERROR_INVALID_PARAM The UART module provides an invalid callback function when 00201 * registering the UART module as a user. 00202 * Or the value pointed to by *p_uart_uid is not a valid 00203 * GPIOTE number. 00204 * @retval NRF_ERROR_NO_MEM GPIOTE module has reached the maximum number of users. 00205 */ 00206 uint32_t app_uart_init(const app_uart_comm_params_t * p_comm_params, 00207 app_uart_buffers_t * p_buffers, 00208 app_uart_event_handler_t error_handler, 00209 app_irq_priority_t irq_priority, 00210 uint16_t * p_uart_uid); 00211 00212 /**@brief Function for getting a byte from the UART. 00213 * 00214 * @details This function will get the next byte from the RX buffer. If the RX buffer is empty 00215 * an error code will be returned and the app_uart module will generate an event upon 00216 * reception of the first byte which is added to the RX buffer. 00217 * 00218 * @param[out] p_byte Pointer to an address where next byte received on the UART will be copied. 00219 * 00220 * @retval NRF_SUCCESS If a byte has been received and pushed to the pointer provided. 00221 * @retval NRF_ERROR_NOT_FOUND If no byte is available in the RX buffer of the app_uart module. 00222 */ 00223 uint32_t app_uart_get(uint8_t * p_byte); 00224 00225 /**@brief Function for putting a byte on the UART. 00226 * 00227 * @details This call is non-blocking. 00228 * 00229 * @param[in] byte Byte to be transmitted on the UART. 00230 * 00231 * @retval NRF_SUCCESS If the byte was succesfully put on the TX buffer for transmission. 00232 * @retval NRF_ERROR_NO_MEM If no more space is available in the TX buffer. 00233 * NRF_ERROR_NO_MEM may occur if flow control is enabled and CTS signal 00234 * is high for a long period and the buffer fills up. 00235 */ 00236 uint32_t app_uart_put(uint8_t byte); 00237 00238 /**@brief Function for getting the current state of the UART. 00239 * 00240 * @details If flow control is disabled, the state is assumed to always be APP_UART_CONNECTED. 00241 * 00242 * When using flow control the state will be controlled by the CTS. If CTS is set active 00243 * by the remote side, or the app_uart module is in the process of transmitting a byte, 00244 * app_uart is in APP_UART_CONNECTED state. If CTS is set inactive by remote side app_uart 00245 * will not get into APP_UART_DISCONNECTED state until the last byte in the TXD register 00246 * is fully transmitted. 00247 * 00248 * Internal states in the state machine are mapped to the general connected/disconnected 00249 * states in the following ways: 00250 * 00251 * - UART_ON = CONNECTED 00252 * - UART_READY = CONNECTED 00253 * - UART_WAIT = CONNECTED 00254 * - UART_OFF = DISCONNECTED. 00255 * 00256 * @param[out] p_connection_state Current connection state of the UART. 00257 * 00258 * @retval NRF_SUCCESS The connection state was succesfully retrieved. 00259 */ 00260 uint32_t app_uart_get_connection_state(app_uart_connection_state_t * p_connection_state); 00261 00262 /**@brief Function for flushing the RX and TX buffers (Only valid if FIFO is used). 00263 * This function does nothing if FIFO is not used. 00264 * 00265 * @retval NRF_SUCCESS Flushing completed (Current implementation will always succeed). 00266 */ 00267 uint32_t app_uart_flush(void); 00268 00269 /**@brief Function for closing the UART module. 00270 * 00271 * @details This function will close any on-going UART transmissions and disable itself in the 00272 * GPTIO module. 00273 * 00274 * @param[in] app_uart_uid User id for the UART module. The app_uart_uid must be identical to the 00275 * UART id returned on initialization and which is currently in use. 00276 00277 * @retval NRF_SUCCESS If successfully closed. 00278 * @retval NRF_ERROR_INVALID_PARAM If an invalid user id is provided or the user id differs from 00279 * the current active user. 00280 */ 00281 uint32_t app_uart_close(uint16_t app_uart_id); 00282 00283 00284 #endif //APP_UART_H__ 00285 00286 /** @} */
Generated on Tue Jul 12 2022 19:04:38 by 1.7.2