Improve OpenWRT default image config for Raspberry Pi Zero (also useful for other Pi variants)

Feature Requests
1

There is this key concept of x86 images that makes setting up x86 OpenWRT devices very easy and user-friendly:
The first user friendly key design part of x86 images is that the ~15 typical network PCI card kernel modules are all already included into default images.

The second user-friendly design part of x86 images is that OpenWRT would initialize x86 devices in a certain way on first boot:

  1. it would identify all available network interfaces on the first boot and auto-assign the LAN interface to the first found port
  2. if more network ports are found, WAN interface would automatically be assigned to the second found port
  3. x86 would automatically add any additional network ports to the device list, but not default-assign further ports to the LAN interface bridge.

This behaviour ensures that you have a minimum viable x86 system being able to easily bootstrap and admin-connect and that is able to load more optional packages within seconds after booting and with no tedious manual preparation effort.

Now in contrast, I recently tried OpenWRT on both Raspberry 4 and Raspberry Zero and I really miss a similar concept for Raspberry devices: Both device types suffer a lot from the fact that typical kernel modules for USB network adapters seem not included into the OpenWRT default images. The missing device init prep step then prevents further preinitializing the network config as known from x86 systems.

Especially to get a Raspberry Zero (which has no vendor-built-in network card) into a working network device state, where you can both connect as admin to LuCi and are then able to download and add additional packages, feels difficult on a borderline level. Also though Raspberry Zero W has built-in Wifi 2.4, this Wifi module cannot work as client and AP station at the same time due to limitations of Broadcom, so you cannot even use Wifi workarounds, to simplify the manual network bootstrapping comfig work.

A x86 typically has sufficient RAM and disk space, so aiming at space-preserving 4MB images on x86 was never made any key priority so far.
Now even a small Rasperry Zero has generous 512MB RAM and all Raspberries use an SD card, which can provide beyond 2 digit GBytes storage, so wasting disk space does not seem like a problem either on Raspberry.

So my feature request question would be:
The current OpenWRT Raspberry image state feels difficult, time consuming and not at all fun to use.
Couldn‘t e.g. the x86 OpenWRT PCI network card concept and init behavior be simply reused for initializing USB-based network adapters on Raspberry-like devices? Shouldn‘t that be part of default images?
(or did I maybe miss to understand important design decisions of OpenWRT images for Raspberry-like devices?

2

What about creating a PR adding the commonly necessary modules to the list (and move the discussion about it there)?

  • kmod-usb-net-rtl8150
  • kmod-usb-net-rtl8152
  • kmod-usb-net-asix
  • kmod-usb-net-asix-ax88179

sound reasonable for a start.

1 Like
3

Thanks for your help so far

As a first step, I tried to find out, what the problem is:
With your module list (and the now again working firmware-selector.openwrt.org, I think I figured out the key OpenWRT network basics that are missing on the current Raspberry Zero image (and maybe there are other alike devices)

As long as these basic parts are missing, it is practically impossible for a beginner and still super hard for OpenWrt semi-intermediates like me, to get OpenWRT up and running on Raspberry Pi Zero via OpenWRT default image.

Again for bystanders, to understand, what the initalization problem on the Raspberry Zero is: The device has no built-in NIC (but it has SD-card + 1 USB-OTG-port, which can be converted into a regular USB port via USB-OTG adapter + any USB hub). And the current image does not have any preinitializing config, to get a simple network access.
So to make any use of it in a way that people actually expect from an OpenWrt deployment, you need to connect USB-NIC adapters.

But from then on, the kernel module neededs to run those adapters aren't there by default, and also a few keyparts are missing in the network config file.

To make it clear: The current OpenWRT image is definitely not broken, it is just super hard for beginers and intermediates to make any good use of it via OpenWRT, especially, since I cound not find step-by-step documentation for those steps. It just does not feel right in its current form from an OpenWRT user perspective.

The following is what I found so far, to make it a lot (!) more easy to setup OpenWRT network on the Pi Zero. Once those thinfs are added, the Zero behaves just as easy to setup as any x86 device, where you add custom NICs.

1.packages I added to the default image, to give it USB LAN adapter support out of the box. I also added Luci, as I think a network device is not a real grown-up OpenWrt device, if its most important signature service is missing). I was not using a snapshot release, Zero seems to not have Luci in its default package list at the moment):
kmod-usb-net-rtl8150 kmod-usb-net-rtl8152 kmod-usb-net-asix kmod-usb-net-asix-ax88179 kmod-usb-net luci-ssl

(Those were the 4 USB NIC drivers, you suggested + usb-net + luci-ssl)

2.then in addition, the following 2 config file parts need to be added to /etc/config/network (for which so far, I had to add them via connecting a keyboard + HDMI-monitor to the Pi Zero and directly edit the file (since the network is not initialized in the current default image):

So I had to add the first NIC (which gets mapped to eth0) to brlan

config device
	option name 'br-lan'
	list ports 'eth0'

and I also added the second NIC (which gets mapped to eth1) to wan. Plus I also added wan6, as this was not there in the default as well:

config interface 'wan'
	option proto 'dhcp'
	option device 'eth1'

config interface 'wan6'
	option proto 'dhcpv6'
	option reqaddress 'try'
	option device 'eth1'
	option reqprefix '56'

The nice result now is, once you reboot or reload_config, using the Zero has suddenly become a super-easy-to-use OpenWRT device:

  • If you add a first USB-NIC, that first USB-NIC will be mapped to eth0
  • if you add a second USB-NIC, that will be mapped to eth1.
  • So now it is as easy, to add 1 USB-LAN adapter to the Zero, to get access via LAN + LUCI + SSH
  • add any optional 2nd USB-LAN adapter, to have WAN access from the device via the 2nd USB-NIC, which then allows to download add packages and start routing and stuff out of the box.

And this is, what gets you to the magic point of what OpenWRT from my perspective should be right out of the box on any supported device: Behaving like a real network device. Now you can now do things like opkg list and all your well known command line friends ork and ssh-connect works and so on....

I have to admit though, I do not know what has led to the Zero image as it is so far, maybe there were good reasons to have it that way.
Feel free to comment.

I am not sure, if I am gifted sufficiently, to pull a Pull Request stunt (well, if anyone thinks at allthat the previous suggestion is any kind of good idea). But I thought at least I could tried to properly research and document my point as first step.

4

Update: This is what I use as image customization parameter on the Firmware Selector

  • for Raspberry (Zero)
  • on 23.05rc3 (might be the useful for all 23.05.xx not tested so far)

Image Selector Installed custom packages (adds the common USB LAN dongle drivers, should be suitable for any Raspberry, not jsut for Zero):

kmod-usb-net-rtl8150 kmod-usb-net-rtl8152 kmod-usb-net-asix kmod-usb-net-asix-ax88179 kmod-usb-net luci-ssl kmod-usb-net-rndis usb-modeswitch usbutils

Image Selector Start Script (Specifically constructed for reconstructing an OpenWRT default network file config on the Raspberry Zero, maybe partly suitable for other RPIs as well: not sure if all Raspberry images miss those parameters in their default set):

#to add up to 2 USB RJ45 dongles, those will then appear as eth0 and eth1, default mapped to LAN and WAN:

#add eth0 to LAN interface:
uci add_list network.@device[-1].ports='eth0'

#add back the WAN interface and eth1:
uci set network.wan=interface
uci set network.wan.proto='dhcp'
uci set network.wan.device='eth1'
uci commit

(still planning to investigate PR things in the future, for now just preserving content)

5

Seems like lack of network ports on Pi Zero is the reason it's super hard for beginners. Maybe beginners should be directed to a different device, which does have network ports and is thus easier to set up?

AFAIK the network config is usually generated on first boot. As far as I remember, on squashfs systems there's no /rom/etc/config/network, which I took as an indication that the network config is auto-built on boot. I'd be curious what will happen if you try to include a static network config file in your improvement PR.