Tuyaopen/dev Loop

TuyaOpen Build-Deploy-Debug Loop

Loop Workflow

The standard development iteration cycle for TuyaOpen hardware:

┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
│  Build  │────>│  Flash  │────>│ Monitor │────>│ Analyze │────>│ Decide  │
│         │     │         │     │  Logs   │     │ Results │     │         │
└─────────┘     └─────────┘     └─────────┘     └─────────┘     └────┬────┘
     ^                                                               │
     │                         ┌──────────┐                          │
     └─────────────────────────│ Fix Code │<─────── if error ────────┘
                               └──────────┘         if ok → done

Step-by-step

1. Build: tos.py build — compile firmware (see skill tuyaopen/build)

2. Flash: Flash firmware to the device from the project directory:

   tos.py flash -p <port>        # specify port (recommended)
   tos.py flash                   # auto-detect port
   tos.py flash -p <port> -d      # debug output
   

   Which port? Run tyutool_cli list-ports --json and group on usbSerial — one physical board is one usbSerial:

   • 1 port → single-serial board: flash, auth and log all share it.
   • 2+ ports → dual-serial board (T5/T5AI etc.): flash = lowest usbInterface, monitor/log = the other.

   Rank by usbInterface, not by COM/ttyACM number — on Windows the flash port can be the higher COM. Typical, not guaranteed: if flash fails on one port, swap to the other of the same usbSerial. Serial permission required on Linux (once): sudo usermod -aG dialout $USER then reboot.

   On single-serial boards the loop is sequential: the monitor holds the only port, so stop it before flashing (else Access is denied / Device or resource busy) and start it again after. Dual-serial boards can keep the log port open across a flash.

3. Monitor / capture logs: tos.py monitor -p <port> for interactive sessions, or hands-off background logging via tuyaopen/debug-helper (monitor_helper.py start -p <port> → tail → stop).

4. Analyze: read the log file under <project_dir>/.target_logging/ for errors, warnings, crash indicators (patterns below)

5. Decide: pass (device healthy) or fail (fix code and restart loop)

LINUX shortcut

For LINUX platform targets, skip flash/monitor — use the bundled script:

$OPEN_SDK_PYTHON .agents/skills/tuyaopen-dev-loop/scripts/build_run.py          # build + run + auto-analyze (30s timeout)
$OPEN_SDK_PYTHON .agents/skills/tuyaopen-dev-loop/scripts/build_run.py 60       # custom timeout in seconds
$OPEN_SDK_PYTHON .agents/skills/tuyaopen-dev-loop/scripts/build_run.py 0        # no timeout

Or manually:

./dist/<project>_<version>/<project>_<version>.elf 2>&1 | tee device.log

Both dist/ (canonical output) and .build/bin/ (build intermediate) contain the ELF. Use dist/ for consistency.

Log Format & Patterns

TuyaOpen log format

[MM-DD HH:MM:SS ty X][source_file.c:line] message

Where X is the log level: E (error), W (warn), N (notice), I (info), D (debug), T (trace).

Key patterns to watch

Log level hierarchy

ERR > WARN > NOTICE > INFO > DEBUG > TRACE

Default log level: DEBUG. Set via tal_log_init(TAL_LOG_LEVEL_DEBUG, 1024, callback).

CLI Testing

Built-in CLI (tal_cli) via debug UART (prompt: tuya> ). Commands, registration, batch testing: references/ERROR_CODES.md.

Device State

Agent Iteration Strategy

On build failure

1. Read the compiler error output carefully.
2. Identify the source file and line.
3. Fix the code.
4. tos.py build again. Repeat until build succeeds.

On flash failure

1. Check serial port (T5 dual-port: try the other port if flash fails — see the Flash step above).
2. Wait ~1 minute if port is busy.
3. Retry with the other port if available.
4. If still failing, ask the user to check hardware connection.

On runtime error (log analysis)

1. Capture log output after flash (monitor for 10-30 seconds).
2. Search for ty E (errors) and OPRT_ patterns.
3. Map error codes using references/ERROR_CODES.md.
4. Identify the source file and line from the log.
5. Fix the code based on the error context.
6. Restart the loop: build → flash → monitor.

On no output

1. Verify serial port and baud rate match the chip (check the baud rate table: T2=115200, T3/T5AI=460800, ESP32=115200, LN882H=921600).
2. Reset the device manually.
3. If still no output, the firmware may have crashed before log init — review recent code changes.

AI agent helper: tuyaopen/debug-helper (monitor_helper.py)

Full reference: skill tuyaopen/debug-helper. Script path (relative to SDK root):

.agents/skills/tuyaopen-debug-helper/scripts/monitor_helper.py

Logs are always written to <project_dir>/.target_logging/ (gitignored by the SDK).

Typical flow

# 1. Start background monitor (non-blocking)
$OPEN_SDK_PYTHON .agents/skills/tuyaopen-debug-helper/scripts/monitor_helper.py \
    --json start -p /dev/ttyACM1

# 2. Flash on the other port while monitor keeps logging
tos.py flash -p /dev/ttyACM0

# 3. Read log after boot
$OPEN_SDK_PYTHON .agents/skills/tuyaopen-debug-helper/scripts/monitor_helper.py \
    --json tail -n 200

# 4. Stop and release port
$OPEN_SDK_PYTHON .agents/skills/tuyaopen-debug-helper/scripts/monitor_helper.py stop

Iteration loop (analyze → fix → re-run)

Repeat until logs are clean:

1. Build → tos.py flash -p <port>
2. monitor_helper.py start -p <monitor-port> — capture boot + runtime trace
3. monitor_helper.py tail -n 200 → search ty E, OPRT_, watchdog, MQTT
4. Edit code → go to step 1
5. monitor_helper.py stop when done so the port is free for the next flash