文档

用户定义的计数器

注意:cFos充电管理器可以使用SunSpec(设备类型为 "SunSpec太阳能逆变器/仪表")读出大多数太阳能逆变器。在这种情况下,您不需要创建自己的电表定义。

cFos计费管理器允许您创建自己的仪表定义,以支持不在标准曲目中的仪表。目前有三种类型。Modbus计数器、HTTP/JSON计数器和MQTT/JSON计数器。这些计数器的定义文件非常相似。Modbus计数器通过Modbus从特定的寄存器中读取它们的数据,而HTTP/JSON计数器通过HTTP请求获取它们的数据,并解析JSON作为响应。对于 MQTT/JSON 计数器,cFos 计费管理器订阅 MQTT 主题,并将主题下发布的消息解析为 JSON。对于解析,cFos计费管理器使用一个小型的 "查询语言"。下面是cFos Charging Manager中MQTT功能的文档。

除了一些预定义的变量,如电流和电压,用户定义的计数器还可以读入未知的用户定义的变量,查询输入和设置输出。读取变量和设置输出允许对公式进行评估。结合下面描述的充电管理器变量和全局充电管理器输出,这是一个强大的功能,甚至允许某些家庭自动化任务和控制外部设备,如电池存储。如果你实现了这方面的控制任务,请给我们反馈。我们对人们用cFos充电管理器控制的内容非常感兴趣,这有助于我们根据客户的需求进一步开发充电管理器。

下面是一个简单的定义Modbus的例子,它读取一个单一的有功功率的寄存器。你可以根据你的具体应用轻松地修改寄存器的编号。
单个寄存器的定义示例.

这里有一个Modbus定义的例子和一个HTTP/JSON定义的例子。
下载Modbus仪表的定义样本
下载HTTP/JSON表的定义样本

充电管理器已经带有一些这样的文件,但你可以在 "系统配置 "下上传你自己的文件,也可以再次删除它们。
在这里,你会发现我们提供的大部分仪表定义。
下载提供的计数器定义

如果你已经创建了自己的计数器文件,并且它可能与其他用户有关,如果你能将它提供给我们,我们将非常感激。然后我们将在未来版本的收费管理器中提供它。

下载更多电表的定义

定义文件的结构。

仪表定义是JSON文件,有一个全局的JSON对象,有属性和子对象。rtype'决定了读操作的类型:0 = Modbus, 1 = HTTP/JSON, 2 = MQTT/JSON。数字可以选择以十进制或十六进制指定,前缀为0x。此外,允许使用//的单行注释。我们建议通过JSON5验证器来运行你的定义文件,例如这个JSON5验证器

你肯定应该读过公式这一章,以了解哪些值可以在下面的参考中用于公式。

Modbus定义有一个对象'rtu',具有以下属性。

silence_period, in msec.确定,在Modbus RTU访问前的停顿长度,以便设备识别信息的开始。
silence_same_slave, true: 在对同一设备进行多次访问时也会观察到停顿。
retries: 如果设备没有响应,重试的次数。
rcv_timeout: in msec.每次访问直到设备响应的最长等待时间。

这些全局属性适用于Modbus TCP和RTU。

modbus_read
modbus_read_max_registers:一次可以读取的最大寄存器数量。
modbus_allow_gaps:true = 在一次读取操作中可以读取未使用的寄存器区域。

对于Modbus TCP和HTTP/JSON,有一个对象'tcp',其属性如下。

connect_timeout: 是msec。TCP连接的最大等待时间。
delay_after_connect: 单位是msec。连接建立后暂停,再发送第一条命令。

这两种定义类型(Modbus和HTTP/JSON)都有以下附加属性。

upd_delay:毫秒,决定读取设备的时间间隔。如果查询过于频繁,某些设备会超载。
manufacturer:字符串,制造商名称。
delay_accumulated(延迟累积): true = 每 3 秒或有足够电量时才查询累积值(千瓦时)。false = 始终查询这些值。
ui_addr:URL,如果与设备地址不同,用于调用 Web 界面。
reserved(保留):包含解释为 0 的值的数组(如果设备根据型号支持某些值,则该数组非常有用)。

如果省略上面列出的属性,cFos 充电管理器会使用默认值,这在大多数情况下都很有效。

在 JSON 定义中,下一步是定义仪表用来读取或计算电流、电压等值的变量。充电管理器知道以下变量:
type_designation、version、firmware_version、serial:这些变量构成了磁贴扩展信息中显示的型号名称。
voltage_l1..voltage_l3、current_l1..current_l3、power_w、power_var、power_va、power_w_l1..power_w_l3:cFos 充电管理器会尝试计算电压_l1...l3、有符号电流_l1...l3、power_w 和 power_va 的值。您不必指定所有变量。
import_wh、export_wh: 充电管理器使用这些变量来显示 import_wh 和 export_wh。对于单向电表(如逆变器),应始终只定义 import_wh。对于双向计量表(如蓄电池或电网基准计量表),应仅定义 Export_wh。

soc:如果可用,电池储能罐的充电状态将以 % 显示在磁贴中。
此外,您还可以定义名称不同的其他变量,这些变量在每次更新时读出或使用公式计算。如果定义的变量以 CM.开头,例如 CM._set_price,分配的值将存储在全局充电管理器变量中(见下文),并可进行相应的查询。
以*.开头的变量如果定义了以 * 开头的变量,则这些变量将显示在用户界面中计量表的扩展信息下,例如电池存储的温度。

一个变量的定义。

该对象以上面列出的变量命名,并具有以下属性:
fixed: 具有固定值的字符串。如果不能确定数值,例如type_designation或voltage,则非常有用。
expr:字符串,变量不被读出,而是作为一个公式被评估。
type:如果不是fixed或expr,则变量的类型:int16, int32, float, int64, string。这对Modbus来说很重要,以便以正确的格式读出寄存器。对于JSON/HTTP,你通常可以采用float。
分辨率:float,读取值乘以'分辨率'。电压的值必须是伏特,电流是毫安培,功率是瓦特,能量是瓦特小时(Wh)。在负的'分辨率'下,如果一个值有相反的符号,你可以反转它。
once: bool (true or false), 如果是真的,当设备被初始化时只读一次值,否则定期读。
address: number (Modbus) or string (HTTP/JSON), the Modbus register number or the HTTP URL of the value to be read.
query:字符串,对于HTTP JSON来说,是收费管理器查询语言的规范,用它在JSON响应中找到要读取的值。
order: 字符串,对于Modbus来说是字节顺序,可以是 "hl "或 "lh",值在其中出现。length: 数字,对于Modbus来说是寄存器中字符串的长度。通过变量 "version "和 "firmware_version","length "被用来将数字版本变成带点的字符串。长度 "允许使用2或4的值,这将导致版本格式a.b和a.b.c.d。对于'长度'2和类型'int16',计费管理器用点来分隔低字节和高字节,对于int32低字和高字,对于'int64'低字和高字。对于'长度'4和'int32',计费管理器将值分成4个字节,用点分开。对于'int64'则是相应的4个字。
regex:字符串。如果指定了正则表达式,计数器的响应不需要是JSON格式的。结果,要么是正则表达式的整个匹配,要么是第一组被评估。请仅在设备不返回JSON的情况下使用。下面是我们的正则表达式的特征列表:
any char: .
named classes:\
匿名类: [a-z0-9_], [^0-9], [^\d]
有替代品的组:(ab|cd|ef)
非捕获组:(?:ab|cd)
(贪婪)一次或没有:a? ,a?
(贪婪)多次或没有:A*, A*?
(贪婪)一次或多次:a+, a+?
字符串的开始:^
字符串的结束:$

投入的定义。

充电管理器可以从每个设备的不同寄存器或JSON元素查询多达32个输入值。输入 "属性是一个JSON数组。你必须为每个输入定义以下属性:
地址:地址(Modbus寄存器或URL)。

查询。 将通过该请求读取的输入位数。对于HTTP/JSON,查询语言要在响应中找到值。

cFos计费管理器在每次更新时都会读取所有以这种方式定义的输入,并在内部将这些比特放在一个数组中,然后可以用公式查询,Input1...InputN。

产出的定义。

充电管理器可以为每个设备切换多达32个输出。输出被定义在 "输出 "中,作为输出对象的JSON数组。 在每个更新周期结束时,如果各输出的状态发生了变化,所有输出都会被切换。
对于每个输出,你必须在输出对象中定义以下属性:
地址:带有可选的HTTP方法的HTTP URL,例如:GET http://www.example.com?output1=${var1}。为了设置 Modbus 寄存器,您可以使用 cFos 计费管理器的 HTTP API。计费管理器检测本地主机上的匹配访问,并将请求重定向到内部处理程序,因此您不需要像外部HTTP API访问那样进行授权。如果所有替换后的URL是空的,则不设置输出。例如,你只能在某些变量存在时切换输出(见公式:exists()函数)。在地址中,你可以额外指定${address}和${id}。这是在设置中定义的当前设备地址和Modbus ID。地址和ID主要用于使用Modbus API(见下文)。
body:POST或PUT的可选HTTP主体。
在URL和正文中,你可以使用${expr}公式,引用全局充电管理器变量或来自各自的计数器。公式'expr'在设置输出时被评估,并在URL或body的文本中替换。如果在上面的例子中,http://www.example.com?output1=1 设置输出,http://www.example.com?output1=0 删除输出,你可以定义一个变量'var1'并根据需要将其设置为1或0。通过这种方式,你也可以在Modbus寄存器中写入数值来控制内存性能,这些数值之前已经用公式存储在一个变量中。
如果你不在URL中传递数值,而是需要根据公式将一个文本替换成另一个文本,比如Shelly WLAN插座,你可以这样写:${if expr`text1`text2}。撇号 "是一个回车键(ASCII码96)。如果'expr'!=0,则插入text1,否则是text2。对于Shelly WLAN套接字,URL看起来像这样:http://<ip-addr>/relay/0?turn=${if expr`on`off},即如果expr !=0,充电管理器就会调用http://<ip-addr>/relay/0?turn=on,否则http://<ip-addr>/relay/0?

如果你输入相对路径作为URL,充电管理器会采用为相应设备配置的地址。如果你输入'localhost'作为域,充电管理器采用它所运行的设备的地址。如果它检测到对自己的API的访问,它使用内部处理程序,而不是执行完整的HTTP访问,这样你就不必在计数器定义中存储用户名和密码。一个以*开头的URL将导致计费管理器总是执行一个完整的HTTP访问。

重置输出:除了 "输出 "数组外,你还可以定义一个名为 "重置 "的数组,其结构与 "输出 "数组类似。当设备被停用时,这可以用来将输出重置为初始值。有了它,再加上用户定义的变量和 "once": true,你就可以把设备设置回它的初始状态。
定期写入输出:对于某些设备,必须定期写入输出,否则设备会将数值重置为 "默认值"。例如,如果存储器控制有一段时间没有主动写入,Kostal存储器会再次使用其默认规则。要定期设置输出,可以在地址前加上#xxx#,其中xxx表示每隔多少秒就重写一次输出,即使要写的值一直保持不变。例如,如果地址是/cnf?cmd=set_cm_vars&name=test&val=42,你可以用#30#/cnf?cmd=set_cm_vars&name=test&val=42来确保这个值每30秒被写入。

查询语言的定义。

目前,成员名称和运算符". "和"[]"可以在 "查询 "搜索表达式中使用,例如。

测试名为 "测试 "的元素
name1.name2子对象 "name1 "中名为 "name2 "的元素
名称[idx]对象元素 "name "的元素 "idx"。"idx "可以是一个数字,例如对数组而言,或者是一个字符串。
name["u2"]对象元素 "name "的元素 "u2",对应于 "name.u2"
name[{"el1": "v1", "el2": 3}].value选择满足对象符号条件的数组元素,评估名为'value'的元素。例如,在这里,在数组'name'中,选择具有作为对象元素的'el1',值为'v1'和'el2',值为3的元素,然后从这个对象中返回元素'value'的值。

全球充电管理器的变量。

你可以在计费管理器配置中创建变量。你可以使用一个固定值或一个公式作为数值。在每个更新周期结束时,如果有必要,计费管理器会重新计算这些变量的值。然后你可以在(某些)计费管理器参数、计费规则中使用它们,或控制输出。你也可以把Ex.member或Mx.member写成变量。这里,ExMx是充电管理器中设置的壁挂炉或电表的设备ID。 成员是一个 "用户定义 "的变量,存储在相应的设备中。一些变量可能有特殊含义。对于KEBA "out1 "是开关输出,对于ABB B23仪表 "out1 "和 "out2 "是开关输出(对于支持该功能的型号)。一个1会切换输出,一个0会再次关闭。

如果你有一些电器必须在某些条件下被打开,但又要运行一段时间(如洗衣机、洗碗机),你也可以把变量定义为 "触发器"。然后,该变量的公式就是该变量被设置为1的条件。在一个可调整的时间后,它又会被设置为0。只要条件满足,"再触发条件 "可以使关闭(即把变量设置为0)之前的时间一再延长。

出于测试目的,您可以显示充电管理器和电表变量,例如当前的 Awattar 价格:


                        计数器变量截图显示

全球充电管理器的输出。

在充电管理器配置中,你可以配置全局输出,如上文 "输出 "下的计数器定义中所述。如果它们的状态发生了变化,就会在每个更新周期结束时设置这些。如果你想在用户定义的设备中控制开关输出,建议采用上述惯例(见充电管理器变量)。你在用户定义的计数器中设置名称为 "out1"、"out2 "等的变量,并在用户定义的计数器中设置输出,根据这些变量的值来切换输出。

充电管理器的全球Modbus API。

充电管理器的Modbus API用于控制具有任何Modbus RTU或TCP地址的Modbus设备(可从充电管理器访问)。对于Modbus RTU,输入COMx,bd,8,p,s作为地址,其中x是COM端口号,bd是波特率,p是奇偶校验('N'、'E'或'O'),s是停止位的数量(1或2),如各个设备的配置。对于 Modbus TCP,收件人是充电管理器网络中设备的 IP 地址,包括端口号。
Modbus API的URL(用于HTTP GET)是:
/cnf?cmd=modbus_get 或 /cnf?cmd=modbus_set
cFos计费管理器支持以下附加查询参数:
addr:上面提到的Modbus RTU或TCP设备地址。
func:Modbus功能编号,例如用于读取3或4,用于写入6或16。
id:Modbus设备的设备ID。
reg:Modbus寄存器编号。值可以用十进制或十六进制(前缀为0x)给出。
val:数字,要写进寄存器的值。
类型:'w' 16位(默认),d = 32位,f = float,q = 64位,s = string。
cnt:数字,字符串在寄存器中的最大长度,其他类型省略或设置为1。
order:字符串,字节的顺序,可以是 "hl "或 "lh"。

注意:如果你的 "计数器 "主要有控制任务,你可以在这个瓦片的设置中勾选 "隐藏设备 "选项,这样这个设备就不会出现在开始页。

注意:一些通过HTTP读取的仪表需要一个用户名/密码作为授权。你可以在HTTP访问的地址中指定,例如用http://username:password@192.168.2.111。如果你的用户名或密码包含"@",你必须用"%40 "代替。