DOCSEARCHbyAlgolia
Submit Docs

OpenBK7231T/OpenBeken

repository·main·Indexed 25 days ago

https://github.com/openshwprojects/openbk7231t_app

A multi-platform open-source firmware alternative to Tasmota and ESPHome for Tuya-based modules and various chipsets, including Beken, Bouffalo Lab, WinnerMicro, Espressif, and Realtek. It offers MQTT and Home Assistant integration, an advanced scripting and events system, and support for TuyaMCU, I2C, and SPI drivers. The project provides Docker-based build environments for compiling SDKs across different architectures, including Apple Silicon (ARM) via x86 emulation.

Tokens
56.6K
Snippets
85
Records
310
Agent score
81%

What's inside OpenBK7231T_App

  2. Overview of OpenBK7231T/OpenBeken

    main
    OpenBK7231T/OpenBeken is a firmware alternative to Tasmota and ESPHome designed for modern Tuya-based modules. It provides MQTT and Home Assistant compatibility. While originally focused on the BK7231T chipset, it has evolved into a multi-platform application supporting a wide range of chipsets from vendors such as Espressif, Beken, WinnerMicro, Realtek, and Bouffalo Lab.

  3. Overview of OpenBeken features

    main

    OpenBeken is a highly configurable firmware for various Wi-Fi modules. Key capabilities include:

    • Tasmota Compatibility: Supports Tasmota-like setup, configuration, and common Tasmota JSON over HTTP and MQTT.
    • Home Assistant Integration: Supports MQTT compatibility with both YAML generator and Home Assistant Discovery.
    • Extensible Driver System: Includes support for TuyaMCU (with an analyzer tool), I2C (e.g., AHT30, BME680, MCP23017), SPI (e.g., BL0942SPI), and specialized drivers like Motor Driver Bridges and synchronized PWM groups.
    • Scripting & Automation: Features an advanced scripting and events system (mirroring Tasmota rules) and supports LittleFS for storing scripts and large files. You can also use a short startup command (up to 512 characters) in flash config for quick driver initialization.
    • Power Management: Advanced deep sleep with GPIO/timer wakeup and hybrid power save systems.
    • Custom UI: Uses LittleFS and a REST API to host custom HTML/CSS/JS pages directly on the device for custom GUIs.
    • Lighting: Supports RGBCW LED control (compatible with Home Assistant) and DDP lighting protocol (for xLights).

  5. Understand platform-specific feature constraints and warnings

    main

    When reviewing the platform support matrix, pay attention to the following specific constraints and implementation details:

    OTA (Over-the-Air Updates)

    • Partition Layout: For some platforms (e.g., BK7231S/U), success depends on the partition layout set in the bootloader. Using SPI flash QIO firmware is recommended for guaranteed success.
    • Methodology: For BL602/LF686, LN882H, TR6260, and others marked with ⁴, OTA is only available in the Web App, not via HTTP.
    • Exclusions: OTA is excluded for the 1MB variation of certain chips (²).
    • Tuya BK7252 Warning: OTA on Tuya BK7252 is not supported. The stock bootloader will not perform the update, and using a custom bootloader may brick the device because it won't encrypt the main partition on unpack (¹⁴).

    WiFi and WPA3

    • Manual Enablement: For ESP8266/ESP32, WPA3 must be manually enabled in sdkconfig.defaults by setting CONFIG_ESP8266_WIFI_ENABLE_WPA3_SAE or CONFIG_ESP_WIFI_ENABLE_WPA3_SAE to y (¹³).
    • Build Variants: WPA3 support for BK7231T/N is only available in _ALT builds (¹²).

    Peripherals and GPIO

    • PWM: Software PWM is used on some platforms (e.g., ESP8266/ESP32), which may result in flickering (⁷). On some platforms, PWM channels may overlap, so be careful with pin assignments (⁸).
    • Interrupts: For GD32VW553, be careful with assignments; only one interrupt per pin is supported (e.g., you cannot use A00 and B00 together) (³).
    • IR: IR support is often 'Receive only' (⁹).

    Power Management

    • Deep Sleep: For ESP32, deep sleep is limited to Timer sleep only; GPIO wakeup is not supported (¹⁰).
    • ECR6600 Warning: After waking up, the device may refuse to connect to WiFi until it is power cycled (¹¹).

  6. Use script variables (constants) in commands

    main

    The system provides a set of constants (script variables) that can be used directly within commands to perform logic or mathematical expressions. These variables allow you to access real-time device states, sensor readings, and system information.

    For example, you can use channel variables to perform math in a command, such as setting a channel to a value derived from another channel: setChannel 15 2*$CH14+5.

    setChannel 15 2*$CH14+5

  7. Note on constant naming conventions (v2.5+)

    main

    Since version 2.5, the library has transitioned from using #define for constant definitions to a const approach following the C++ Style Guide.

    Constants now use the kConstantName format (e.g., kMyConstant). While many common #define macros have been aliased for backward compatibility, new protocol implementations will only support the kConstantName style. If your code fails to compile after an update, check if you are referencing a constant that should now use the k prefix.

  9. Supported Chipsets and Modules

    main

    OpenBeken supports a vast array of chipsets. Key families include:

    • Beken Family: BK7231T (e.g., WB3S, WB2S), BK7231N (e.g., CB2S, CB2L), BK7231M (non-Tuya version), BK7231S/U, and BK7238.
    • Bouffalo Lab Family: BL602, BL616/BL618, LF686, and TG7100C.
    • WinnerMicro Family: W800, W801, W803, W600, W601, and T6605.
    • Espressif Family: ESP32 (original and S/C variants) and ESP8266/ESP8285.
    • Realtek (Ameba) Family: RTL8711AM, RTL8710B, RTL8710C/RTL8720C, RTL8720D, and RTL87x1DA.
    • Other: XR809, XR806, LN882H, ECR6600, TXW81X, RDA5981, and GD32VW553.

    For a comprehensive list of supported devices and templates, visit the interactive devices database.

  10. Use Channel Types for improved UI

    main

    Channel types describe the kind of value stored in a channel and are used to provide a better user interface in the OpenBeken web panel. While often not required, they are necessary for specific control patterns.

    Example: For a Tuya Fan Controller with 3 speeds, setting the channel type to LowMidHigh will display a radio button UI instead of a simple toggle or slider.

    Note on TuyaMCU: Some channels use _div10 or _div100 suffixes. This is used for TuyaMCU devices that send values as integers (e.g., sending 215 for 21.5C). The firmware stores the integer and converts it to a float only for display.

  11. Handle TuyaMCU power metering with divider types

    main

    TuyaMCU devices often send power metering values as integers. To display these correctly on the WWW panel, use specific ChannelType variants that include a divider. Note that these types are not used for BL09** or CSE** sensors.

    Common power metering types include:

    • Voltage_div10, Voltage_div100
    • Current_div10, Current_div100, Current_div1000
    • Power, Power_div10, Power_div100
    • Frequency, Frequency_div10, Frequency_div100, Frequency_div1000
    • ActivePower, ReactivePower
    • PowerFactor_div100, PowerFactor_div1000
    • EnergyTotal_kWh_div100, EnergyTotal_kWh_div1000
    • EnergyToday_kWh_div1000
    • EnergyExport_kWh_div1000
    • EnergyImport_kWh_div1000

  12. Automate devices with Console/Script commands

    main

    OpenBeken provides a wide range of console commands to automate device behavior. These commands can be triggered via several methods:

    • Manual entry: Directly in the command line.
    • HTTP: Sent via HTTP requests (similar to Tasmota).
    • MQTT: Sent via MQTT messages.
    • Scripting: Used within internal scripts or autoexec.bat.