How to make a USB gadget on Armbian Linux

Armbian USB gadget guide.md

This guide will include a step-by-step guide on how to set up an board running Armbian to act as a gadget device (similar to how it's been advertized with the Pi Zero)

Prerequisites

You will need a:

• Armbian supported board with an OTG port
• A temporary spare monitor, USB keyboard and display cable (or serial, if you'd like that instead)
• USB cable
• (depending on board) Seperate power cable

Flashing Armbian

The first step would be to download the apropriate Armbian image for your board and flash it to an SD card. In my case, I'll be using the mainline edition of the OrangePi One image.

Notes on cabling

While downloading/flashing, please check if your device is powered via the OTG port. Some devices are and some aren't:

For example, the Raspberry Pi Zero can be powered via the USB and the Orange Pi One can't.

Once you've figured that out, please plug in cables accordingly. PLUGGING IN A POWER CABLE WHILST HAVING POWER FROM THE OTG PORT COULD FRY THE BOARD/PORT, BE WARNED

My Pi Zero suffered this fate :(

Plug in the usual cables

For the serial people, you already know what to do; but for monitor users, plug in your display and USB keyboard into your board and start it up.

Initial Armbian setup

Once booted, do the inital setup. The password, user accounts and so on.

Type in reboot and once booted again login as root with the password you've set.

Enabling usbhost* devices

Now, once logged in type in:

armbin-config

You'll get a configuration screen and a complaint about no internet. Just ignore it and you'll see the Configuration Utility screen.

Within this screen, you'll select System > Hardware and enable the following (by pressing Space):

• usbhost0
• usbhost1
• usbhost2
• usbhost3

Once done, press Enter to apply changes. Use Escape to return back and exit out of the utility.

(We aren't done yet though)

Adding ethernet/serial drivers

With your favorite text editor open /boot/armbianEnv.txt

After the overlays line add:

extraargs=console=ttyGS0,115200 modules-load=dwc2,g_cdc (if you want a USB serial for debugging)

and

modules-load=dwc2,g_ether (without USB serial device)

Exit and save and reboot the board for these to apply.

(Recommended) Optionally hardcode the MAC addresses of the USB gadget device

If you choose to use either g_cdc or g_ether you might notice that on each reboot the MAC address changes and messes with your host systems' ability to properly save the connection settings for your Pi board. This can be fixed by just setting the MAC addresses yourself.

In the same extraargs in the /boot/armbianEnv.txt file you can add:

• For g_cdc: g_cdc.host_addr=00:22:82:ff:ff:00 g_cdc.dev_addr=00:22:82:ff:ff:01
• For g_ether: g_ether.host_addr=00:22:82:ff:ff:00 g_ether.dev_addr=00:22:82:ff:ff:01

In here host_addr referrs to the address seen on the computer which is the USB host (aka your PC) and dev_addr is the one seen from your Pi board.

How to connect the Pi to the net?

Once you've set those kernel parameters and have rebooted, you must set up network otherwise that USB gadget device isn't being used.

We must do this both on the Pi and the host machine.

Setting up a shared network on the host

Since your Pi or whatever will depend on the hosts network, make sure that the network that shows up on your PC is of "shared".

Do this first so that the Pi can actually connect to this.

On Windows, you do this by entering into Network device properties and enabling the shared network for that "network adapter".

On Linux (assuming you run NetworkManager, like most people do):

1. Open nmtui in your terminal.
2. Select Edit a connection and press enter to open it.
3. Tap the right arrow key to select the second column, and once you've selected Add, open it.
4. Select the type Ethernet
5. Name the network whatever you'd like, just make it so that you can immediatelly know what it is.
6. Change the IPv4 configuration to "Shared" and disable IPv6.
7. Expand the IPv4 configuration by highlighting "Show" and pressing enter.
8. Select and enable "Require IPv4 addressing for this connection"
9. Enable "Automatically connect" and "Available to all users"
10. Press Ok and connect to said network by going back one step (via the escape key) and going to "Activate a connection" then starting it.
11. Quit nmtui by pressing escape continously until you've exited the program.

How to connect your Pi to the network we just created

There's two sane ways I see this being supported:

• Either you really like systemd and having configuration files for everything
• Or you can set up NetworkManager for the sake of convenience and being in the 21. century in regards to network settings

I unfortunately won't go into legacy networking tools since I don't want to bother with them.

But before that, get onto your Pi by opening a serial link via putty or your preferred serial terminal software (the baud rate by default is 115200).

Once you get on your Pi, if you have set up serial over USB, you'll need to enable the login (getty) for it.

On your Pi, run the following.

systemctl enable --now getty@ttyGS0

You should have a login on your USB's serial connection now.

SystemD-NetworkD

NOTE: You'll lose the ability to use NetworkManager for Wi-Fi connections, so do this only if you don't want to use NetworkManager at all.

If you've decided that systemd is the way, the first step would be to disable NetworkManager since that is enabled by default:

systemctl disable --now NetworkManager

And since systemd-networkd relies on config files, you must create a config file.

Create a /etc/systemd/network/20-usb0.network with the following content:

[Match]
Name=usb0

[Network]
DHCP=yes

Now run

systemctl enable systemd-networkd

and reboot.

NetworkManager

1. Open the nmtui configuration utility.
2. Select 'Edit a connection' and press enter
3. Press the right key so you select the column on the right and enter once you highlight 'Add'
4. We want 'Ethernet' so choose that
5. Name the network however you like (fxp. "Shared host network")
6. In the device field we can set either the device name usb0 or set the MAC address that you hardcoded. This would be 00:22:82:ff:ff:01 if you followed this guide to the word.
7. Leave IPv4 and IPv6 as Automatic, enable Automatically connect and Available to all users.
8. Select Ok and press enter.
9. Press escape to go back one level.
10. Go into Activate a connection and turn on the network that you just created by highlighting it and pressing enter.
11. Once you're connected press escape until you're out of the program. Annnnd... done.

Recommended (but optional) Installing avahi for easier sshing

Since our host machine doesn't really know what device is connected to it, we can make the Pi share it's name with it.

This is done by enabling a service called "avahi" which takes care of implementing mDNS for us. This is a service which exchanges the device names for us.

First you'll need to access the commandline of the Pi.

Run the following to set everything up as it needs to be:

sudo apt update
sudo apt upgrade
sudo apt install avahi-daemon libnss-mdns libnss-mymachines
sudo systemctl enable --now ssh

Check your hostname (mine is orangepione) and log out.

Unplug everything that's not needed, leaving only the USB + (optionally) the power cable.

Finally

ssh yourpishostname.local on Linux

or just the hostname on Windows (like so: ssh yourpishostname).

Have fun.