kmpm / rpi-usb-gadget Goto Github PK

View Code? Open in Web Editor NEW

103.0 7.0 27.0 46 KB

Script to set up a Raspberry PI 4 as a USB gadget.

Shell 100.00%

rpi4 rpi usb-gadget

rpi-usb-gadget's Introduction

rpi-usb-gadget

Script for setting up a Raspberry PI 4 as USB gadget.

I can not take full credit for this since I am standing on the shoulders of giants.

Usage

wget https://raw.githubusercontent.com/kmpm/rpi-usb-gadget/master/rpi4-usb.sh
bash rpi4-usb.sh

If you answer no to any of the questions the script will exit but should be safe to restart. You will be asked to choose between ECM or RNDIS type of network. RNDIS works better if your host is Windows and ECM might be better on Linux/Mac.

If the script doesn't run successfully you might have a broken partial configuration.

FAQ

Q: Can we use RPi4 as USB gadget without providing it power separately?

A: Yes... but. The Raspberry PI 4 can draw up to 3A and that is quite alot. Some USB ports only deliver 100-500 mA and you might not be able to even boot but it I have used it on several normal PCs fine, although with lighter loads. Otherwise you will need to power it separately through the GPIO pins (you can even use the official Raspberry Pi PoE HAT for that).

Q: Does it work with RPi5?

A: Haven't tried it yet and I haven't got any external reports this far. There is no real reason that it shouldn't though.

Warning / License

This script will modify '/boot/[firmware/]config.txt', '/boot/[firmware/]cmdline.txt' and other files. Warning, It might brick your device!

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

rpi-usb-gadget's People

Contributors

Stargazers

Watchers

rpi-usb-gadget's Issues

No reaction on USB in Windows Host

Applying the script on a fresh raspbian image from today (02-05-2023), doesn't work. Means after connecting the Raspberry Pi 4 B to the host usb, and booting up, there's no reaction on the host-usb when observing either by device manager nor the usb-tree-view application.

I checked that all entries were made.
I checked lsmod that the driver is loaded.
I checked that the ip-address is shown in the usb0 device when using command "ifconfig".
I checked that the system services are properly executed.

Sourcing power from the computer?

Let me ask a straightforward easy question.

Can we use RPi4 as USB gadget without providing it power separately?

I.e. I wish to use RPi4 as USB gadget, but I don't have power sockets around. If I plug it into my computer as USB OTG, can it function as an USB gadget? Like a mass storage?

Thank you

Not working on Raspberry Pi 4

I recently used your script on a Raspberry Pi 4 so I can use the Pi with my iPad Pro.

The Script executed without any issue, but I don't see the interface. Neither on my mac, nor on my iPad. I already tried different cables. When I execute ifconfig on the pi I can see the usb0 interface.

Are there any debugging possibilities or known issues?

Network device type selection not working

Steps to reproduce

Run rpi4-usb.sh script
Inputting 2 at the end to configure ECM network device type

Expected behavior

Inputting 2 when selecting network device type should configure "net-ecm".

Actual behavior

Inputting 2 configures "net-rndis".

Proposed solution

Correcting rpi4-usb.sh line 253 DEVICeTYPE to DEVICETYPE. I made a pull request #3 to fix this. Testing locally on my machine reproduced issue and after fix "net-ecm" can be configured correctly.

P.S: Thanks for building this script, really helps alot especially as this is my first time playing around with Raspberry Pi :)

Ubuntu 22.04 support

On Rpi4, ubuntu 22.04_64bit_server

bash
 curl -O https://raw.githubusercontent.com/ahmadsum1/rpi-usb-gadget/master/rpi4-usb.sh
bash rpi4-usb.sh
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 10311  100 10311    0     0  21782      0 --:--:-- --:--:-- --:--:-- 21845
This script will modify '/boot/firmware/config.txt', '/boot/firmware/cmdline.txt' and other files.
Warning, It might brick your device!

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Continue with modifications?
Are you sure? [y/N] y
Do you want to use a DHCP server for the USB network?
This will install dnsmasq and configure it for the USB network
Are you sure? [y/N] y

Enter the base IP address for the USB network
Only the first 3 groups
Example 10.55.0
Enter the base IP address: 10.55.0
[sudo] password for skb:

Add the line modules-load=dwc2,g_ether to /boot/firmware/cmdline.txt
Are you sure? [y/N] y

Add the line 'libcomposite' to '/etc/modules'
Are you sure? [y/N] y
libcomposite
grep: /etc/dhcpcd.conf: No such file or directory

Add the line 'denyinterfaces usb0' to '/etc/dhcpcd.conf'
Are you sure? [y/N] y
denyinterfaces usb0

Install dnsmasq
Are you sure? [y/N] y
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  dns-root-data dnsmasq-base
Suggested packages:
  resolvconf
The following NEW packages will be installed:
  dns-root-data dnsmasq dnsmasq-base
0 upgraded, 3 newly installed, 0 to remove and 2 not upgraded.
Need to get 388 kB of archives.
After this operation, 988 kB of additional disk space will be used.
Do you want to continue? [Y/n] y
Get:1 http://ports.ubuntu.com/ubuntu-ports jammy-updates/main arm64 dns-root-data all 2023112702~ubuntu0.22.04.1 [5,136 B]
Get:2 http://ports.ubuntu.com/ubuntu-ports jammy-updates/main arm64 dnsmasq-base arm64 2.90-0ubuntu0.22.04.1 [363 kB]
Get:3 http://ports.ubuntu.com/ubuntu-ports jammy-updates/universe arm64 dnsmasq all 2.90-0ubuntu0.22.04.1 [19.7 kB]
Fetched 388 kB in 0s (777 kB/s)
Selecting previously unselected package dns-root-data.
(Reading database ... 209666 files and directories currently installed.)
Preparing to unpack .../dns-root-data_2023112702~ubuntu0.22.04.1_all.deb ...
Unpacking dns-root-data (2023112702~ubuntu0.22.04.1) ...
Selecting previously unselected package dnsmasq-base.
Preparing to unpack .../dnsmasq-base_2.90-0ubuntu0.22.04.1_arm64.deb ...
Unpacking dnsmasq-base (2.90-0ubuntu0.22.04.1) ...
Selecting previously unselected package dnsmasq.
Preparing to unpack .../dnsmasq_2.90-0ubuntu0.22.04.1_all.deb ...
Unpacking dnsmasq (2.90-0ubuntu0.22.04.1) ...
Setting up dnsmasq-base (2.90-0ubuntu0.22.04.1) ...
Setting up dns-root-data (2023112702~ubuntu0.22.04.1) ...
Setting up dnsmasq (2.90-0ubuntu0.22.04.1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/dnsmasq.service → /lib/systemd/system/dnsmasq.service.
Job for dnsmasq.service failed because the control process exited with error code.
See "systemctl status dnsmasq.service" and "journalctl -xeu dnsmasq.service" for details.
invoke-rc.d: initscript dnsmasq, action "start" failed.
× dnsmasq.service - dnsmasq - A lightweight DHCP and caching DNS server
     Loaded: loaded (/lib/systemd/system/dnsmasq.service; enabled; vendor preset: enabled)
     Active: failed (Result: exit-code) since Sat 2024-07-20 05:05:41 CEST; 42ms ago
    Process: 1536 ExecStartPre=/etc/init.d/dnsmasq checkconfig (code=exited, status=0/SUCCESS)
    Process: 1544 ExecStart=/etc/init.d/dnsmasq systemd-exec (code=exited, status=2)
        CPU: 102ms

Jul 20 05:05:41 raspberrypi systemd[1]: Starting dnsmasq - A lightweight DHCP and caching DNS server...
Jul 20 05:05:41 raspberrypi dnsmasq[1544]: dnsmasq: failed to create listening socket for port 53: Add
ress already in use
Jul 20 05:05:41 raspberrypi dnsmasq[1544]: failed to create listening socket for port 53: Address alre
ady in use
Jul 20 05:05:41 raspberrypi dnsmasq[1544]: FAILED to start up
Jul 20 05:05:41 raspberrypi systemd[1]: dnsmasq.service: Control process exited, code=exited, status=2
/INVALIDARGUMENT
Jul 20 05:05:41 raspberrypi systemd[1]: dnsmasq.service: Failed with result 'exit-code'.
Jul 20 05:05:41 raspberrypi systemd[1]: Failed to start dnsmasq - A lightweight DHCP and caching DNS s
erver.
Processing triggers for man-db (2.10.2-1) ...
Processing triggers for dbus (1.12.20-2ubuntu4.1) ...
Scanning processes...
Scanning processor microcode...
Scanning linux images...

Running kernel seems to be up-to-date.

Failed to check for processor microcode upgrades.

No services need to be restarted.

No containers need to be restarted.

No user sessions are running outdated binaries.

No VM guests are running outdated hypervisor (qemu) binaries on this host.
Created /etc/dnsmasq.d/usb-gadget
configure static ip '10.55.0.1' for interface usb0
tee: /etc/network/interfaces.d/usb0: No such file or directory
Created /etc/network/interfaces.d/usb0
Created /usr/local/sbin/usb-gadget.sh


Select network device type
1) RNDIS Network device type (best with windows)
2) ECM Network device type
Pick an option: 1

You selected 'net-rndis' which will be configured in
the systemd unit file for usb-gadget.

Created /lib/systemd/system/usb-gadget.service
Created symlink /etc/systemd/system/sysinit.target.wants/usb-gadget.service → /lib/systemd/system/usb-gadget.service.


Done setting up as USB gadget
You must reboot for changes to take effect

If you chose to use dnsmasq, then
you can reach the device on 10.55.0.1 when connected by USB.
If not then your host must assign an IP address to the usb0 interface.


If you want to disable the usb0/gadget interface then
please run 'sudo systemctl disable usb-gadget'
and reboot.

Missing line in usb0 interface settings

On RPi4 model B and a fresh raspios (2024-03-15-raspios-bookworm-arm64-lite.img.xz), after running the script ('y' on all prompts, default IP and choosing '2) ECM Network device type') and restarting, I get the following error:

$ systemctl status networking.service 
× networking.service - Raise network interfaces
     Loaded: loaded (/lib/systemd/system/networking.service; enabled; preset: enabled)
     Active: failed (Result: exit-code) since Tue 2024-05-21 16:22:14 CEST; 2min 48s ago
       Docs: man:interfaces(5)
    Process: 499 ExecStart=/sbin/ifup -a --read-environment (code=exited, status=1/FAILURE)
    Process: 601 ExecStopPost=/usr/bin/touch /run/network/restart-hotplug (code=exited, status=0/SUCCESS)
   Main PID: 499 (code=exited, status=1/FAILURE)
        CPU: 131ms

May 21 16:22:14 raspberrypi systemd[1]: Starting networking.service - Raise network interfaces...
May 21 16:22:14 raspberrypi ifup[499]: ifup: /etc/network/interfaces.d/usb0:3: misplaced option
May 21 16:22:14 raspberrypi ifup[499]: ifup: unknown interface usb0
May 21 16:22:14 raspberrypi systemd[1]: networking.service: Main process exited, code=exited, status=1/FAILURE
May 21 16:22:14 raspberrypi systemd[1]: networking.service: Failed with result 'exit-code'.
May 21 16:22:14 raspberrypi systemd[1]: Failed to start networking.service - Raise network interfaces.

The reason is an invalid generated interface config for usb0:

$ cat /etc/network/interfaces.d/usb0
auto usb0
allow-hotplug usb0
  address 10.55.0.1
  netmask 255.255.255.248

It misses a line that says the interface should use a static IP address. After adding it, and a power cycle, the USB connection started working.

$ cat /etc/network/interfaces.d/usb0
auto usb0
allow-hotplug usb0
iface usb0 inet static
  address 10.55.0.1
  netmask 255.255.255.248

The interface config seems to be generated here:

rpi-usb-gadget/rpi4-usb.sh

Line 188 in 596892f

address $BASE_IP.1

Adding the missing line should fix that.

Also "otg_mode=1" may need to be disabled in config.txt. (I did that during debugging and did not verify if it's necessary, and perhaps that relates only to the compute module 4 so it's not relevant)

/boot/config.txt is now moved to /boot/firmware/config/txt

One command executed adds the line "dtoverlay=dwc2" to /boot/config.txt. however, as of recent updates, the conifg file needed to be changed is moved to the directory /boot/firmware/config.txt. adding "dtoverlay=dwc2" to this config file enables the pi to work as a usbc gadget after running this script.

Don't use fixed MAS addresses

Lines 150 and 151 use fixed values for the host and device MAC addresses. This will cause a conflict if two Pi configured by this script are connected to the same USB host.

It would be better to derive MAC addresses from the Pi's serial number and to use the locally administered range as explained here: https://github.com/thagrol/Guides