How to use RNDIS

This guide explains the steps needed to get USB RNDIS working, using the STM32F4Discovery board as example.

If you don’t know RNDIS, it is a way to share Ethernet-like connection over USB port without using any external device to it. Just a USB cable between your board (that has USB Device) and your computer.

WARNING: RNDIS is going to be removed from Linux kernel because they understand it as an unsecure protocol. That said use it aware of this risk and also be aware that it was tested up to Ubuntu 22.04 LTS and couldn’t work in future versions.

Compiling

  1. Configure the RNDIS

    There is a sample configuration to use RNDIS on stm32f4discovery board. If your board doesn’t save a sample example then you need to create a configuration by yourself looking this config.

    Just use stm32f4discovery:rndis board profile for this purpose.

    $ cd nuttx
    $ ./tools/configure.sh stm32f4discovery:rndis
    
  2. Compile

    $ make -j
    

Flashing

  1. Flash the generated nuttx.bin to your board:

    $ $ sudo openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c init -c "reset halt" -c "flash write_image erase nuttx.bin 0x08000000"
    ...
    Open On-Chip Debugger 0.11.0
    ...
    Info : STLINK V2J14S0 (API v2) VID:PID 0483:3748
    Info : Target voltage: 3.203144
    Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints
    Info : starting gdb server for stm32f4x.cpu on 3333
    Info : Listening on port 3333 for gdb connections
    target halted due to debug-request, current mode: Thread
    xPSR: 0x01000000 pc: 0x08000188 msp: 0x20003f24
    Info : device id = 0x10036413
    Info : flash size = 1024 kbytes
    auto erase enabled
    wrote 262144 bytes from file nuttx.bin in 11.043253s (23.182 KiB/s)
    Info : Listening on port 6666 for tcl connections
    Info : Listening on port 4444 for telnet connections
    

Setup RNDIS in your computer

These steps show how to connect your board to your Linux machine.

Todo

Add Mac and Windows instructions

  1. Reset your board

  2. Plug a USB cable from the STM32F4Discovery’s microUSB to your computer

  3. Confirm that your board was detected as a USB RNDIS device:

    $ dmesg
    ...
    [ 1099.821480] usb 3-3: new full-speed USB device number 12 using xhci_hcd
    [ 1099.972379] usb 3-3: New USB device found, idVendor=584e, idProduct=5342, bcdDevice= 0.01
    [ 1099.972389] usb 3-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
    [ 1099.972393] usb 3-3: Product: RNDIS gadget
    [ 1099.972396] usb 3-3: Manufacturer: NuttX
    [ 1099.972398] usb 3-3: SerialNumber: 1234
    [ 1099.988952] usbcore: registered new interface driver cdc_ether
    [ 1099.990144] rndis_host 3-3:1.0: skipping garbage
    [ 1099.990641] rndis_host 3-3:1.0: dev can't take 1558 byte packets (max 660), adjusting MTU to 602
    [ 1099.992089] rndis_host 3-3:1.0 eth0: register 'rndis_host' at usb-0000:00:14.0-3, RNDIS device, a0:e0:de:ad:ca:fe
    [ 1099.992102] usbcore: registered new interface driver rndis_host
    [ 1099.994026] usbcore: registered new interface driver rndis_wlan
    [ 1099.997001] rndis_host 3-3:1.0 enxa0e0deadcafe: renamed from eth0
    
  4. Configure your Linux distro to share network to this USB RNDIS device:

    Click in the top right corner of your Ubuntu and go to:

    NuttX Ethernet -> Wired Settings

    Click in the ‘Gear icon’ and in the tab “IPv4” select: “Shared to other computers”

    Click on “Apply”

    Disconect and connect the USB cable to force it to get IP.

  5. Identify what IP address your board got:

    $ tail -f /var/log/syslog
    ...
    Jan 28 10:30:24 dev dnsmasq-dhcp[35526]: DHCPDISCOVER(enxa0e0deadcafe) 00:e0:de:ad:ca:fe
    Jan 28 10:30:24 dev dnsmasq-dhcp[35526]: DHCPOFFER(enxa0e0deadcafe) 10.42.0.86 00:e0:de:ad:ca:fe
    Jan 28 10:30:24 dev dnsmasq-dhcp[35526]: DHCPREQUEST(enxa0e0deadcafe) 10.42.0.86 00:e0:de:ad:ca:fe
    Jan 28 10:30:24 dev dnsmasq-dhcp[35526]: DHCPACK(enxa0e0deadcafe) 10.42.0.86 00:e0:de:ad:ca:fe nuttx
    Jan 28 10:30:29 dev systemd[1]: NetworkManager-dispatcher.service: Deactivated successfully.
    ^C
    
  6. Ping this IP to confirm it is working:

    $ ping 10.42.0.86
    PING 10.42.0.86 (10.42.0.86) 56(84) bytes of data.
    64 bytes from 10.42.0.86: icmp_seq=1 ttl=64 time=0.809 ms
    64 bytes from 10.42.0.86: icmp_seq=2 ttl=64 time=0.849 ms
    ^C
    --- 10.42.0.86 ping statistics ---
    2 packets transmitted, 2 received, 0% packet loss, time 1027ms
    rtt min/avg/max/mdev = 0.809/0.829/0.849/0.020 ms
    
  7. Connect to your board over telnet:

    $ telnet 10.42.0.86
    Trying 10.42.0.86...
    Connected to 10.42.0.86.
    Escape character is '^]'.
    
    NuttShell (NSH) NuttX-12.0.0
    nsh>