Thêm thiết bị Tuya không được hỗ trợ bởi Tuya Cloud vào Home Assistant bằng Tuya Local, cách lấy LocalKey

Nhiều thiết bị dùng chipset Tuya — đèn, ổ cắm, cảm biến công suất, kẹp dòng đo điện, đồng hồ đo năng lượng, trạm sạc — khi add vào Home Assistant bằng integration Tuya chuẩn (cloud) lại rơi vào một trong các trường hợp: HASS không nhận diện được kiểu thiết bị (không ra entity, hoặc ra entity rỗng/sai), model datapoint (DP) trong cloud không đầy đủ nên thiếu các giá trị quan trọng, hoặc đơn giản là phụ thuộc mạng ra Internet nên hay lag hay mất thiết bị khi Tuya cloud chậm.

Với các thiết bị đó, cách xử lý dứt điểm là dùng Tuya Local: Home Assistant nói chuyện trực tiếp với thiết bị qua WiFi trong mạng nội bộ (protocol Tuya 3.3/3.4/3.5, mã hoá bằng LocalKey), bỏ qua cloud ở tầng điều khiển. Trong hệ thống của mình, mình đang chạy 3 thiết bị dạng này: 2 kẹp dòng đo công suất cho trạm sạc xe điện (model pj1103_clamp_meter) và 1 đồng hồ đo điện năng 2 chiều cho lưới (model matsee_2way_energymeter) — cloud không expose đủ data mình cần, nên mình chuyển sang kết nối local.

So sánh các integration

Trước hết để rõ có 3 integration Tuya phổ biến trong HASS:

make-all/tuya-local có iot_class: local_push — thiết bị đẩy state về HASS thay vì HASS phải poll. Kiến trúc đơn giản như sau:

Thiết bị (WiFi Tuya)
      |
      | protocol Tuya local (3.3/3.4/3.5, AES + LocalKey)
      v
Home Assistant (tuya_local)
      |
      v
Entities: switch / sensor / number / climate / cover / fan / vacuum...

Tuya cloud: không tham gia ở tầng điều khiển
(vẫn nhận status nền từ thiết bị nếu thiết bị vẫn kết cloud)

Ba lưu ý quan trọng trước khi đi tiếp (từ docs của tuya-local):

• Mỗi thiết bị Tuya thường chỉ cho phép 1 kết nối local cùng lúc. Nếu app Tuya/SmartLife trên điện thoại đang mở, hoặc một integration local khác cũng đang kết cùng thiết bị đó, sẽ xung đột.
• Kết nối local không chặn thiết bị báo status về cloud — đây không phải biện pháp bảo mật, mà là tăng tốc độ, tăng độ tin cậy, và mở khóa dữ liệu mà cloud không expose.
• Thiết bị chạy pin (cảm biến cửa sổ, smoke alarm...) không qua hub thì không làm local được do giới hạn tiết kiệm năng lượng.

Cài đặt

1. Cài HACS nếu chưa có.
2. Trong HACS thêm custom repository https://github.com/make-all/tuya-local (category: integration) rồi install.
3. Restart Home Assistant.

Lấy LocalKey — phần chính của bài

LocalKey là chuỗi hex 32 ký tự dùng để mã hoá/mã hoá ngược giao thức local của thiết bị. Mỗi thiết bị một key, và quan trọng: key đổi mỗi lần bạn pair thiết bị lại với app. Có 4 cách lấy, xếp từ dễ đến khó.

Cách 1: Cloud-assisted config (dễ nhất, khuyến nghị)

Chính config flow của tuya_local có chế độ cloud:

1. Settings → Devices & Services → Add Integration → Tuya Local.
2. Chọn chế độ cloud (hoặc cloud_fresh_login nếu token cũ hết hạn).
3. Đăng nhập bằng tài khoản Tuya/SmartLife (tài khoản app thông thường) — không cần tài khoản Tuya IoT developer.
4. Chọn thiết bị trong danh sách; integration tự lấy device_id + local_key, và scan LAN để điền luôn IP.
5. Tiếp tục sang Stage One (kiểm tra kết nối) rồi Stage Two/Three như hướng dẫn bên dưới.

Token cloud chỉ sống vài giờ nên integration không lưu lại — tiện cho việc add nhiều thiết bị liên tiếp trong một phiên. Cách này cũng là đường an toàn nhất hiện tại, vì Tuya đã bắt đầu giới hạn thời gian truy cập dữ liệu key trong IoT developer portal (trial khoảng 1 tháng, mỗi 6 tháng mới refresh được trial mới).

Cách 2: Tuya IoT Developer Portal (thủ công)

Cần tài khoản iot.tuya.com đã link với app Tuya Smart/SmartLife:

1. Cloud → Devices: xem danh sách thiết bị, ghi lại Device ID. Nếu không thấy thiết bị, kiểm tra chọn đúng server/region ở góc trên trang.
2. Cloud → API Explorer → Devices Management → Query Device Details in Bulk → nhập Device ID (nhiều ID thì tách bằng dấu phẩy).
3. Kết quả trả về local_key.
4. IP của thiết bị lấy từ router (nên đặt IP tĩnh trước).

Cách 3: tinytuya wizard (CLI)

tinytuya là library nền của các integration local này, có wizard đi một lượt cả quét thiết bị lẫn lấy key:

pip install tinytuya
python -m tinytuya wizard

Trả lời các câu hỏi:

• API Key / API Secret: lấy từ iot.tuya.com (Access ID / Access Secret của project).
• Device ID: bất kỳ thiết bị nào trong tài khoản (để pull full list), hoặc gõ scan để quét LAN.
• Region: chọn đúng data center của tài khoản (US, EU, Central Europe...).
• Download DP Name mappings: Y.
• Poll local devices: Y (nếu thiết bị cùng mạng với máy HASS).

Kết quả nằm trong file devices.json:

{
  "id": "xxxxxxxxxxxxxxxxxxxxxx",
  "key": "<local-key-32-hex>",
  "ip": "192.168.1.64",
  "node_id": "<node-id-cua-thiet-bi-con (chua co neu khong phai hub)>",
  "mapping": { "dps": "..." }
}

node_id bắt buộc với thiết bị con (Zigbee/BT chạy qua hub Tuya). Phần mapping cực kỳ hữu ích khi thiết bị chưa có sẵn trong database của integration — bạn có đủ thông tin DP để tự khai báo device mới hoặc submit PR lên repo.

Cách 4: Sniff traffic (nâng cao, fallback cuối)

App Tuya nói chuyện với thiết bị qua MQTT; khi app pair/sync thiết bị, LocalKey xuất hiện trong traffic. Có thể bắt bằng các tool sniff MQTT (extension duyệt web TuyaLocalKey hay tool cộng đồng), hoặc dùng tuya-device-config (SDK chính chủ của Tuya chạy trên sandbox của họ). Cách này chỉ cần dùng khi 3 cách trên không khả thi, ví dụ thiết bị nằm trong tài khoản cloud bạn không có quyền truy cập data.

Dấu hiệu nhận LocalKey sai: với protocol 3.1, setup vẫn "thành công" vì key chỉ được dùng khi gửi lệnh — bạn chỉ phát hiện khi thử bật/tắt. Với protocol 3.3 trở lên, key dùng để giải mã dữ liệu nên setup sẽ lỗi ngay lập tức — đây lại là tín hiệu tốt, biết sớm key sai.

Thêm thiết bị vào Home Assistant

Sau khi có đủ host (IP), device_id, local_key:

Stage One — kết nối. Điền 4 trường:

Integration thử kết nối và đọc DPS (datapoints) thật từ thiết bị trước khi cho qua.

Stage Two — kiểu thiết bị. Danh sách được lọc từ database hàng nghìn thiết bị, giữ lại những cái khớp với DPS thực nhận được. Chọn đúng model — vì chọn sai phải xoá entry rồi add lại (mỗi kiểu thiết bị tạo bộ entity khác nhau, không nên "đổi" type tại chỗ). Nếu model bạn không thấy trong danh sách, log của integration (level WARNING khi setup) sẽ in danh sách DPS nhận được — dùng nó để khai báo device mới, hoặc submit issue/PR lên repo.

Stage Three — đặt tên. Tên này là nền cho entity names; với nhiều thiết bị cùng loại (vd nhiều kẹp dòng) nên đặt tên phân biệt như Minh Home, Trạm sạc xe điện.

Lỗi thường gặp

• Key sai sau khi pair lại: mỗi lần pair lại với app, LocalKey đổi. Update config entry bằng key mới.
• Protocol misdetect: một số thiết bị 3.2/3.22 bị detect thành 3.3 (hoặc ngược lại). Dấu hiệu: đọc được state nhưng điều khiển không ổn định. Sửa: set protocol_version thủ công trong options.
• Thiết bị "đóng cửa" khi mất cloud: một số thiết bị ngừng phản hồi nếu không connect được server Tuya trong thời gian dài. Mẹo: block cả DNS lẫn TCP tới Tuya để chế độ offline "sạch" hơn (nếu bạn thực sự muốn chạy offline hoàn toàn).
• Rate limit / thiết bị treo: thiết bị Tuya thường không chịu được nhiều lệnh liên tiếp — có thể reboot hoặc offline 30s đến vài phút. Trong automation, chèn delay giữa các lệnh; gộp nhiều thuộc tính vào 1 lệnh (vd light.turn_on kèm nhiều thuộc tính) nếu thiết bị hỗ trợ.
• Xung đột kết nối local: đóng app Tuya/SmartLife trên điện thoại (hoặc không cho app truy cập local), và không chạy 2 integration local cùng lúc trên cùng một thiết bị.
• Thiết bị qua hub: dùng device_id/host/local_key của hub, kèm node_id của thiết bị con. Số sub-device bị giới hạn theo số connection của hub (thường 1–3). Nếu hub là Zigbee, cân nhắc dùng thẳng ZHA hoặc Zigbee2MQTT sẽ gọn hơn.
• Điền IP "Auto": phát hiện động hoạt động nhưng kém tin cậy — fail khi có integration khác đang giữ kết nối local, hoặc mạng nhiều subnet. Nên đặt IP tĩnh trong router, vừa nhanh reconnect vừa ổn định.

Khi nào vẫn nên dùng Tuya Cloud?

• Thiết bị đã được cloud map đúng và đủ entity cần dùng — không cần thêm local làm gì.
• Cần điều khiển từ ngoài mạng nội bộ (local cần tunnel/VPN; cloud thì remote sẵn).
• Thiết bị có tính năng cloud-only (một số preset, firmware OTA qua cloud).

Mẹo thực tế của mình: chạy song song cả cloud và local trên một thiết bị là ổn (cloud không dùng kết nối local nên không xung đột) — cloud làm dự phòng và remote, local làm đường điều khiển chính. Chỉ cần nguyên tắc: mỗi thiết bị chỉ một integration local.

Tổng kết

Khi một thiết bị Tuya "không được hỗ trợ" trong Home Assistant, phần lớn vấn đề nằm ở tầng cloud (model DP chưa map, cloud không expose đủ data). Chạy local bằng make-all/tuya-local giải quyết gần như toàn bộ, và bước khó nhất — lấy LocalKey — hiện đã có đường cloud-assisted ngay trong config flow, không cần tài khoản developer. Hai điều nhớ trước khi bắt đầu: đặt IP tĩnh cho thiết bị, và đóng app Tuya/SmartLife trên điện thoại để tránh tranh giành kết nối local.