From dfe9da65379140bcdb4684d0de7c47829d33f7e5 Mon Sep 17 00:00:00 2001 From: Scott Leonard Date: Wed, 26 Nov 2025 04:00:17 +0000 Subject: [PATCH] Add GL-XE300 Device Tree --- GL-XE300 Device Tree.-.md | 44 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 GL-XE300 Device Tree.-.md diff --git a/GL-XE300 Device Tree.-.md b/GL-XE300 Device Tree.-.md new file mode 100644 index 0000000..9ef2084 --- /dev/null +++ b/GL-XE300 Device Tree.-.md @@ -0,0 +1,44 @@ +The GL.iNet GL-XE300 (Puli) is supported under OpenWrt's ath79/nand target. In the OpenWrt 24.10.4 source, the board's DTS file is present at the expected path: + +target/linux/ath79/dts/qca9531_glinet_gl-xe300.dts + +Target System: Atheros ath79 (DTS), Subtarget: NAND and then the GL.iNet GL-XE300 profile in menuconfig. This ensures the correct DTS and image recipe are used. The DTS will be compiled into the final device tree blob (DTB) that is baked into the firmware. To customize pins or add features like I²C, you will need to modify this DTS (or apply a patch) and rebuild the firmware. + +- GPIO0 - Controls the LTE modem power (exported as lte_power, set high on boot) +- GPIO1 - Drives the WAN LED (active low) +- GPIO3 - Used for the Reset button (active low) +- GPIO10 - LAN status LED (active low) +- GPIO12 - WLAN status LED (active low, default trigger WiFi) +- GPIO13 - 3G/4G (LTE) status LED (active low) +- GPIO17 - SD card detect switch (active low, exported as sd_detect) + +GPIO4 and GPIO15 are free from conflicts in the default OpenWrt DTS, so you can repurpose them. We found no evidence in the upstream DTS or kernel that these pins are used for strapping or critical functions on this board. (They are not used for boot selection, which on QCA9531 is handled by other pins - unused GPIOs can generally float without issues as per QCA datasheets.) Thus, using GPIO4 and GPIO15 for a software I²C bus should be safe. + +A few other GPIOs on this device are not obvious from the DTS but are worth noting: + +- GPIO16 - Although not mentioned in the DTS, GL.iNet's firmware uses GPIO16 to control USB power on the “no-battery” variant of the XE300 +- If you remove the internal battery, the USB 5V rail must be enabled by driving GPIO16 high (GL's init script exports GPIO16 for this). In the battery model, this is handled by the charge controller, but in a custom build you should ensure GPIO16 remains output-high if you want the USB port powered. So avoid repurposing GPIO16. +- “Power” Button - The XE300 has a power button in addition to reset (used for special boot modes). The DTS did not define a gpio-key for a power button, but it's likely wired to a GPIO (possibly GPIO2 or another) that U-Boot/firmware monitors. Be mindful not to hijack any pin that might be the power button input. (Since it's not defined in DTS, GL's firmware likely handles it out-of-band.) + +Implementing I²C via i2c-gpio (Build-Time Device Tree Customization) + +To add a custom I²C bus using GPIO4 (SDA) and GPIO15 (SCL), you will use the i2c-gpio driver. OpenWrt 24.10.x uses a recent kernel where runtime or user-space hacks are deprecated, so the proper method is to modify the device tree, not a runtime overlay or the old i2c-gpio-custom module: + +Do not rely on insmod-based dynamic config. The old approach of using kmod-i2c-gpio-custom with module parameters (e.g. insmod i2c-gpio-custom bus0=0,5,4) no longer works on modern OpenWrt (it was removed around 21.02 due to kernel changes). Users have reported that simply inserting the custom module fails (e.g. i2cdetect finds nothing, as it returns almost instantly). This confirms that the new kernels expect device-tree enumeration for software I²C. + +Device-tree overlays at runtime are not supported by default on OpenWrt. While the kernel's configfs overlay interface exists in theory, OpenWrt generally does not include the necessary patches and configuration in official builds (attempts to use Raspberry Pi-style DT overlays on ath79 will not work out-of-the-box). In short, runtime DT overlay is deprecated/unavailable in this environment, so you cannot simply drop in a DTBO at boot. + +The correct solution is to edit the GL-XE300's DTS and add an i2c-gpio node that uses GPIO4 and GPIO15. For example, you would append something like: + +&i2c { /* Use a new node name if &i2c is not pre-defined in qca953x.dtsi */ + compatible = "i2c-gpio"; + pinctrl-names = "default"; + pinctrl-0 = <>; /* (if you disable JTAG or other pinctrl settings, include here if needed) */ + sda-gpios = <&gpio 4 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; + scl-gpios = <&gpio 15 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; + i2c-gpio,delay-us = <4>; /* nominal delay, adjust if needed for speed */ + #address-cells = <1>; + #size-cells = <0>; +}; + +**GPIO voltage and pull-ups: The QCA9531 SoC's GPIOs are 3.3V. Ensure your I²C devices are also 3.3V or use level shifting. You will need pull-up resistors on SDA/SCL (if not already on the board) since i2c-gpio will treat GPIO4/15 as open-drain lines. The DTS flags above handle the software side of open-drain, but physical pull-ups are needed for the bus.** \ No newline at end of file