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>