stm32l4xx_hal_uart_ex.c

00001 /**
00002   ******************************************************************************
00003   * @file    stm32l4xx_hal_uart_ex.c
00004   * @author  MCD Application Team
00005   * @version V1.5.1
00006   * @date    31-May-2016
00007   * @brief   Extended UART HAL module driver.
00008   *          This file provides firmware functions to manage the following extended
00009   *          functionalities of the Universal Asynchronous Receiver Transmitter Peripheral (UART).
00010   *           + Initialization and de-initialization functions
00011   *           + Peripheral Control functions
00012   *
00013   *
00014   @verbatim
00015   ==============================================================================
00016                ##### UART peripheral extended features  #####
00017   ==============================================================================
00018 
00019     (#) Declare a UART_HandleTypeDef handle structure.
00020 
00021     (#) For the UART RS485 Driver Enable mode, initialize the UART registers
00022         by calling the HAL_RS485Ex_Init() API.
00023 
00024 
00025   @endverbatim
00026   ******************************************************************************
00027   * @attention
00028   *
00029   * <h2><center>&copy; COPYRIGHT(c) 2016 STMicroelectronics</center></h2>
00030   *
00031   * Redistribution and use in source and binary forms, with or without modification,
00032   * are permitted provided that the following conditions are met:
00033   *   1. Redistributions of source code must retain the above copyright notice,
00034   *      this list of conditions and the following disclaimer.
00035   *   2. Redistributions in binary form must reproduce the above copyright notice,
00036   *      this list of conditions and the following disclaimer in the documentation
00037   *      and/or other materials provided with the distribution.
00038   *   3. Neither the name of STMicroelectronics nor the names of its contributors
00039   *      may be used to endorse or promote products derived from this software
00040   *      without specific prior written permission.
00041   *
00042   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00043   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00044   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00045   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00046   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00047   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00048   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00049   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00050   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00051   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00052   *
00053   ******************************************************************************
00054   */
00055 
00056 /* Includes ------------------------------------------------------------------*/
00057 #include "stm32l4xx_hal.h"
00058 
00059 /** @addtogroup STM32L4xx_HAL_Driver
00060   * @{
00061   */
00062 
00063 /** @defgroup UARTEx UARTEx
00064   * @brief UART Extended HAL module driver
00065   * @{
00066   */
00067 
00068 #ifdef HAL_UART_MODULE_ENABLED
00069 
00070 /* Private typedef -----------------------------------------------------------*/
00071 /* Private define ------------------------------------------------------------*/
00072 /* Private macros ------------------------------------------------------------*/
00073 /* Private variables ---------------------------------------------------------*/
00074 /* Private function prototypes -----------------------------------------------*/
00075 /** @defgroup UARTEx_Private_Functions UARTEx Private Functions
00076   * @{
00077   */
00078 static void UARTEx_Wakeup_AddressConfig(UART_HandleTypeDef *huart, UART_WakeUpTypeDef WakeUpSelection);
00079 /**
00080   * @}
00081   */
00082 
00083 /* Exported functions --------------------------------------------------------*/
00084 
00085 /** @defgroup UARTEx_Exported_Functions  UARTEx Exported Functions
00086   * @{
00087   */
00088 
00089 /** @defgroup UARTEx_Exported_Functions_Group1 Initialization and de-initialization functions
00090   * @brief    Extended Initialization and Configuration Functions
00091   *
00092 @verbatim
00093 ===============================================================================
00094             ##### Initialization and Configuration functions #####
00095  ===============================================================================
00096     [..]
00097     This subsection provides a set of functions allowing to initialize the USARTx or the UARTy
00098     in asynchronous mode.
00099       (+) For the asynchronous mode the parameters below can be configured:
00100         (++) Baud Rate
00101         (++) Word Length
00102         (++) Stop Bit
00103         (++) Parity: If the parity is enabled, then the MSB bit of the data written
00104              in the data register is transmitted but is changed by the parity bit.
00105         (++) Hardware flow control
00106         (++) Receiver/transmitter modes
00107         (++) Over Sampling Method
00108         (++) One-Bit Sampling Method
00109       (+) For the asynchronous mode, the following advanced features can be configured as well:
00110         (++) TX and/or RX pin level inversion
00111         (++) data logical level inversion
00112         (++) RX and TX pins swap
00113         (++) RX overrun detection disabling
00114         (++) DMA disabling on RX error
00115         (++) MSB first on communication line
00116         (++) auto Baud rate detection
00117     [..]
00118     The HAL_RS485Ex_Init() API follows the UART RS485 mode configuration
00119      procedures (details for the procedures are available in reference manual).
00120 
00121 @endverbatim
00122 
00123   Depending on the frame length defined by the M1 and M0 bits (7-bit, 
00124   8-bit or 9-bit), the possible UART formats are listed in the 
00125   following table.
00126   
00127     Table 1. UART frame format.
00128     +-----------------------------------------------------------------------+
00129     |  M1 bit |  M0 bit |  PCE bit  |             UART frame                |
00130     |---------|---------|-----------|---------------------------------------|
00131     |    0    |    0    |    0      |    | SB |    8 bit data   | STB |     |
00132     |---------|---------|-----------|---------------------------------------|
00133     |    0    |    0    |    1      |    | SB | 7 bit data | PB | STB |     |
00134     |---------|---------|-----------|---------------------------------------|
00135     |    0    |    1    |    0      |    | SB |    9 bit data   | STB |     |
00136     |---------|---------|-----------|---------------------------------------|
00137     |    0    |    1    |    1      |    | SB | 8 bit data | PB | STB |     |
00138     |---------|---------|-----------|---------------------------------------|
00139     |    1    |    0    |    0      |    | SB |    7 bit data   | STB |     |
00140     |---------|---------|-----------|---------------------------------------|
00141     |    1    |    0    |    1      |    | SB | 6 bit data | PB | STB |     |
00142     +-----------------------------------------------------------------------+
00143 
00144   * @{
00145   */
00146 
00147 /**
00148   * @brief Initialize the RS485 Driver enable feature according to the specified
00149   *         parameters in the UART_InitTypeDef and creates the associated handle.
00150   * @param huart: UART handle.
00151   * @param Polarity: select the driver enable polarity.
00152   *        This parameter can be one of the following values:
00153   *          @arg @ref UART_DE_POLARITY_HIGH DE signal is active high
00154   *          @arg @ref UART_DE_POLARITY_LOW  DE signal is active low
00155   * @param AssertionTime: Driver Enable assertion time:
00156   *                         5-bit value defining the time between the activation of the DE (Driver Enable)
00157   *                         signal and the beginning of the start bit. It is expressed in sample time
00158   *                         units (1/8 or 1/16 bit time, depending on the oversampling rate)
00159   * @param DeassertionTime: Driver Enable deassertion time:
00160   *                         5-bit value defining the time between the end of the last stop bit, in a
00161   *                         transmitted message, and the de-activation of the DE (Driver Enable) signal.
00162   *                         It is expressed in sample time units (1/8 or 1/16 bit time, depending on the
00163   *                         oversampling rate).
00164   * @retval HAL status
00165   */
00166 HAL_StatusTypeDef HAL_RS485Ex_Init(UART_HandleTypeDef *huart, uint32_t Polarity, uint32_t AssertionTime, uint32_t DeassertionTime)
00167 {
00168   uint32_t temp = 0x0;
00169 
00170   /* Check the UART handle allocation */
00171   if(huart == NULL)
00172   {
00173     return HAL_ERROR;
00174   }
00175   /* Check the Driver Enable UART instance */
00176   assert_param(IS_UART_DRIVER_ENABLE_INSTANCE(huart->Instance));
00177 
00178   /* Check the Driver Enable polarity */
00179   assert_param(IS_UART_DE_POLARITY(Polarity));
00180 
00181   /* Check the Driver Enable assertion time */
00182   assert_param(IS_UART_ASSERTIONTIME(AssertionTime));
00183 
00184   /* Check the Driver Enable deassertion time */
00185   assert_param(IS_UART_DEASSERTIONTIME(DeassertionTime));
00186 
00187   if(huart->gState == HAL_UART_STATE_RESET)
00188   {
00189     /* Allocate lock resource and initialize it */
00190     huart->Lock = HAL_UNLOCKED;
00191 
00192     /* Init the low level hardware : GPIO, CLOCK, CORTEX */
00193     HAL_UART_MspInit(huart);
00194   }
00195 
00196   huart->gState = HAL_UART_STATE_BUSY;
00197 
00198   /* Disable the Peripheral */
00199   __HAL_UART_DISABLE(huart);
00200 
00201   /* Set the UART Communication parameters */
00202   if (UART_SetConfig(huart) == HAL_ERROR)
00203   {
00204     return HAL_ERROR;
00205   }
00206 
00207   if(huart->AdvancedInit.AdvFeatureInit != UART_ADVFEATURE_NO_INIT)
00208   {
00209     UART_AdvFeatureConfig(huart);
00210   }
00211 
00212   /* Enable the Driver Enable mode by setting the DEM bit in the CR3 register */
00213   SET_BIT(huart->Instance->CR3, USART_CR3_DEM);
00214 
00215   /* Set the Driver Enable polarity */
00216   MODIFY_REG(huart->Instance->CR3, USART_CR3_DEP, Polarity);
00217 
00218   /* Set the Driver Enable assertion and deassertion times */
00219   temp = (AssertionTime << UART_CR1_DEAT_ADDRESS_LSB_POS);
00220   temp |= (DeassertionTime << UART_CR1_DEDT_ADDRESS_LSB_POS);
00221   MODIFY_REG(huart->Instance->CR1, (USART_CR1_DEDT|USART_CR1_DEAT), temp);
00222 
00223   /* Enable the Peripheral */
00224   __HAL_UART_ENABLE(huart);
00225 
00226   /* TEACK and/or REACK to check before moving huart->gState and huart->RxState to Ready */
00227   return (UART_CheckIdleState(huart));
00228 }
00229 
00230 
00231 /**
00232   * @}
00233   */
00234 
00235 /** @defgroup UARTEx_Exported_Functions_Group3 Peripheral Control functions
00236   * @brief    Extended Peripheral Control functions
00237  *
00238 @verbatim
00239  ===============================================================================
00240                       ##### Peripheral Control functions #####
00241  ===============================================================================
00242     [..] This section provides the following functions:
00243      (+) HAL_UARTEx_EnableClockStopMode() API enables the UART clock (HSI or LSE only) during stop mode
00244      (+) HAL_UARTEx_DisableClockStopMode() API disables the above functionality
00245      (+) HAL_MultiProcessorEx_AddressLength_Set() API optionally sets the UART node address
00246          detection length to more than 4 bits for multiprocessor address mark wake up.
00247      (+) HAL_UARTEx_StopModeWakeUpSourceConfig() API defines the wake-up from stop mode
00248          trigger: address match, Start Bit detection or RXNE bit status.
00249      (+) HAL_UARTEx_EnableStopMode() API enables the UART to wake up the MCU from stop mode
00250      (+) HAL_UARTEx_DisableStopMode() API disables the above functionality
00251      (+) HAL_UARTEx_WakeupCallback() called upon UART wakeup interrupt
00252 
00253 
00254 @endverbatim
00255   * @{
00256   */
00257 
00258 
00259 
00260 
00261 /**
00262   * @brief By default in multiprocessor mode, when the wake up method is set
00263   *        to address mark, the UART handles only 4-bit long addresses detection;
00264   *        this API allows to enable longer addresses detection (6-, 7- or 8-bit
00265   *        long).
00266   * @note  Addresses detection lengths are: 6-bit address detection in 7-bit data mode, 
00267   *        7-bit address detection in 8-bit data mode, 8-bit address detection in 9-bit data mode.
00268   * @param huart: UART handle.
00269   * @param AddressLength: this parameter can be one of the following values:
00270   *          @arg @ref UART_ADDRESS_DETECT_4B 4-bit long address
00271   *          @arg @ref UART_ADDRESS_DETECT_7B 6-, 7- or 8-bit long address
00272   * @retval HAL status
00273   */
00274 HAL_StatusTypeDef HAL_MultiProcessorEx_AddressLength_Set(UART_HandleTypeDef *huart, uint32_t AddressLength)
00275 {
00276   /* Check the UART handle allocation */
00277   if(huart == NULL)
00278   {
00279     return HAL_ERROR;
00280   }
00281 
00282   /* Check the address length parameter */
00283   assert_param(IS_UART_ADDRESSLENGTH_DETECT(AddressLength));
00284 
00285   huart->gState = HAL_UART_STATE_BUSY;
00286 
00287   /* Disable the Peripheral */
00288   __HAL_UART_DISABLE(huart);
00289 
00290   /* Set the address length */
00291   MODIFY_REG(huart->Instance->CR2, USART_CR2_ADDM7, AddressLength);
00292 
00293   /* Enable the Peripheral */
00294   __HAL_UART_ENABLE(huart);
00295 
00296   /* TEACK and/or REACK to check before moving huart->gState to Ready */
00297   return (UART_CheckIdleState(huart));
00298 }
00299 
00300 
00301 /**
00302   * @brief Set Wakeup from Stop mode interrupt flag selection.
00303   * @param huart: UART handle.
00304   * @param WakeUpSelection: address match, Start Bit detection or RXNE bit status.
00305   * This parameter can be one of the following values:
00306   *      @arg @ref UART_WAKEUP_ON_ADDRESS
00307   *      @arg @ref UART_WAKEUP_ON_STARTBIT
00308   *      @arg @ref UART_WAKEUP_ON_READDATA_NONEMPTY
00309   * @retval HAL status
00310   */
00311 HAL_StatusTypeDef HAL_UARTEx_StopModeWakeUpSourceConfig(UART_HandleTypeDef *huart, UART_WakeUpTypeDef WakeUpSelection)
00312 {
00313   HAL_StatusTypeDef status = HAL_OK;
00314   uint32_t tickstart = 0;
00315 
00316   /* check the wake-up from stop mode UART instance */
00317   assert_param(IS_UART_WAKEUP_FROMSTOP_INSTANCE(huart->Instance));
00318   /* check the wake-up selection parameter */
00319   assert_param(IS_UART_WAKEUP_SELECTION(WakeUpSelection.WakeUpEvent));
00320 
00321   /* Process Locked */
00322   __HAL_LOCK(huart);
00323 
00324   huart->gState = HAL_UART_STATE_BUSY;
00325 
00326   /* Disable the Peripheral */
00327   __HAL_UART_DISABLE(huart);
00328 
00329   /* Set the wake-up selection scheme */
00330   MODIFY_REG(huart->Instance->CR3, USART_CR3_WUS, WakeUpSelection.WakeUpEvent);
00331 
00332   if (WakeUpSelection.WakeUpEvent == UART_WAKEUP_ON_ADDRESS)
00333   {
00334     UARTEx_Wakeup_AddressConfig(huart, WakeUpSelection);
00335   }
00336 
00337   /* Enable the Peripheral */
00338   __HAL_UART_ENABLE(huart);
00339 
00340   /* Init tickstart for timeout managment*/
00341   tickstart = HAL_GetTick();
00342 
00343   /* Wait until REACK flag is set */
00344   if(UART_WaitOnFlagUntilTimeout(huart, USART_ISR_REACK, RESET, tickstart, HAL_UART_TIMEOUT_VALUE) != HAL_OK)
00345   {
00346     status = HAL_TIMEOUT;
00347   }
00348   else
00349   {
00350     /* Initialize the UART State */
00351     huart->gState = HAL_UART_STATE_READY;
00352   }
00353 
00354   /* Process Unlocked */
00355   __HAL_UNLOCK(huart);
00356 
00357   return status;
00358 }
00359 
00360 
00361 /**
00362   * @brief Enable UART Stop Mode.
00363   * @note  The UART is able to wake up the MCU from Stop 1 mode as long as UART clock is HSI or LSE.
00364   * @param huart: UART handle.
00365   * @retval HAL status
00366   */
00367 HAL_StatusTypeDef HAL_UARTEx_EnableStopMode(UART_HandleTypeDef *huart)
00368 {
00369   /* Process Locked */
00370   __HAL_LOCK(huart);
00371 
00372   huart->gState = HAL_UART_STATE_BUSY;
00373 
00374   /* Set UESM bit */
00375   SET_BIT(huart->Instance->CR1, USART_CR1_UESM);
00376 
00377   huart->gState = HAL_UART_STATE_READY;
00378 
00379   /* Process Unlocked */
00380   __HAL_UNLOCK(huart);
00381 
00382   return HAL_OK;
00383 }
00384 
00385 /**
00386   * @brief Disable UART Stop Mode.
00387   * @param huart: UART handle.
00388   * @retval HAL status
00389   */
00390 HAL_StatusTypeDef HAL_UARTEx_DisableStopMode(UART_HandleTypeDef *huart)
00391 {
00392   /* Process Locked */
00393   __HAL_LOCK(huart);
00394 
00395   huart->gState = HAL_UART_STATE_BUSY;
00396 
00397   /* Clear UESM bit */
00398   CLEAR_BIT(huart->Instance->CR1, USART_CR1_UESM);
00399 
00400   huart->gState = HAL_UART_STATE_READY;
00401 
00402   /* Process Unlocked */
00403   __HAL_UNLOCK(huart);
00404 
00405   return HAL_OK;
00406 }
00407 
00408 /**
00409   * @brief UART wakeup from Stop mode callback.
00410   * @param huart: UART handle.
00411   * @retval None
00412   */
00413 __weak void HAL_UARTEx_WakeupCallback(UART_HandleTypeDef *huart)
00414 {
00415   /* Prevent unused argument(s) compilation warning */
00416   UNUSED(huart);
00417 
00418   /* NOTE : This function should not be modified, when the callback is needed,
00419             the HAL_UARTEx_WakeupCallback can be implemented in the user file.
00420    */
00421 }
00422 
00423 /**
00424   * @}
00425   */
00426 
00427 /**
00428   * @}
00429   */
00430 
00431 /** @addtogroup UARTEx_Private_Functions
00432   * @{
00433   */
00434 
00435 /**
00436   * @brief Initialize the UART wake-up from stop mode parameters when triggered by address detection.
00437   * @param huart: UART handle.
00438   * @param WakeUpSelection: UART wake up from stop mode parameters.
00439   * @retval None
00440   */
00441 static void UARTEx_Wakeup_AddressConfig(UART_HandleTypeDef *huart, UART_WakeUpTypeDef WakeUpSelection)
00442 {
00443   assert_param(IS_UART_ADDRESSLENGTH_DETECT(WakeUpSelection.AddressLength));
00444 
00445   /* Set the USART address length */
00446   MODIFY_REG(huart->Instance->CR2, USART_CR2_ADDM7, WakeUpSelection.AddressLength);
00447 
00448   /* Set the USART address node */
00449   MODIFY_REG(huart->Instance->CR2, USART_CR2_ADD, ((uint32_t)WakeUpSelection.Address << UART_CR2_ADDRESS_LSB_POS));
00450 }
00451 
00452 /**
00453   * @}
00454   */
00455 
00456 #endif /* HAL_UART_MODULE_ENABLED */
00457 
00458 /**
00459   * @}
00460   */
00461 
00462 /**
00463   * @}
00464   */
00465 
00466 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/