This application note explains how to configure the i.MX RT1170 as the composite USB Gadget providing the USB Ethernet and the Mass storage functions over the USB OTG High-Speed link.
In practical embedded applications, the Ethernet Gadget can be used for organizing TCP/IP-based communications with the i.MX RT1170 over the USB physical link. The Mass Storage Gadget can to used to share data on physical or virtual storage of the IMXRT1170 board to a PC, for example provide access to its SD card.
1. Configuration and Build
To enable USB Gadgets functionality in the rootfs project, do the following:
Activate the cross development environment:
$ . ./ACTIVATE.sh $ cd projects/rootfs
Select the appropriate USB Gadget in the Linux configuration menu (go to the Device Drivers -> USB support -> USB Gadget Support -> USB Gadget functions configurable through
configfsmenu, and select the RNDIS and Mass storage options):$ make kmenuconfig Build the project: $ make
Run the resultant
rootfs.uImageon the target.Configure the USB Gadgets in the Linux console on the target board:
Mount the
configfsFile System:/ # mount -t configfs configfs /sys/kernel/config/
Create new composite USB gadget:
/ # mkdir /sys/kernel/config/usb_gadget/g1
Add description for new device:
/ # cd /sys/kernel/config/usb_gadget/g1 /sys/kernel/config/usb_gadget/g1 # echo 0x525 > idVendor /sys/kernel/config/usb_gadget/g1 # echo 0xa4a7 > idProduct /sys/kernel/config/usb_gadget/g1 # mkdir strings/0x409 /sys/kernel/config/usb_gadget/g1 # echo 00001 > strings/0x409/serialnumber /sys/kernel/config/usb_gadget/g1 # echo user > strings/0x409/manufacturer /sys/kernel/config/usb_gadget/g1 # echo mygadget > strings/0x409/product
Create configuration for the composite device:
/sys/kernel/config/usb_gadget/g1 # mkdir configs/c.1 /sys/kernel/config/usb_gadget/g1 # mkdir configs/c.1/strings/0x409 /sys/kernel/config/usb_gadget/g1 # echo composite > configs/c.1/strings/0x409/configuration /sys/kernel/config/usb_gadget/g1 # echo 120 > configs/c.1/MaxPower
Define the mass storage function:
/sys/kernel/config/usb_gadget/g1 # mkdir functions/mass_storage.0 Mass Storage Function, version: 2009/09/11 LUN: removable file: (no medium)
Provide whole SD card to mass storage:
/sys/kernel/config/usb_gadget/g1 # echo /dev/mmcblk0 > functions/mass_storage.0/lun.0/file
Define the Ethernet Gadget (RNDIS) function:
/sys/kernel/config/usb_gadget/g1 # mkdir functions/rndis.usb0 using random self ethernet address using random host ethernet address
Link the Gadget functions to the composite device:
/sys/kernel/config/usb_gadget/g1 # ln -s functions/mass_storage.0/ configs/c.1/ /sys/kernel/config/usb_gadget/g1 # ln -s functions/rndis.usb0 configs/c.1
Enable the USB Gadget on either USB1 (
ci_hdrc.0) or USB2 (ci_hdrc.1) port:/sys/kernel/config/usb_gadget/g1 # echo ci_hdrc.1 > UDC
2. Connect to the Linux Host
The host PC will detect the i.MX RT1170 as 2 devices: RNDIS Ethernet and USB Mass Storage:
$ dmesg | tail [81641.785983] usb 3-3.1.2: new high-speed USB device number 20 using xhci_hcd [81641.888722] usb 3-3.1.2: New USB device found, idVendor=0525, idProduct=a4a7, bcdDevice= 5.15 [81641.888729] usb 3-3.1.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [81641.888731] usb 3-3.1.2: Product: mygadget [81641.888732] usb 3-3.1.2: Manufacturer: user [81641.888734] usb 3-3.1.2: SerialNumber: 00001 [81641.945525] usb-storage 3-3.1.2:1.0: USB Mass Storage device detected [81641.945761] scsi host10: usb-storage 3-3.1.2:1.0 [81641.949113] rndis_host 3-3.1.2:1.1 usb0: register 'rndis_host' at usb-0000:2f:00.3-3.1.2, RNDIS device, fe:bc:a0:60:1b:d5 [81641.954094] rndis_host 3-3.1.2:1.1 enxfebca0601bd5: renamed from usb0 [81642.958387] scsi 10:0:0:0: Direct-Access Linux File-Stor Gadget 0515 PQ: 0 ANSI: 2 [81642.958655] sd 10:0:0:0: Attached scsi generic sg9 type 0 [81642.958903] sd 10:0:0:0: Power-on or device reset occurred [81642.959298] sd 10:0:0:0: [sdi] 62521344 512-byte logical blocks: (32.0 GB/29.8 GiB) [81642.959546] sd 10:0:0:0: [sdi] Write Protect is off [81642.959549] sd 10:0:0:0: [sdi] Mode Sense: 0f 00 00 00 [81642.959807] sd 10:0:0:0: [sdi] Write cache: enabled, read cache: enabled, doesn't support DPO or FUA [81642.961618] sdi: sdi1 [81642.961847] sd 10:0:0:0: [sdi] Attached SCSI removable disk
3. Using the Ethernet Function of the Composite USB Gadget
Setup an IP address of the USB Ethernet interface on the USB Device (i.MX RT1170) side. Select an address that will not conflict with the other network sub nets in the system (if present):
/ # ifconfig usb0 192.168.2.2
Setup an IP address of the USB Ethernet interface on the USB host (PC) side (obviously, select the address from the same sub-net as the Gadget):
Linux host example:
$ sudo ifconfig enxfebca0601bd5 192.168.2.1
Check communication between i.MX RT1170 and the host over USB with
ping:on i.MX RT1170:
/ # ping 192.168.2.1 -c 3 PING 192.168.2.1 (192.168.2.1): 56 data bytes 64 bytes from 192.168.2.1: seq=0 ttl=64 time=0.798 ms 64 bytes from 192.168.2.1: seq=1 ttl=64 time=0.428 ms 64 bytes from 192.168.2.1: seq=2 ttl=64 time=0.389 ms --- 192.168.2.1 ping statistics --- 3 packets transmitted, 3 packets received, 0% packet loss round-trip min/avg/max = 0.389/0.538/0.798 ms / #
on PC:
$ ping 192.168.2.2 -c 3 PING 192.168.2.2 (192.168.2.2) 56(84) bytes of data. 64 bytes from 192.168.2.2: icmp_seq=1 ttl=64 time=0.339 ms 64 bytes from 192.168.2.2: icmp_seq=2 ttl=64 time=0.280 ms 64 bytes from 192.168.2.2: icmp_seq=3 ttl=64 time=0.292 ms --- 192.168.2.2 ping statistics --- 3 packets transmitted, 3 received, 0% packet loss, time 2030ms rtt min/avg/max/mdev = 0.280/0.303/0.339/0.025 ms
4. Using the Mass Storage Function of the Composite USB Gadget
On the Linux host check the Mass Storage Gadget is automatically mounted:
$ mount | grep "/dev/sd" dev/sdb1 on /media/sasha/987E-02F8 type vfat (rw,nosuid,nodev,relatime,uid=1001,gid=1001,fmask=0022,dmask=0022, codepage=437,iocharset=iso8859-1,shortname=mixed,showexec,utf8,flush, errors=remount-ro,uhelper=udisks2)
Verify that the mounted media contains the boot image:
$ ls /media/sasha/987E-02F8 rootfs.uImage 'System Volume Information'
5. Configuration USB Multifunction Composite Gadget via a Script
For convenience the usb_gadget.sh script is included into the rootfs project.
To configure USB Gadget as a mass storage device the following command can be used on the target board:
/ # usb_gadget.sh -m -p 0 Mass Storage Function, version: 2009/09/11 LUN: removable file: (no medium) USB Gadet config done / #
To configure USB Gadget as a network device the following command can be used on the target board:
/ # usb_gadget.sh -r -p 0 using random self ethernet address using random host ethernet address usb0: HOST MAC 5a:32:a9:e7:72:85 usb0: MAC 22:ff:72:5f:e5:64 USB Gadet config done / #
To configure USB Gadget as a mass storage and a network devices the following command can be used on the target board:
/ # usb_gadget.sh -m -r -p 0 Mass Storage Function, version: 2009/09/11 LUN: removable file: (no medium) using random self ethernet address using random host ethernet address usb0: HOST MAC 06:b2:3f:33:72:e8 usb0: MAC a6:b2:16:ae:fa:e1 USB Gadet config done / #
To deactivate configured USB composite gadget the following command can be used on the target board:
/ # usb_gadget.sh -d USB gadgets deactivated / #
Note: For configuring USB port 2 as USB gadget use the <-p 1> option.