RTLPlayground gives cheap 2.5G switches a managed firmware

Why the unmanaged variant is the target

RTLPlayground is a playground for firmware development for advanced users of RTL8372 and RTL8373 based 2.5Gbit switches, and the rationale is stated early in the README.

For each hardware configuration of these devices, there is usually a managed and an unmanaged version sold, with mostly identical hardware. The aim is to provide management features also for unmanaged devices, with additional features such as Management VLAN, DHCP servers, multi-language support, IPv6 and TLS-encrypted web-pages.

That framing is what makes the project worth reading, and it is also what defines its audience. The hardware is cheap and widely available, and the managed variant costs more for features the hardware can already do. Putting a different firmware on the cheap one is a way to get those features without the price difference.

The README is honest about the gap between the aim and the state. At present, only the following features are provided, and the list is long: a modern web-interface with mouse-over to display further information, a serial console interface to configure all features, IGMP to configure Multicast streaming, port configuration showing detailed information about own and Link-partner advertised speed settings and configuration of these settings on the local side, per-port configuration of frame sizes for Jumbo-Frame support or limiting MTUs for particular devices, per-port EEE configuration with detail on the support offered by the link partner and the EEE status of a port, VLAN configuration, SFP information with the current sensor values such as temperatures and RX and TX power shown in the CLI and as mouse-over on the web, mirror configuration, link aggregation groups, detailed information on port packet statistics, configuration saved to flash via the web-interface, firmware updates via the web, and installation as a firmware upgrade from the original web-interface.

The list also says what is not there, and that matters more than the list of what is.

The warnings about managed switches and Spanning Tree

The README is unusually direct about the risks, and this is the part an evaluator should not skim.

While the firmware provides already considerable improvements over the original managed firmware, it still lacks support for the proprietary loop prevention protocols as well as DHCP. Spanning Tree is available, with a pointer to doc/stp.md, but is a simplified implementation, and the README says to read that document before enabling it on a switch you administer over the network.

Then the instruction: if you need these features, do not install the playground on your managed devices.

The reason is a specific failure mode rather than a general one. A managed switch relies on the vendor's loop prevention, often ring or loop guard, and on DHCP for address assignment. Replace the firmware with something that has neither, and the switch can end up in a bridging loop that floods the network, or come up with no address. On a switch you administer over the network, that is a serious operational problem rather than a learning exercise.

The simplified Spanning Tree is called out separately because Spanning Tree is the fallback that people reach for when a loop happens, and a simplified implementation is exactly the case where you do not want to rely on it without reading the document first.

So the guidance in the README is: this firmware is for the unmanaged variant, and the one hardware operation you may need is a SOIC clamp on the flash chip, which is also used for BIOS backups. For this no soldering skills are necessary, so the physical requirement is a clamp and a bit of care, not an electronics bench.

Hardware coverage and the device list

The firmware supports all hardware features of three device configurations, and the README states them as port counts rather than model names.

The three are 4 2.5GBit ports plus 2 SFP+ ports, 5 2.5GBIT plus 1 SFP+ port, and 8 2.5GBit plus 1 SFP+ port.

The important caveat follows immediately. Devices sold usually have a fairly common design, however there may be differences in the LED configuration, since switches have LEDs with different colours and use types of LEDs. The list of tested devices is in doc/supported_devices.md.

That is the honest boundary of the project, and it is a real one. A switch is not determined by its switch chip; the PHY, the port layout, the LED wiring and the flash chip all vary between products that share the same Realtek part number. The code is written against a board definition, and the LED handling is the part most likely to differ between two units that otherwise look identical.

The README also mentions the light situation on the documentation side, with a doc/ directory holding supported_devices.md, stp.md and adding-a-device.md, and an html/ directory holding the web interface assets that get compiled into the firmware image.

Building the firmware

The build requirements are for a specific toolchain, and one of them is a version constraint rather than a package name.

Install the following particular build requisites, for Debian 12/13, noting that Ubuntu 24.04 still has an older version of sdcc but you will need sdcc version 4.5 for the code to compile:

sudo apt install make gcc sdcc xxd python-is-python3 libjson-c-dev zlib1g-dev

The toolchain choice is what the Makefile shows. CC defaults to sdcc, and the flags are -mmcs51 -I. -Imachine -Ihttpd -Iuip, with ASM defaulting to sdas8051. The -mmcs51 flag is the 8051 instruction set, which tells you the target of the code: the switch's management microcontroller, not a Linux host.

The board you build for is selected by a MACHINE variable:

make MACHINE=DEFAULT_8C_1SFP

The name selects the board definition machine/<name>.c, and make without a MACHINE value stops with an error listing what is expected. If your board is not in the list yet, doc/adding-a-device.md is where you add one.

The output is a .bin file rather than a .img, in order to make IMSProg happy, and the image location is stored in RTLPlayground/output/rtlplayground_version_machine.bin, for example rtlplayground-v0.1.0-12c98ba-dirty-LIANGUO_ZX_SWTGW215AS.bin. The dirty suffix in that name comes from the Makefile, which appends it when git status reports uncommitted changes to tracked files, and the git hash itself comes from git rev-parse --short HEAD.

The build is also made reproducible in a way that matters for firmware. The Makefile honours SOURCE_DATE_EPOCH, falling back to the HEAD commit date and then to wall clock time, and the comment explains why: it keeps same-commit builds byte-identical, and the build date is baked into the image and covered by the trailing CRC.

Docker, the simulator, and upgrading a managed switch

There is a Dockerfile for a reproducible build environment, and there is a local simulator so you can work on the web interface without touching hardware.

The image is built with:

docker build -t rtlplayground-dev .

and the firmware is built inside the container with the machine variable filled in:

docker run --rm -v $(pwd):/workspace rtlplayground-dev make MACHINE=DEFAULT_8C_1SFP

The resulting .bin file appears in output/ on your host, and the host tools alone can be built with make -C tools. The container is based on debian:13-slim with the same package set as the native instructions, and it sets git config --global --add safe.directory /workspace for the same reason JPF does, since the Makefile calls git describe and the bind mount makes the ownership mismatch.

The simulator is the most useful part for a contributor. It runs the web-interface simulator locally as a local webserver:

docker run --rm -p 8080:8080 -v $(pwd):/workspace rtlplayground-dev \
  tools/output/httpd_sim /workspace/html

Port 8080 on the host, the html directory served from the mounted workspace.

There is a second build path for the managed variant. Managed switches can be updated from the existing original firmware using a specific upgrade image, which is built in the installer directory with make, and the resulting file is RTLPlayground/installer/output/rtlplayground_oem_upgrade.bin.

The caution on that image is specific. It must ONLY be used for original OEM firmware web interface firmware upgrade, you do not need this image if you are already on RTLplayground firmware, and unless you go back to the original OEM firmware you would only flash this specific firmware once. Future upgrades of RTLPlayground will only need to follow the direct flashing path.

Where RTLPlayground fits, and where it stops

The comparison worth making is with buying the managed variant of the same switch, and with the alternatives to running a switch's management firmware at all.

Buying the managed variant gives you the vendor's firmware, which is what the README says the playground still lacks: the proprietary loop prevention protocols and DHCP. If you need those, and most production networks do, the managed switch is the right answer and the project says so. The playground is for the case where the unmanaged switch is already on your desk and you want VLANs, IGMP, a web interface and per-port statistics.

The alternative of not having management at all is worth naming, because a cheap unmanaged switch does have a feature set, just a small one. What you get by running the playground instead is a serial console, a web interface, flash-backed configuration, SFP sensor telemetry and firmware you can update over the network rather than over a serial cable.

The limits are the ones the README already states. The proprietary loop prevention protocols and DHCP are missing. The Spanning Tree implementation is simplified and the documentation asks you to read it before enabling it. The feature list is not the full aim, since the aim mentions IPv6, TLS-encrypted web pages and multi-language support that are not in the current list. And the hardware coverage is bounded by the tested device list, with LED behaviour being the most likely difference between two otherwise identical units.

There is also the physical dimension that a software project does not usually have. To do meaningful development you will need to use a serial console, so soldering skills are required, and flashing must be done via a SOIC-8 PatchClamp or by soldering a socket for the flash chip. The README also says that installation is strongly discouraged unless you can at least make a backup of the original flash content via a SOIC clamp and can re-install that firmware if something is wrong.

The project also offers a way in for people who do not want to open a device at all. If you don't want to open your device, you can use the project's code to learn about the devices by looking at the image using e.g. Ghidra, and a standalone device simulator runs entirely under Linux as a local webserver.

On maintenance, the last push was on 2026-10-20 and the repository is not archived, with a single tagged release v0_1_alpha from 2025-11-23. The version in the Makefile is 0.1.0, which tells you where the project is in its life.

Editorial conclusion

RTLPlayground suits an owner of an unmanaged RTL837x based 2.5Gbit switch who wants management features without buying the managed variant, since the firmware provides the web interface, the console and the configuration surface the stock firmware lacks. It is the wrong tool for a managed switch, because the firmware lacks the proprietary loop prevention protocols and DHCP and its Spanning Tree is a simplified implementation, and the README says plainly not to install the playground on your managed devices. Before you build, read doc/supported_devices.md and doc/stp.md, and confirm you can make a backup of the original flash with a SOIC clamp, because the recovery path is a physical operation on the chip.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. logicog/RTLPlayground on GitHub
4. README
5. Releases