thomluther/anker-solix-api v3.4.1

3.4.1

on GitHub

Enhancements:

• MQTT cloud support enhancements

  • Improved MQTT data monitor tool
    • Added command line options to support automated usage without prompts
    • Added key press function to send a single real time trigger instead of starting the realtime trigger loop
    • Added key press function to send a status request command
    • Modified realtime trigger loop to use status request commands permanently instead of real time trigger command, for device types that have the status request command described as fully supported (mean the device will publish all status messages from the realtime trigger)
  • Enhanced MQTT descriptions for existing and new devices, merged field names to consistent naming for extraction in the Api library
    • C1000 Gen 2 249
  • Added new tool grep_mqtt_cmd.py to grep full command messages from dump files and compare status message fields to identify the bytes that represent the state if the device control. (Many thanks to @jmozmoz for the idea and tool)
    • See updated MQTT decoding guidelines, especially this comment to understand how you can analyze MQTT device commands.

• Export module enhancements

  • Added support for status request command. If described for the device as fully supported, it will be used to request status message in 5 sec intervals instead of using the realtime trigger for 1 minute period during the export
  • Note: Command topic is not subscribed for the export, so no command messages will be exported

• Updated monitor tool for new system and device data fields with additional settings

  • Added support for C1000 Gen 2

• Enhanced options to describe MQTT commands and their values

  • Basically each individual device control/setting must be described with as a single feature with a defined command name
  • However, Anker's device control implementation across the device differs a lot, and may also change from generation to generation
  • Simple commands typicall contain only a single parameter field and are easy to described and compose
  • Complex commands may change multiple fields. They could have dependencies of the changed parameter, or exiting states of other controls
  • Some command fields may be of static nature, their value can be described with a default setting for the field
  • Other fields may depend on the control parameter field and follow it with some fixed mapping rules
  • Some commands use their own message type (easy to describe in SOLIXMQTTMAP)
  • Other commands are grouped under the same message type, but using different fields in the same command message depending on the setting that should be changed.
  • This requires nested command descriptions in the SOLIXMQTTMAP, and updating only individual keys of the command template will get more complicated to describe. See examples for A17C5 and A1763
  • Some device controls may even trigger more than one command message, this must be verified carefully while analyzing MQTT commands in MQTT dumps
  • Typically each command message starts with a pattern field in a2, and ends with a timestamp field in fe using seconds
  • Newer device change the timestamp field from fe to fd, but now using different type to represent timestamp in milliseconds
    • For some commands the timestamp fields may even be screwed up by the App, as this is a new format.
    • Obviously the timestamp in the command message may be ignored by the device, like it ignores existence of XOR checksum byte?
  • Therefore it is important to document a full command message example for each individual control of your device.
  • Command message structures may also change over time (bug fixing of App and or device firmware changes)

• Other enhancements

  • Support checksum byte in MQTT messages. This was ignored so far (since unknown)
  • The message decoder will display the checksum byte in the header, and also an XOR validation result across the message
  • Note: It is assumed that this byte is not really mandatory, but leaving it off from commands resulted in command message lengths that were shorter by one byte compared to command messages from the App or Cloud. This mismatch is now fixed.
  • Updated README for MQTT client and monitor, supported devices and modified command line options for the monitor tool.

Fixes:

• Added missing XOR checksum byte to composed command messages
• Fixed descriptions for battery_soc for proper merge with Api fields. battery_soc refers to the 'average or overall' SOC of the device
  • If the device has separate SOC values for the main battery, it must be described as 'main_battery_soc'
  • The name 'battery_soc_total' should only be used for devices that may report an overall SOC state across multiple devices, like power dock may report for multiple solarbanks.
  • These naming conventions have been hard coded in the battery energy calculation routines
• Various other fixes in the codebase

Breaking changes:

• Command line options have been made consistent between the tools, abbreviations of options now only use single dash
  • You may have to adopt your scripts or cron jobs if using command line arguments for the monitor or mqtt_monitor
• Continuous renaming of MQTT data fields may be required as values are understood, validated and merged across the various devices
• The device agnostic MQTT device modules are no longer maintained (C1000 and F3800)
  • They will be removed once a common, scalable and module command framework was implemented.
  • There will be MQTT device classes per device type, which will specify supported command features and values per PN.
  • Any example modules utilizing those classes will then also break and have to be updated to the new generic MQTT device classes

Full Changelog: v3.4.0...v3.4.1