DOCSEARCHbyAlgolia
Submit Docs

linux-android

repository·main·Indexed 25 days ago

https://github.com/mayukh4/linux-android

A project to repurpose old Android phones into a full Linux desktop environment or a dedicated Home Assistant smart home server using Termux without root access. Supports multiple desktop environments (XFCE4, LXQt, MATE, KDE Plasma), GPU acceleration via Turnip/Adreno, and Home Assistant Core installation via proot-distro.

Tokens
2.4K
Snippets
7
Records
12
Agent score
31%

What's inside linux-android

  1. How the conflict-safe installer works

    main
    The installation script uses a safe_install_pkg function to handle package conflicts in Termux (e.g., between vulkan-loader-android and vulkan-loader-generic). Before attempting an installation, the function reads the Conflicts field from apt-cache show. If a conflicting package is already present, the script skips the new package with a warning and continues, preventing the installation from crashing.

  2. Configure GPU Acceleration for Linux Desktop

    main

    The script automatically detects your GPU to enable hardware acceleration:

    • Qualcomm Adreno (Snapdragon): Uses Turnip (Vulkan driver) + Zink (OpenGL via Vulkan) for near-native performance.
    • Mali / Other GPUs: Falls back to Zink + SwRast (software Vulkan).

    If you need to tweak Mesa flags, the GPU environment configuration is stored in ~/.config/linux-gpu.sh. This file is automatically loaded by start-linux.sh every time you start your desktop.

  3. Access your Linux Android phone via SSH

    main

    The setup script installs OpenSSH, allowing you to control your phone from a PC on the same WiFi network.

    1. Initial Setup (on the phone)

    Open Termux and run:

    sshd
passwd

    Use whoami to find your username (e.g., u0_a123).

    2. Find your IP address

    ip addr show wlan0 | grep 'inet '

    3. Connect from your PC

    Use Port 8022 (the default Termux SSH port):

    ssh your-termux-username@192.168.1.42 -p 8022

    4. File Transfer (SCP)

    From PC to Phone:

    scp -P 8022 myfile.txt u0_a123@192.168.1.42:~/

    From Phone to PC:

    scp -P 8022 u0_a123@192.168.1.42:~/somefile.txt ./

    5. Persistent SSH

    To make the SSH server start automatically whenever Termux opens, add it to your .bashrc:

    echo 'sshd 2>/dev/null' >> ~/.bashrc

  5. Auto-start the Linux desktop on Termux launch

    main

    To automatically launch the Linux desktop whenever you open Termux, add the start script to your ~/.bashrc file and uncomment it.

    # Add this to ~/.bashrc
# Uncomment to auto-launch desktop on Termux open
# bash ~/start-linux.sh

  6. Install Home Assistant as a Smart Home Server

    main

    Turn an Android phone into an always-on Home Assistant hub. This runs Home Assistant Core inside a lightweight Ubuntu container via proot-distro.

    Requirements & Limitations

    • No Bluetooth: HA cannot access the phone's Bluetooth stack via Termux.
    • No USB Dongles: Zigbee/Z-Wave sticks won't work without root.
    • No mDNS/Auto-discovery: Android 10+ blocks /proc/net/dev. You must add devices manually by IP address or cloud API.
    • No Docker/Add-ons: This is HA Core, not HA OS.

    Installation

    Run the following in Termux:

    curl -O https://raw.githubusercontent.com/mayukh4/linux-anroid/main/setup-homeassistant.sh
bash setup-homeassistant.sh

    Note: Installation takes 15–45 minutes as it compiles Python dependencies.

    Management

    Start HA:

    bash ~/start-homeassistant.sh

    Stop HA:

    bash ~/stop-homeassistant.sh

    Accessing the Dashboard

    Open a browser on any device on your WiFi network and navigate to: http://<your-phone-ip>:8123

    To find your phone's IP, run this in Termux:

    ip addr show wlan0 | grep 'inet '

    Keeping HA running in the background

    To prevent Android from killing the process, use termux-wake-lock and nohup:

    termux-wake-lock
nohup bash ~/start-homeassistant.sh > ~/hass.log 2>&1 &

  7. Install a Linux Desktop on Android

    main

    You can turn an old Android phone into a full Linux desktop environment using Termux. This process requires an arm64 (64-bit) processor, at least 3 GB of RAM (4 GB+ recommended for KDE Plasma), and 5–10 GB of free storage. Qualcomm Snapdragon chips provide the best GPU acceleration via Turnip/Adreno, though other GPUs are supported with lighter performance.

    Prerequisites

    1. Install Termux: Download from F-Droid (do not use the Play Store version).
    2. Install Termux-X11: Download the latest .apk from GitHub Releases.
    3. Grant Permissions: Ensure both apps have necessary permissions.

    Installation Steps

    1. Pre-upgrade Termux

    Open Termux and run the following to prevent crashes and keep the process alive during installation:

    termux-wake-lock
pkg upgrade -y

    2. Run the Setup Script

    Download and execute the setup script. The script will prompt you to choose a desktop environment (XFCE4, LXQt, MATE, or KDE Plasma) and whether to install Wine.

    curl -O https://raw.githubusercontent.com/mayukh4/linux-anroid/main/termux-linux-setup.sh
chmod +x termux-linux-setup.sh
bash termux-linux-setup.sh

    3. Start the Desktop

    Run the start script, then open the Termux-X11 app on your phone to view the desktop.

    bash ~/start-linux.sh

    To stop the desktop:

    bash ~/stop-linux.sh

  8. Configure GPU flags for the desktop

    main

    You can customize GPU behavior by editing ~/.config/linux-gpu.sh, which is sourced every time the desktop starts. Common tweaks include forcing software rendering for debugging or overriding OpenGL versions.

    # Force software rendering (for debugging)
export GALLIUM_DRIVER=llvmpipe

# Enable Mesa debug output
export MESA_DEBUG=1

# Change OpenGL version override
export MESA_GL_VERSION_OVERRIDE=3.3

  9. Troubleshoot installation and desktop issues

    main

    If you encounter issues during or after the setup, refer to these common solutions:

    • Script exits mid-install: Check ~/termux-setup.log to identify the specific package that caused the failure.
    • Desktop doesn't appear: The desktop renders inside the Termux-X11 app, not the Termux terminal. Open the app manually.
    • Black screen in Termux-X11: Run stop-linux.sh then start-linux.sh again. Note that KDE Plasma may take 20–30 seconds longer to boot on the first run.
    • 'library not found' or 'cannot link executable': This is a libpcre crash. Close Termux, reopen it, run pkg upgrade -y, and re-run the installation script.
    • Package install fails (unmet dependencies/Conflicts): The script uses safe_install_pkg to skip conflicting packages. If it still fails, check the logs and report the issue with your device model and Android version.
    • Audio not working: Wait 5–10 seconds after the desktop appears for PulseAudio to initialize.
    • Wine doesn't launch: Ensure your desktop is running first, then run winecfg from the terminal inside the desktop environment.

  10. Troubleshoot Home Assistant issues

    main

    Specific troubleshooting for Home Assistant (HA) deployments:

    • 'pip install homeassistant' compilation errors: Ensure build dependencies are installed. Run proot-distro login ubuntu and install python3-dev, libffi-dev, libssl-dev, and cargo. Then run:
      source ~/hass-venv/bin/activate && pip install homeassistant
    - **Dashboard not loading at port 8123**: The first launch can take 5–10 minutes. Monitor the output by running:
  ```bash
proot-distro login ubuntu -- bash -c "source ~/hass-venv/bin/activate && hass -c ~/hass-config"

    Ensure your phone and browser are on the same WiFi network.

    • 'address already in use' error: An instance is already running. Stop it with bash ~/stop-homeassistant.sh or pkill -f "hass -c".
    • Devices not discovered automatically: Android 10+ restricts /proc/net/dev, preventing mDNS/Zeroconf. Add devices manually via IP address or use cloud-based integrations (e.g., Tuya, Govee Cloud).
    # To monitor HA initialization:
proot-distro login ubuntu -- bash -c "source ~/hass-venv/bin/activate && hass -c ~/hass-config"

# To stop a running HA instance:
bash ~/stop-homeassistant.sh
# OR
pkill -f "hass -c"

  11. Run the Hello Server demo

    main

    The Hello Server is a simple Flask web server demo that displays live system information from your Android device.

    To run it:

    1. Install the flask dependency using pip.
    2. Execute the hello_server.py script located in the examples/ directory.
    3. Open a web browser (such as Firefox, which is included in the standard setup) and navigate to http://localhost:5000 to view the live system info.
    pip install flask
python examples/hello_server.py

  12. Compare Desktop Environments for Linux Android

    main

    When running the termux-linux-setup.sh script, you can choose from several desktop environments. Choose based on your phone's hardware capabilities:

    DesktopBest ForResource Usage
    XFCE4Most users (Default)Low–Medium
    LXQtOld or low-RAM phones (2–3 GB)Very Low
    MATEClassic desktop feelMedium
    KDE PlasmaPowerful phones onlyHigh