Waydroid GPS Patcher

A comprehensive GPS patcher for Waydroid Android images that enables hardware GPS functionality within the Android container.

What This Script Does

This script automatically patches Waydroid Android system and vendor images to add complete GPS/GNSS support by:

• Installing GPS Libraries: Downloads and installs Android GPS/GNSS HAL libraries for your system architecture
• Configuring GPS Services: Sets up proper GPS configuration files and service definitions
• Updating Android Manifests: Modifies system manifests to register GPS hardware interfaces
• Expanding Images: Automatically expands system and vendor images if they lack sufficient space
• Setting Permissions: Configures proper file permissions and service user contexts
• Device Mounting: Updates Waydroid configuration to mount the host GPS device

After running this script, Android apps within Waydroid will be able to access real GPS data from your host system's GPS hardware.

Prerequisites

System Requirements

• Linux system with Waydroid installed and configured
• Root access (script must be run with sudo)
• GPS device available on the host system (e.g., /dev/ttyUSB0, /dev/ttyACM0, etc.)
• Python 3 with standard libraries

Required Tools

The script requires these system tools to be installed:

# Ubuntu/Debian
sudo apt install e2fsprogs mount util-linux file

# Fedora/RHEL
sudo dnf install e2fsprogs util-linux file

# Arch Linux
sudo pacman -S e2fsprogs util-linux file

Waydroid Setup

1. Waydroid must be properly installed and have been initialized at least once
2. Android images must exist in /etc/waydroid-extra/images/
   • system.img
   • vendor.img
3. Waydroid should be stopped before running the script (script will handle this)

GPS Hardware

• A working GPS device connected to your system
• Device should be accessible (e.g., /dev/ttyUSB0, /dev/ttyACM0, /dev/ttyGPS0)
• User permissions to access the GPS device (add user to dialout group)

Installation & Usage

1. Download the Script

git clone <your-repo-url>
cd <repo-name>

2. Configure GPS Device

Edit the script to match your GPS device:

GPS_DEVICE = "/dev/ttyGPS0"  # Change to your actual GPS device
BAUD_RATE = 9600            # Change to your GPS device's baud rate

Common GPS devices:

• USB GPS dongles: /dev/ttyUSB0 or /dev/ttyACM0
• Serial GPS: /dev/ttyS0
• Custom: /dev/ttyGPS0 (if using gpsd or similar)

3. Run the Patcher

sudo python3 gps_config.py

The script will:

1. Check prerequisites and stop Waydroid
2. Expand images if needed (adds 200MB to system, 100MB to vendor)
3. Download GPS libraries from GitHub
4. Mount and patch both images
5. Install GPS libraries and configuration
6. Update Android manifests and build properties
7. Configure Waydroid for GPS device mounting

4. Post-Installation Setup

After the script completes successfully:

# Add your user to dialout group for GPS access
sudo usermod -aG dialout $USER

# Restart Waydroid
waydroid session stop
sudo systemctl restart waydroid-container
waydroid session start

# Reboot your system (recommended)
sudo reboot

5. Making GPS Device Persistent (If Needed)

If you're using GPSD and your GPS device disappears after reboot, you may need to create a persistent device symlink. This is common when using USB GPS devices with GPSD.

Check if you need this fix: After reboot, if Waydroid GPS stops working, check if the device exists:

ls -la /dev/ttyGPS0

If the device is missing, create a udev rule:

First, identify your GPS device:

udevadm info /dev/gps0

Look for the ATTRS{idVendor} and ATTRS{idProduct} values, then create a udev rule:

sudo tee /etc/udev/rules.d/99-waydroid-gps.rules << 'EOF'
# Create ttyGPS0 symlink for Waydroid when GPS device is detected
# Replace idVendor and idProduct with your device's actual values
SUBSYSTEM=="tty", ATTRS{idVendor}=="1546", ATTRS{idProduct}=="01a8", SYMLINK+="ttyGPS0"
EOF

Apply the rule:

sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=ttyACM0  # or whatever your GPS device is

Verify:

ls -la /dev/ttyGPS0  # Should show the symlink

This creates a persistent /dev/ttyGPS0 device that survives reboots without interfering with GPSD's access to the hardware.

Configuration

GPS Device Settings

The script is pre-configured for these defaults:

• Device: /dev/ttyGPS0
• Baud Rate: 9600
• Android Version: 13
• Images Directory: /etc/waydroid-extra/images

Customization

You can modify these settings at the top of the script:

IMAGES_DIR = "/etc/waydroid-extra/images"  # Waydroid images location
ANDROID_VERSION = "13"                     # Android version (11 or 13)
GPS_DEVICE = "/dev/ttyGPS0"               # Your GPS device path
BAUD_RATE = 9600                          # GPS device baud rate

Testing GPS Functionality

1. Verify GPS Device Access

# Test GPS device outside Waydroid
cat /dev/ttyGPS0

# Should show NMEA sentences like:
# $GPRMC,123456.00,A,1234.5678,N,12345.6789,W,0.123,456.78,060825,,,A*XX

2. Test Inside Waydroid

# Enter Waydroid shell
waydroid shell

# Check if GPS device is mounted
ls -la /dev/ttyGPS0

# Read GPS data
cat /dev/ttyGPS0

3. Test with Android Apps

Install GPS testing apps from the Play Store or F-Droid:

• GPS Test (recommended)
• GPS Status & Toolbox
• GPS Essentials

These apps should show:

• Satellite count and signal strength
• Current coordinates
• GPS fix status (2D/3D)
• Accuracy information

Troubleshooting

Common Issues

Script fails with "No space left on device"

• The script should automatically expand images, but if it fails, manually expand them:

sudo e2fsck -f /etc/waydroid-extra/images/system.img
sudo resize2fs /etc/waydroid-extra/images/system.img

GPS device not persistent after reboot

• This commonly happens with USB GPS devices when using GPSD
• GPSD creates /dev/gps0 but the script expects /dev/ttyGPS0
• Solution: Create a udev rule to automatically create the symlink:

# First identify your GPS device
udevadm info /dev/gps0

# Create udev rule (replace vendor/product IDs with your device's values)
sudo tee /etc/udev/rules.d/99-waydroid-gps.rules << 'EOF'
SUBSYSTEM=="tty", ATTRS{idVendor}=="1546", ATTRS{idProduct}=="01a8", SYMLINK+="ttyGPS0"
EOF

# Apply the rule
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=ttyACM0

Waydroid won't start after patching

• Check Waydroid logs: sudo journalctl -u waydroid-container
• Try restarting: sudo systemctl restart waydroid-container
• Verify image integrity: sudo waydroid upgrade

GPS not working in Android

• Check if GPS is enabled in Android Settings > Location
• Verify GPS service is running: waydroid shell then ps -A | grep gnss
• Check Android logs: waydroid shell then logcat | grep -i gps

Architecture Support

The script automatically detects your system architecture and downloads the appropriate GPS libraries:

• x86_64: Intel/AMD 64-bit
• arm64-v8a: ARM 64-bit (like Raspberry Pi 4)
• armeabi-v7a: ARM 32-bit
• x86: Intel/AMD 32-bit

Debug Mode

For verbose output, you can modify the script to add debug logging or run commands manually to isolate issues.

Technical Details

What Gets Modified

System Image (system.img):

• /system/etc/vintf/manifest.xml - Adds GNSS HAL interface
• /system/etc/vintf/compatibility_matrix.*.xml - Adds GNSS HAL support
• /system/build.prop - Enables GPS hardware flags

Vendor Image (vendor.img):

• /vendor/bin/hw/android.hardware.gnss@*.service - GNSS service binaries
• /vendor/lib/hw/android.hardware.gnss@*.so - GNSS HAL libraries
• /vendor/etc/init/android.hardware.gnss@*.rc - Service definitions
• /vendor/etc/gps.conf - GPS configuration
• /vendor/etc/gps.xml - GPS XML configuration
• /vendor/etc/gnss/gps.conf - GNSS-specific configuration

Waydroid Configuration:

• Updates LXC configuration to mount GPS device into container

Architecture Detection

The script automatically detects your system architecture using uname -m and maps it to Android architecture names for downloading the correct GPS libraries.

Credits

• GPS libraries sourced from Lolmc0587/android_gps_libraries
• Developed for Waydroid Android container system
• Tested on Android 13 images

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Known Working Configurations

• Fedora 40 + Waydroid + USB GPS dongle (/dev/ttyUSB0)
• Ubuntu 22.04 + Waydroid + Serial GPS (/dev/ttyS0)
• Arch Linux + Waydroid + Bluetooth GPS (via rfcomm)
• Fedora 40 + Waydroid + u-blox GPS + GPSD (requires udev rule for persistence)

Please share your working configurations to help others!

GPSD Integration

If you're using GPSD (GPS daemon) on your host system, you may need additional configuration:

GPSD creates its own device symlinks (typically /dev/gps0) that may disappear after reboot. The script expects /dev/ttyGPS0, so you'll need to create a persistent symlink using a udev rule as described in the troubleshooting section.

GPSD and Waydroid can coexist - GPSD maintains exclusive access to the hardware device (e.g., /dev/ttyACM0), while Waydroid accesses the same GPS data through the /dev/ttyGPS0 symlink. Both point to the same underlying device.