USB Component  Version 6.16.0
MDK Middleware for USB Device and Host Communication
USB Mouse

The USB Mouse example application shows how to control the mouse pointer of a host PC with a microcontroller device using USB Device HID.

The following picture shows an exemplary connection of the development board (in this case a MCBSTM32F400) to a host PC. Using the joystick on the development board you can move the mouse pointer on the screen. Pressing the joystick down will issue a left-click action.

Create the "USB Mouse" Project

In this example, we are using the MCBSTM32F400 board with the STM32F407IGHx device. Create a new project in MDK (Select Device STMicroelectronics:STM32F4 Series: STM32F407:STM32F407IG:STM32F407IGHx). In the Manage Run-Time Environment window, select the following components:

  • Board Support:Joystick (API):Joystick (Variant MCBSTM32F400)
  • CMSIS:Core
  • CMSIS:RTOS2 (API):Keil RTX5
  • CMSIS Driver:USB Device (API):Full-speed
  • Device:STM32Cube Framework (API):Classic
  • USB:Device: 1
  • USB:Device:HID:1

Click the Resolve button and then OK.

Before continuing to add the required source code, you need to add a template file called USBD_User_HID_Mouse_0.c:

  • Right-click on Source Group 1 and select Add New Item to Group 'Source Group 1'....
  • Click on User Code Template and select the USB Device HID Mouse template.
  • Click Add to copy the file USBD_User_HID_Mouse_0.c to the project.

Your Project should look like this:

USB Mouse Project Structure

Source Files

  • Click on New (Ctrl + N) to create a new file.
  • Save it (File -> Save) as main.h.
  • Copy the following code into the main.h file and save it again:
    /**
      ******************************************************************************
      * @file    Templates/Inc/main.h 
      * @author  MCD Application Team
      * @brief   Header for main.c module
      ******************************************************************************
      * @attention
      *
      * <h2><center>&copy; COPYRIGHT(c) 2017-2018 STMicroelectronics</center></h2>
      *
      * Redistribution and use in source and binary forms, with or without modification,
      * are permitted provided that the following conditions are met:
      *   1. Redistributions of source code must retain the above copyright notice,
      *      this list of conditions and the following disclaimer.
      *   2. Redistributions in binary form must reproduce the above copyright notice,
      *      this list of conditions and the following disclaimer in the documentation
      *      and/or other materials provided with the distribution.
      *   3. Neither the name of STMicroelectronics nor the names of its contributors
      *      may be used to endorse or promote products derived from this software
      *      without specific prior written permission.
      *
      * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
      * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
      * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
      * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
      * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
      * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
      * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
      * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
      *
      ******************************************************************************
      */
      
    /* Define to prevent recursive inclusion -------------------------------------*/
    #ifndef __MAIN_H
    #define __MAIN_H
    
    /* Includes ------------------------------------------------------------------*/
    #include "stm32f4xx_hal.h"
    #include "cmsis_os2.h"                  // ::CMSIS:RTOS2
    
    /* Exported types ------------------------------------------------------------*/
    /* Exported constants --------------------------------------------------------*/
    extern uint64_t app_main_stk[];
    extern const osThreadAttr_t app_main_attr;
    
    /* Exported macro ------------------------------------------------------------*/
    
    
    /* Exported functions ------------------------------------------------------- */
    extern void app_main (void *arg);
    
    #endif /* __MAIN_H */
    
    /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/ 
    
  • Right-click on Source Group 1 and select Add New Item to Group 'Source Group 1'....
  • Click on C File (.c) and enter main in the Name box.
  • Copy the following code into the main.c file:
    /**
      ******************************************************************************
      * @file    Templates/Src/main.c 
      * @author  MCD Application Team
      * @brief   Main program body
      *
      * @note    modified by ARM
      *          The modifications allow to use this file as User Code Template
      *          within the Device Family Pack.
      ******************************************************************************
      * @attention
      *
      * <h2><center>&copy; COPYRIGHT(c) 2017-2018 STMicroelectronics</center></h2>
      *
      * Redistribution and use in source and binary forms, with or without modification,
      * are permitted provided that the following conditions are met:
      *   1. Redistributions of source code must retain the above copyright notice,
      *      this list of conditions and the following disclaimer.
      *   2. Redistributions in binary form must reproduce the above copyright notice,
      *      this list of conditions and the following disclaimer in the documentation
      *      and/or other materials provided with the distribution.
      *   3. Neither the name of STMicroelectronics nor the names of its contributors
      *      may be used to endorse or promote products derived from this software
      *      without specific prior written permission.
      *
      * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
      * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
      * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
      * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
      * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
      * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
      * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
      * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
      *
      ******************************************************************************
      */
    
    /* Includes ------------------------------------------------------------------*/
    #include "main.h"
    
    #ifdef _RTE_
    #include "RTE_Components.h"             // Component selection
    #endif
    #ifdef RTE_CMSIS_RTOS2                  // when RTE component CMSIS RTOS2 is used
    #include "cmsis_os2.h"                  // ::CMSIS:RTOS2
    #endif
    
    #ifdef RTE_CMSIS_RTOS2_RTX5
    /**
      * Override default HAL_GetTick function
      */
    uint32_t HAL_GetTick (void) {
      static uint32_t ticks = 0U;
             uint32_t i;
    
      if (osKernelGetState () == osKernelRunning) {
        return ((uint32_t)osKernelGetTickCount ());
      }
    
      /* If Kernel is not running wait approximately 1 ms then increment 
         and return auxiliary tick counter value */
      for (i = (SystemCoreClock >> 14U); i > 0U; i--) {
        __NOP(); __NOP(); __NOP(); __NOP(); __NOP(); __NOP();
        __NOP(); __NOP(); __NOP(); __NOP(); __NOP(); __NOP();
      }
      return ++ticks;
    }
    #endif
    
    /** @addtogroup STM32F4xx_HAL_Examples
      * @{
      */
    
    /** @addtogroup Templates
      * @{
      */
    
    /* Private typedef -----------------------------------------------------------*/
    /* Private define ------------------------------------------------------------*/
    /* Private macro -------------------------------------------------------------*/
    /* Private variables ---------------------------------------------------------*/
    /* Private function prototypes -----------------------------------------------*/
    static void SystemClock_Config(void);
    static void Error_Handler(void);
    
    /* Private functions ---------------------------------------------------------*/
    /**
      * @brief  Main program
      * @param  None
      * @retval None
      */
    int main(void)
    {
    
      /* STM32F4xx HAL library initialization:
           - Configure the Flash prefetch, Flash preread and Buffer caches
           - Systick timer is configured by default as source of time base, but user 
                 can eventually implement his proper time base source (a general purpose 
                 timer for example or other time source), keeping in mind that Time base 
                 duration should be kept 1ms since PPP_TIMEOUT_VALUEs are defined and 
                 handled in milliseconds basis.
           - Low Level Initialization
         */
      HAL_Init();
    
      /* Configure the system clock to 168 MHz */
      SystemClock_Config();
      SystemCoreClockUpdate();
    
    
      /* Add your application code here
         */
    
    #ifdef RTE_CMSIS_RTOS2
      /* Initialize CMSIS-RTOS2 */
      osKernelInitialize ();
    
      /* Create application main thread */
      osThreadNew(app_main, NULL, &app_main_attr);
    
      /* Start thread execution */
      osKernelStart();
    #endif
    
      /* Infinite loop */
      while (1)
      {
      }
    }
    
    /**
      * @brief  System Clock Configuration
      *         The system Clock is configured as follow : 
      *            System Clock source            = PLL (HSE)
      *            SYSCLK(Hz)                     = 168000000
      *            HCLK(Hz)                       = 168000000
      *            AHB Prescaler                  = 1
      *            APB1 Prescaler                 = 4
      *            APB2 Prescaler                 = 2
      *            HSE Frequency(Hz)              = 8000000
      *            PLL_M                          = 25
      *            PLL_N                          = 336
      *            PLL_P                          = 2
      *            PLL_Q                          = 7
      *            VDD(V)                         = 3.3
      *            Main regulator output voltage  = Scale1 mode
      *            Flash Latency(WS)              = 5
      * @param  None
      * @retval None
      */
    static void SystemClock_Config(void)
    {
      RCC_ClkInitTypeDef RCC_ClkInitStruct;
      RCC_OscInitTypeDef RCC_OscInitStruct;
      
      /* Enable Power Control clock */
      __HAL_RCC_PWR_CLK_ENABLE();
      
      /* The voltage scaling allows optimizing the power consumption when the device is 
         clocked below the maximum system frequency, to update the voltage scaling value 
         regarding system frequency refer to product datasheet.  */
      __HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE1);
    
      /* Enable HSE Oscillator and activate PLL with HSE as source */
      RCC_OscInitStruct.OscillatorType = RCC_OSCILLATORTYPE_HSE;
      RCC_OscInitStruct.HSEState = RCC_HSE_ON;
      RCC_OscInitStruct.PLL.PLLState = RCC_PLL_ON;
      RCC_OscInitStruct.PLL.PLLSource = RCC_PLLSOURCE_HSE;
      RCC_OscInitStruct.PLL.PLLM = 25;
      RCC_OscInitStruct.PLL.PLLN = 336;
      RCC_OscInitStruct.PLL.PLLP = RCC_PLLP_DIV2;
      RCC_OscInitStruct.PLL.PLLQ = 7;
      if(HAL_RCC_OscConfig(&RCC_OscInitStruct) != HAL_OK)
      {
        /* Initialization Error */
        Error_Handler();
      }
      
      /* Select PLL as system clock source and configure the HCLK, PCLK1 and PCLK2 
         clocks dividers */
      RCC_ClkInitStruct.ClockType = (RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK | RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2);
      RCC_ClkInitStruct.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
      RCC_ClkInitStruct.AHBCLKDivider = RCC_SYSCLK_DIV1;
      RCC_ClkInitStruct.APB1CLKDivider = RCC_HCLK_DIV4;  
      RCC_ClkInitStruct.APB2CLKDivider = RCC_HCLK_DIV2;  
      if(HAL_RCC_ClockConfig(&RCC_ClkInitStruct, FLASH_LATENCY_5) != HAL_OK)
      {
        /* Initialization Error */
        Error_Handler();
      }
    
      /* STM32F405x/407x/415x/417x Revision Z devices: prefetch is supported  */
      if (HAL_GetREVID() == 0x1001)
      {
        /* Enable the Flash prefetch */
        __HAL_FLASH_PREFETCH_BUFFER_ENABLE();
      }
    }
    /**
      * @brief  This function is executed in case of error occurrence.
      * @param  None
      * @retval None
      */
    static void Error_Handler(void)
    {
      /* User may add here some code to deal with this error */
      while(1)
      {
      }
    }
    
    #ifdef  USE_FULL_ASSERT
    
    /**
      * @brief  Reports the name of the source file and the source line number
      *         where the assert_param error has occurred.
      * @param  file: pointer to the source file name
      * @param  line: assert_param error line source number
      * @retval None
      */
    void assert_failed(uint8_t* file, uint32_t line)
    { 
      /* User can add his own implementation to report the file name and line number,
         ex: printf("Wrong parameters value: file %s on line %d\r\n", file, line) */
    
      /* Infinite loop */
      while (1)
      {
      }
    }
    #endif
    
    /**
      * @}
      */ 
    
    /**
      * @}
      */ 
    
    /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/
    
  • Right-click on Source Group 1 and select Add New Item to Group 'Source Group 1'....
  • Click on C File (.c) and enter app_main in the Name box.
  • Copy the following code into the app_main.c file:
    #include "main.h"
    #include "rl_usb.h"
    
    #include "Board_Joystick.h"
    
    // Main stack size must be multiple of 8 Bytes
    #define APP_MAIN_STK_SZ (1024U)
    uint64_t app_main_stk[APP_MAIN_STK_SZ / 8];
    const osThreadAttr_t app_main_attr = {
      .stack_mem  = &app_main_stk[0],
      .stack_size = sizeof(app_main_stk)
    };
    
    /*------------------------------------------------------------------------------
     *        Application
     *----------------------------------------------------------------------------*/
    __NO_RETURN void app_main (void *arg) {
      uint32_t state, state_ex = 0;
      uint8_t  mouse_in_report[4];
      bool     update;
    
      (void)arg;
    
      Joystick_Initialize();
    
      USBD_Initialize    (0);               /* USB Device 0 Initialization        */
      USBD_Connect       (0);               /* USB Device 0 Connect               */
    
      while (1) {
        state  = Joystick_GetState();
        update = 0;
        mouse_in_report[0] = 0;
        mouse_in_report[1] = 0;
        mouse_in_report[2] = 0;
        mouse_in_report[3] = 0;
     
        if ((state ^ state_ex) & JOYSTICK_CENTER) {
          mouse_in_report[0] = (state & JOYSTICK_CENTER) ? 1 : 0;   /* Left Click */
          update   = 1;
          state_ex = state;
        }
        if (state & JOYSTICK_LEFT  ) { mouse_in_report[1] = (uint8_t)(-4); update = 1; } /* X Left  */
        if (state & JOYSTICK_RIGHT ) { mouse_in_report[1] =            4 ; update = 1; } /* X Right */
        if (state & JOYSTICK_UP    ) { mouse_in_report[2] = (uint8_t)(-4); update = 1; } /* Y Up    */
        if (state & JOYSTICK_DOWN  ) { mouse_in_report[2] =            4 ; update = 1; } /* Y Down  */
     
        if (update) {
          USBD_HID_GetReportTrigger(0, 0, mouse_in_report, 4);
        }
      }
    }
    

Before building the project, you need to edit these configuration files (in Configuration Wizard view):

  • Under Device, double-click RTE_Device.h and:
    • enable I2C1 (Inter-integrated Circuit Interface 1) [Driver_I2C1] (for the Joystick connected to I2C1) and:
      • set I2C1_SCL Pin to PB8
      • set I2C1_SDA Pin to PB9
    • enable USB OTG Full-speed and under it:
      • enable Device [Driver_USBD0]
  • Under USB, double-click USBD_Config_0.c and under USB Device 0:Device Settings change:
    • set Product ID to 0x3502
  • Under USB, double-click USBD_Config_HID_0.h and under USB Device: Human Interface Device class (HID) 0:Human Interface Device Class Settings change:
    • set Maximum Input Report Size (in bytes) to 4 as this is the size of report that is sent for a mouse position change and button presses from the main function
    • enable Use User Provided HID Report Descriptor and:
      • set User Provided HID Report Descriptor Size (in bytes) to 52

Before building and downloading the project to the target, make sure that the correct debugger is set in the Options for Target dialog (ALT + F7). You may then build and download the example project to the evaluation board using the ┬ÁVision commands:

  • Project --> Build target (F7)
  • Flash   --> Download (F8)
  • Debug --> Start/Stop Debug Session (Ctrl + F5)
  • Debug --> Run (F5)

After these steps, the project should start executing on your evaluation kit. In case of errors, refer to the Evaluation Board User's Guide for configuration information.

Using the "USB Mouse" Project

Hardware Setup

  • Verify all jumper settings on the target hardware.
  • Connect the development board to a host PC attaching a Micro-USB cable to the USBFS port. Observe how it is recognized as a USB HID device with the mouse protocol:
  • Play around with the joystick and see how the mouse moves on the screen.