This repository contains utility scripts designed to help identify GPIO pins when their hardware functions are unknown. Each script is tailored to a specific probing use case.

Both scripts include configuration variables at the top that you may need to adjust, such as the list of GPIOs to scan. It is generally recommended to avoid GPIOs that are already in use by the system. You can check currently active pins by running cat /sys/kernel/debug/gpio and excluding any that appear configured.

Based on experience, the lower-numbered GPIOs are typically things like nand, switches, etc & the higher-numbered GPIOs are often left unconfigured by default - making them a safe starting point for scanning.

Please note that probing certain pins may occasionally cause your device to crash or reboot. If this happens, simply reboot the device and remove the problematic GPIO from your scan list before trying again.

⚠️ LICENSE WARNING: GPLv2 / GPLv3 INCOMPATIBILITY⚠️

These scripts are licensed under GPLv3-or-later. It is NOT compatible with GPLv2-only projects (such as the Linux Kernel or OpenWrt).

DO NOT use this script to build binaries for distribution if the underlying source code is licensed GPLv2-only. Doing so creates a license conflict that makes the resulting binary undistributable and constitutes a copyright violation.

This script is intended for:

Private use only (no distribution of binaries).
Projects that are fully GPLv3 or GPLv2-or-later (where the user chooses GPLv3).

If you need a script for a fully compliant GPLv3-or-later project you are free to use and modify this one to suit your needs.

If you need a script for OpenWrt, use the GPLv2-or-later version in the official repository if you intend to distribute binaries (coming soon).

mooleshacat / catspeed.cc is not responsible for any potential license violations you create for yourself.

🛠️ OpenWRT Developer Suite

owrt-dev-suite-utils is integrated into another GPLv3-or-later project owrt-dev-suite which contains an advanced and highly customizable build script for OpenWRT.

For advanced and highly customizable developer build script for OpenWRT, see the dedicated GPLv3 owrt-dev-suite:
👉 github.com/catspeed-cc/owrt-dev-suite

finding GPIOs to probe

You can find GPIOs to probe by listing them in two ways:

cat /sys/kernel/debug/gpio to get all of them
cat /sys/kernel/debug/gpio | grep "in low func0 2mA pull down" to get likely unconfigured ones

When including them in the script do not put 'GPIO' just put the numbers.

`usb-power-probe.sh`

This script was originally developed to identify the USB power/enable line on the TEW-829DRU router. On this specific hardware, GPIOs are offset by 512 (meaning logical pin 0 corresponds to actual GPIO 512, logical pin 1 to 513, and so on). Ensure that the base offset matches your target device's architecture.

Identify a list of GPIOs to scan (use cat /sys/kernel/debug/gpio to view all available pins).
Open the script and add your chosen logical pin numbers to the CANDIDATES variable.
Adjust the BASE offset if necessary for your device.
Insert a USB flash drive with an LED indicator into the port you wish to test.
Run the script using ./usb-power-probe.sh.
Monitor both the terminal output for USB-related dmesg messages and the USB drive's LED for any activity or flashing.
If the router crashes or reboots, remove that specific GPIO from your CANDIDATES list and try again.

`button-probe.sh`

This script identifies which GPIO pin corresponds to a physical button by monitoring its electrical state changes. It exports each candidate GPIO as an input, records its initial state, prompts you to press and release the button, and reports whether the value changed.

Open the script and add your candidate logical GPIO numbers to the BUTTON_CANDIDATES variable.
Verify or manually set the auto-detected base offset at the top of the script if needed.
Run the script using ./button-probe.sh.
Follow the on-screen instructions: hold down the button and press Enter, then release it and press Enter again.
If a matching pin is found, you will be prompted to decide whether to continue scanning the remaining pins.
If the router crashes or reboots, remove that GPIO from your BUTTON_CANDIDATES list, reboot the device, and restart the process.

Disclaimer

mooleshacat and catspeed-cc are not responsible for any hardware damage caused by using these tools. Proceed at your own risk.