Russell Senior
8635eeedc3
Add support for RTL9313-based Ubiquiti UniFi USW Pro XG 10 PoE switch
with 10x 10G RJ45 and 2x SFP+ ports.
Hardware
========
- RTL9313 switch SoC
- 512 MiB RAM
- 32 MiB SPI-NOR flash
- 10x 100M/1G/2.5G/5G/10G RJ45 ports via RTL8264B and RTL8261BE
- PoE: 10x 802.3bt, 90W per port, 400W total budget
- 2x 1G/2.5G/10G SFP+ ports
- Buttons: 1x Reset
- LEDs:
- System LED white/blue
- RGBW LED per port
- Console: TTL 3.3V, 115200 8N1, populated 4-pin header J19,
front to back: VCC, RX, TX and GND
(device must be opened to access header)
- Etherlighting feature (lighting patterns and color control)
- Vendor firmware: U-Boot + LEDE-based Ubiquiti OS
MAC address
===========
Single MAC address in EEPROM partition, applied to all ports.
Known issues
============
- Etherlighting not controllable, driver WIP. Port LEDs for link work
though. By default, the controller keeps the LEDs in a breathing
state, gated by the link state delivered by the Realtek SoC.
Disclaimer
==========
Stock firmware uses a dual-bank layout (kernel0/kernel1, ~15 MiB each).
OpenWrt replaces both banks with a single contiguous firmware partition.
Flashing OpenWrt overwrites both stock kernel slots; U-Boot remains
intact and can be used for recovery.
Installation
============
1. Enable SSH on the stock UniFi OS and log in with user account.
(at this stage you may make backups of the flash, just to be sure)
2. Copy the OpenWrt sysupgrade image to /tmp on the switch (e.g. via
scp).
3. Adjust IMG below to point at the copied file, then run the block as a
whole. It writes kernel0, splits into kernel1 if the image is larger
than that slot (otherwise invalidates kernel1 so U-Boot cannot pick
a stale bank), and reboots:
IMG=/tmp/openwrt-realtek-rtl931x-ubnt_usw-pro-xg-10-poe-squashfs-sysupgrade.bin
K0_BLOCKS=$((0xec0000 / 0x10000))
dd if="$IMG" of=/dev/mtdblock2 bs=64k count=$K0_BLOCKS conv=fsync
if [ "$(wc -c < "$IMG")" -gt $((0xec0000)) ]; then
dd if="$IMG" of=/dev/mtdblock3 bs=64k skip=$K0_BLOCKS conv=fsync
else
dd if=/dev/zero of=/dev/mtdblock3 bs=64k count=1 conv=fsync
fi
sync
reboot
Then it comes up in OpenWrt.
You may also install the image in any other way, just make sure to
write it to the kernel0 partition and if the image is larger than
15,104 kiB, write the rest to the kernel1 partition, otherwise invalidate
it so U-Boot cannot boot from the second bank.
4. It is recommended to modify the bootcmd to speedup the boot and prevent
any issues due to the dual-boot selection. Since U-Boot by default
uses bootubnt which does a lot of (unneeded) RTK initialization,
quite some time passes until Linux is started. Additionally, the
U-boot logic fiddles with some bits on flash which causes JFFS2
errors in OpenWrt. While this doesn't seem to cause issues yet, be
defensive and set the bootcmd to:
bootm 0xb4150000
This directly boots the uImage from flash, without doing all the
initialization. OpenWrt is able to bootstrap the networking completely
on its own.
It does not matter which bank stock booted from when the dd block
runs: both banks are touched in the same pass (kernel0 written, kernel1
either written or invalidated). With kernel1 invalidated, U-Boot's
internal fallback kicks in and permanently switches to kernel0 on the
next boot, so the device stays on OpenWrt as long as kernel0 is
bootable.
Recovery
========
Since the installation procedure invalidates or partially overwrites
the second bank, recovery requires serial console access (see Hardware
above for pinout).
1. Interrupt U-Boot autoboot by spamming the Escape key during early
boot to drop into the U-Boot prompt.
2. Bring up networking:
rtk network on
3. Transfer an OpenWrt initramfs image via TFTP and boot it:
setenv ipaddr <switch-ipaddr>
setenv serverip <tftpserver-ipaddr>
setenv bootfile openwrt-realtek-rtl931x-ubnt_usw-pro-xg-10-poe-initramfs-kernel.bin
tftpboot
bootm
4. From the running initramfs OpenWrt, do a sysupgrade to reflash
OpenWrt or whatever you want to recover. There is no need for the
complicated procedure from installation since OpenWrt sees the
firmware partition already as a whole.
Return to stock firmware
========================
There is no fully-supported revert path. The stock firmware blob is a
Ubiquiti UBNT archive (header + parts, see firmware-utils' fw.h) that
embeds a u-boot and a kernel0 uImage payload; only the latter is
relevant when writing back to the kernel partitions.
The snippet below extracts the kernel0 uImage from such a blob by
locating the uImage offset and size using binwalk. It is provided as a
best-effort starting point; verify the result before flashing,
otherwise you're on your own:
BLOB=US3.rtl93xx_7.4.1+X.Y.Z.bin
binwalk $BLOB | grep uImage > uimage-info.txt
OFF=$(cut -d\ -f1 uimage-info.txt)
SIZE=$(sed -nE 's/^.*image size: ([0-9]+) bytes,.*/\1/p' uimage-info.txt)
dd if="$BLOB" of=kernel0.uImage bs=1 skip="$OFF" count="$SIZE"
Once you have a clean uImage, it can be written to the kernel partition
from within OpenWrt. If you adjusted the bootcmd during installation,
make sure to restore it to the default "bootcmd=bootubnt". After a reboot,
Ubiquiti's firmware should boot.
Or, if you did backups of the flash before, just write the backup to the
flash.
(lightly modified from Jonas commit adding support for usw-pro-8-poe)
Signed-off-by: Russell Senior <russell@personaltelco.net>
Link: https://github.com/openwrt/openwrt/pull/25425
Signed-off-by: Jonas Jelonek <jonas@jonasjelonek.de>
OpenWrt Project is a Linux operating system targeting embedded devices. Instead of trying to create a single, static firmware, OpenWrt provides a fully writable filesystem with package management. This frees you from the application selection and configuration provided by the vendor and allows you to customize the device through the use of packages to suit any application. For developers, OpenWrt is the framework to build an application without having to build a complete firmware around it; for users this means the ability for full customization, to use the device in ways never envisioned.
Sunshine!
Download
Built firmware images are available for many architectures and come with a package selection to be used as WiFi home router. To quickly find a factory image usable to migrate from a vendor stock firmware to OpenWrt, try the Firmware Selector.
If your device is supported, please follow the Info link to see install instructions or consult the support resources listed below.
An advanced user may require additional or specific package. (Toolchain, SDK, ...) For everything else than simple firmware download, try the wiki download page:
Development
To build your own firmware you need a GNU/Linux, BSD or macOS system (case sensitive filesystem required). Cygwin is unsupported because of the lack of a case sensitive file system.
Requirements
You need the following tools to compile OpenWrt, the package names vary between distributions. A complete list with distribution specific packages is found in the Build System Setup documentation.
binutils bzip2 diff find flex gawk gcc-6+ getopt grep install libc-dev libz-dev
make4.1+ perl python3.8+ rsync subversion unzip which
Quickstart
-
Run
./scripts/feeds update -ato obtain all the latest package definitions defined in feeds.conf / feeds.conf.default -
Run
./scripts/feeds install -ato install symlinks for all obtained packages into package/feeds/ -
Run
make menuconfigto select your preferred configuration for the toolchain, target system & firmware packages. -
Run
maketo build your firmware. This will download all sources, build the cross-compile toolchain and then cross-compile the GNU/Linux kernel & all chosen applications for your target system.
Related Repositories
The main repository uses multiple sub-repositories to manage packages of
different categories. All packages are installed via the OpenWrt package
manager called opkg. If you're looking to develop the web interface or port
packages to OpenWrt, please find the fitting repository below.
-
LuCI Web Interface: Modern and modular interface to control the device via a web browser.
-
OpenWrt Packages: Community repository of ported packages.
-
OpenWrt Routing: Packages specifically focused on (mesh) routing.
-
OpenWrt Video: Packages specifically focused on display servers and clients (Xorg and Wayland).
Support Information
For a list of supported devices see the OpenWrt Hardware Database
Documentation
Support Community
- Forum: For usage, projects, discussions and hardware advise.
- Support Chat: Channel
#openwrton oftc.net.
Developer Community
- Bug Reports: Report bugs in OpenWrt
- Dev Mailing List: Send patches
- Dev Chat: Channel
#openwrt-develon oftc.net.
License
OpenWrt is licensed under GPL-2.0