使用者定義的計數器

備註： cFos Charging Manager 可以讀取大部分使用 SunSpec 的太陽能變頻器 (裝置類型「SunSpec Solar Inverter / Meter」)。在這種情況下，您不需要建立自己的電表定義。

cFos Charging Manager 允許您建立自己的計費器定義，以支援標準項目中沒有的計費器。目前有三種類型：Modbus 計數器、HTTP/JSON 計數器和 MQTT/JSON 計數器。這些計數器的定義檔案非常相似。Modbus 計數器透過 Modbus 從特定暫存器讀取資料，而 HTTP/JSON 計數器透過 HTTP 請求擷取資料，並在回應中讀取 JSON。對於 MQTT/JSON 計數器，cFos Charging Manager 會訂閱 MQTT 主題，並讀取主題下發佈的 JSON 訊息。cFos 計費管理器使用小型「查詢語言」進行讀取。以下是cFos Charging Manager 中 MQTT 功能的說明文件。

除了一系列預先定義的變數（例如電流和電壓）之外，使用者定義的計數器也可以讀取未知的使用者定義變數、查詢輸入和設定輸出。讀取變數和設定輸出可以分析公式。結合以下所述的充電管理員變數及全域充電管理員輸出，這是一項強大的功能，甚至可執行某些家庭自動化任務及控制外部裝置，例如電池儲存裝置。如果您使用此功能實現控制任務，請提供回饋。我們對客戶使用 cFos Charging Manager 控制的內容非常感興趣，這有助於我們根據客戶需求進一步開發 Charging Manager。

以下是一個簡單的 Modbus 定義範例，讀出單一暫存器的有功功率。您可以針對特定的應用，輕鬆修改暫存器號碼：
單一暫存器的定義範例.

以下是一個 Modbus 定義範例和一個 HTTP/JSON 定義範例：
下載 Modbus 計數器的定義範例
下載 HTTP/JSON 計數器的定義範例

Charging Manager 已提供一些這樣的檔案，但您可以在「系統組態」下上傳或刪除自己的檔案。
您可以在此找到我們提供的大部分儀表定義：
下載提供的計數器定義

如果您已建立了自己的計數器檔案，且該檔案可能與其他使用者相關，請提供給我們，我們將不勝感激。我們將隨收費管理器的未來版本一起提供。

定義檔案的結構：

計數器定義是 JSON 檔案，具有全局 JSON 物件，該物件具有屬性和子物件。rtype'決定讀取操作的類型：0 = Modbus、1 = HTTP/JSON、2 = MQTT/JSON。mtype' 決定裝置類型：0 = 其他裝置、1 = 電錶、2 = 變頻器、4 = 電池儲存。

您可以使用前綴 '0x' 指定十進位或十六進位的數字。也允許使用 '//' 的單行註解。我們建議透過 JSON5 驗證器來執行您的定義檔案，例如這個JSON5 驗證器

您應該先閱讀公式章節，才能瞭解哪些值可以用在以下參考的公式中。

Modbus 定義有一個具有下列屬性的物件 'rtu'：

silence_period，以毫秒為單位：決定 Modbus RTU 存取前的暫停時間長度，以便裝置可辨識訊息的開始。
silence_same_slave，true：多次存取同一裝置時也會保持暫停。
retries：如果裝置沒有回應，重試的次數。
rcv_timeout：以毫秒為單位：每次存取時，裝置回應前的最長等待時間。

這些全局屬性適用於 Modbus TCP 和 RTU：

modbus_read：
modbus_read_max_registers: 讀取 Modbus 指令的函式號碼，通常是 3 或 4。
modbus_allow_gaps: true = 在讀取操作中可以讀取未使用的暫存器區域。

有一個 'tcp' 物件，具有下列 Modbus TCP 和 HTTP/JSON 的屬性：

connect_timeout: 以毫秒為單位: TCP 連線的最長等待時間。
delay_after_connect: 以毫秒為單位: 連線建立後，在傳送第一個指令前的暫停時間。

這兩種定義類型（Modbus 和 HTTP/JSON）也具有下列屬性：

upd_delay: 以毫秒為單位：決定可讀取裝置的間隔。如果查詢太頻繁，有些裝置會超載。
manufacturer: 字串，製造商的名稱。
delay_accumulated: true = 累積值 (kWh) 只會每 3 秒查詢一次，或在有足夠電力時才會查詢。false = 這些值會一直被查詢。
ui_addr: URL，如果與用於呼叫 Web 介面的裝置位址不同。
reserved：包含解釋為 0 的值的陣列 (如果裝置依機型支援特定值，則此陣列很有用)。

如果省略上面列出的屬性，cFos Charging Manager 會使用預設值，在大多數情況下都運作良好。

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 Charging Manager 會嘗試根據這些值來計算電壓_l1..l3、有簽號的電流_l1..l3、power_w 和 power_va。您不必指定所有變數。
import_wh, export_wh: Charging Manager 會使用這些變數來顯示 import_wh 和 export_wh。對於單向電表 (例如逆變器)，您應該只定義 import_wh。只有雙向電錶 (例如儲存電錶或電網參考電錶) 才應該定義 export_wh。

soc: 如果有的話，電池儲存的充電狀態會以 % 顯示在磚塊中。
您也可以定義其他具有不同名稱的變數，這些變數會在每次更新時讀出或使用公式計算。如果您定義以 'CM.' 開頭的變數，例如 CM._set_price，則所指定的值會儲存在全域 Charging Manager 變數中（請參閱下文），並可據此進行查詢。
以 * 開頭的變數如果您定義了以 '*' 開頭的變數，這些變數會顯示在使用者介面中電錶磚的延伸資訊下，例如電池儲存單元的溫度。
注意：變數名稱只能使用數字和字母 a-z 及 A-Z。

變數的定義：

該物件以上面列出的變數名稱命名，並具有以下屬性：
fixed：具有固定值的字串。如果無法確定值，例如 type_designation 或電壓，則此物件非常有用。
expr：字串。
type: 如果不是固定值或 expr，則變數的類型：int16、uint16、int32、uint32、float、int64、字串。這對於 Modbus 來說很重要，以便以正確的格式讀取暫存器。uint16 和 uint32 是只能接受正數的類型。對於 JSON/HTTP，通常可以使用 float。
解析度：float。讀取值乘以 「解析度」。電壓值的單位必須是伏特，電流值的單位必須是毫安，功率值的單位必須是瓦特，能量值的單位必須是瓦特小時 (Wh)。使用負 「解析度」，如果數值有相反的符號，您可以將其反轉。
一次： bool（true 或 false）。如果為真，則只在裝置初始化時讀取一次值，否則會定期讀取。
位址：數字 (Modbus) 或字串 (HTTP/JSON)。要讀取的值的 Modbus 暫存器號碼或 HTTP URL。
query：字串。對於 HTTP JSON，充電管理器在 JSON 回應中找到要讀取的值的查詢語言規格。
order（順序）：字串。對於 Modbus，該值存在的位元組順序（"hl 「或 」lh"）。length：數字。對於 Modbus，字串在暫存器中的長度；對於變數 'version「 和 」firmware_version'，'length' 用來將數字版本轉換為帶點的字串。length' 允許的值為 2 或 4，會產生版本格式 a.b 和 a.b.c.d。當 'length「 為 2 且類型為 」int16「 或 」uint16「 時，Charging Manager 會用點分隔低位元組和高位元組，用 」int32「 或 」uint32「 分隔低位元組和高位元組字元，用 」int64' 分隔低位元組和高位元組字元。對於 'lenth「 4 和 」int32「 或 」uint32'，計費管理器會將數值分割成 4 個位元組，並以點分隔。對於 'int64' 則為相應的 4 個字元。
regex：字串。如果指定了正則表達式，計數器回應不需要是 JSON 格式。正規表達式的整個匹配或第一組都會被評估為結果。請僅在裝置不傳回 JSON 時使用。以下是我們正規表達式的功能清單：
any char: .
named classes：\d \s \w \D \S \W
匿名類別：[a-z0-9_]、[^0-9]、[^\d]
有替代字元的群組：(ab|cd|ef)
非捕捉群組：(?:ab|cd)
(貪婪) 一次或無：a
?(greedy) many or none: a*, a*
?(greedy) 一次或多次：a+, a+?
開始字串：^
結束字串：$

輸入的定義：

充電管理員可從各種暫存器或 JSON 元素為每個裝置請求多達 32 個輸入值。輸入 "屬性是一個 JSON 陣列。您必須為每個輸入定義下列屬性：
address: 位址 (Modbus 暫存器或 URL)。
計數：使用此請求讀取的輸入位元數。
query：對於 HTTP/JSON，在回應中尋找數值的查詢語言。

每次更新時，cFos Charging Manager 都會讀取以此方式定義的所有輸入，並將位元儲存在內部的陣列中，然後可以使用公式 Input1...InputN進行查詢。

輸出的定義：

Charging Manager 最多可切換每個裝置的 32 個輸出。輸出在 「輸出」 中定義為輸出物件的 JSON 陣列。 在每個更新週期結束時，如果各輸出的狀態已改變，所有輸出都會被切換。
您必須在每個輸出物件中定義下列屬性：
位址： HTTP URL，可選擇 HTTP 方法，例如 GET http://www.example.com?output1=${var1}。要設定 Modbus 暫存器，您可以使用 cFos Charging Manager 的 HTTP API。Charging Manager 會識別 localhost 上的適當存取，並將請求重定向至內部處理程式，因此您不需要像外部 HTTP API 存取一樣需要授權。如果 URL 在所有替換之後為空，則不會設定輸出。例如，您只能在某些變數存在時切換輸出 (請參閱公式：exists() 函式)。您也可以在位址中指定 ${address} 和 ${id}。這是設定中定義的目前裝置位址和 Modbus ID。address「 和 」id' 主要用於使用 Modbus API (請參閱下文)。
body: POST 或 PUT 的可選 HTTP body。
在 URL 和 body 中，您可以使用 ${expr} 來使用引用全局充電管理器變數或來自相關計數器的公式。公式 'expr' 會在設定輸出時進行評估，並取代 URL 或正文的文字。如果在上面的例子中，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?turn=off。

如果輸入相對路徑作為 URL，充電管理器會使用為各裝置設定的位址。如果輸入「localhost」作為網域，充電管理程式會使用其執行的裝置位址。如果它識別到自己的 API 存取，它會使用內部處理程式，而不是執行完整的 HTTP 存取，這樣您就不必在計數器定義中輸入使用者名稱和密碼。以 '*' 開頭的 URL 會導致計費管理員始終執行完整的 HTTP 存取。

重設輸出：除了 "outputs 「陣列外，您也可以定義一個名為 」resets 「的陣列，其結構與 」outputs "陣列相似。這可讓輸出在裝置停用時重設為初始值。這可以與使用者定義變數和 "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 秒寫入一次。

查詢語言的定義：

目前，成員名稱和運算符號「.」和「[]」可用於「查詢」搜尋表達式，範例：

Global Charging Manager 變數：

您可以在 Charging Manager 設定中建立變數。您可以使用固定值或公式作為值。在每個更新週期結束時，Charging Manager 會視需要重新計算這些變數的值。然後，您可以在（某些）Charging Manager 參數、計費規則中使用這些變數，或控制輸出。您也可以將Ex.member 或Mx.member 寫成變數。在這種情況下，Ex和Mx是在充電管理器中設定的壁掛盒或電錶的裝置 ID。member 「是 」使用者定義 "的變數，會儲存在對應的裝置中。有些變數可能有特殊意義：對於 KEBA，"out1 「是切換輸出；對於 ABB B23 計量表，」out1 「和 」out2 "是切換輸出（對於支援此功能的型號）。1 切換輸出，0 則再次關閉。

如果您的電器在某些條件下必須開啟，但之後又必須運轉一段時間（例如洗衣機、洗碗機），您也 可以將變數定義為「觸發器」。在這種情況下，變數的公式就是將變數設為 1 的條件。經過一段可調整的時間後，變數會再次設定為 0。只要條件滿足，「重新觸發條件 」允許關閉（即變數設置為 0）前的時間一再延長。

注意：變數名稱只能使用數字和字母 a-z 及 A-Z。

為了測試目的，您可以顯示充電管理員和計量表變數，例如目前的 Awattar 價格：

Global Charging Manager Outputs（全球充電管理員輸出）：

在 Charging Manager 設定中，您可以設定全局輸出，如上文計數器定義中「輸出」一節所述。如果它們的狀態已改變，則會在每個更新週期結束時設定。如果要控制使用者定義裝置中的切換輸出，建議使用上述慣例 (請參閱 Charging Manager 變數)：您在使用者定義計數器中設定名稱為 "out1"、"out2" 等的變數，並在使用者定義計數器中設定根據這些變數的值來切換輸出的輸出。

Charging Manager 的 Global Modbus API：

Charging Manager 的 Modbus API 用於控制具有任何 Modbus RTU 或 TCP 位址（可從 Charging Manager 存取）的 Modbus 裝置。與個別設備的設定一樣，輸入 COMx,bd,8,p,s 作為 Modbus RTU 的位址，其中 x 是 COM 連接埠號碼，bd 是鮑率，p 是奇偶校驗（'N'、'E「或」O'），s 是停止位元數（1 或 2）。對於 Modbus TCP，addresse 是 Charging Manager 網路中裝置的 IP 位址，包括連接埠號。
Modbus API 的 URL (HTTP GET) 為：
/cnf?cmd=modbus_get 或 /cnf?cmd=modbus_set
cFos 充電管理器支援下列額外查詢參數：
addr：
func: Modbus 功能編號，例如讀取 3 或 4，寫入 6 或 16。
id: Modbus 設備的 Device ID。
reg: Modbus 暫存器編號。
val: 數值：要寫入寄存器的值。
類型： 'w' 16 位元 (預設)、d = 32 位元、f = 浮點值、q = 64 位元、s = 字串。
cnt：數字：寄存器中字串的最大長度，其他類型省略或設定為 1。
order：字串：位元組順序，可以是 "hl「 或 」lh"。

注意： 如果您的「計數器」主要有控制任務，您可以在此磁磚的設定中勾選「隱藏裝置」選項，這樣此裝置就不會出現在開始頁面上。

注意：某些透過 HTTP 讀取的計數器需要使用者名稱/密碼作為授權。您可以在 HTTP 存取的位址中指定此項，例如使用http://username:password@192.168.2.111。如果您的使用者名稱或密碼包含「@」，則必須使用「%40」取代。