Skip to main content

FAQs

General Troubleshooting FAQs

Environment Setup and Activation

Q1: How do I activate tos.py and why do I need to reactivate it?

To activate tos.py, run the activation script in the TuyaOpen root directory:

  • Linux/Mac: . ./export.sh
  • Windows (PowerShell): .\export.ps1 (may need Set-ExecutionPolicy RemoteSigned -Scope LocalMachine first)
  • Windows (CMD): .\export.bat

Important: You must reactivate tos.py each time you open a new terminal session. The activation sets up the Python virtual environment and PATH variables needed for the build system.

Q2: What should I do if tos.py activation fails?

If activation fails:

  • Linux: Install python3-venv package: sudo apt-get install python3-venv
  • Delete and recreate venv: Remove the ./.venv directory and run the activation script again
  • Check Python version: Ensure Python 3.8 or later is installed
  • Windows: Make sure you're using CMD or PowerShell (not Git Bash or MSYS2, which are incompatible)
Q3: Why can't I use Git Bash or MSYS2 on Windows?

TuyaOpen's build system is incompatible with Linux-like terminal environments on Windows (Git Bash, MSYS2). You must use:

  • Windows CMD (Command Prompt)
  • PowerShell

The build scripts rely on Windows-native path handling and command execution that these Linux-like environments don't support properly.

Q4: What are the system requirements for TuyaOpen?

Minimum requirements:

  • Operating Systems: Windows 10/11, Ubuntu 20.04/22.04/24.04 LTS (recommended), macOS (with Homebrew)
  • Tools: Git >= 2.0.0, CMake >= 3.28.0, Make >= 3.0.0, Ninja >= 1.6.0, Python >= 3.8.0
  • Linux packages: build-essential, ninja-build, cmake-curses-gui, python3-pip, python3-venv
  • Hardware: USB data cable, compatible development board
Q5: How do I verify my environment is set up correctly?

After activation, run these commands to verify:

tos.py version    # Should show version number
tos.py check      # Should verify all tools and download submodules

If tos.py version shows [Unknown version], it means the repository has no tags (common in forked repositories) but this won't affect functionality.

Build Problems

Q1: What should I do if my build fails with missing dependencies?

If your build fails with errors about missing packages or modules:

  • Run tos.py check to automatically install required dependencies.
  • Ensure your Python environment and PATH configuration are correct.
Q2: Why is my board not detected by the build system?

If the build script cannot detect your hardware board or shows errors about an undefined board:

  • Make sure the correct target board is selected using tos.py config choice.
  • Confirm your board configuration file exists at {PATH_TO_APP_PROJECT_ROOT}/config/your_t5_custom_board.config.
  • The config directory should include Kconfig overlay files for each board.
  • Not all apps/demos are compatible with every board; review app documentation.
  • The build system supports multiple chips, board versions, or platforms (Linux/MCU) if your code supports them.
Q3: When do I need to create a new Board BSP?

If your hardware or PCB is custom (i.e., not matching existing boards):

  • Use tos.py new board to generate the BSP structure and config files.
  • Centralize hardware initialization and board drivers in the BSP.
  • Reuse your BSP across projects for easier maintenance and separation of hardware/application logic.
Q4: How do I resolve compilation errors?

If your build fails with errors, warnings, or stops mid-compilation:

  • Review the documentation for troubleshooting steps.
  • If unresolved, open a ticket on GitHub Issues or ask for help on Discord.
  • AI-powered coding tools may provide helpful suggestions or guidance.
Q5: Why is compilation slow on Windows?

If each file takes up to 3 seconds to compile or the process gets stuck:

  • Open Task Manager (Ctrl + Shift + Esc), find and close the MSPCManagerService process.
  • If the above doesn't work, move the entire TuyaOpen directory to a non-system drive (e.g., D drive).
  • Add the directory to the exclusion list in Windows Security - Virus & threat protection settings.
Q6: What should I do if tos.py check fails?

If the check command reports errors:

  • Tools not installed or version too low: Install or upgrade the corresponding tools (git >= 2.0.0, cmake >= 3.28.0, make >= 3.0.0, ninja >= 1.6.0).
  • Submodules download fails: Manually execute git submodule update --init in the TuyaOpen root directory.
  • Python venv issues: If activation failed, delete the ./.venv directory and re-activate. Ensure python3-venv is installed (sudo apt-get install python3-venv on Linux).

Hardware

Q1: How do I reset pairing information and network configuration?

To reset your device's pairing information and network configuration:

  • Standard Reset (Most MCU Devices):

    • Restart (RESET) the device three times within 5 seconds.
    • On the fourth boot, the network and pairing status should be cleared automatically.
    • Refer to your device's documentation for any model-specific reset procedure.

  • For Linux Runtimes:
    If you are developing or testing on Linux, you can manually clear persistent key-value data for pairing and network status by deleting the tuyadb folder. This folder serves as the cache for network and pairing information.
    Example:

    rm -rf tuyadb/*

Configuration and Kconfig Issues

Q1: How do I select the correct board configuration?

Use tos.py config choice to select from pre-validated configurations:

  • The command lists all available board configurations for your project
  • Configurations come from two sources (in priority order):
    1. Project-specific config/ directory
    2. Global boards/ directory
  • After selection, the configuration is saved to app_default.config in your project directory
Q2: What is the difference between config choice and config menu?
  • tos.py config choice: Selects a pre-configured board setup from available options. This is the recommended way to get started quickly.
  • tos.py config menu: Opens an interactive menu (menuconfig) to manually configure all Kconfig options. Use this for advanced customization.

Note: Both operations perform a deep clean before execution since they may change the toolchain.

Q3: Why can't I select/deselect certain Kconfig options in menuconfig?

If an option is grayed out or cannot be changed:

  • The option may be forced by a select statement in your board's Kconfig file (e.g., boards/T5AI/TUYA_T5AI_EVB/Kconfig)
  • Options with select ENABLE_XXX are automatically enabled and cannot be manually disabled
  • To change this, you need to modify the board's Kconfig file directly
Q4: How do I save my custom configuration for reuse?

After modifying configuration via tos.py config menu:

  • Use tos.py config save to save your current configuration
  • Enter a name when prompted (e.g., my_custom_board.config)
  • The configuration will be saved to your project's config/ directory
  • You can then select it later using tos.py config choice
Q5: Arrow keys don't work in config menu on Windows. What should I do?

This is a terminal compatibility issue. Try:

  • Use alternative keys: h (left), j (down), k (up), l (right)
  • Switch between CMD and PowerShell to find which works better
  • Use the spacebar to toggle options and Enter to confirm

Authorization and License Issues

Q1: What is the difference between TuyaOpen license and TuyaOS license?
  • TuyaOpen license: Consists of UUID and AuthKey specifically for TuyaOpen Framework. These are not interchangeable with TuyaOS licenses.
  • TuyaOS license: Used only for TuyaOS projects, cannot be used with TuyaOpen Framework.
  • Always ensure you're using TuyaOpen-specific UUID and AuthKey when working with TuyaOpen projects.
Q2: How do I obtain a TuyaOpen license (UUID and AuthKey)?

You can obtain TuyaOpen licenses through:

Q3: How do I write authorization information to my device?

Two methods are available:

  • Method 1 - Command line: Use tos.py monitor -b 115200, then enter auth uuidxxxxxxxxxxxxxxxx keyxxxxxxxxxxxxxxxxxxxxxxxxxxxxx in the interactive prompt
  • Method 2 - Code: Modify tuya_config.h in your project and set TUYA_OPENSDK_UUID and TUYA_OPENSDK_AUTHKEY macros, then rebuild and flash

Note: Use the serial port used for flashing (not the log port) for authorization commands.

Q4: How do I verify my authorization was written correctly?

After writing authorization:

  • Use tos.py monitor to connect to the device
  • Enter auth-read command in the interactive prompt
  • You should see your UUID and AuthKey displayed
  • If you see xxxxxxxxxxxxxxxx instead of actual values, the authorization was not written correctly
Q5: What does "Authorization read failure" mean in device logs?

If you see errors like:

[ty E][tal_kv.c:269] lfs open UUID_TUYAOPEN -2 err
[ty E][tuya_authorize.c:107] Authorization read failure.

This indicates:

  • The device cannot read the authorization information from storage
  • Authorization was not properly written or was corrupted
  • Re-write the authorization using one of the methods above and reboot the device

Flashing and Device Boot

Q1: Why does flashing fail or my device is not detected?

If the flash command fails or your device is not detected:

  • Verify that you are using a data USB cable (not a charge-only cable).
  • Install the appropriate serial port drivers for your platform.
  • Try another USB port or a different cable.
  • Specify the port directly (e.g. tos.py flash --port /dev/ttyUSB0). For more details, check out the flashing guide.
  • Place your device in download mode/boot mode if needed.
  • Check device connections using lsusb (Linux) or Device Manager (or Windows Device Manager).
Q2: What should I do if my device won't boot?

If your device has no display, no response, or no serial output after power-on:

  • Check the USB cable and port.
  • Inspect the power supply (consider another port or adapter).
  • Look for short circuits.
  • Reflash the firmware.
  • Watch for error messages in the serial output during boot.
Q3: Why do I see "Port [xxx] may be busy" when flashing?

If you see this message:

  • Wait approximately 1 minute and retry
  • The delay varies depending on virtual machines and serial chip models
  • For T5 series boards in virtual machines, there's a known delay before the port becomes available
  • You can verify the port exists with ls /dev/tty* (Linux) but may need to wait before it's usable
Q4: Why does my T5 board show two serial ports?

T5 series development boards have two separate serial ports:

  • Download/Flash port: Used for firmware flashing and authorization
  • Log port: Used for viewing device logs and monitoring

Identifying ports:

  • Windows: Check Device Manager - port with letter A is download port, letter B is log port
  • Linux/Mac: Generally, the device with the smaller number is the flash port, larger number is the log port
  • If unsure, test both ports when flashing
Q5: How do I fix serial port permission errors on Linux?

If you get permission denied errors when accessing serial ports:

sudo usermod -aG dialout $USER

Then reboot your system for the changes to take effect. After reboot, you should be able to access serial ports without sudo.

Q6: Why is tyutool_gui detected as a virus on Windows?

This is a false positive from Windows Defender. To resolve:

  • Place the tyutool_gui tool in a non-system drive (e.g., D: drive)
  • Add the directory to the exclusion list in Windows Security - Virus & threat protection settings
  • The tool is safe and provided by TuyaOpen project

Connectivity Issues

Q1: What if my device can't connect to Wi-Fi?

If your device fails to connect to Wi-Fi when pairing:

  • Use a 2.4GHz Wi-Fi network (5GHz is not supported).
  • Ensure your Wi-Fi SSID and password information is correct.
  • Move the device closer to your router.
  • Check router settings such as MAC filtering.
  • Reset the device and try the pairing process again.

If the issue is not resolved, please ask for help on GitHub Issues and attach the full device log.

Q2: How do I resolve cloud connection issues?

If the device does not appear in the app or cannot connect to the cloud:

  • Confirm UUID and AuthKey are correct and TuyaOpen-specific.
  • Ensure the device is online and internet connectivity is available.
  • Check Tuya Cloud service status.
  • Review device logs for connection errors.
  • Reset and re-pair the device if issues persist.

If the issue is not resolved, please ask for help on GitHub Issues and attach the full device log.

Peripheral and Feature Issues

Q1: What do I do if my screen is blank or not displaying?

If you see a blank screen or display errors:

  • Make sure you've selected the correct display target board.
  • Check the display settings in menuconfig.
  • Confirm LVGL is enabled.
  • Look for display initialization messages in the serial monitor.
  • Verify your demo app supports screen output.
Q2: Why isn't the AI Agent responding?

If there is no response to voice or AI commands:

  • Check the device's network connectivity.
  • Review the serial monitor for AI service-related errors.
  • Confirm the microphone is connected and operational.
  • Make sure wake word detection is enabled and functioning.
  • Verify the device is properly paired and connected to Tuya Cloud.
  • Check that AI Agent services are enabled in your project configuration.
Q3: How do I enable audio codec drivers (microphone/speaker)?

To enable audio functionality:

  • First, ensure your audio codec and hardware are supported: Check your board's documentation and Kconfig files to verify that your development board supports the audio codec hardware (microphone/speaker) you want to use
  • Run tos.py config menu in your project directory
  • Navigate to audio codec configuration options
  • Enable the appropriate audio codec for your board
  • Ensure your board's Kconfig file includes select ENABLE_AUDIO_CODECS if audio is pre-configured
  • If your board doesn't have pre-registered audio devices, you'll need to implement the audio driver bridge yourself
  • Rebuild the project after configuration changes
Q4: Why aren't my peripheral drivers (button, display, etc.) working?

If peripherals aren't functioning:

  • Verify the peripheral is enabled in Kconfig (tos.py config menu)
  • Check that both src/peripherals/<peripheral>/Kconfig and boards/<platform>/<board>/Kconfig have the required configuration
  • Ensure your board's hardware initialization code registers the peripheral
  • Review serial logs for driver initialization errors
  • Verify hardware connections and pin configurations match your board setup

Pairing Issues with Tuya Cloud / Tuya Smart Life App

Q1: Why is my device not detected in the app during pairing?

If your device does not appear in the app during pairing:

  • Verify your UUID and Auth license code is properly configured.
  • Reset network configuration:
    • For MCUs: Restart (RESET) the device three times within 5 seconds.
    • For Linux/Ubuntu: Remove the tuyadb cache folder and try again.
Q2: What if I can't connect to Wi-Fi during pairing?

If connection fails during Wi-Fi setup in the app:

  • Make sure your network is 2.4GHz (most Wi-Fi MCUs do not support 5GHz).
    • For MCUs: Confirm the router supports 2.4GHz.
    • For Linux: Use network tools (ipconfig, etc.) to verify connectivity and check hardware interfaces.
  • Ensure the Wi-Fi password is typed correctly.
  • Move the device closer to your router.
Q3: What if my device appears in the app but does not respond after pairing?

If the device is shown in the app but unresponsive after pairing:

  • Check serial monitor for error messages.
  • Review device logs for cloud connectivity information.
  • Make sure required DPs (Data Points) are implemented in your firmware.
  • Verify the device is actually online (check cloud connection status in logs).
  • Ensure your firmware handles DP commands from the cloud correctly.
Q4: How do I put my device into pairing mode?

For most TuyaOpen demos (like switch_demo and your_chat_bot):

  • Quick reset method: Restart (RESET) the device three times within 5 seconds
  • The device will enter pairing mode on the fourth boot
  • Check device logs for pairing mode indicators (e.g., STATE_START, TUYA_EVENT_BIND_START)
  • Some devices may have physical buttons or other methods - refer to your specific device documentation
Q5: What should I do if pairing fails due to incorrect authorization?

If device logs show authorization errors:

  • Verify UUID and AuthKey are correctly written (use auth-read command)
  • Ensure you're using TuyaOpen-specific licenses (not TuyaOS licenses)
  • Check that authorization values don't show as xxxxxxxxxxxxxxxx in logs
  • Re-write authorization information and reboot the device
  • For more details, see the Device Authorization guide

Project Creation and Structure

Q1: How do I create a new project?

Use tos.py new project to create a new application:

  • The command will prompt for a project name
  • You can specify a framework template with --framework parameter (default is base, also supports arduino)
  • The template is copied from tools/app_template/ directory
  • After creation, use tos.py config choice to select a board configuration
  • Then build with tos.py build
Q2: Where should I run tos.py commands?

Critical: Always run tos.py commands from your application project directory, not from the TuyaOpen root:

  • ✅ Correct: cd apps/tuya_cloud/switch_demo && tos.py build
  • ❌ Wrong: Running from TuyaOpen root directory will cause errors
  • The project directory is where your CMakeLists.txt and app_default.config files are located
Q3: What is the difference between apps/ and example/ directories?
  • apps/: Contains full-featured applications and demos (e.g., tuya_cloud/switch_demo, tuya.ai/your_chat_bot)
  • example/: Contains smaller code examples demonstrating specific features or APIs
  • Both can be compiled using tos.py build after selecting a board configuration
  • Choose based on your learning or development needs
Q4: How do I clean build artifacts?

Two cleanup options:

  • Standard clean: tos.py clean - Removes build cache but keeps configuration
  • Force clean: tos.py clean -f - Performs deep clean, deletes entire .build directory
  • Use force clean when switching between different board configurations or when experiencing build issues

Git and Submodule Issues

Q1: How do I update TuyaOpen dependencies?

After updating the main TuyaOpen repository (via git pull or git checkout):

  • Run tos.py update to automatically update related dependencies
  • This command updates toolchain dependencies based on platform/platform_config.yaml
  • Dependencies are switched to the specified commit as configured

Linux Runtime Support FAQs

Overview

While TuyaOpen is primarily designed for MCU devices, it also supports Linux runtime environments (e.g., embedded Linux on ARM/x86/x64). This allows you to develop applications using Tuya's framework on a wide variety of hardware platforms, provided you handle the required hardware integrations.

Q1: What Linux platforms and architectures are supported?

The TuyaOpen framework can be compiled for common Linux architectures including:

  • x86 (32-bit)
  • x64 (64-bit)
  • ARM (32 and 64-bit, e.g., Raspberry Pi and similar SBCs)

You may need to configure your build toolchain to match your target hardware.

Q2: How do I implement hardware (GPIO, SPI, I2C, PWM, and more..) support on Linux?

Unlike MCU environments where hardware access is direct, Linux systems manage hardware through the kernel and board support packages (BSPs). For TuyaOpen to interact with hardware:

  • Implement Linux drivers: Ensure your hardware is accessible via a Linux device driver or standard sysfs interface.
  • Create a bridge in the TuyaOpen codebase: You are responsible for writing or adapting hardware interface code (for GPIO, SPI, PWM, QSPI, Camera, etc.) to conform to the TuyaOpen driver interfaces.
  • Leverage existing interfaces: Reference Linux libraries like wiringPi, libgpiod, or kernel /dev/* nodes for common peripherals.
Q3: Does TuyaOpen provide Linux hardware abstraction?

TuyaOpen provides the framework and abstractions for cloud connectivity, device pairing, and AI-agent functionality. However, hardware peripheral support (GPIO, SPI, PWM, Camera, QSPI, etc.) must be implemented by the developer, using your platform's kernel/BSP capabilities.

Q4: How do I cross-compile TuyaOpen for my Linux platform?
  • Use the correct cross-compiler toolchain for your target (e.g., arm-linux-gnueabihf-gcc for ARM).
  • Modify the TuyaOpen build configuration (usually via CMake or Makefile) to suit your target architecture and sysroot.
  • Test your binary on your hardware and troubleshoot dependencies (such as missing libc versions or device drivers).
Q5: What should I do if my device isn't enumerated or hardware fails to open?
  • Ensure your kernel or BSP enables and exports the necessary device files (e.g., /dev/spidev*, /dev/video*, /sys/class/gpio/*).
  • Check permissions: Run your app with sufficient privileges, or adjust udev rules.
  • Debug using standard Linux tools like dmesg, lsmod, and ls /dev.
Q6: Can I use Tuya cloud and AI-agent features on Linux?

Yes! TuyaOpen handles the cloud connectivity and AI-agent features across platforms. As long as you provide the hardware bridge implementations, the rest of the device logic, pairing, cloud integrations, OTA, and AI features will work similarly to MCU deployments.