USB Component  Version 6.16.1
MDK Middleware for USB Device and Host Communication
Ethernet-over-USB (for Linux hosts)

The Ethernet-over-USB example connects a computer via USB to a Cortex-M system that provides an Ethernet interface for network connectivity. The Linux Kernel provides native support for the CDC (NCM) USB Device class. This example shows how to connect a Ubuntu system via USB to an MCBSTM32F400 development board.

The following picture shows an exemplary connection of the development board (in this case a MCBSTM32F400) to a host PC.

Create the "Ethernet-over-USB" 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:

  • CMSIS:Core
  • CMSIS:RTOS2 (API):Keil RTX5
  • CMSIS Driver:Ethernet MAC (API):Ethernet MAC
  • CMSIS Driver:Ethernet PHY (API):KSZ8081RNA
  • CMSIS Driver:USB Device (API):High-speed
  • Device:STM32Cube Framework (API):Classic
  • USB:Device: 1
  • USB:Device:CDC: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_CDC_NCM_ETH_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 CDC NCM Ethernet Bridge template.
  • Click Add to copy the file USBD_User_CDC_NCM_ETH_0.c to the project.

Your Project should look like this:

Ethernet-over-USB 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"
    
    // 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) {
    
      (void)arg;
    
      USBD_Initialize    (0);               /* USB Device 0 Initialization        */
      USBD_Connect       (0);               /* USB Device 0 Connect               */
    
      while (1) {
        osThreadFlagsWait (0, osFlagsWaitAny, osWaitForever);
      }
    }
    

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

  • Under Device, double-click RTE_Device.h and:
    • enable ETH (Ethernet Interface) [Driver_ETH_MAC0] and:
      • disable ENET:MII (Media Independent Interface)
      • enable ENET:RMII (Reduced Media Independent Interface) and:
        • set ETH_RMII_TXD0 Pin to PG13
        • set ETH_RMII_TXD1 Pin to PG14
        • set ETH_RMII_TX_EN Pin to PG11
    • enable USB OTG High-speed and under it:
      • enable Device [Driver_USBD1]
  • Under USB, double-click USBD_Config_0.c and under USB Device 0 change:
    • set Connect to hardware via Driver_USBD# to 1
    • enable High-speed
    • under Device Settings change:
      • set Max Endpoint 0 Packet Size to 64
      • set Product ID to 0x3518
  • Under USB, double-click USBD_Config_CDC_0.h and under USB Device: Communication Device Class (CDC) 0 change:
    • set Communication Class Subclass to Network Control Model (NCM)

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 "Ethernet-over-USB" Project

Hardware Setup

  • Verify all jumper settings on the target hardware.
  • Connect the development board to a host Linux PC (native or in a virtual machine) attaching a Micro-USB cable to the USBHS port and using an Ethernet cable to the ETH connector.
  • Using a virtual machine, you need to connect to the VM:
Attach USB Device to Virtual Machine
  • Within the Linux system (here Ubuntu), you should be able to see a wired Ethernet connection (with the MAC address 1E:30:6C:A2:45:5E):
Wired Ethernet Connection using the USB CDC NCM Device
Note
Set the MAC address in the USB CDC configuration file USBD_Config_CDC_0.h.

Troubleshooting

Especially when working with virtual machines, the USB connection is not passed onto the guest system properly. Then it can help to restart the guest. Also, to make Ubuntu use the network adapter that you like, do the following: In Ubuntu's search, enter "network". The Network Connections program will be available in the search results:

Double-click to open and then mark the Wired connection 1 and click Edit:

Select the MAC address of your Ethernet-over-USB device and press Save and Close:

This should instruct Ubuntu to use your device for the network connection. Also, try to disconnect any other network adapter from the virtual machine.