bluetti-bt-lib

Inofficial Library for basic communication to bluetti powerstations. Core functions based on https://github.com/warhammerkid/bluetti_mqtt

The current Roadmap for this project and repositories using this library can be found here

Disclaimer

This library is provided without any warranty or support by Bluetti. I do not take responsibility for any problems it may cause in all cases. Use it at your own risk.

Projects using this library

• Home Assistant Integration
• MQTT Server (planned)
• UPS Server (NUT compatible)

Supported Powerstations and data

Validated

Added and mostly validated by contributors (some are moved here from the HA Integration https://github.com/Patrick762/hassio-bluetti-bt):

Controls

Validated:

Added and mostly validated by contributors:

Battery pack data

Installation

pip install bluetti-bt-lib

Commands for testing

Commands included in this library should only be used for testing.

Scan for supported devices

usage: bluetti-scan [-h] [-r REGEX] [-s SCAN_TIME]

Detect bluetti devices by bluetooth name

options:
  -h, --help            show this help message and exit
  -r REGEX, --regex REGEX
                        Custom regex to match device name
  -s SCAN_TIME, --scan-time SCAN_TIME
                        How long to scan for devices (seconds)

Example output: ['EB3A', '00:00:00:00:00:00']

Detect device type by mac address

usage: bluetti-detect [-h] mac

Detect bluetti devices

positional arguments:
  mac         Mac-address of the powerstation

options:
  -h, --help  show this help message and exit

Example:

bluetti-detect 00:00:00:00:00:00

Example output: Device type is 'EB3A' with iot version 1 and serial 0000000000000. Full name: EB3A0000000000000

Read device data for supported devices

usage: bluetti-read [-h] [-m MAC] [-t TYPE] [-e ENCRYPTION]

Detect bluetti devices

options:
  -h, --help            show this help message and exit
  -m MAC, --mac MAC     Mac-address of the powerstation
  -t TYPE, --type TYPE  Type of the powerstation (AC70 f.ex.)
  -e ENCRYPTION, --encryption ENCRYPTION
                        Add this if encryption is needed

Example:

bluetti-read -m 00:00:00:00:00:00 -t EB3A

Example output:

FieldName.DEVICE_TYPE: EB3A
FieldName.DEVICE_SN: 0000000000000
FieldName.BATTERY_SOC: 92%
FieldName.DC_INPUT_POWER: 0W
FieldName.AC_INPUT_POWER: 0W
FieldName.AC_OUTPUT_POWER: 0W
FieldName.DC_OUTPUT_POWER: 0W
FieldName.CTRL_AC: False
FieldName.CTRL_DC: True
FieldName.CTRL_LED_MODE: LedMode.OFF
FieldName.CTRL_POWER_OFF: False
FieldName.CTRL_ECO: False
FieldName.CTRL_ECO_TIME_MODE: EcoMode.HOURS1
FieldName.CTRL_CHARGING_MODE: ChargingMode.STANDARD
FieldName.CTRL_POWER_LIFTING: False

Write to supported device

INFO: Devices with encryption are currently not supported!

usage: bluetti-write [-h] [-m MAC] [-t TYPE] [--on ON] [--off OFF] [-v VALUE] [-e ENCRYPTION] field

Write to bluetti device

positional arguments:
  field                 Field name (ctrl_dc f.ex.)

options:
  -h, --help            show this help message and exit
  -m MAC, --mac MAC     Mac-address of the powerstation
  -t TYPE, --type TYPE  Type of the powerstation (AC70 f.ex.)
  --on ON               Value to write
  --off OFF             Value to write
  -v VALUE, --value VALUE
                        Value to write (integer, see enum for value)
  -e ENCRYPTION, --encryption ENCRYPTION
                        Add this if encryption is needed

Example:

bluetti-write -m 00:00:00:00:00:00 -t EB3A --on on ctrl_ac

Adding fields

To add new fields, you can use the bluetti-detect command to first find out which version of iot protocol is used and if it uses encryption.

After you got this information, you can use the bluetti-readall command to read every registry and save the data to a json file and a hexdump (10 bytes per line). You should also note all values you see in the app to later compare the data.

Here's how to use the bluetti-readall command:

usage: bluetti-readall [-h] [-m MAC] [-v VERSION] [-e ENCRYPTION]

Detect bluetti devices

options:
  -h, --help            show this help message and exit
  -m MAC, --mac MAC     Mac-address of the powerstation
  -v VERSION, --version VERSION
                        IoT protocol version
  -e ENCRYPTION, --encryption ENCRYPTION
                        Add this if encryption is needed

With the separate tool at bluetti-bt-raw-reader you can view those values in a more understandable way.

You can also share the output with me using this form

To test added fields with the created json file, use bluetti-parse:

usage: bluetti-parse [-h] file

Parse readall output files

positional arguments:
  file        JSON file of the powerstation readall output

options:
  -h, --help  show this help message and exit