If a Tuya Wi-Fi device connects in LocalTuya, tuya-local or tinytuya and then drops a few seconds later, the local key is the usual suspect, and the usual advice is to extract it again. The Tuya local protocol version, 3.3, 3.4 or 3.5 on most devices, is the other number that has to be right, and it gets far less attention.
This piece covers what the versions mean, how to find yours, and which Home Assistant integration speaks which. The LAN protocol is local at runtime; once a device is set up, none of this needs the Tuya cloud.
This is research synthesis. No Tuya hardware has been scanned or reset on this site’s bench. Everything below comes from the tinytuya and tuya-local READMEs, the original LocalTuya README, our own earlier Tuya articles, and community reports. Where the diagnostic order is our own reasoning rather than something a source states, it says so.
Three numbers people mix up
Three different version numbers float around Tuya devices, and forum threads blend them. A 2020 Home Assistant Community thread on Tuya protocol versions never cleanly separates the first two, and a 2022 thread asks whether 3.1 or 3.3 maps to a TuyaOS release, with no answer in view.
- Firmware version. The build running on the module. It changes with updates and is not the setting you enter in an integration.
- TuyaOS version. The vendor’s operating system generation. Also not what the integration asks for.
- LAN protocol version. The dialect a device speaks on port 6668 when something on your network talks to it directly. This is the 3.1 to 3.5 value. The tinytuya README says the caller has to specify it because it changes both the communication and the encryption.
Only the third one goes into your config.
What 3.3, 3.4 and 3.5 change
The sources list 3.1, 3.2, 3.3, 3.4 and 3.5, and tuya-local adds a 3.22 option, covered in the note under “Finding your device’s version”.
The one hard requirement tinytuya’s README states is for 3.5, which needs AES-GCM. The pure-Python pyaes library works only up to 3.4 and will not work for 3.5 devices, while PyCA cryptography (the default) and PyCryptodome cover it. If you run tinytuya yourself and a newer device fails while older ones work, check the crypto backend first.
The bigger change starts at 3.4. tinytuya’s README credits community developers with reverse-engineering the 3.4 and 3.5 session-key handling, as our tinytuya guide notes. From 3.4 on, a connection opens with a handshake that sets up a session key. One independent ESP32 implementation describes 3.4 as AES-ECB with HMAC-SHA256 after that handshake, and 3.5 as AES-GCM. That is a third-party reading of a reverse-engineered protocol, not Tuya documentation, so treat the cipher detail as indicative.
| Version | What the sources say | Key / crypto note | Discovery broadcast |
|---|---|---|---|
| 3.1 | Oldest listed. Key mainly encrypts outgoing commands (tuya-local README) | Wrong key may not fail until you control the device | UDP 6666 |
| 3.3 | Common middle version. tuya-local warns auto-detection can confuse it with 3.2 and 3.22 | Wrong key fails at setup | UDP 6667 |
| 3.4 | Session-key handshake. Listed by tinytuya, tuya-local and the original LocalTuya | pyaes still works | UDP 6667 |
| 3.5 | Listed by tinytuya and tuya-local. Original LocalTuya README stops at 3.4 | Needs AES-GCM, so pyaes will not work | UDP 6667, plus 7000 for solicited discovery |
Wrong version and wrong key look alike
The tuya-local README explains something that clears up a lot of confusion. On 3.1 the local key mainly encrypts the commands you send, so a wrong key does not fail during setup and only shows up when you try to control the device. On newer versions the key also decrypts what the device sends back, so a wrong key fails during configuration.
That explains why a wrong key looks different across device generations. tinytuya’s error handling explains why a wrong version gets mistaken for one: its error 914 (ERR_KEY_OR_VER) is a single code for both causes.
Our inference, not a sourced diagnostic: if the library cannot tell the causes apart, you cannot either from the symptom alone. A wrong configured version shows up as connect-then-reset, a key error or, as our tinytuya guide notes, a silent timeout, with no message saying “version mismatch”. A client speaking 3.3 to a 3.4 device also skips the handshake the device expects, which fits the connect-then-reset pattern, though no source states that link. So check the version before extracting the key again. No vendor document states that order.
A community log shows the shape: a client connecting on protocol 3.3 while configured for 3.4, then an immediate socket reset, repeating every few seconds, reported as a version mismatch. It comes from a thread about Tuya Local, a Homey app, not the Home Assistant integration tuya-local (its v1.0.174 does not fit make-all’s date-based releases). Treat it as an illustration, not a bug to look up.
When a previously good key stops working, that is a separate failure, covered in why a Tuya local key seems to stop working.
Finding your device’s version
There are three routes, in rough order of reliability.
Scan with tinytuya. The network scan lists each device’s IP address, ID and detected version, which is the cleanest answer when it works. Our tinytuya guide covers running it without Home Assistant.
python3 -m tinytuya scan
The scan listens for the UDP broadcasts devices send, and the port already hints at the generation: 6666 for 3.1 and 3.2, 6667 for 3.3 and later, and 7000 for solicited discovery on 3.5 devices. Control then runs over TCP 6668. Broadcasts do not cross VLANs, so a scan from another subnet comes back empty even when everything else is fine. Our guide to Tuya on an IoT VLAN covers the cross-subnet side, and blocking Tuya devices from the internet covers the no-internet setup.
Let tuya-local auto-detect. tuya-local recommends auto when you are unsure, but warns that it can confuse 3.2, 3.3 and 3.22 and suggests trying other versions if commands are unreliable. Auto is a good first pass and a poor final answer for a flaky device.
Trial and error. Last resort. In LocalTuya you pick the version from a list, and the original README gives no advice on choosing. With a scan result in hand this should not be necessary.
Some devices have 22-character IDs, which tinytuya calls “Device22”. Per tinytuya’s README they need extra configuration, an explicit device type and data points, to poll correctly. tuya-local separately lists a 3.22 option, which its README says auto-detection can confuse with 3.2 and 3.3. We could not confirm from the documentation whether 3.22 is tuya-local’s handling for these devices. If a scan shows a 22-character ID and status polling returns nothing useful, read up on Device22 handling, and in tuya-local include 3.22 among the versions you try.
Which integration handles which version
As of October 2026, the table below reflects README-level statements only.
| Tool | Versions stated | Auto option |
|---|---|---|
| tinytuya | 3.1 to 3.5 (caller must specify) | Scan reports detected version |
| tuya-local | auto, 3.1, 3.2, 3.3, 3.4, 3.5, 3.22 | Yes |
| LocalTuya, original (rospogrigio) | 3.1 to 3.4 | Not mentioned |
| LocalTuya, xZetsubou fork | Not confirmed for this piece | Not confirmed |
The LocalTuya rows need context. The original repository’s README lists 3.1 to 3.4 and says nothing about 3.5 or an auto option, but that repository has stalled. Our LocalTuya vs tuya-local comparison explains why xZetsubou/hass-localtuya is the fork the community points at. We could not confirm the fork’s protocol list for this piece, and READMEs can lag code, so check the fork’s own documentation before relying on it for a 3.5 device. Separately, the 2026 Home Assistant core breakage affects LocalTuya regardless of protocol.
For a Practitioner starting fresh on a mixed fleet, tuya-local is the lower-risk choice on paper, because its README lists every version and has an auto option. Setup is gated on the key either way, as our key extraction guide explains.
tuya-local’s cloud-assisted setup fetches credentials from the Tuya cloud using a short-lived token, valid for a few hours, so you can add several devices in a row. Setup touches the cloud once, and runtime is local after that. Do not block the cloud before you have your keys. Getting a key without a developer account covers that route.
Fix order
This is our own reasoning from the sources, not a tested procedure.
- Confirm the local key, and ask when the device was last paired. tuya-local’s README says the key changes each time the device is paired. If nobody has reset it, re-paired it or moved it to another Wi-Fi network since the key last worked, extracting it again returns the same key.
- Confirm the protocol version. Scan with tinytuya, or try tuya-local’s auto option, then pin the version you find.
- Confirm the network path: the discovery and control ports above, and whether the device and Home Assistant can actually reach each other.
- Only then consider a different integration. If your device reports 3.5 and your integration’s documentation stops at 3.4, moving to one that lists 3.5 may be the real fix.
What we could not verify
A few things the sources do not settle, so we are leaving them open.
- Which devices ship 3.5. We found no primary source mapping device models to protocol versions, so we are not naming any.
- Whether a firmware update changes a device’s protocol version. Users report it. LocalTuya issue #2189 describes a device that stopped responding locally, while still working in the Tuya app, after a suspected firmware or protocol change, and our key explainer treats a version bump as a cause. We found no vendor statement or confirmed case.
- Whether Tuya is retiring older LAN versions on new firmware. One unsourced claim says so. We found no primary source, so treat it as rumor.
- What tuya-local’s 3.22 option does, and whether LocalTuya forks support 3.5. Both described above, both unconfirmed.
FAQ
How do I find the protocol version of my Tuya device? Run the tinytuya network scan from a host on the same network segment as the device. It prints the IP, ID and detected version. tuya-local’s auto option is the other route.
What is the difference between 3.3, 3.4 and 3.5? From 3.4 on, a connection starts with a session-key handshake, and 3.5 requires AES-GCM, which is why pure-Python pyaes cannot handle it. The finer detail comes from community reverse-engineering, not Tuya documentation.
Why does LocalTuya connect and then disconnect immediately? One common cause is a version or key mismatch, which tinytuya treats as a single error condition. Another is the Home Assistant 2026 breakage, which is unrelated to protocol.
Does LocalTuya support Tuya protocol 3.5? The original repository’s README lists 3.1 to 3.4, and that repository has stalled. We could not confirm 3.5 support in the maintained xZetsubou fork, so check its README.
Is a wrong local key the same as a wrong protocol version? No, but they can look the same. tinytuya’s error 914 covers both. On 3.1 a wrong key hides until you send a command. On newer versions it fails at setup.
What this research verified
The version lists come from the tinytuya, tuya-local and original LocalTuya READMEs as read in early October 2026. The discovery ports and the session-key credit come from our earlier tinytuya and IoT VLAN articles, which checked them against tinytuya’s documentation. Runtime stays local; the only cloud touch is the key fetch at setup. No scan output is included because no Tuya hardware is on the bench yet.
After setup, check that the integration reports the version your scan found, and that power-cycling the device does not bring back the connect-then-reset pattern. If a stable device starts resetting after a firmware update, rescan before you re-extract the key.