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