Skip to main content
Back to LearnTuyaOpen SDK

Flash and monitor your device

Write the firmware bin you just built onto the board with tos.py flash, then watch it boot and run with tos.py monitor โ€” both from the project directory.

Beginner8 minFlashing

What you get at the end

Your board is running the firmware you built, and you can see its serial log streaming in a terminal โ€” the proof it boots and the foundation for pairing it next.

  • tos.py flash writes the bin from .build/bin/ to the device over the serial port you pick.
  • tos.py monitor streams the device log; reset the board after starting it to capture the full boot.
  • Both commands use tyutool_cli under the hood โ€” tos.py downloads it automatically on first use.

Before you flash

Connect the board to your PC over USB. Then handle the one OS-specific prerequisite:

  • On Linux, grant serial port access once, then reboot: sudo usermod -aG dialout $USER.
  • If you run a virtual machine, map the serial port through to the VM before flashing.

Flash the firmware

Run tos.py flash from the project directory (the same place you ran tos.py build). It lists the serial ports it sees โ€” pick yours by number.

โฏ tos.py flash
[INFO]: Run Tuya Uart Tool.
[INFO]: Use default baudrate: [921600]
[INFO]: Use default start address: [0x00]
--------------------
1. /dev/ttyACM1
2. /dev/ttyACM0
--------------------
Select serial port: 2
...
[INFO]: Write flash success
[INFO]: CRC check success
[INFO]: Reboot done
[INFO]: Flash write success.

Common flags

`-p`, `--port`Target serial port (e.g. `/dev/ttyACM0`, `COM3`). Omit to pick from a list.
`-b`, `--baud`Uart baud rate (default 921600).
`-d`, `--debug`Show flash debug messages.

You must be in the application project path and the project must have compiled successfully first.

Monitor the log

Run tos.py monitor and select the log port. Reset the board manually after starting, to capture the full boot log. Quit with Ctrl+C, then press Enter.

โฏ tos.py monitor
[INFO]: Run Tuya Uart Tool.
--------------------
1. /dev/ttyACM1
2. /dev/ttyACM0
--------------------
Select serial port: 1
[INFO]: Open Monitor. (Quit: Ctrl+c)
[01-01 00:03:25 ty D][tuya_health.c:75] feed watchdog
[01-01 00:03:35 ty D][tuya_health.c:75] feed watchdog
  • On Linux/Mac the smaller port number is usually the flash port, the larger one the log port. On Windows check Device Manager.
  • You can also write the authorization code through monitor โ€” see Equipment Authorization in the docs.
  • To exit: press Ctrl+C, then press Enter.

Two serial ports on T5 series boards

T5 series dev boards expose two serial ports โ€” one for flashing, one for logging. If you cannot tell which is which, just try both when flashing.

  • Windows: in Device Manager, the port with the A-number is the download port, the B-number is the log port.
  • Linux/Mac: generally the smaller number flashes, the larger logs.
  • VM mapping of T5 serial ports can take about a minute to settle โ€” a device busy notice right after mapping is normal.

Troubleshooting

Flashing gets stuck or repeatedly fails at the write stage

Usually a missing serial-port driver. See Install drivers in the tyutool docs. On Mac, the same cause explains an undetected port.

Port [xxx] may be busy

Wait about a minute and retry. VM mapping duration varies by VM and serial chip. Make sure no other monitor is holding the port.

T5 board shows a port but flashes fail with device busy

VM mapping has a settling delay โ€” about a minute after mapping. Wait, then retry without re-mapping.

Windows Defender flags the GUI flashing tool

Place tyutool_gui on a non-system drive (e.g. D:) and add the directory to Windows Security โ†’ Virus & threat protection exclusions. The CLI used by tos.py flash is not affected.

Next: pair the device โ†’Full flashing docs โ†’