ioBroker.ecoflow-mqtt

Tests:

ecoflow-mqtt adapter for ioBroker

connects to products of Ecoflow ([https://www.ecoflow.com])

WARNING

This adapter uses a non-offical communication with the devices. Wrong communication or setting wrong values can affect the functionality of the device and may lead to exclusion from the service.

The adapter is based on the work of:

• my own evaluation and research
• https://github.com/tolwi/hassio-ecoflow-cloud
• https://haus-automatisierung.com/hardware/2023/02/13/ecoflow-river-2-usv-batteriespeicher.html
• https://forum.iobroker.net/topic/66743/ecoflow-connector-script-zur-dynamischen-leistungsanpassung
• https://konkludenz.de/en/making-ecoflow-wave2-smart-home-capable-with-node-red-and-mqtt

Installation

The adapter is in stable repository and therefore you can install it by searching it. If updates are available the you should install them.

If a very new version is available it might be neccesary to make a custom install from npm/github. In such case the expert mode must be enabled to get access to the "octacat" icon.

EF credentials

In Admin Page (first tab) the mqqt credentials for the mqqt Broker need to be inserted.

• UserName - something like "app-...."
• UserID - a 19 digit number
• UserPassword - an alphanumeric
• ClientID - a string starting with "ANDROID_...."

There are 3 possibilities:

1. by script https://github.com/mmiller7/ecoflow-withoutflow/blob/main/cloud-mqtt/ecoflow_get_mqtt_login.sh
2. by website https://energychain.github.io/site_ecoflow_mqtt_credentials/
3. by adapters own alogorithm (pressing the button), for this the ecoflow username and password is necessary.

The mqqt Broker settings are default and usually need no modification.

Device setup and Configuration

Use the tab "Device(s) Configuration" for adding your equipment.

• add a new row
• set the deviceID of Powerstream as shown in the app, something like "HW51...."
• give it a name
• select the version (600W or 800W)

• add a new row
• set the deviceID of Powerstation as shown in the app, string varies by type of device
• give it a name
• select the device type
• if additional battery pack is connected, check the port number where it is connected

• add a new row
• set the deviceID of Smart Plug as shown in the app, something like "HW52...."
• give it a name
• set the type to "plug"

• add a new row
• set the deviceID of Shelly as shown in the app, please be aware that the ID is different to the Shelly device itself
• give it a name
• set the type to "Shelly3EM"

• add a new row
• set the deviceID of Generator as shown in the app, something like "DGEB...."
• give it a name
• set the type to "Generator"

• add a new row
• set the deviceID of Generator as shown in the app, something like "SP10...."
• give it a name
• set the type to "SHP" or "SHP2"

• add a new row
• set the deviceID of power kit as shown in the app, something like "M10...."
• give it a name
• set the type to "Power Kit BP2000" or "Power Kit BP5000"
• if there is a second or third battery connected, then check it as slave1 or slave2

• add a new row
• set the deviceID of Generator as shown in the app, something like "HJ31...."
• give it a name
• set the type to "Power Ocean"
• if there is a second or third battery connected, then check it as slave1 or slave2

• add a new row
• set the deviceID of Smart Plug as shown in the app, something like "KT21ZCH..."
• give it a name
• set the type to "Wave2"

• add a new row
• set the deviceID of Smart Plug as shown in the app, something like "BX11ZCB..."
• give it a name
• set the type to "Glacier"

Use the tab "Homeassistant" for setup of MQTT connection to HA

• enable the service
• set the user settings of the MQTT Broker of HA
• set the connection parameter of the MQTT Broker of HA
• select debug settings if required

Modification at HA side:

• The adapter uses the discovery function in HA, no configuration of datapoints in HA is needed.
• MQTT add-on ...

Updating the adapter

Usually it is enough to install the next version on top of the old one. In some cases (e.g. 1.0.0) it might be needed to erase the whole object tree. If datapoint related values are changed, like min or max of the range, the you have to:

• stop the adapter
• deleted the concerned datapoints
• start the adapter After this the new ranges are taken over.

ioBroker adapter functions

• the defined devices are connected to the adapter via mqtt
• the adapter filters the incomming messages of the devices. only changed values are stored internally
• if the App prevents adjusting at a certain condition, when known it is replicated (e.g. inverter ON when below minimum battery charge is prevented, you can see a warning in the log )
• not everything is known, so information to status interpretation may be uncertain, this is mostly marked with trailing "?"

remarks to update of data point setup (min, max, unit, ....)

If settings to a data point are changed in the new version of adapter (e.g. name, unit, max value) the change is not effective until you:

• stop the adapter instance
• delete the respective datapoint or the whole object structure of the adapter instance
• start the adapter instance

During startup the datapoints are created, but not changed when existing.

remarks to warnings/errors

Some occurances in the adapter are tagged as warning or error in order to appear in the log when the loglevel is in info mode. This is not necessarily a failure or an indicator for not working adapter, it is more a sign for a not expected behaviour. The cause might not be in the adapter itself, but the attention is set.

HA connector/gateway

• the MQTT discovery function in HA enables an elegant way of information exchange
• the MQTT discovery function may not be activated when MQTT broker is already running in HA, it needs to be enabled during reconfiguration of MQTT service
• at each start of iobroker adapter all discovery objects are transmitted to HA (even they should retain in HA)
• iobroker adapter filters the incomming messages of the devices. only changed values are stored internally and transferred to HA.
• if a value is not set by device data update, it will appear as unknown in HA
• if the device is reachable, then the availability will be shown in the device connectivity, this is inherited to the "sub-devices" (unavailability is precessed in the same way)

annotations to functionality

• Due to to the asynchronity of information updates and command transfer sometimes race conditions may be visible. So a switch is commanded and its toggling back and forth before it stays, can be observed.
• restart of HA may not be recognized correctly in iobroker, so it needs a manual restart of the adapter (WIP)

Implemented Devices & Structure with Datapoints

some explanation to the device data

• number -> data point with numeric value
• level -> adjustable data point with numeric value, sometimes also selections which have numeric representation
• switch -> adjustable data point boolean
• diagnostic -> boolean or multi state data point transferred to text
• string -> datapoint as text only
• array -> datapoint with array
• value to text conversion might use a non-validated text (feedback is welcome), this is indicated be "?" at the end of text

Powerstation

River Max

River Pro

Delta Mini

Delta

Delta Max

Delta Pro

River 2 Max

River 2 Pro

Delta 2

Delta 2 Max

Delta Pro Ultra

Smart Home Panel

Smart Home Panel

Smart Home Panel 2

Power Kit & Hub

Power Kit

Power Ocean

Power Ocean

Generator

Generator

Dual Fuel generator is not available, could be implemented, if data is available.

Powerstream

Powerstream

The 800W version is also implemented and only difference ist the 800W maximum power. supply priority -> 0/false = prioritized grid supply; -> 1/true = prioritized battery supply (charging)

Smart Plugs

Smart Plug

Shelly devices

Shelly3EM

Wave 2 Air conditioner

Wave2

Wave is not available, could be implemented, if data is available.

Glacier refrigerator

Glacier

ToDo

• check forgotten boundary conditions for commands (inhibit cmd, or additional value)
• check beep command if reversing needed
• SlaveBattery DM, outWatts multiplication by 10
• more getCmds for SHP values

Changelog

1.0.5 (npm)

• (foxthefox) mppt.outWatts 500 -> 600; inverter_heartbeat.invOutputWatts 800 -> 810
• (foxthefox) update of Readme (adapter now in stable)
• (foxthefox) changes for responsive design #160

1.0.4 (npm)

• (foxthefox) some more protobuf decoding for power ocean (ev pulse portion)
• (foxthefox) correction for powerkit telegram reception #99
• (foxthefox) corrected/imroved powerkit datapoints

1.0.3 (npm)

• (foxthefox) watth16/17/18 upper range 10kWh
• (foxthefox) 'Backup reserve' option added for D2M #137
• (foxthefox) preparations for DeltaPro3 decode

1.0.2 (npm)

• (foxthefox) correction of SHP commands (#130)

1.0.1 (npm)

• (foxthefox) correction to level commands (not recognized when appendix level.xxx)
• (foxthefox) "this." for timer functions
• (foxthefox) corrected some debug functions
• (foxthefox) min js-controller = 5.0.12

1.0.0 (npm) BREAKING

• (foxthefox) correction of state roles (requires deletion of ecoflow objecttree!)
• (foxthefox) deletion of InverterHeartbeat2 of power stream, since latest FW does not deliver this telegram anymore (most likely part of the larger inverter_heartbeat)
• (foxthefox) some multiplication and max settings for SHP and Power Ocean corrected,

0.0.42 (npm)

• (foxthefox) correction SHP command
• (foxthefox) new data point power ocean, range min corrections
• (foxthefox) shelly3em model definition
• (foxthefox) IOB checker corrections

0.0.41 (npm)

• (foxthefox) correction in Compare function

0.0.40 (npm)

• (foxthefox) IOB checker corrections

0.0.39 (npm)

• (foxthefox) update devDeps
• (foxthefox) eslint upgrade and corrections

0.0.38 (npm)

• (foxthefox) additional datapoints for power ocean
• (foxthefox) corrections for upper limit on power ocean data points

0.0.37 (npm)

• (foxthefox) corrections for HA discovery of PowerOcean/SHP2/PowerKit

0.0.36 (npm)

• (foxthefox) correction bmsMaster.cellVol/cellTemp as array for DeltaPro
• (foxthefox) correction for transfer of values derived from protobuf to HA
• (foxthefox) enhanced to device specific logging

0.0.35 (npm)

• (foxthefox) unified detail debug settings, device specific debugging (new checkbox in device config)

0.0.34 (npm)

• (foxthefox) first implementation for power ocean kit
• (foxthefox) first implementation for smart home panel 2
• (foxthefox) new values watth16/17/18 for powerstream
• (foxthefox) deltapro max values mmpt.inAmp, mpptTemp
• (foxthefox) fixed updates to info.reconnects
• (foxthefox) fixed #90 cfgAcEnabled on river2max
• (foxthefox) logging enhancements

0.0.33 (npm)

• (foxthefox) added Power Kit
• (foxthefox) added new object ratedPower as command for powerstream

0.0.32 (npm)

• (foxthefox) added Shelly3EM reporting (cloud to cloud connection to be setup in EF App)

0.0.31 (npm)

• (foxthefox) optimization EF MQTT reconnect
• (foxthefox) initial update slave battery to HA
• (foxthefox) online status from latestQuotas
• (foxthefox) adapter config merge all device tabs into one (to overcome the problem that on tablets the last tab is not reachable), size adjustment
• (foxthefox) correction for deltapro at xt60ChgType
• (foxthefox) correction for river2max commands

0.0.30 (npm)

• (foxthefox) correction for River2Pro/Max cmd dcChgCurrent
• (foxthefox) correction for Delta2 cmd dcChgCurrent/pv2DcChgCurrent
• (foxthefox) correction for slave battery transfer to HA

0.0.29 (npm)

• (foxthefox) new objects for wave2
• (foxthefox) device emulation
• (foxthefox) mppt max value corrections

0.0.28 (npm)

• (foxthefox) fix value normalization (DP,wave2,glacier)
• (foxthefox) set actions initially to false to avoid null
• (foxthefox) fix latestQuotas for glacier/wave2
• (foxthefox) enhance logging

0.0.27 (npm)

• (foxthefox) fixed issues with additional battery and homeassistant transfer
• (foxthefox) bmsMaster Delta Pro new points (maxVolDiff,mosState,cellSeriesNum,cellNtcNum)
• (foxthefox) fix issue with SHP heartbeat.errorCodes

0.0.26 (npm)

• (foxthefox) bmasMaster.amp max = 50
• (foxthefox) corrections SHP

0.0.25 (npm)

• (foxthefox) new datapoints for DeltaPro

0.0.24 (npm)

• (foxthefox) SHP incomming data processing

0.0.23 (npm)

• (foxthefox) correction to latestQuotas (shift from info to action)
• (foxthefox) X_Unknown_15 range max 1000
• (foxthefox) new debug button for devices with protobuf msg

0.0.22 (npm)

• (foxthefox) Homeassistant Connector/Gateway
• (foxthefox) added Generator (indication only, no knowledge on commands)
• (foxthefox) added Delta Pro Ultra
• (foxthefox) added Smart Home Panel
• (foxthefox) latestQuotas/getTimeTaskConfig moved from info to action
• (foxthefox) uptime no max boundary
• (foxthefox) several adjustable values which represent a mode or predefined set of settings are now using "states" definition (IOB)
• (foxthefox) changed factor for pd/usb1Watts, usb2Watts, qcUsb1Watts, qcUsb2Watts
• (foxthefox) info for offline/online status with EF cloud
• (foxthefox) correction for protobuf cmds (dataLen)
• (foxthefox) some strings are now diagnostic
• (foxthefox) X_unknown_15/17/34 are now numbers
• (foxthefox) skip telegrams where openBmsIdx=0, bqSysStatReg=0
• (foxthefox) deltapro mppt value changes (inWatts/outWatts max=1600, mult= 0.001)
• (foxthefox) deltapro new values bmsMaster.diffSoc, bmsMaster.packSn

0.0.21 (npm)

• (foxthefox) more debug on connection
• (foxthefox) new datapoints for wave2
• (foxthefox) deleted max on duration values
• (foxthefox) moved several datapoints from number/string to arrays (mainly wave2/glacier)
• (foxthefox) moved datapoints from string to arrays (bms*.hwVersion, bms*.hwEdition, bms*.cellVol, bms*.cellTemp, pd.bmsKitState)
• (foxthefox) plug switch "dynWattEnable" which includes plug for dynamic watts of powerstream

0.0.20 (npm)

• (foxthefox) first additional integration tests
• (foxthefox) corrections in data model
• (foxthefox) new datapoints for glacier
• (foxthefox) new button in config for 'debug quotas' (retrieving data for all JSON-devices and displaying it)

0.0.19 (npm)

• (foxthefox) better error handling of incomplete messages from pstream
• (foxthefox) added indication of time tasks
• (foxthefox) cleanup pstream/plugs creation (both are protobuf)
• (foxthefox) further refactoring of code -> devices must be again defined !
• (foxthefox) differentiation between actual energy values and historical
• (foxthefox) getAllTaskCfg for powerstations in structure info
• (foxthefox) initial lastQuotas after adapter start for powerstream and plug
• (foxthefox) interpreted unknown values have now clear names
• (foxthefox) cyclic latestQuotas call instead of forced disconnect and reconnect (reconnects value only for checking, if stays with 0/null adapter has still mqtt telegrams)
• (foxthefox) new data points for deltamax
• (foxthefox) corrected pstream value changes to 0 (numbers), pdata must be omitted

0.0.18 (npm)

• (foxthefox) correction of wrong version number io io-package.json

0.0.17

• (foxthefox) added ems objects for River2Pro
• (foxthefox) more logging to pstream decode
• (foxthefox) spelling correction for latestQuotas

0.0.16

• (foxthefox) correction for array of devices, cause of "loosing" power stations

0.0.15

• (foxthefox) new implementation of Wave 2 Air conditioner
• (foxthefox) new implementation of Glacier refrigerator
• (foxthefox) correction of factors for delta2/delta2max/river2pro/river2max (mppt.?Vol, mppt.?Amp, mppt.?Watts)
• (foxthefox) some shifting from string to diagnostics
• (foxthefox) some updates to max values
• (foxthefox) delta2/delta2max pd.chgPowerAC and pd.chgPowerDC changed from power to energy
• (foxthefox) correction of plug_heartbeat values, protobuf shifts from snake_case to camelCase

0.0.14

• (foxthefox) new implementation of River 2 Pro, River 2 Max, River Pro, River Max
• (foxthefox) new feature get "lastQuotas"
• (foxthefox) recfactoring of protobuf encoding
• (foxthefox) watth5=daily energy plug, watth6=on time plug
• (foxthefox) plug_heartbeat new values unknown16...19

0.0.13

• (foxthefox) correction for changing of factors for pstations
• (foxthefox) watth5 for plugs
• (foxthefox) more logging pstream/plug
• (foxthefox) optional detection of no updates from mqtt server -> reconnection

0.0.12

• (foxthefox) new command brightness for plugs
• (foxthefox) correction of factors for plugs
• (foxthefox) powerstream bpType with value as texts
• (foxthefox) DELTA 2 factors corrected (mppt.inVol, mppt.inAmp,mppt.carOutAmp, mppt.carOutVol)
• (foxthefox) naming of watth1...8 (except 5)

0.0.11

• (foxthefox) correction this.pstreamStatesDict to cope with pstream and plug

0.0.10

• (foxthefox) unknown pstream message debug possibility
• (foxthefox) inv.outTemp max=90°C, inverter_heartbeat.pv1/2inputWatts max=600W
• (foxthefox) new function -> smart plugs

0.0.9

• (foxthefox) final version of credential creation, at least 6.12.3 for admin required
• (foxthefox) pd.wattsInSum max=4000W, pd.wattsOutSum max=4000W
• (foxthefox) unknwon59 -> batChargingTime, battMin -> batDischargingTime
• (foxthefox) processing multiple messages in one datagram

0.0.8

• (foxthefox) Delta2Max mppt.outVol mult=0.001 instead 0.1
• (foxthefox) handling additional battery for Delta2Max
• (foxthefox) pd.dsgPowerAC -> mult 0.001 Delta2Max
• (foxthefox) pd.chgPowerAC -> mult 0.001 Delta2Max
• (foxthefox) inv.acChgRatedPower -> max 4000W
• (foxthefox) inv.FastChgWatts -> max 2400W
• (foxthefox) chgwatts Delta 2 -> min 50W

0.0.7

• (foxthefox) jsonUI wrong attr for additional battery corrected

0.0.6

• (foxthefox) device doc
• (foxthefox) cfgDcChgCurrent/pv2DcChgCurrent changed back to start at 4A

0.0.5

• (foxthefox) cfgDcChgCurrent/pv2DcChgCurrent again with min=0, seems that there comes 0 at a certein telegram and causing warning
• (foxthefox) energy values (yield per day) for powerstream

0.0.4

• (foxthefox) new switch inverter_heartbeat.feedPriority (handling the excessive solar energy when battery is full)

0.0.3

• (foxthefox) requirement for admin 6.12.2 -> 6.12.0
• (foxthefox) iverter_heartbeat pv1InputCur, pv2InputCur factor corrected now 0.1
• (foxthefox) ems.chgAmp factor 0.0001 ( seemed too high by factor 10 )
• (foxthefox) bmsMaster.tagChgAmp factor 0.0001 ( seemed too high by factor 10 )
• (foxthefox) delta2max command for cfgDcChgCurrent/pv2DcChgCurrent changed
• (foxthefox) ensuring that commanded bppowerSoc value is always minimum 5% higher than the ems.minDsgSoc, also putting actual minDsgSoc into the command

0.0.2

• (foxthefox) pv2DcChgCurrent as level in delta2max
• (foxthefox) *pv2DcChgCurrent with range 4-8 and step 2
• (foxthefox) chgPauseFlag as switch in delta2max

0.0.1 (npm)

• (foxthefox) initial release

License

MIT License

Copyright (c) 2023-2024 foxthefox [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Disclaimer

This open-source software is not affiliated with or endorsed by the company Ecoflow in any way. Use of the software is at your own risk and discretion, and I assume no liability for any potential damages or issues that may arise from using the software. It is important to be aware that using this open-source software comes without direct support or guarantees from the company Ecoflow.