logo elektroda
logo elektroda
X
logo elektroda
Advanced Search
logo elektroda

Tuya JSON specification - how to get smart device IO template automatically?

p.kaczmarek2 3090 11

TL;DR

  • OpenBeken’s BK7231GUIFlashTool automatically extracts Tuya JSON to build GPIO templates for smart devices like a 6014HA relay, WiFi LED, and button module.
  • It parses Tuya keys such as rl1_pin, bt1_pin, netled_pin, baud, and module to identify relays, buttons, LEDs, PWM outputs, TuyaMCU, and module type.
  • The feature works from a live device or a 2MB flash backup, and the decoded JSON can be pasted into the template importer.
  • Automatic decoding makes cloudless conversion faster than ESP8266/Tasmota-style manual GPIO probing, with OpenBeken converting the JSON into a template.
  • The key list is not comprehensive, and more Tuya JSON keywords will be added over time.
Generated by the language model.
ADVERTISEMENT
Report a violation of the law
Reply Cool? Ranking DIY | New topic
Notify about new articles
📢 Listen (AI):
  • Sample Tuya configuration JSON with various parameters.
    Automatic Tuya JSON extraction allows you to automatically configure the GPIO template of your smart device. Unlike in Tasmota, where all GPIO probing has to be done manually, OpenBeken flasher BK7231GUIFlashTool is able to extract the Tuya GPIO roles, so it can automatically tell which pin is used for relay, which pins are used for PWMs, which baud is used for TuyaMCU, etc.
    The usage of this feature has been presented already in our video:



    Today I am going to show you few more details about the Tuya JSON inner working.
    Let's start by considering a sample JSON:
    Code: JSON
    Log in, to see the code

    This is a description of a simple 6014HA device, featuring a single relay, WiFi LED and a button.
    The most important keys here start with "rl1_", "netled_", and "bt1_".
    The "rlX_" prefix stands for relay. There can be multiple relays, so X stands for the relay number.
    There are multiple keys for relays:
    Code: C / C++
    Log in, to see the code

    The "lv" key stands for active level. Value 1 means that relay is active-high, so relay is closed when the given GPIO has high level.
    This is a standard for all Tuya products so we are not even parsing that.
    The more important key is rl1_pin, which is a GPIO index of Relay pin. 14 there means that relay is on P14 (not on the 14th pin of QFN case).
    The same logic applies to buttons. There can be also multiple buttons, for example, bt1_pin is a GPIO of a first button, and bt2_pin is a GPIO of second button. Futhermore, there can be also LEDs following relay states, so led1_pin, led2_pin, etc is possible.
    Of course, most of IO roles are not numbered, for example, status_led_pin. Here is more detailed list of Tuya JSON keys:
    - status_led_pin - this is a WiFi pairing LED
    - bz_pin_pin - buzzer pin
    - samp_sw_pin - battery ADC sampling enable pin
    - samp_pin - battery ADC sampling pin used to measure battery voltage
    - i2c_scl_pin and i2c_sda_pin - I2C bus pins
    - alt_pin_pin - ALERT pin (interrupt from temperature/humidity sensor)
    - one_wire_pin - OneWire bus for DS18B20, etc
    - backlit_io_pin - backlight pin
    - max_V and min_V - battery voltages for battery measurement
    - rl_on1_pin and rl_off1_pin - this is used for bridge (bistable) relay
    - k1pin_pin (etc) - alias for button pin
    - door1_magt_pin - door sensor pin for non-TuyaMCU device
    - onoff1, onoff2, etc - this is used to connect old-style bistable switch on relay modules
    - basic_pin_pin - this is a PIR sensor for motion detectors
    - netled_pin - WiFi LED (again), also may be used as netled1_pin
    - ele_pin - BL0937 energy metering pin ELE
    - vi_pin - BL0937 energy metering pin VI (Voltage/Current)
    - sel_pin_pin- BL0937 energy metering sel pin
    - sel_pin_lv - BL0937 sel pin level (usually 1, active-high)
    - r_pin, g_pin, b_pin, c_pin, w_pin - R G B C W PWMs for lamps and LEDs
    - micpin, also sometimes mic - microphone input for music-based effects
    - ctrl_pin - it seems it may be a LED strip controller button
    - mosi - SPI MOSI, always 16 on Beken, used for example to drive WS2812B
    - buzzer_io - again, buzzer pin
    - buzzer_PWM - buzzer PWM frequency
    - irpin or infrr - IR input (receiver)
    - infre - IR output (sending)
    - reset_pin - reset/pair button
    - wfst_pin - WiFi state LED, again, pairing LED
    - pwmhz - PWM frequency (for LED?)
    - pirsense_pin - PIR sensitivity adjustment (probably via PWM)
    - pirlduty - PIR adjust duty (min)
    - pirfreq - PIR adjust frequency
    - pirmduty - PIR adjust duty (max)
    - pirin_pin - PIR input (read this value to detect PIR state, 1 or 0)
    - total_bt_pin - again, reset/pair button
    There are also some twowire (I2C-like) LED controllers, like SM2253, BP5758. They are using keys:
    - iicscl - I2C (not really I2C, because adressation is missing) Clock
    - iicsda - I2C (as above) Data
    I haven't investigated it fully, but it seems that LED drivers have separate RGB and CW (or separately, C and W) current limits.
    - ehccur, wampere, iicccur - SM2135 current levels (color mode?)
    - dccur - BP5758D current level (color mode?)
    - dwcur - BP5758D current level (cool/warm mode?)
    - cjwcur - BP1658CJ current level (cool/warm mode?)
    - cjccur - BP1658CJ current level (color mode?)
    - _2235ccur - SM2235 current level (color mode?)
    - _2335ccur - SM2335 current level (color mode?)
    - kp58wcur - KP18058 current level (cool/warm mode?)
    - kp58ccur - KP18058 current level (color mode?)
    - iicr, iicg, iicb, iicc, iicw - color indexes for I2C-like RGBCW drivers (they are not standarized)
    Futhermore, there is BL0942 and TuyaMCU related keyword:
    - baud - TuyaMCU/BL0942 communication baud rate
    And there is a generic information keyword:
    - module - name of the WiFi module, like CBU, CB3S, etc

    The list above is not comprehensive and more information will be added there over time.

    To extract Tuya Config JSON from a live device or from 2MB flash backup, use our flasher:
    https://github.com/openshwprojects/BK7231GUIFlashTool
    To decode Tuya JSON, you can use our online utility:
    https://openbekeniot.github.io/webapp/templateImporter.html
    For some sample Tuya flash dumps, check out flash dumps library:
    https://github.com/openshwprojects/FlashDumps

    As you can see, Tuya JSON decoding can make "cloudless" conversion of your Tuya device much faster and easy than it was in case of ESP8266/Tasmota devices. Most of the related GPIO roles are included in JSON, so you don't have to guess anymore. Futhermore, OpenBeken can automatically convert Tuya JSON to a template, so all you have to do is just to copy and paste the extracted text.

    Cool? Ranking DIY
    Helpful post? Buy me a coffee.
    About Author
    p.kaczmarek2
    Moderator Smart Home  
    Offline 
    p.kaczmarek2 wrote 14394 posts with rating 12315, helped 650 times. Been with us since 2014 year.
  • ADVERTISEMENT
  • #2 21155828
    divadiow
    Level 38  
    Posts: 4839
    Help: 420
    Rate: 852
    very interesting.

    I fed ChatGPT all the cloudcutter json files and it came back with this deduped list.

    Code: Text
    Log in, to see the code
  • #3 21156229
    p.kaczmarek2
    Moderator Smart Home  
    Posts: 14394
    Help: 650
    Rate: 12315
    They don't have all pins, for example, "micpin" seems to be missing.
    Helpful post? Buy me a coffee.
  • #4 21156243
    divadiow
    Level 38  
    Posts: 4839
    Help: 420
    Rate: 852
    true. those are included in the jsons but my GPT request wasn't good enough. anyway, it's a snapshot of the variety used, as you say in the first post.
  • ADVERTISEMENT
  • #5 21156244
    p.kaczmarek2
    Moderator Smart Home  
    Posts: 14394
    Help: 650
    Rate: 12315
    Btw those key names doesn't seem standarized, as I have seen both "micpin" and "mic"
    Helpful post? Buy me a coffee.
  • #6 21156250
    divadiow
    Level 38  
    Posts: 4839
    Help: 420
    Rate: 852
    it'd be a bit of task to have Easy Flasher cater for them all I guess
  • ADVERTISEMENT
  • Helpful post
    #7 21447785
    divadiow
    Level 38  
    Posts: 4839
    Help: 420
    Rate: 852
    netled_reuse also indicates if an LED is shared - I guess for wifi then for on/off purposes once wifi established. This could be used to assign a new dual-purpose pin assignment that changes the LED behaviour after wifi connected - removing the need for any autoexec script.

    https://www.elektroda.com/rtvforum/find.php?q=netled_reuse
  • ADVERTISEMENT
  • #8 21447813
    p.kaczmarek2
    Moderator Smart Home  
    Posts: 14394
    Help: 650
    Rate: 12315
    So you'd like to have a separate LED pin role? I don't know, LED_State? StateLED?
    Helpful post? Buy me a coffee.
  • #9 21447841
    divadiow
    Level 38  
    Posts: 4839
    Help: 420
    Rate: 852
    An idea perhaps. I think I saw this floated before somewhere. Even if netled_reuse is wrong (I don't think it is), a single assignment to change the behaviour of LED depending on wifi connection would be a cool thing.
  • #10 21447878
    insmod
    Level 31  
    Posts: 1353
    Help: 160
    Rate: 425
    My idea is to make keep WifiLED, but allow assigning channel to it. So, as soon as wifi is connected, it would act like a led for assigned channel.
    But, if channel is 0, then keep original behavior.
  • #11 21447955
    p.kaczmarek2
    Moderator Smart Home  
    Posts: 14394
    Help: 650
    Rate: 12315
    Good idea but not perfect - channel 0 is often used for relays, so it's a normal channel, not a special value.
    We can't do -1 as well, because channel indexes are stored as unsigned byte....
    Maybe we could introduce a special value or something, like 255.
    Helpful post? Buy me a coffee.
  • #12 21834399
    divadiow
    Level 38  
    Posts: 4839
    Help: 420
    Rate: 852
    I got LLM to make a bulk bin file finder, Tuya KV locator, decrypter and json extractor for the purpose of extracting all pins in user_param_keys Easy Flasher is not yet handling. This was run against FlashDumps and a load of other local collections scraped from various places.

    Initial findings:

    JSON files in ZIP: 1609
    Unique (byte-identical de-dupe): 1361
    Duplicates removed: 248
    (Counts shown as: unique KVs / total files, after byte-identical de-dupe in the combined pack.)

    Pin assignment keys to add
    1) key_pin (+ key_lv) — 15 / 18
    - Map as: Button input (like bt*_pin / k*pin_pin) + polarity via *_lv

    2) sound_pin — 6 / 6
    - Map as: Buzzer/Sounder output (same bucket as buzzer_io / bz_pin_pin)

    3) total_led_pin (+ total_led_lv) — 4 / 4
    - Map as: Indicator LED pin (status/overall LED)

    4) display_led1_pin (+ display_led1_lv) — 2 / 2
    - Map as: Indicator LED pin (treat like led1_pin)

    5) net_led_pin (+ net_led_lv) — 2 / 3
    - Map as: WiFi/Status LED alias (treat like netled_pin / netled1_pin) or report as TODO

    6) lightplus_sw_pin (+ lightplus_sw_lv) — 2 / 2
    7) lightminus_sw_pin (+ lightminus_sw_lv) — 2 / 2
    - maybe map as: Button inputs (brightness +/- style); polarity via *_lv or report as TODO

    8) tamper_pin_pin (+ tamper_pin_lv) — 1 / 1
    - maybe map as: Digital input (tamper switch); polarity via *_lv or report as TODO

    GPIO-bearing keys to surface (pins, but role not safe to auto-assign)
    9) zero_io_pin — 2 / 2
    - Likely timing/zero-cross style input; recommend “report only” for now

    10) hl_ctl_io_pin — 2 / 2
    11) a_ctl_io_pin — 2 / 2
    12) p_sw_io_pin — 2 / 2
    - “control IO” pins (ECR6600-style); recommend “report only” for now

    13) Singletons (report only): expowctrl_pin, p_type_pin, l_pin, m_pin — 1 / 1 each
    14) RGB naming variants (report only unless you want to treat as PWM pins):
    red_pin, green_pin, blue_pin — 1 / 1 each (+ corresponding *_lv seen)

    “Pins” that don’t include “_pin” but should be handled as aliases
    15) ir — 12 / 17
    - Map as: IR Receiver pin (alias to irpin/infrr-style meaning)

    16) MOSI — 2 / 2
    17) MISO — 3 / 3
    - Map as: SPI MOSI/MISO aliases (tuyaconfig.cs only handles uppercase MOSI/MISO)

    UART-ish GPIO assignments
    18) ele_rx / ele_tx — 14 / 16
    19) series_rx / series_tx — 4 / 6
    - Recommend printing as: “UART (ele/series) RX/TX on Pxx”

    Not factored in EF assignments: polarity / active-level keys
    Top prevalence *_lv keys in this pack (unique KVs with user_param_key):
    - rl1_lv 314
    - bt1_lv 240
    - netled1_lv 203
    - total_bt_lv 116
    - netled_lv 104
    - rl2_lv 101
    - led1_lv 82
    - sel_pin_lv 74
    - wfst_lv 26
    - key_lv 15
    - basic_pin_lv 13
    - status_led_lv 13
    (Plus many others: bt2_lv, rl3_lv, etc.)

    We already have Role vs Role_n variants (Btn/Btn_n, Rel/Rel_n, LED/LED_n, WifiLED/WifiLED_n, BL0937SEL/BL0937SEL_n, etc.), so wiring *_lv into role selection seems like it could be straight forward.

    Obviously all needs checking and proving out.
Reply Cool? Ranking DIY | New topic
Notify about new articles
📢 Listen (AI):
Report a violation of the law

Topic summary

✨ The discussion focuses on the automatic extraction of Tuya JSON configurations to identify GPIO roles in smart devices, enabling automatic setup of IO templates without manual probing as required in Tasmota. The OpenBeken BK7231GUIFlashTool is highlighted for its capability to extract pin functions such as relays, PWMs, and TuyaMCU baud rates from JSON files. A deduplicated list of common GPIO key names extracted from cloudcutter JSON files was shared, including pins like alarm_pin, bt1_pin, relay_pin, and netled_pin, though some keys like "micpin" are missing or inconsistently named (e.g., "micpin" vs. "mic"). The lack of standardized key naming complicates comprehensive support in flashing tools like Easy Flasher. Additionally, the concept of dual-purpose LED pins was discussed, particularly the "netled_reuse" flag indicating shared LED usage for WiFi and device status. Proposals include assigning WiFi LED behavior to specific channels, with considerations on channel numbering constraints and potential use of special values (e.g., 255) to differentiate LED roles. These insights aim to improve automatic GPIO role detection and flexible LED behavior assignment in Tuya-based smart device firmware.
Generated by the language model.
Today's popular

FAQ

TL;DR: From a live device or a 2MB flash dump, OpenBeken tools can extract Tuya JSON and auto-build a GPIO template. As the thread puts it, "you don't have to guess anymore." This FAQ is for Tuya modders who want faster pin mapping, relay setup, LED detection, and TuyaMCU baud discovery without manual probing. [#21155505]

Why it matters: Tuya JSON turns reverse-engineering from trial-and-error into a repeatable import workflow for BK7231 and related Tuya devices.

Method GPIO discovery Relay/button/LED mapping TuyaMCU baud detection Typical effort
OpenBeken + Tuya JSON Automatic from extracted JSON Yes Yes Copy, paste, convert
Tasmota manual probing Manual Manual Manual investigation Much slower

Key insight: The most useful Tuya JSON fields are the pin-role keys, such as relay, button, LED, UART, and metering entries. Once extracted, OpenBeken can convert many of them straight into a usable template. [#21155505]

Quick Facts

  • A sample Tuya JSON in the thread describes a 6014HA device with 1 relay, 1 WiFi LED, and 1 button, showing how a small smart switch exposes usable pin metadata. [#21155505]
  • BK7231GUIFlashTool can extract Tuya config from a live device or a 2MB flash backup, then feed that data into OpenBeken template generation. [#21155505]
  • A bulk scan shared later covered 1609 JSON files inside ZIPs, reduced to 1361 unique entries after removing 248 duplicates by byte-identical de-duplication. [#21834399]
  • In the sample JSON, rl1_pin is P14, netled_pin is P24, and bt1_pin is P26; these are GPIO indexes, not package-pin numbers. [#21155505]

How do I automatically extract a Tuya JSON configuration from a live device or a 2MB flash dump with BK7231GUIFlashTool?

You use BK7231GUIFlashTool to read the Tuya configuration and then export the JSON. 1. Connect to the live device or open a 2MB flash backup. 2. Extract the Tuya Config JSON with the flasher. 3. Copy the extracted text into the OpenBeken decoder to generate a template. This workflow is explicitly described for both live devices and 2MB dumps, so you do not need manual GPIO probing first. [#21155505]

What is Tuya JSON, and how does it help OpenBeken build a GPIO template automatically?

Tuya JSON is the device configuration blob that lists hardware roles such as relay pins, button pins, LED pins, and communication settings. OpenBeken uses those keys to infer functions like relay output on P14, WiFi LED on P24, and button input on P26 in the sample device. Because the JSON already names many roles, OpenBeken can convert the extracted text into a GPIO template automatically instead of asking you to guess each pin. [#21155505]

Why is Tuya JSON-based GPIO detection easier in OpenBeken than manual GPIO probing in Tasmota?

It is easier because the Tuya JSON already contains many GPIO roles, so OpenBeken can parse them directly. The thread contrasts this with Tasmota, where all GPIO probing must be done manually. In the OpenBeken flow, relay pins, PWM pins, and even TuyaMCU baud can come from the JSON, which removes much of the trial-and-error process. The practical result is faster cloudless conversion with fewer wrong pin assignments. [#21155505]

How should I interpret common Tuya JSON keys like rl1_pin, bt1_pin, netled_pin, and baud?

Interpret them as hardware-role fields tied to specific GPIO indexes or communication settings. rl1_pin means relay 1 GPIO, bt1_pin means button 1 GPIO, netled_pin means WiFi LED GPIO, and baud means the UART speed used for TuyaMCU or BL0942 communication. In the sample JSON, rl1_pin is 14, netled_pin is 24, and bt1_pin is 26. Those values map to P14, P24, and P26, not to package pin positions. [#21155505]

What does the Tuya JSON active-level field like rl1_lv or bt1_lv mean, and how should it be used?

It defines which logic level makes that function active. For example, rl1_lv:1 means the relay is active-high, so the relay closes when that GPIO goes high. The same pattern applies to buttons, LEDs, and other roles with *_lv fields. Later analysis also showed many active-level keys in real dumps, including rl1_lv in 314 unique KVs and bt1_lv in 240, which makes polarity handling important for correct template assignment. [#21834399]

Which Tuya JSON keys are used for relays, buttons, LEDs, PIR sensors, BL0937 energy metering, and TuyaMCU communication?

Relays use keys like rl1_pin, buttons use bt1_pin or k1pin_pin, LEDs use led1_pin, netled_pin, status_led_pin, or wfst_pin, PIR uses basic_pin_pin, pirin_pin, and pirsense_pin, BL0937 uses ele_pin, vi_pin, and sel_pin_pin, and TuyaMCU communication uses baud. The thread also lists bistable-relay keys such as rl_on1_pin and rl_off1_pin, plus battery, I2C, OneWire, and RGB PWM keys. That breadth is why Tuya JSON is so useful for auto-mapping. [#21155505]

Where can I paste and decode an extracted Tuya JSON online to convert it into an OpenBeken template?

You can paste it into the OpenBeken online template importer mentioned in the thread. The author states that the extracted Tuya JSON can be decoded with the web utility and then converted into a template, so the workflow is copy-and-paste rather than manual reconstruction. The same post also points to BK7231GUIFlashTool for extraction and a flash-dump library for examples, which makes the importer part of a larger toolchain. [#21155505]

What is TuyaMCU in the context of Tuya JSON, and what does the baud key tell me about the device?

baud tells you the communication speed used by the TuyaMCU or BL0942 link on that device. "TuyaMCU" is a device-side microcontroller that handles functions through a serial link, with a JSON-exposed baud setting that tells OpenBeken how that UART is configured. In practice, the thread treats baud as a direct clue for automatic setup, alongside GPIO roles, so it helps identify how the WiFi module talks to the rest of the hardware. [#21155505]

How complete is the list of Tuya JSON pin names, and why do aliases like micpin and mic both appear?

The list is useful but not complete, and aliases exist because Tuya key naming is not fully standardized. The thread explicitly says the list is not comprehensive and will grow over time. It also gives a concrete alias example: both micpin and mic were seen for microphone input. A later reply adds that a GPT-generated key list missed micpin, which shows why Easy Flasher and related parsers must handle variants rather than relying on one exact spelling. [#21156244]

What is the difference between netled_pin, net_led_pin, status_led_pin, wfst_pin, and netled_reuse in Tuya devices?

They all relate to LED behavior, but they do not mean exactly the same thing. netled_pin and net_led_pin are WiFi LED names, with net_led_pin appearing later as an alias candidate. status_led_pin and wfst_pin also refer to pairing or WiFi-state LEDs. netled_reuse is different: it indicates that one LED may be shared, first for WiFi state and later for on/off or channel state after connection. That makes it a behavior flag, not just a pin name. [#21447785]

How could OpenBeken handle a shared WiFi/status LED after connection when netled_reuse indicates dual-purpose behavior?

A practical approach is to keep the WiFi LED role and allow a channel assignment after WiFi connects. One proposal in the thread says the LED should keep normal WiFi behavior until connection, then act as the LED for an assigned channel. Another post notes a hard edge case: channel 0 is already a normal relay channel, and -1 cannot be used because the value is stored as an unsigned byte. A special value such as 255 was suggested instead. [#21447955]

Which additional user_param_key pin names are still missing from Easy Flasher handling, such as key_pin, sound_pin, total_led_pin, or ele_rx and ele_tx?

The thread identifies several missing or under-handled keys, including key_pin, sound_pin, total_led_pin, display_led1_pin, net_led_pin, lightplus_sw_pin, lightminus_sw_pin, tamper_pin_pin, zero_io_pin, hl_ctl_io_pin, a_ctl_io_pin, p_sw_io_pin, ir, MOSI, MISO, ele_rx, ele_tx, series_rx, and series_tx. The later bulk analysis ranked them by frequency, with key_pin at 15/18, sound_pin at 6/6, and ele_rx/ele_tx at 14/16. Those counts help prioritize Easy Flasher updates. [#21834399]

When should a newly discovered Tuya JSON GPIO key be auto-assigned in Easy Flasher, and when is it safer to report it only?

Auto-assign it when the role is clear and consistent across devices, and report it only when the role is ambiguous. The thread treats key_pin, sound_pin, and total_led_pin as strong candidates for direct mapping because they clearly match button, buzzer, or indicator LED functions. By contrast, keys such as zero_io_pin, hl_ctl_io_pin, a_ctl_io_pin, and p_sw_io_pin were recommended as report-only because their exact function is not yet safe to assign automatically. That policy reduces wrong templates. [#21834399]

How do SPI and IR-related aliases like MOSI, MISO, ir, irpin, infrr, and infre show up in Tuya JSON, and how should they be mapped?

They appear as both standard and alias-style names, so the parser should normalize them. The thread lists mosi as SPI MOSI, later reports uppercase MOSI and MISO as aliases, and suggests mapping them as SPI pins. For infrared, it lists irpin or infrr as IR receiver input and infre as IR sender output, while later analysis adds plain ir as another receiver-style alias seen 12/17 times. Normalizing these names prevents missed assignments. [#21834399]

What are BL0937, BL0942, SM2135, BP5758D, and BP1658CJ in Tuya-based devices, and which JSON keys usually identify them?

They are chip families identified through characteristic Tuya JSON keys. "BL0937 is an energy-metering IC that exposes measurement-related pins, with separate ELE, VI, and selector signals in Tuya JSON.ele_pin, vi_pin, and sel_pin_pin usually point to BL0937, while baud can indicate BL0942 or TuyaMCU serial communication. LED-driver families such as SM2135, BP5758D, and BP1658CJ appear through current-limit and I2C-like keys, including ehccur, dccur, dwcur, cjwcur, cjccur, iicscl, and iicsda. [#21155505]
Generated by the language model.
ADVERTISEMENT