MQTT data decoding guidelines

[thomluther]

This document describes the general decoding requirements for MQTT data of your Anker Solix device.

MQTT Overview

MQTT data as it can be received from the Anker MQTT server is a binary, proprietary format. With the great ground work from people in flip-dots SolixBLE project, especially from @LeagueRaINi in this comment, the general data structure is described as he discovered it for the BT traffic. Fortunately with the great work from @rschoebel in discussion #218, we figured out that the MQTT data packets follow the same BT binary structure. So the data is not encrypted like the power Api data as it was originally assumed, it is proprietary hex data that is just base64 encoded in the MQTT message.

At the end it makes sense that BT and MQTT data structures are the same, since both interfaces are direct device interfaces from the mobile App to control the device in same way. The BT interface is just used for the local communication (and limited in distance), while the MQTT server is the remote communication interface via the cloud. There is additionally the power cloud Api interface, but the power cloud provides data and services around systems, which are a combination of one or more devices that interact. Furthermore all energy tracking and stats are done in the power cloud only. The mobile App combines and merges the data from all those interfaces in a way, that the source of the data is not recognizable. Only the direct device real time data is definitely being pulled directly from the MQTT server. The mobile App home screen data for Solarbank systems is probably from the power cloud server . They may however update almost in realtime, because an owning account can trigger real time data publishing via the MQTT server. While the power cloud servers are probably also subscribed to all your device topics, they also receive much more MQTT data while you have opened the system in the mobile App. Therefore the home screen can provide more frequent data updates as well (implemented for Solarbank 2+ systems). Other systems like power panels or X1 seem to map the MQTT data directly into the home screen, since they do not seem to have power consumption data on the power cloud.

Once an MQTT client subscribed to the MQTT cloud server under your specific device topic, it can receive data as provided regularly from your device. The frequency depends on the device model and its current state. Devices in standby will rarely send MQTT data to the cloud, while regular updates vary in a 60-300 seconds range typically.

Now you may wonder why the mobile app can display real time data for your device. Well, there is a trigger capability via the MQTT server to request real time data updates for a certain period of time. Fortunately, with great support from @rschoebel, we figured out the topic and data package that is published for the update trigger command and I was able to put that all into a framework that can be utilized in this Api library. This real time update trigger capability is also used in the mqtt_monitor tool.

While there is no local MQTT capability, the data via the MQTT server provide lots of other capabilities that still have to be evaluated. But this also comes with a challenge, and that is the binary format of the data. Since each device type, even various device configurations, can result in different binary data patterns and different fields or message types, it is up on the device owners, which is YOU, to monitor, decode and document the data stream for your specific model type.

And for the proper value decoding you have to get creative, and you need to do a lot of testing, setting changes and data comparisons, to identify which bytes reflect which values or settings of the device.

In order to simplify that approach, the library has an easy to use mqtt_monitor tool, that allows you to control the data flow and aids in various byte conversions already, in order to give you an idea what a message data 'field' could represent. The monitor uses color highlighting to simplify the data decoding. Following is a sanitized screenshot how such an MQTT message looks like for my device (unfortunately the solarbank battery was empty already when I took it, therefore you see only few values):

The decoder shows already field descriptions that must first be defined in the mqttmap.py module. The monitor structures the binary data already into the used Solix data pattern as it is known so far. Therefore various device message types can be structured in the same way and a common description pattern can be used.

So far there have been identified 7 different data field types 0x00 - 0x06, they are described in detail in the mqttmap.py module.

MQTT Monitor

In the monitor you just have to enter your Anker account credentials and country, then you will be asked which of the found owning devices under your account you want to monitor.

Note

It seems that only owning devices allow topic subscription, therefore the mobile App also has very limited capabilities once used with a system member account. Devices cannot be shared with members and members can typically not access any device of the shared system at all. They cannot see any real time data in the home screen either, since the App cannot trigger real time data updates through MQTT servers.

You can optionally log the screen output to a file for later review, because messages can wrap really fast while real time data is being received. Following is the usage menu of the monitor while monitoring messages. It reacts on key press. This was tested on Linux and Windows platforms, so it should hopefully also work on Mac OS.

----------------------------------------------------------------------------------------------------
MQTT Monitor key menu:
----------------------------------------------------------------------------------------------------
[K]ey list to show this [M]enu
[U]nsubscribe all topics. This will stop receiving MQTT messages
[S]ubscribe root topic. This will subscribe root only
[T]oggle subscribed topic. If only one topic identified from root topic, toggling is not possible
[R]eal time data trigger loop OFF (Default) or ON for continuous status messages
[O]ne real time trigger for device (timeout 60 seconds)
[I]mmediate status request for device
[C]ontrol MQTT device, select described command and parameter values to be published
[V]iew value extraction refresh screen or MQTT message decoding
[D]isplay snapshot of extracted values
[Q]uit, [ESC] or [CTRL-C] to stop MQTT monitor
Hit [Enter] to continue...

The monitor will initially subscribe to the device root topic, but not trigger real time updates yet. So initially it will receive messages in the regular device intervals if you don't use the mobile App in parallel. Once messages from various topics are received, you can also toggle subscription to a dedicated topic. If you need to pause the message printout while using the message decoding view, you can simply unsubscribe from topics for immediate pause. To get real time messages, you need to enable the real time trigger. This will use a timeout of 60 seconds but continue to trigger within the timeout interval until you disable the real time trigger again. After disabling, you have to wait until the used timeout of 60 seconds is over. While RT trigger is active, the monitor will publish another trigger every 60 seconds to keep the device in real time data publish mode.

Note

The mobile app seems to use a real time trigger timeout of 5 minutes, the maximum timeout is unknown, but large timeouts don't make sense either, if the trigger can be republished as required. In order to have NO realtime triggered messages in the monitor, you have to wait at least 5 minutes after you closed the mobile app to ensure that its last realtime trigger timed out.

The value screen of the monitor shows the active monitor settings, the accumulated value extractions (if there are already field descriptions defined in mqttmap.py), some MQTT statistics, the received topics and the last message details. Following is a sanitized example,

Realtime Trigger:  ON, Active topic: 'dt/anker_power/A17C0/AZxxxxxxxxxxxx06/#'
Start: 2025-09-10 21:31:05, Received: 25.513 KB (100.640 KB/h), Sent: 7.219 KB ( 28.476 KB/h), Messages: 63 (7.705 KB)
2025-46-10 21:46:17: Received message '08:57' on topic: dt/anker_power/A17C0/AZxxxxxxxxxxxx06/state_info
----------------------------------------------------------------------------------------------------
device_sn                : AZxxxxxxxxxxxx06          wifi_name                : wifi-network-1
wifi_signal              : 66                        timestamp_1?             : 2025-09-10 23:45:47
timestamp_2?             : 2025-09-10 21:45:47       charging_status          : 4
output_preset            : 600                       photovoltaic_power       : 0
charging_power           : 0                         output_power             : 0
?                        : 0                         battery_soc              : 5
temperature              : 19                        sw_version               : 2.1.5
sw_controller            : 2.1.5                     sw_esp?                  : 1.2.2
allow_export_switch      : 0                         priority_discharge_switch: 0
output_cutoff_data       : 5                         lowpower_input_data      : 4
input_cutoff_data        : 5                         inverter_brand           : ANKER
inverter_model           : A5140                     min_load?                : 100
----------------------------------------------------------------------------------------------------
Received Topics:
dt/anker_power/A17C0/AZxxxxxxxxxxxx06/param_info
dt/anker_power/A17C0/AZxxxxxxxxxxxx06/state_info
cmd/anker_power/A17C0/AZxxxxxxxxxxxx06/req
----------------------------------------------------------------------------------------------------
Received Messages:
{"count": 63, "bytes": 7890, "": {"040d": {"count": 1, "bytes": 17}, "0857": {"count": 16, "bytes": 224}, "0407": {"count": 1, "bytes": 59}, "0408": {"count": 15, "bytes": 2730}, "0856": {"count": 15, "bytes": 495}, "0405": {"count": 15, "bytes": 4365}}}
----------------------------------------------------------------------------------------------------
{'head': {'version': '1.0.0.1', 'client_id': 'AZxxxxxxxxxxxx06', 'sess_id': '5754-0777', 'msg_seq': 48714, 'cmd': 16, 'cmd_status': 1, 'sign_code': 0, 'seed': 'null', 'timestamp': 1757834777}, 'payload': '{"data":"/wkOAAxxxxxxxxxxMjg=","sn":"AZxxxxxxxxxxxx06","pn":"A17C0"}'}
Device hex data:
ff:09:0e:00:03:01:0f:08:57:00:a1:01:32:38

In principle you need the message decoding output to identify the value representation of various fields and bytes, while the value screen allows to verify proper value extraction from byte data according to the mapping descriptions. The value screen is also useful to monitor descriptions for their correctness over longer periods. Sometimes you can only guess what a field value may stand for (for example output power, or internal total energy yields which may not be published via the App), while in another situation you discover that it shows values that must be a different interpretation of the field.

Documentation for your device type

In order to describe the field mappings to values, you should create a discussion post here in the repository (one per device model number). Since each device may use various message types, various patterns may have to be described. You can use the A17C0 description as example.
Optionally you can also enhance the mapping directly in the SOLIXMQTTMAP and create a pull request with your changes. The known field value formats are described in class DeviceHexDataTypes. Some fields are base values, and their conversion was found to be fixed. Their corresponding value conversion is highlighted in color, other conversion types for those fields can be ignored typically. But there are other fields which may be composed of various formats, values etc, especially 0x05 and 0x06 format types. The conversion options are just options. You have to get creative to understand the real byte interpretation. You may need manual and other byte type conversion as well. Do not rely only on the presented conversion options of the built in decoder....
Due to the data fuzziness, it is important to document the description with example value calculations here as well. The resulting unit should also be documented, typically power is in W, Energy in kWh and others may be %, °C or other units.

Important

Do not make final field descriptions before you validated the description in various device scenarios for correctness! You need to avoid to use different names for same value types across various devices. Preferably the power Api field names should be used also for MQTT data descriptions as long as they have the same value.

You can use field hints by ending the description name with a '?' to indicate that this is not validated yet and value must be used with care.

Tip

Some base fields also require creative conversions. For example software versions use integer value fields. But sometimes a byte stands for a single version digit, for other devices the whole byte may stand for the version, e.g. int 215 for version "2.1.5".

If field names contain "sw_" or "version", their value(s) will therefore be converted into a version string. Otherwise values are typically not converted into strings, except the bytes are supposed to use the 0x00 base type for string format.
If byte values need a conversion to correspond to final field value, this can be specified with a "factor" value in the field description. It will be used as multiplier for the byte value, while the float precision of the factor is being applied for int values.

Additional Reference:

The Anker Solix X1 now officially supports the modbus protocol. While those binary data format structure is different than the MQTT/BT format structures, the individual value format/unit/length/type may be identical. So looking at the supported values in this guide may help to understand which values and settings may be reported via MQTT and how the bytes may have to be decoded, especially for X1 device types.

So now its on you to understand MQTT data of your device.

Tip

Use your mobile App in parallel to the MQTT monitor and compare value decoding options or identify bit masks for setting changes that you perform in the App. Compare byte patterns to previous message byte patterns to recognize setting changes. Once a change is applied in the App, it is typically visible in the next message containing that setting, There is no big delay if you trigger real time data updates, and while you have the App open, it does the realtime trigger for you anyway. In that case, you can only 'u'nsubscribe from all messages to stop message output in the monitor while the App is opened.

Happy decoding!

Update Dec 2025:

It turned out that not every device reacts on real time trigger in each condition. However, it appears that those devices always react on a single status request command, where the same status messages are published as with the active realtime trigger (0405 and others).
So in principle the status request is useful for one immediate set of status messages, while the real time trigger may repeat that automatically in 3-10 second intervals for the given period of time (if accepted by the device).

Important

Depending on Anker's implementation of the status request command per device, the device may send only the typical real time status message, but NOT additional status messages types that may only be published with the realtime trigger active.

One example of missing status messages after status request command are Expansion status messages for SB2 and later devices. That means unique data only found in extra status messages may require the realtime trigger for the particular device.

The monitoring and export tools have been adopted accordingly in actual main branch:

• export_system.py will use 60 sec RT trigger per default during export, unless the SOLIXMQTTMAP describes the status request command as fully supported by the device. In that case, it will push the status request in 5 seconds intervals for 60 seconds instead of using the real time trigger. Status request command responses are more reliable than with real time trigger, but it must be confirmed to work per device (and described as supported command)
• mqtt_monitor.py got 2 new key options: 'O' for one time real time trigger, and 'I' for immediate status request. The existing 'R' real time trigger loop was also changed to prefer usage of regular status requests in 5 sec intervals instead of RT triggers within the RT timeout intervals. This should make regular status messages more reliable for devices that are confirmed to fully support the status request command in the mapping description. In order to test whether the device fully supports immediate status requests, ensure no real time trigger is active (no regular 0405 messages) and then hit the 'I' key to see if the device provides 0405 and other status messages immediately, which are otherwise only sent while realtime trigger is active. If the same messages are published as with active realtime trigger, the status request command should be described as fully supported command in the mapping for your device type.
• monitor.py got 1 new key options in live mode: 'I' for immediate status request, This will use the status request command on all subscribed devices and you should see whether something new was extracted in the MQTT data. The 'R' real time trigger is still a single RT trigger command with timeout of 60 seconds. If there are no status messages or MQTT data updates after the 'R' command, the device may not react on Real time triggers in its current state. Likewise if there are no immediate MQTT data after the 'I' command, the device may not react on status request commands, I observed that for the shellyP3em, while the realtime triggers seem to work. If only a subset of status messages is returned with the command, other values in the monitor may not change, but this is difficult to recognize.

I plan to make an additional button available in the HA integration beside the existing Real Time trigger. This will enable choice which of the 2 commands are more reliable to get 'real time' data. The immediate status request should be more reliable, and it can be automated in HA at desired intervals for a single update. With the RT, the device have to publish much more data as requested and maybe at another interval as desired (3-10 seconds typically).

To get a guideline how to decode MQTT commands from your app and the corresponding state change in the status messages, please refer to this comment

[thomluther]

Outlook

While more device models must be decoded and being described first, there is still a long way to go before the MQTT data can be commonly integrated into the Api library and the existing cache structures. Following are challenges and concerns:

• MQTT real time data may produce lots of additional traffic, not only to your client, but also to the cloud infrastructure which it probably was not designed for. Real time data is typically published only while you have opened the app and watch your system or device data, but not 24x7 as could be used through the libarary and HA integration
• It is not clear, what impact real time data triggering may have while devices are in standby. The App typically stops communication to the device while in standby, and real time trigger would probably keep them awake 24x7, therefore also increasing their power consumptions
• Power System data as provided today via the library caches cannot be easily merged with real time device data. This is just a subset of the system correlated data from the cloud, and refreshing just a subset of data may invalidate other system data not being refreshed with the same received message. Therefore a merge of same power cloud and MQTT cloud values will not be implemented.
• Controls via MQTT server are unknown, while the topic might be the same as for the update trigger publish, the data packages are quite unique for your device model. This can only be identified if you are able to sniff App TLS traffic to the MQTT server, and that is not an easy task (at least not for me and I have not been able to find an easy way to do so, because the App does not run on emulators and may require a BT emulation as well).

In the long term, following enhancements could be possible for the library and the HA integration with the parallel MQTT interface:

• Merge dedicated MQTT values to cloud caches for missing cloud fields, such as temperature or certain device settings not exposed to the power cloud
• Add stand alone device values to the api caches, which are not supported at all by the power cloud, such as portable power stations. This would enable monitoring capabilities in HA for those devices.
• Implement controllable real time data trigger for stand alone or main system devices, which could provide more data points. This will also increase update frequency of system data provided through the power cloud. However, this must be used with care due to concerned impacts mentioned above.

[thomluther]

From @kb1ibt:
I just want to provide some context for some of the header and basic fields

Bytes [4]-[6] -- 03 00/01 01/02/0c/0d/0f/10/11/13:

• 03 is hardcoded in the FW
• 00/01 explains how it was handled, usually
  -- 00 is handled by the module chip (often an esp32), also usually opcodes <=0x40
  -- 01 is relayed from a different chip like the MCU
• 01/02/0c/0d/0f/10/11/13 is what function role the handled the message
  -- 01 negotiation, auth, connect
  -- 02 WiFi provisioning, ops 0x30-0x33
  -- 0c factory (usually only JTAG or similar)
  -- 0d protobuf-upload handshake, module -> cloud (at least on the A1783 and A2345)
  -- 0f app ↔ device commands, telemetry and pushes;
  -- 10 the module ↔ MCU link
  -- 11 session ops, on some models the same handler as 0f
  -- 13 WiFi provisioning, ops 0x22–0x25

Bytes [7-8]:

• high nibble of byte 7, on BLE:
  -- 0x40 is encrypted
  -- 0x80 is fragmented
  -- 0xc0 is both
• low nibble of byte 7:
  -- 0x08 XOR of request, so 0a00 is the response to 0200 another example 0a05 for 0205, but this is more of a guideline than a hard rule

The "optional message increment" is a status bit for the command response, where:

• 00 is success
• 01 is fail
• 04 is payload wrong

and there are some others, also on the BLE side there is also a required field, but only for fragments which tells which fragment and which order.

[hacki11]

I can not stress enough how awesome your work here is, thank you for this!
I know that the values are not yet fully decoded but what is already available is already very useful (SB3 owner). I wonder if you have plans to add something like a MQTT Bridge/Gateway/Forwarder acting as a MQTT client for Ankers MQTT Server, subscribing and decoding the data as you do and publish the decoded data points as separate MQTT topics to another, locally hosted MQTT broker. With something like this in place, we can put it in a docker image and the integration in home automation is nearly done. I guess this is not really the scope of anker-solix-api, but this project can use this api of course. Something like a anker-solix-mqtt-bridge. What do you think?

[thomluther]

I don't have in plan to do anything like that.
I only plan to use the optional MQTT data directly in the HA integration, but not sure yet how to merge it with Api data.

The point is, that MQTT data is only a subset of data. Good enough for standalone devices, but for power Systems with multiple devices they may not show the full picture.

But if anyone wants to use the library to build such a project, feel free. Just be aware that there will still be couple of breaking changes and also the namings are still 'adjustable'. It will not become something that is easy to consume by users, since names, structures etc can change, and everybody would have to build its own entities, or you need to have solid autodiscovery structure for HA with bridged MQTT data. This has to be permanently maintained and enhanced, and I have neither the time nor any interest to do so.

Such a bridge would also need to trigger realtime data most of the time to get anything from the devices... Continued real time data triggering is nothing what I plan to support in general, as it may have unknown impact to the whole scalability of the infrastructure.

I plan however to provide a button like trigger capability for the HA integration with the same Timeout of 5 min as used by the App, so everyone is able to control how long and which devices should be triggered with an automation.
While RT data is triggered, the normal Api data should also refresh in shorter intervals, so there should be no need to update existing Api values with MQTT values, but only add the values missing. This is very device specific.

[hacki11]

So I did write a mqtt_bridge.
Connects to Anker MQTT server and to a MQTT broker of your choice. Enables realtime mode for all found devices and forwards the decoded mqtt messages. I have added a Dockerfile and Docker Compose to let it run.
Now I have all the data as fresh as possible (3s) in ioBroker to do all the load management calculations without one system lagging far behind. And for me (SB3 Pro) the most relevant data is already decoded (power, energy, battery, etc.).

It accepts the envvars:
MQTT_HOST, MQTT_PORT, MQTT_USER, MQTT_PASSWORD.
ANKER credentials as usual.

MQTT Prefix is kept original (dt).

[thomluther]

MQTT command and state analysis and description

Meanwhile the MQTT command root topic was added to the mqtt_monitor as well. Once subscribed, you can see all commands that are send via the App to your device via the server.
To filter only command messages, you can search for pattern '03 00 0f', or toggle to the cmd topic after the first command was received.

Following is the Realtime Trigger example command message sent to the device:

Received message on topic: cmd/anker_power/A17C0/AZxxxxxxxxxxxx06/req
{'head': {'version': '1.0.0.1', 'client_id': 'android-anker_power-39xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7c-d8xxxxxxxxxxxxxxxxxxxxxxxxxxxxcb', 'sess_id': '1', 'msg_seq': 1, 'cmd': 17, 'cmd_status': 2, 'sign_code': 1, 'seed': '1', 'timestamp': 1760291317, 'device_pn': 'A17C0', 'device_sn': 'AZxxxxxxxxxxxx06'}, 'payload': '{"device_sn":"AZxxxxxxxxxxxx06","account_id":"39xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7c","data":"/wkfAAMADwBXoQEiogIBAaMFAywBAAD+BQP16etofw=="}'}
2025-10-12 17:48:37 Device hex data:
ff:09:1f:00:03:00:0f:00:57:a1:01:22:a2:02:01:01:a3:05:03:2c:01:00:00:fe:05:03:f5:e9:eb:68:7f
--------------------- Solarbank_1 / A17C0 / 0057 / Header ----------------------
ff 09   : 2 Byte Anker Solix message marker (supposed 'ff 09')
1f 00   : 2 Byte total message length (31) in Bytes (Little Endian format)
03 00 0f: 3 Byte fixed message pattern (supposed `03 00/01 0f` for send/receive)
00 57   : 2 Byte message type pattern (varies per device model and message type)
        : 1 Byte optional message increment (  0)
-- Fields --|- Value (Hex/Decode Options)---------------------------------------
Fld Len Typ        uIntLe/var          sIntLe         floatLe      dblLe/4int
a1   01  --    22
└->   1 unk              b'"'     --> pattern_22
a2   02  01    01
└->   2 ui                  1               1  --> set_realtime_trigger
a3   05  03    2c:01:00:00
└->   5 var             300;0             300           0.000        44;1;0;0   --> trigger_timeout_sec
fe   05  03    f5:e9:eb:68
└->   5 var       -5643;26859      1760291317 8912574951632641944715264.000 245;233;235;104 -> msg_timestamp
--------------------------------------------------------------------------------

In this way you can figure out the various bytes and message types that are used to modify device settings via MQTT. In order to implement those, full message dumps will be required since all fields have to be constructed for command messages. Also the valid setting values must be described.

How to decode device commands and corresponding state changes

First some general rules:

• Focus on a single control that you modify in the app
• Document all options the App supports for this control
  • They must be provided along the command descriptions, in order to validate the values when commands will be composed by the library
  • There are various options to describe value options, value maps, value ranges including steps etc.
  • If the state value extraction uses a 'factor' to convert the value, the command value description must specify the same as 'divider' to convert an extracted state value back into the value to be sent to the device
  • All value options or ranges must be described according to the converted state value, since that is the value that applications will use. The divider will ensure to convert the used setting value into the value required for the particular device command message.
• Create a separate file dump for each control setting that you analyze
• To recognize the resulting command states, you need to compare the status messages before and after the command.

In order to simplify this approach, the mqtt_monitor can now be started with command line options. This allows to automate launch options and the runtime of the monitor (e.g. for regular dumps via a cron job to monitor long term value behavior of unknown field values). If you use the mqtt_monitor for command decoding, give each dump file a corresponding prefix to recognize afterwards which device control was changed in the dump.

Once you launch the monitor and Anker app in parallel, there is no need to enable the realtime trigger in the monitor. It will be triggered permanently by the app and you will see those 0057 trigger commands as well.
Now toggle the device control via the app to various settings. If there is only an integer used for a descriptive App setting, (e.g. various display brightness levels), you should toggle to all of them and remember the order, otherwise you cannot map the option name to values later on.

Once you have a finished dump file, you can use a little tool that was started by @jmozmoz (Many thanks for this). An enhanced version of the tool is now available in the library and called grep_mqtt_cmd.py. It is not commonly described, because it cannot be used as is. You need to modify the source code and adopt it to the particular filename and device message types that you want to analyze.

What does it do for you?
The tool will traverse the lines in the specified dump file and extract and print only the decoded message part (without confidential device info contained in the topic etc). Of course, decoded status messages that will be printed may contain device serials etc.
You can define one message type that is used as the status message, which will be compared for changes after each printed message.
You can define message types that you want to exclude from printing. This allows you to extract only specific message types you are interested in, and the defined state message is compared for changes before and after the printed message.
If you do not exclude the state message itself, you can also see the different fields (lines) between 2 status messages.
Status message fields that may change all the time can be excluded via keywords in those lines (e.g. you can exclude certain field names, or extracted timestamps etc.)

Here is a short description how to adopt:

# define screen width for diff lines
screen_width = 180
# define filename to be verified
test_file = Path(__file__).parent / "mqttdumps" / "A1763" / "CMD.AC.Smart.Modus.txt"
#test_file = Path(__file__).parent / "mqttdumps" / "A17C0_mqtt_dump_2025_14_02__22_14_35.txt"
# define messages that should not be printed
excluded_msgs = ["0421", "0900", "0057", "0040", "0857", "0901", "0902", "0903"] # A1763
#excluded_msgs = ["405", "0057", "0040", "0857"] # Solarbank
# define status message types that should be compared after a printed message
compare_msg = "0421"
#compare_msg = "0405"
# define words in lines that should be excluded in found differences
skip_diff_words = ["fd  ", "fe  ", "timestamp"]

And here is an example snippet of the output, which shows the setting changes and state fields for AC output mode (smart/normal toggle):

10:08:42 INFO: ------------------------- Pps / A1763 / 0101 / Header --------------------------
ff 09   : 2 Byte Anker Solix message marker (supposed 'ff 09')
21 00   : 2 Byte total message length (33) in Bytes (Little Endian format)
03 00 0f: 3 Byte fixed message pattern (supposed `03 00/01 0f` for send/receive)
01 01   : 2 Byte message type pattern (varies per device model and message type)
: 1 Byte optional message increment (  0)
-- Fields --|- Value (Hex/Decode Options)---------------------------------------
Fld Len Typ        uIntLe/var          sIntLe         floatLe      dblLe/4int
a1   01  --    22
└->   1 unk              b'"' --> pattern_22
a6   02  01    00
└->   2 ui                  0               0 --> set_ac_output_mode
fd   0e  00    31:37:36:34:38:33:39:33:32:32:34:38:37
└->  14 str   b'1764839322487' --> msg_timestamp (2025-12-04 10:08:42)
--------------------------------------------------------------------------------
Found differences in: 0421
a4   1b  04    00:00:00:00:64:00:32:01:00:00:00:00:00:00:00:0a:00:01:00:00:00:00:00:64:0 | a4   1b  04    00:00:00:00:64:00:32:00:00:00:00:00:00:00:00:0a:00:01:00:00:00:00:00:64:0
1:03                                                                                     | 1:03                                                                                    
└->  27 bin   b'\x00\x00\x00\x00d\x002\x01\x00\x00\x00\x00\x00\x00\x00\n\x00\x01\x00\x00 | └->  27 bin   b'\x00\x00\x00\x00d\x002\x00\x00\x00\x00\x00\x00\x00\x00\n\x00\x01\x00\x00
\x00\x00\x00d\x01\x03' --> {'04': {'name': 'ac_input_limit', 'type': b'\x02'}, '20': {'n | \x00\x00\x00d\x01\x03' --> {'04': {'name': 'ac_input_limit', 'type': b'\x02'}, '20': {'n
ame': 'ac_fast_charge_switch', 'type': b'\x01'}, '22': {'name': 'set_output_port_memory_ | ame': 'ac_fast_charge_switch', 'type': b'\x01'}, '22': {'name': 'set_output_port_memory_
switch', 'type': b'\x01'}}                                                               | switch', 'type': b'\x01'}}                                                              
10:08:47 INFO: ------------------------- Pps / A1763 / 0101 / Header --------------------------
ff 09   : 2 Byte Anker Solix message marker (supposed 'ff 09')
21 00   : 2 Byte total message length (33) in Bytes (Little Endian format)
03 00 0f: 3 Byte fixed message pattern (supposed `03 00/01 0f` for send/receive)
01 01   : 2 Byte message type pattern (varies per device model and message type)
: 1 Byte optional message increment (  0)
-- Fields --|- Value (Hex/Decode Options)---------------------------------------
Fld Len Typ        uIntLe/var          sIntLe         floatLe      dblLe/4int
a1   01  --    22
└->   1 unk              b'"' --> pattern_22
a6   02  01    01
└->   2 ui                  1               1 --> set_ac_output_mode
fd   0e  00    31:37:36:34:38:33:39:33:32:37:35:32:35
└->  14 str   b'1764839327525' --> msg_timestamp (2025-12-04 10:08:47)
--------------------------------------------------------------------------------
Found differences in: 0421
a4   1b  04    00:00:00:00:64:00:32:00:00:00:00:00:00:00:00:0a:00:01:00:00:00:00:00:64:0 | a4   1b  04    00:00:00:00:64:00:32:01:00:00:00:00:00:00:00:0a:00:01:00:00:00:00:00:64:0
1:03                                                                                     | 1:03                                                                                    
└->  27 bin   b'\x00\x00\x00\x00d\x002\x00\x00\x00\x00\x00\x00\x00\x00\n\x00\x01\x00\x00 | └->  27 bin   b'\x00\x00\x00\x00d\x002\x01\x00\x00\x00\x00\x00\x00\x00\n\x00\x01\x00\x00
\x00\x00\x00d\x01\x03' --> {'04': {'name': 'ac_input_limit', 'type': b'\x02'}, '20': {'n | \x00\x00\x00d\x01\x03' --> {'04': {'name': 'ac_input_limit', 'type': b'\x02'}, '20': {'n
ame': 'ac_fast_charge_switch', 'type': b'\x01'}, '22': {'name': 'set_output_port_memory_ | ame': 'ac_fast_charge_switch', 'type': b'\x01'}, '22': {'name': 'set_output_port_memory_
switch', 'type': b'\x01'}}                                                               | switch', 'type': b'\x01'}}                                                              

You can directly see that only field a4 of status 0421 reflects a change after each toggle. The diff lines are not cut, but they are wrapped completely into the column width (screen width / 2), so you can find the difference anywhere in that row.
Comparing each byte in the field more carefully, you can see that byte 07 in the field value (counting from 00) reflects the setting change, first from 01 to 00 and then back from 00 to 01. This byte you have to describe in the a4 field map with the name defined as 'state_name' for the command.
Once you describe such 'bin' or 'strb' type fields that may contain multiple values, you also need to describe which base type the decoder should use for each individual value you described for the field:

# 'str' Field format 0x00 is variable number of bytes, string value (Base type), no special mapping attributes. Fix length must be provided for extraction from start byte, default is first byte containing the length.
# 'ui' Field format 0x01 is 1 byte fix, unsigned int (Base type), "factor" can be specified optionally for value conversion
# 'sile' Field format 0x02 is 2 bytes fix, signed int LE (Base type), "factor" can be specified optionally for value conversion
# 'sfle' Field format 0x05 is 4 bytes, signed float LE (Base type), "factor" can be specified optionally for value conversion

Look at the existing device descriptions to see the various formats how they describe fields. The 'type' description is always required if the field type does not use any of the 4 base types above.

Multibyte value changes should be easier to identify than simple toggles. Just copy the value bytes as set in the command message. You should find the same pattern in the status message somewhere. Note that multi byte values are always in reversed byte order (little endian format), just in case you want to convert values manually between Decimal numbers from the App and hex bytes as they may be reflected in the MQTT messages.

Sometimes a device setting can also flip just one or more bits in a byte value field, typically when the field is bin type. Then a proper bitmask value must be identified and described, that is used to extract the value of the corresponding bits only. As such, the complete hex or decimal value of field may be meaningless, and must be seen as 8 bits where the toggle can change only one or more bits without modifying the others. This will result in completely different hex and decimal values, depending on the combination of existing and modified settings.

[thomluther]

MQTT device control

Release 3.5.0 allows to publish any described and supported MQTT device control through either the monitor or the mqtt_monitor tool. This allows now to verify the decoded and described MQTT commands for your device type.
Simply use the 'c' key to select a described control and provide required or optional parameters for the control. The message decoding will be suppressed until the control publish has been confirmed by you or aborted. If you have subscribed the cmd topics, you will see the decoded published message, which you can use to validate and compare the MQTT command composition, which is entirely based on your mapping descriptions.
You need to verify the control changes in the mobile App in parallel. Some control changes may require to re-enter the device details panel to get refreshed in the mobile App. If control are not properly applied, it is most likely a wrong command or field description in the mapping. You need to use and dump same control via the App to verify/compare the decoded command messages and identify the mismatch.

Note

• Device firmware changes may introduce additional fields in the control, that are not described yet.
• Certain device controls may trigger more than one MQTT command through the App or Cloud. Multiple commands per control are not implemented (yet) in the MQTT control framework of this library. Subsequent commands for controls will have to be described and understood entirely before such multi command controls can be supported.
• Some MQTT device controls are just a partial command of a control that is manageable also via the cloud Api. If only the device command is published, the cloud Api may not be aware of the control change. One example is the Solarbank min SOC setting (SOC Reserve), which must be triggered through the cloud Api instead of the MQTT control for full functionality.
• Certain Solarbank device controls may work for single solarbank systems, but not if the device is part of a multisystem, where certain controls have dependencies across all devices in the system and must be controlled through the Api (or Station as it is called in the mobile App).