DOCSEARCHbyAlgolia
Submit Docs

TUYA-CONVERT

repository·master·Indexed 26 days ago

https://github.com/ct-open-source/tuya-convert

A tool for flashing alternative open-source firmware, such as Tasmota or ESPurna, onto ESP8266/ESP85 based smart home devices via OTA updates to bypass Tuya cloud services. It supports installation on Linux hosts and deployment via Docker and Docker Compose.

Tokens
1.4K
Snippets
4
Records
7
Agent score
90%

What's inside tuya-convert

  1. Run TUYA-CONVERT using Docker

    master

    Using Docker avoids installing dependencies on your host system.

    Requirements:

    • Linux computer with a Wi-Fi adapter.
    • Secondary Wi-Fi device (e.g., smartphone).
    • docker and docker-compose installed.

    Setup and Execution:

    1. Clone the repo and enter the directory.
    2. Create your environment file: cp .env-template .env.
    3. Edit the .env file to configure settings (e.g., WLAN interface name and LOCALBACKUPDIR).
    4. Build and run the container:
    docker-compose build && docker-compose run --rm tuya

    Useful Docker Commands:

    • Keep container after flashing (for troubleshooting): Remove the --rm flag: docker-compose run tuya.
    • Access bash instead of starting tuya: docker-compose run --entrypoint bash tuya.
    • Rebuild image without cache: docker-compose build --no-cache.
    git clone https://github.com/ct-Open-Source/tuya-convert
cd tuya-convert
cp .env-template .env
# Edit .env before running
docker-compose build && docker-compose run --rm tuya

  2. Flash third-party firmware using TUYA-CONVERT

    master

    Follow these steps to flash an alternative firmware (like Tasmota or ESPurna) onto your Tuya device:

    1. Prepare Firmware: Place your binary file in the /files/ directory.
      • Note: The binary must include the first-stage bootloader and have a maximum filesize of 512KB for the first flash.
      • Tasmota Users: Use tasmota-lite.bin. Never use tasmota-minimal.bin as it will brick your device.
    2. Start Flashing: Run the flashing script and follow the on-screen instructions. The script will install a flash loader, connect to the device's access point, and automatically download a backup of the original firmware.
    3. Initial Configuration:
      • Tasmota: The device will broadcast a tasmota-xxxx AP. Connect to it and navigate to 192.168.4.1 to configure Wi-Fi credentials.
      • ESPurna: The device will broadcast an ESPURNA-XXXXXX AP. Connect using the default password fibonacci, then navigate to 192.168.4.1 to configure Wi-Fi or upgrade the firmware.
    ./start_flash.sh

  3. Install TUYA-CONVERT on Linux

    master

    To install TUYA-CONVERT directly on a Linux host, clone the repository and run the prerequisite installation script.

    Requirements:

    • A Linux computer with a Wi-Fi adapter capable of acting as an Access Point.
    • A secondary Wi-Fi device (e.g., a smartphone) to interact with the device during the process.

    Warning: Flashing alternative firmware can render your device unusable or require soldering to recover. Use this software at your own risk.

    git clone https://github.com/ct-Open-Source/tuya-convert
cd tuya-convert
./install_prereq.sh

  4. Troubleshoot TUYA-CONVERT connectivity and logs

    master

    If you encounter issues during the flashing process, check the following:

    • Network Interface Errors: If you cannot connect to your network card, ensure the WLAN variable in your .env file matches your host's interface name (check via ifconfig).
    • Connection/IP Issues: If your phone cannot connect or get an IP, check smarthack-wifi.log. The log location is defined by LOCALBACKUPDIR in your .env file.
    • Firewall Issues: Some firewalls (e.g., NixOS) may block connections; try disabling the firewall temporarily.
    • Patched Firmware: If the PSK ID in smarthack-psk.log begins with 02, the device is running a newer patched firmware that cannot be flashed with the current workaround.

  5. Configure tuya-convert using Docker Compose

    master

    You can run tuya-convert using Docker Compose. The setup requires specific environment variables and host networking to function correctly.

    Required Environment Variables:

    • WLAN: The SSID of the access point created by the device.
    • AP: The password for the access point created by the device.
    • GATEWAY: The gateway IP address.
    • LOCALBACKUPDIR: The local directory on your host machine where firmware backups will be stored inside the container at /usr/bin/tuya-convert/backups.

    Key Configuration Details:

    • The container must run in privileged: true mode.
    • The container must use network_mode: "host" to interact with the device on the local network.
    version: '3'
services:
  tuya:
    build: .
    privileged: true
    network_mode: "host"
    environment:
        WLAN: ${WLAN}
        AP: ${AP}
        GATEWAY: ${GATEWAY}
    volumes:
      - $LOCALBACKUPDIR:/usr/bin/tuya-convert/backups

  6. Configure Tuya devices via smartconfig

    master

    The smartconfig function from the smartconfig module can be used to send Wi-Fi credentials and Tuya authentication tokens to a device in EZ config mode (blinking fast).

    To use it, you must provide the Wi-Fi password, SSID, region, token, and secret. The script typically iterates through multiple attempts to ensure the device captures the packets.

  7. Configure the Docker environment using config-tuya.sh

    master

    The config-tuya.sh script is used within the Docker container to initialize the config.txt file required by tuya-convert. It populates the configuration file using the following environment variables:

    • WLAN: The SSID of the Wi-Fi network you want the device to connect to.
    • AP: The Access Point (AP) credentials (typically used for the device's setup mode).
    • GATEWAY: The gateway/router IP address.

    These values are written to /usr/bin/tuya-convert/config.txt in the format KEY=VALUE.