diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst index 6b4c332e3c..f61a227e78 100644 --- a/Documentation/guides/index.rst +++ b/Documentation/guides/index.rst @@ -8,6 +8,7 @@ Guides nfs.rst usbtrace.rst simulator.rst + rndis.rst drivers.rst tasktrace.rst cpp_cmake.rst diff --git a/Documentation/guides/rndis.rst b/Documentation/guides/rndis.rst new file mode 100644 index 0000000000..9d2fd4b4d0 --- /dev/null +++ b/Documentation/guides/rndis.rst @@ -0,0 +1,146 @@ +.. include:: /substitutions.rst +.. _rndis: + +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 +--------- + +#. 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. + + .. code-block:: console + + $ cd nuttx + $ ./tools/configure.sh stm32f4discovery:rndis + +#. Compile + + .. code-block:: console + + $ make -j + +Flashing +-------- + +#. Flash the generated nuttx.bin to your board: + + .. code-block:: console + + $ $ 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 + +#. Reset your board + +#. Plug a USB cable from the STM32F4Discovery's microUSB to your computer + +#. Confirm that your board was detected as a USB RNDIS device: + + .. code-block:: console + + $ 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 + +#. 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. + +#. Identify what IP address your board got: + + .. code-block:: console + + $ 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 + +#. Ping this IP to confirm it is working: + + .. code-block:: console + + $ 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 + +#. Connect to your board over telnet: + + .. code-block:: console + + $ 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>