Difference between revisions of "USB Gadget"

From ArmadeusWiki
Jump to: navigation, search
(→‎To emulate a serial port:)
(→‎Installation)
 
(54 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
Instructions to use the USB port of your Armadeus board to communicate with your PC
+
Instructions on how to use the USB device (or OTG) port of your Armadeus board to communicate with your PC; ie see your board from your PC like an USB device.
  
 
==Introduction==
 
==Introduction==
  
−
You can connect your Armadeus board to a PC using its USB port and it can be enumerated as many USB devices (depending on the type of communication way you want to use):
+
You can connect your APF board to your PC using its USB Device port ([[APF9328DevFull]]), a modified USB host port ([[APF27Dev]]), or an USB OTG port put in device mode ([[APF27 PPS]], [[APF51Dev]], [[APF28Dev]], [[APF6Dev]], [[OPOS6ULDev]]), and it can be "enumerated" as most common USB devices (depending on the type of communication you want to use):
−
* serial device
+
* serial device,
−
* net device
+
* net device,
−
* mass storage device
+
* mass storage device.
  
−
==Installation==
+
=== Hardware specifics for the APF27Dev ===
 +
At first, an USB A male / A male cable has to be used like this one: http://fr.farnell.com/pro-signal/psg90024/lead-usb-2-0-am-am-2m-black/dp/1494745
  
−
* configure your Linux kernel:
+
Do not use USB cable with integrated ferrite bead !!
−
[armadeus]$ make linux-menuconfig
+
−
in '''Device Drivers->USB support->USB Gadget Support''', choose '''Support for USB Gadgets''' and activate all USB Gadget Drivers:
+
  
−
[[Image:linux_config_usb_gadget.png]]
+
The APF27dev board is equipped with two USB host ports. '''Only the High Speed Host port (top connector)''' can be configured as an USB Device.
  
−
* save your configuration and then rebuild your kernel image:
+
{{Warning|DO NOT CONNECT TWO HOST PORTS TOGETHER AND TAKE CARE TO USE THE RIGHT USB PORT ON THE APF27DEV !!}}
−
[armadeus]$ make
+
−
now you should have following drivers in your kernel source tree:
+
−
'''drivers/usb/gadget/gadgetfs.ko'''        For test
+
−
'''drivers/usb/gadget/g_ether.ko'''        Ethernet emulation on USB
+
−
'''drivers/usb/gadget/g_file_storage.ko'''  Mass storage
+
−
'''drivers/usb/gadget/g_serial.ko'''        Serial emulation on USB
+
−
'''drivers/usb/gadget/g_zero.ko'''          For test
+
−
'''drivers/usb/gadget/imx_udc.ko'''        i.MXL USB device Core Controller
+
  
−
* reflash your RootFS or manually copy ''imx_udc.ko, g_file_storage.ko & g_serial.ko'' to your target in /lib/modules/...
+
=== Software specifics for the APF27Dev, APF27 PPS, APF51Dev ===
 +
In order to activate the device mode, a new parameter has to be added to the U-Boot console variable:
 +
<pre class="apf">
 +
BIOS> setenv extrabootargs otg_mode=device
 +
BIOS> saveenv
 +
BIOS> boot
 +
</pre>
  
−
==Usage==
+
Your port will now work as an USB device. "''device''" keyword might need to be replaced by "''peripheral''" on recent kernels.
  
−
First, load the core controller driver on your board:
+
==Installation==
−
# modprobe imx_udc
+
−
  usb: imx_udc version: 0.5
+
  
−
===To emulate a mass storage device:===
+
* The drivers are now installed by default (since armadeus-3.0)
−
* [[USB_Gadget#Links |create]] or get a "backing storage file" ([http://artemys25.free.fr/armadeus/binaires/backing_file.gz for example])
+
* you should have following modules in your kernel source tree:
−
* copy this file (uncompressed) in the '''/tmp''' directory of your rootfs (see NetworkConfig if necessary)
+
'''/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]gadgetfs.ko'''        For test
−
  # cp /mnt/nfs/backing_file.gz /tmp/
+
'''/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_ether.ko'''         Ethernet emulation on USB
−
  # gunzip /tmp/backing_file.gz
+
  '''/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_file_storage.ko'''  Mass storage
 +
'''/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_serial.ko'''        Serial emulation on USB
 +
  '''/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_zero.ko'''          For test
 +
* If not here is how to add the missing one: [[Talk:USB_Gadget]]
  
−
* load g_file_storage module:
+
==Usage==
 +
 
 +
===To emulate a mass storage device===
 +
* [[USB_Gadget#Links |create]] or get a "backing storage file" ([ftp://ftp2.armadeus.com/armadeusw/download/backing_file.gz for example])
 +
* copy this file (uncompressed) in the '''/tmp''' directory of your board (here my Host PC has 192.168.0.20 as IP @):
 +
<pre class="apf">
 +
# tftp -g -r backing_file.gz -l /tmp/backing_file.gz 192.168.0.20
 +
# gunzip /tmp/backing_file.gz
 +
</pre>
 +
* load ''g_file_storage'' or ''g_mass_storage'' module (depending on your Linux version):
 +
<pre class="apf">
 
  # modprobe g_file_storage file=/tmp/backing_file
 
  # modprobe g_file_storage file=/tmp/backing_file
 
  g_file_storage gadget: File-backed Storage Gadget, version: 28 November 2005
 
  g_file_storage gadget: File-backed Storage Gadget, version: 28 November 2005
 
  g_file_storage gadget: Number of LUNs=1
 
  g_file_storage gadget: Number of LUNs=1
 
  g_file_storage gadget-lun0: ro=0, file: /tmp/backing_file
 
  g_file_storage gadget-lun0: ro=0, file: /tmp/backing_file
 +
</pre>
 
* connect target's USB cable to your PC and,  
 
* connect target's USB cable to your PC and,  
 
On your Linux Host:
 
On your Linux Host:
−
* as root, launch ''dmesg'' and find the ''/dev/sdaX'' device assigned to your board:
+
* If you have a recent Linux distribution, your device should be automatically mounted. Otherwise:
 +
** as root, launch ''dmesg'' and find the ''/dev/sdaX'' device assigned to your board:
 
  ... usb 1-1.4: new full speed USB device using uhci_hcd and address 7
 
  ... usb 1-1.4: new full speed USB device using uhci_hcd and address 7
 
  ... usb 1-1.4: configuration #1 chosen from 1 choice
 
  ... usb 1-1.4: configuration #1 chosen from 1 choice
Line 60: Line 70:
 
  ...  sd 1:0:0:0: Attached scsi disk sda
 
  ...  sd 1:0:0:0: Attached scsi disk sda
 
  ...  sd 1:0:0:0: Attached scsi generic sg0 type 0
 
  ...  sd 1:0:0:0: Attached scsi generic sg0 type 0
 +
*
 +
** then mount the device and enjoy file sharing:
 +
<pre class="host">
 +
$ sudo mount /dev/sda1 /mnt/tmp
 +
$ cd /mnt/tmp
 +
$ showimage /mnt/tmp/test.jpg
 +
</pre>
  
−
* then mount the device and enjoy file sharing:
+
===To emulate a serial link===
−
[root@toto]# mount /dev/sda1 /mnt/tmp
+
* On your Host PC (if '''usbserial''' module is not already loaded):
−
[root@toto]# cd /mnt/tmp
+
<pre class="host">
−
[root@toto]# showimage /mnt/tmp/test.jpg
+
  $ sudo modprobe usbserial vendor=0x0525 product=0xA4A6
−
 
+
</pre>
−
===To emulate a serial port:===
+
or you can automate it by modifying ''/etc/modprobe.d/options'' file (Tested on *Ubuntu):
−
* On your Host PC (as root):
+
<pre class="host">
−
  # modprobe usbserial vendor=0x0525 product=0xA4A6
+
$ sudo vim /etc/modprobe.d/options
 +
  ...
 +
  options usbserial vendor=0x0525 product=0xA4A6
 +
</pre>
 
* on your APF:
 
* on your APF:
−
# mknod /dev/ttygserial c 127 0  (only needed the first time you want to use it, if not already existing)
+
<pre class="apf">
 
  # modprobe g_serial
 
  # modprobe g_serial
−
  gs_bind: Gadget Serial v2.2 bound
+
  g_serial gadget: Gadget Serial v2.4
−
  gs_module_init: Gadget Serial v2.2 loaded
+
  g_serial gadget: g_serial ready
 +
fsl-usb2-udc: bind to driver g_serial
 +
g_serial gadget: high speed config #2: CDC ACM config
 +
 
 +
# mknod /dev/ttyGS0 c 249 0  (if not created)
 +
</pre>
 
* then connect the USB cable between your PC and your APF and you should see on your Host:
 
* then connect the USB cable between your PC and your APF and you should see on your Host:
−
  # tail -f /var/log/messages
+
<pre class="host">
−
  Nov 27 22:53:50 ...  usb 1-1.4: new full speed USB device using uhci_hcd and address 7
+
  $ tail -f /var/log/messages
−
  Nov 27 22:53:50 ...  usb 1-1.4: configuration #1 chosen from 1 choice
+
  Sep 27 10:06:38 ...  usb 2-1.3: new high speed USB device using ehci_hcd and address 14
−
  Nov 27 22:53:50 ...  usbserial_generic 1-1.4:1.0: generic converter detected
+
  Sep 27 10:06:38 ...  usb 2-1.3: configuration #2 chosen from 1 choice
−
  Nov 27 22:53:50 ...  usb 1-1.4: generic converter now attached to ttyUSB0
+
  Sep 27 10:06:38 ...  cdc_acm 2-1.3:2.0: ttyACM0: USB ACM device
−
* you should now be able to send/receive data through ''/dev/ttyUSB0'' (PC) and ''/dev/ttygserial'' (APF):
+
  Sep 27 10:06:38 ...  usbcore: registered new interface driver cdc_acm
−
  [armadeus]$ echo "COUCOU" > /dev/ttyUSB0
+
Sep 27 10:06:38 ...  cdc_acm: v0.26:USB Abstract Control Model driver for USB modems and ISDN adapters
 +
</pre>
 +
* you should now be able to send/receive data through ''/dev/ttyACM0'' (PC) and ''/dev/ttyGS0'' (APF):
 +
<pre class="apf">
 +
# cat /dev/ttyGS0
 +
</pre>
 +
<pre class="host">
 +
  [armadeus]$ echo "COUCOU" > /dev/ttyACM0
 +
</pre>
 +
<pre class="apf">
 +
COUCOU
 +
</pre>
  
−
  # cat /dev/ttygserial
+
===To emulate an Ethernet link===
−
  COUCOUC
+
* On your Target:
 +
<pre class="apf">
 +
  # modprobe g_ether
 +
ether gadget: using random self ethernet address
 +
ether gadget: using random host ethernet address
 +
usb0: Ethernet Gadget, version: May Day 2005
 +
usb0: using imx_udc, OUT ep2out-bulk IN ep1in-bulk STATUS ep4in-int
 +
usb0: MAC be:df:31:95:16:e0
 +
usb0: HOST MAC 3e:86:1e:94:eb:84
 +
usb0: RNDIS ready
 +
</pre>
 +
* Then, an IP address has to be assigned to the freshly created ''usb0'' network interface:
 +
<pre class="apf">
 +
  # ifconfig usb0 192.168.10.1
 +
</pre>
  
−
==TBDL==
+
* On your Host:
 +
** On '''Linux''' systems: it should be auto-detected and a ''usb0'' interface created, otherwise:
 +
<pre class="host">
 +
$ sudo modprobe cdc_ether
 +
</pre>
 +
** On '''Windows''' systems: <br/>When the target is detected, you will be asked to give the right driver. <br/>You will find it here: [http://www.armadeus.com/_downloads/apf27_PPS/windrivers/ APF27 PPS Windrivers].
  
 +
* Then, set an IP address for Host ''usb0'' interface in the same network as the one you set for Target. It should then work as a standard IP network. You can also install a [[DHCP server]] on your Target.
  
 
==Links==
 
==Links==
−
 
 
* http://www.linux-usb.org/gadget/
 
* http://www.linux-usb.org/gadget/
 +
* http://www.linux-usb.org/usbtest/#gadgets
 
* http://www.linux-usb.org/gadget/file_storage.html
 
* http://www.linux-usb.org/gadget/file_storage.html
 +
* http://lxr.linux.no/source/Documentation/usb/gadget_serial.txt
 +
* [[Serial_Transfer]]
 +
* http://www.linux-usb.org/usbnet/
 +
* http://wiki.gp2x.org/wiki/UsbNet_on_Linux
 +
 +
[[Category:Linux drivers]]
 +
[[Category:USB]]

Latest revision as of 20:23, 31 March 2020

Instructions on how to use the USB device (or OTG) port of your Armadeus board to communicate with your PC; ie see your board from your PC like an USB device.

Introduction

You can connect your APF board to your PC using its USB Device port (APF9328DevFull), a modified USB host port (APF27Dev), or an USB OTG port put in device mode (APF27 PPS, APF51Dev, APF28Dev, APF6Dev, OPOS6ULDev), and it can be "enumerated" as most common USB devices (depending on the type of communication you want to use):

  • serial device,
  • net device,
  • mass storage device.

Hardware specifics for the APF27Dev

At first, an USB A male / A male cable has to be used like this one: http://fr.farnell.com/pro-signal/psg90024/lead-usb-2-0-am-am-2m-black/dp/1494745

Do not use USB cable with integrated ferrite bead !!

The APF27dev board is equipped with two USB host ports. Only the High Speed Host port (top connector) can be configured as an USB Device.

Warning Warning: DO NOT CONNECT TWO HOST PORTS TOGETHER AND TAKE CARE TO USE THE RIGHT USB PORT ON THE APF27DEV !!


Software specifics for the APF27Dev, APF27 PPS, APF51Dev

In order to activate the device mode, a new parameter has to be added to the U-Boot console variable: 

 BIOS> setenv extrabootargs otg_mode=device
 BIOS> saveenv
 BIOS> boot

Your port will now work as an USB device. "device" keyword might need to be replaced by "peripheral" on recent kernels.

Installation

  • The drivers are now installed by default (since armadeus-3.0)
  • you should have following modules in your kernel source tree:
/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]gadgetfs.ko        For test
/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_ether.ko         Ethernet emulation on USB
/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_file_storage.ko  Mass storage
/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_serial.ko        Serial emulation on USB
/lib/modules/`uname -r`/kernel/drivers/usb/gadget/[legacy/]g_zero.ko          For test

Usage

To emulate a mass storage device

  • create or get a "backing storage file" (for example)
  • copy this file (uncompressed) in the /tmp directory of your board (here my Host PC has 192.168.0.20 as IP @):
 # tftp -g -r backing_file.gz -l /tmp/backing_file.gz 192.168.0.20
 # gunzip /tmp/backing_file.gz
  • load g_file_storage or g_mass_storage module (depending on your Linux version):
 # modprobe g_file_storage file=/tmp/backing_file
 g_file_storage gadget: File-backed Storage Gadget, version: 28 November 2005
 g_file_storage gadget: Number of LUNs=1
 g_file_storage gadget-lun0: ro=0, file: /tmp/backing_file
  • connect target's USB cable to your PC and,

On your Linux Host:

  • If you have a recent Linux distribution, your device should be automatically mounted. Otherwise:
    • as root, launch dmesg and find the /dev/sdaX device assigned to your board:
... usb 1-1.4: new full speed USB device using uhci_hcd and address 7
... usb 1-1.4: configuration #1 chosen from 1 choice
... scsi1 : SCSI emulation for USB Mass Storage devices
...    Vendor: Linux     Model: File-Stor Gadget  Rev: 0314
...    Type:   Direct-Access                      ANSI SCSI revision: 02
...  SCSI device sda: 8192 512-byte hdwr sectors (4 MB)
...  sda: Write Protect is off
...  SCSI device sda: 8192 512-byte hdwr sectors (4 MB)
...  sda: Write Protect is off
...   sda: sda1
...  sd 1:0:0:0: Attached scsi disk sda
...  sd 1:0:0:0: Attached scsi generic sg0 type 0
    • then mount the device and enjoy file sharing:
 $ sudo mount /dev/sda1 /mnt/tmp
 $ cd /mnt/tmp
 $ showimage /mnt/tmp/test.jpg

To emulate a serial link

  • On your Host PC (if usbserial module is not already loaded):
 $ sudo modprobe usbserial vendor=0x0525 product=0xA4A6

or you can automate it by modifying /etc/modprobe.d/options file (Tested on *Ubuntu): 

 $ sudo vim /etc/modprobe.d/options
  ...
  options usbserial vendor=0x0525 product=0xA4A6
  • on your APF:
 # modprobe g_serial
 g_serial gadget: Gadget Serial v2.4
 g_serial gadget: g_serial ready
 fsl-usb2-udc: bind to driver g_serial
 g_serial gadget: high speed config #2: CDC ACM config

 # mknod /dev/ttyGS0 c 249 0   (if not created)
  • then connect the USB cable between your PC and your APF and you should see on your Host:
 $ tail -f /var/log/messages
 Sep 27 10:06:38 ...  usb 2-1.3: new high speed USB device using ehci_hcd and address 14
 Sep 27 10:06:38 ...  usb 2-1.3: configuration #2 chosen from 1 choice
 Sep 27 10:06:38 ...  cdc_acm 2-1.3:2.0: ttyACM0: USB ACM device
 Sep 27 10:06:38 ...  usbcore: registered new interface driver cdc_acm
 Sep 27 10:06:38 ...  cdc_acm: v0.26:USB Abstract Control Model driver for USB modems and ISDN adapters
  • you should now be able to send/receive data through /dev/ttyACM0 (PC) and /dev/ttyGS0 (APF):
 # cat /dev/ttyGS0

 [armadeus]$ echo "COUCOU" > /dev/ttyACM0

 COUCOU

To emulate an Ethernet link

  • On your Target:
 # modprobe g_ether
 ether gadget: using random self ethernet address
 ether gadget: using random host ethernet address
 usb0: Ethernet Gadget, version: May Day 2005
 usb0: using imx_udc, OUT ep2out-bulk IN ep1in-bulk STATUS ep4in-int
 usb0: MAC be:df:31:95:16:e0
 usb0: HOST MAC 3e:86:1e:94:eb:84
 usb0: RNDIS ready
  • Then, an IP address has to be assigned to the freshly created usb0 network interface:
 # ifconfig usb0 192.168.10.1
  • On your Host:
    • On Linux systems: it should be auto-detected and a usb0 interface created, otherwise:
$ sudo modprobe cdc_ether
    • On Windows systems:
      When the target is detected, you will be asked to give the right driver.
      You will find it here: APF27 PPS Windrivers.
  • Then, set an IP address for Host usb0 interface in the same network as the one you set for Target. It should then work as a standard IP network. You can also install a DHCP server on your Target.

Links

Retrieved from "http://armadeus.org/wiki/index.php?title=USB_Gadget&oldid=14882"