Outback Mate 3 & 3s Python库 & 命令行界面

这个Python库旨在为所有通过Modbus连接到Mate3/Mate3s（或AXS端口？）的Outback设备提供全面支持。您可以

• 在Python中读取值 - 然后对它们做任何事情，例如监控/警报/动态电源管理等。
• 写入值 - 也就是说，您可以使用Python控制Outback系统。
• （希望）无需了解Modbus。只需使用Python API或CLI即可。
• （希望）以“用户友好”的形式访问完整的Outback规范。您无需了解枚举或位字段中的“魔法数字”（或SunSpec），也无需了解如何解释故障代码，也不必担心二进制补码等其他事物。
• 无需访问系统即可共同开发。也就是说，您可以“转储”系统快照，然后其他人可以像与真实的Mate3通过Modbus交互一样（在合理范围内）与之交互 - 这对于测试/调试等非常有用。

在Python 3.7上进行了测试。可能在3.6上也能工作。

安装

推荐安装方法如下

pip install mate3

之后，您应该能够运行mate3命令。要访问Mate，它必须通过其以太网端口连接到您的本地网络。

您可能需要了解的背景信息...

阅读这些内容将帮助您了解这个库以及如何与Mate交互。

Modbus

希望您根本不需要担心Modbus - 这个库应该会为您抽象掉这一部分。需要注意的是，Modbus是一种通信协议，这个库通过使用同步消息与Mate3物理设备交互来工作。所以

• 信息并不是“实时”的 - 它只是我们上次读取值以来的最新状态。通常，您应该在执行任何操作之前/之后调用read或write。
• 不要过度通信！如果您开始进行太多的read或write操作，可能会使您的Mate的Modbus接口损坏（需要重启来修复）。作为一个经验法则，您可能不想每秒读取一次以上（即使这样，也最好是读取特定的字段，而不是全部）。
• 鉴于以上情况，您可能想使用Mate3Client中的缓存选项，这可以使您在开发代码等过程中完全避免与Mate交互或损坏Mate。每次代码中有错误时都需要重新启动真是太麻烦了。
• 将信息编码到Modbus中时会发生奇怪的事情。希望您永远不会注意到这一点，但如果您看到-1显示为65535的情况，那么可能就是这种情况。

SunSpec & Outback & Modbus

您可以在./mate3/sunspec/doc查看Outback如何实现Modbus的详细信息，但需要注意的关键点是

• SunSpec是为分布式能源系统（例如太阳能）提供的通用Modbus实现。有大量现有的定义，例如充电控制器、逆变器等应该是什么样子。
• Outback使用这些定义，但它们还包括它们自己的附加信息，它们将其称为“配置”定义（通常因为可写入的字段都集中在这里，即您可以更改的内容）。通常，当您使用这个库时，您可能会看到例如charge_controller.config.absorb_volts。在这里，charge_controller代表一个（SunSpec）模块，我们添加了一个特殊的config字段，它实际上是指向Outback配置块的指针。这是为了尝试抽象实现细节，这样您就不必担心有多个充电控制器等。

伪术语表

单词很令人困惑。现在，将以下内容作为大致指南

• 字段 - 这是字段定义，例如absorb_volts是具有“伏特”单位的Uint16。
• 模型 - 这通常指的是特定的Modbus“块”，实际上只是字段集合，这些字段通常与特定设备对齐，例如逆变器模型将具有输出KWH字段，而充电控制器模型则不会。在这里（Outback通常每个设备有两个模型）也是令人困惑的。在上面的例子中，charge_controller代表一个（SunSpec）模型，而charge_controller.config代表另一个（Outback）模型。
• 设备 - 这意味着代表一个物理设备，基本上是我们将Outback配置模型与SunSpec模型包装在一起的方式。
• FieldValue - 这有点像Field，但包含数据（从Modbus读取），即“字段的值”。它还包括一些其他有用的功能，例如自动缩放变量（因为浮点数不是东西）和简单的read或write API。

更多文档？

目前还没有 - 最好的文档是代码和示例，尽管这仅适用于那些了解Python的人。一些其他快速提示

• 开启智能感应！这个库中有很多类型，所以它会使您的生活变得更加容易，例如找到所有可以从您的充电控制器等访问的字段。
• ./mate3/sunspec/models.py 包含了每个模型的全部关键定义，包括所有字段（每个字段都有名称/单位/描述等）。错误标志和枚举也在此正确定义。

使用库

需要更多的文档（见上面），但你可以从 ./examples/getting_started.py 获取代码的大致想法，部分内容如下。

# Creating a client allows you to interface with the Mate. It also does a read of all devices connected to it (via the
# hub) on initialisation:
with Mate3Client("...") as client:
        # What's the system name?
        mate = client.devices.mate3
        print(mate.system_name)
        # >>> FieldValue[system_name] | Mode.RW | Implemented | Value: OutBack Power Technologies | Read @ 2021-01-01 17:50:54.373077
        
        # Get the battery voltage. Note that it's auto-scaled appropriately.
        fndc = client.devices.fndc
        print(fndc.battery_voltage)
        # >>> FieldValue[battery_voltage] | Mode.R | Implemented | Scale factor: -1 | Unscaled value: 506 | Value: 50.6 | ...
         Read @ 2021-01-01 17:50:54.378941

        # Get the (raw) values for the same device type on different ports.
        inverters = client.devices.single_phase_radian_inverters
        for port, inverter in inverters.items():
            print(f"Output KW for inverter on port {port} is {inverter.output_kw.value}")
        # >>> Output KW for inverter on port 1 is 0.7
        # >>> Output KW for inverter on port 2 is 0.0

        # Values aren't 'live' - they're only updated whenever you initialise the client, call client.update_all() or
        # re-read a particular value. Here's how we re-read the battery voltage. Note the change in the last_read field
        time.sleep(0.1)
        fndc.battery_voltage.read()
        print(fndc.battery_voltage)
        # >>> FieldValue[battery_voltage] | Mode.R | Implemented | Scale factor: -1 | Unscaled value: 506 | Value: 50.6 | Read @ 2021-01-01 17:50:54.483401

        # Nice. Modbus fields that aren't implemented are easy to identify:
        print(mate.alarm_email_enable.implemented)
        # >>> False

        # We can write new values to the device too. Note that we don't need to worry about scaling etc.
        # WARNING: this will actually write stuff to your mate - see the warning below!
        mate.system_name.write("New system name")
        print(mate.system_name)
        # >>>  FieldValue[system_name] | Mode.RW | Implemented | Value: New system name | Read @ 2021-01-01 17:50:54.483986

        # All the fields and options are well defined so e.g. for enums you can see valid options e.g:
        print(list(mate.ags_generator_type.field.options))
        # >>> [<ags_generator_type.AC Gen: 0>, <ags_generator_type.DC Gen: 1>, <ags_generator_type.No Gen: 2>]

        # In this case these are normal python Enums, so you can access them as expected, and assign them:
        mate.ags_generator_type.write(mate.ags_generator_type.field.options["DC Gen"])
        # >>> ags_generator_type.DC Gen

使用命令行界面（CLI）

有一个简单的CLI，包含四个主要子命令

• read - 从Mate3读取所有值，并以多种格式打印到stdout。
• write - 将值写入Mate3。（如果你正在做任何事情，你应该使用python API。）
• devices - 显示连接的设备。
• dump - 将所有原始modbus值以与 CachingModbusClient 兼容的格式输出到（JSON）文件，你可以将其与别人分享以帮助调试可能遇到的问题。

对于每个命令，你可以访问帮助（即 mate3 <cmd> -h）获取更多信息。

警告

首先，最重要的警告

警告！请在使用任何 write 功能之前，确保您已经阅读了 许可协议。由于设置错误值（直接或间接），您可能会轻易损坏设备。

此外，还有一些边缘情况可能会导致问题，主要与设备重新分配新端口有关。例如，您有两个逆变器，读取一些值，然后在Hub中将它们的端口切换，再写入一些值——现在可能写入“错误”的设备。目前，最安全的做法是不这样做，除非每次都重启 Mate3Client。关于这一点，如果您需要长时间轮询，建议每次轮询时重新创建 Mate3Client（而不是重用），因为这有助于避免这些问题（或其它问题）。虽然有一些例外，但在打破规则之前，你应该知道为什么你要这样做。

故障排除

一些想法（可能有助于解决问题）

设置日志级别为DEBUG

查看CLI的 mate3 -h，否则查看以下（或类似）python代码

from loguru import logger
logger.remove()
logger.add(sys.stderr, level="DEBUG")

列出设备

$ mate3 devices --host ...
name                                               address    port
----                                               -------    ----
Mate3                                              40069      None
ChargeController                                   40986      4
ChargeControllerConfiguration                      41014      4
...

它们都在吗？

创建原始modbus值的转储

查看 mate3 dump -h。你可以将生成的JSON文件发送给某人以帮助调试。（只是注意，它包括关于Mate的所有数据，例如任何密码等。）

将数据写入Postgres

查看 ./examples/postgres_monitor/README.md

贡献

查看 ./CONTRIBUTING.md

致谢

这最初是基于basrijn的Outback_Mate3库的重构版本，尽管自那以后已经完全重写。无论如何，感谢basrijn！