Documentatie

Door gebruiker gedefinieerde tellers

Opmerking: De cFos Charging Manager kan de meeste omvormers voor zonne-energie uitlezen met SunSpec (apparaattype "SunSpec Solar Inverter / Meter"). In dit geval hoeft u geen eigen meterdefinitie te maken.

Met de cFos Charging Manager kunt u uw eigen meterdefinities maken om meters te ondersteunen die niet in het standaardrepertoire zitten. Er zijn momenteel drie soorten: Modbus-tellers, HTTP/JSON-tellers en MQTT/JSON-tellers. De definitiebestanden voor deze tellers lijken sterk op elkaar. Modbus-tellers lezen hun gegevens via Modbus uit specifieke registers, terwijl HTTP/JSON-tellers hun gegevens ophalen via een HTTP-verzoek en JSON als antwoord parseren. Voor MQTT/JSON-tellers abonneert de cFos Charging Manager zich op MQTT-onderwerpen en parseert berichten die onder het onderwerp als JSON worden gepubliceerd. Voor het parsen gebruikt de cFos Charging Manager een kleine "querytaal". Hier is de documentatie van de MQTT-mogelijkheden in de cFos Charging Manager.

Naast een aantal vooraf gedefinieerde variabelen, zoals stroom en spanning, kunnen door de gebruiker gedefinieerde tellers ook onbekende door de gebruiker gedefinieerde variabelen inlezen, ingangen opvragen en uitgangen instellen. Door het inlezen van variabelen en het instellen van uitgangen kunnen formules worden geëvalueerd. In combinatie met de hieronder beschreven Charging Manager-variabelen en globale Charging Manager-uitgangen is dit een krachtige functie en maakt het zelfs bepaalde domotica-taken en de besturing van externe apparaten zoals batterijopslag mogelijk. Als u hiermee controletaken realiseert, geef ons dan feedback. Wij zijn zeer geïnteresseerd in wat mensen regelen met de cFos Charging Manager en het helpt ons om de Charging Manager verder te ontwikkelen volgens de behoeften van de klant.

Hier is een eenvoudige voorbeelddefinitie voor Modbus die één register voor actief vermogen uitleest. U kunt het registernummer gemakkelijk wijzigen voor uw specifieke toepassing:
Voorbeelddefinitie voor één register.

Hier is een voorbeelddefinitie voor Modbus en een voor HTTP/JSON:
Download voorbeelddefinitie voor Modbus-meter
Download voorbeelddefinitie voor HTTP/JSON meter

De Laadmanager wordt al geleverd met een paar van dergelijke bestanden, maar u kunt uw eigen bestanden uploaden onder "Systeemconfiguratie" en ze ook weer verwijderen.
Hier vindt u de meeste van de meter definities die wij aanbieden:
Download meegeleverde teller definities

Als u uw eigen tellerbestand hebt gemaakt en het zou relevant kunnen zijn voor andere gebruikers, dan zouden we u zeer dankbaar zijn als u het ons ter beschikking zou willen stellen. Dan zullen wij het met toekomstige versies van de Laadmanager meeleveren.

Download meter definities voor extra meters

Structuur van een definitiebestand:

Meterdefinities zijn JSON-bestanden met een globaal JSON-object dat eigenschappen en kindobjecten heeft. rtype" bepaalt het type leesoperatie: 0 = Modbus, 1 = HTTP/JSON, 2 = MQTT/JSON. Getallen kunnen naar keuze worden opgegeven in decimaal of hex met voorvoegsel 0x. Bovendien is commentaar van één regel met // toegestaan. Wij raden aan uw definitiebestanden door een JSON5-validator te laten lopen, bijvoorbeeld deze JSON5-validator

U moet beslist het hoofdstuk Formules hebben gelezen om te begrijpen welke waarden in formules in de volgende referentie kunnen worden gebruikt.

Modbus definities hebben een object "rtu" met de volgende eigenschappen:

silence_period, in msec. bepaald, de pauzeduur vóór een Modbus RTU-toegang, zodat het apparaat het begin van een bericht herkent.
silence_same_slave, true: de pauze wordt ook in acht genomen bij meerdere toegangen tot hetzelfde apparaat.
retries: het aantal retries als het apparaat niet reageert.
rcv_timeout: in msec. de maximale wachttijd per toegang tot het apparaat reageert.

Deze globale eigenschappen gelden voor Modbus TCP en RTU:

modbus_read: Het functienummer van het Modbus-leescommando, gewoonlijk 3 of 4.
modbus_read_max_registers: Het maximum aantal registers dat per keer kan worden gelezen.
modbus_allow_gaps: true = Ongebruikte registergebieden mogen bij een leesoperatie worden gelezen.

Voor Modbus TCP en HTTP/JSON is er een object 'tcp' met de volgende eigenschappen:

connect_timeout: is msec. de maximale wachttijd voor een TCP-verbinding.
delay_after_connect: in msec. Pauzeer nadat de verbinding tot stand is gebracht voordat u het eerste commando verzendt.

Beide definitietypen (Modbus en HTTP/JSON) hebben de volgende aanvullende eigenschappen:

upd_delay: in msec. bepaalt het interval waarin een apparaat kan worden gelezen. Sommige apparaten worden overbelast als ze te vaak worden opgevraagd.
manufacturer: String, naam van de fabrikant. Dit wordt weergegeven in de uitgebreide informatie van de tegel.
delay_accumulated: true = Geaccumuleerde waarden (kWh) worden alleen elke 3 seconden opgevraagd of als er voldoende vermogen is. false = Deze waarden worden altijd opgevraagd.
ui_addr: URL, indien verschillend van het apparaatadres voor het oproepen van de webinterface.
reserved: Array met waarden die als 0 worden geïnterpreteerd (handig als het apparaat bepaalde waarden ondersteunt, afhankelijk van het model).

Als je de bovenstaande eigenschappen weglaat, neemt de cFos Charging Manager standaardwaarden aan die in de meeste gevallen goed werken.

In de JSON-definitie is de volgende stap de definitie van variabelen die de meter gebruikt om waarden voor stroom, spanning, enzovoort uit te lezen of te berekenen. De Laadmanager kent de volgende variabelen:
type_aanduiding, versie, firmware_versie, serie: Deze vormen de modelnaam zoals weergegeven in de uitgebreide info van de tegel. Deze worden eenmalig opgevraagd bij het instellen of resetten van de meter.
voltage_l1..voltage_l3, current_l1..current_l3, power_w, power_var, power_va, power_w_l1..power_w_l3: De cFos Charging Manager probeert hieruit waarden te berekenen voor voltage_l1..l3, getekende stroom_l1..l3, power_w en power_va. Je hoeft niet alle variabelen op te geven. De cFos Laadmanager probeert de waarden te berekenen uit de bestaande variabelen.
import_wh, export_wh: De Laadmanager gebruikt deze variabelen om import_wh en export_wh weer te geven. Voor eenrichtingsmeters (bijv. omvormers) moet u altijd alleen import_wh definiëren. Export_wh moet alleen worden gedefinieerd voor bidirectionele meters (zoals opslagtanks of netreferentiemeters).

soc: Indien beschikbaar wordt de opladingsstatus van een accuopslagtank in % weergegeven in de tegel.
Daarnaast kun je andere variabelen definiëren met verschillende namen die bij elke update worden uitgelezen of berekend met formules. Als je variabelen definieert die beginnen met CM., bijv. CM._set_price, worden de toegekende waarden opgeslagen in de globale Laadmanager-variabelen (zie hieronder) en kunnen ze dienovereenkomstig worden opgevraagd.
Variabelen met *: Als u variabelen definieert die beginnen met *, worden ze in de UI weergegeven in de tegel van de meter onder uitgebreide informatie, bijv. de temperatuur van een accuopslag.

Definitie van een variabele:

Het object wordt genoemd naar de bovengenoemde variabele en heeft de volgende eigenschappen:
fixed: String met vaste waarde. Nuttig als bijvoorbeeld geen waarde kan worden bepaald, bijv. voor type_aanduiding of spanning.
expr: String, de variabele wordt niet uitgelezen maar als formule geëvalueerd.
type: Indien niet fixed of expr, het type van de variabele: int16, int32, float, int64, string. Dit is belangrijk voor Modbus om de registers in het juiste formaat uit te lezen. Voor JSON/HTTP kunt u meestal float nemen.
resolutie: float, de uitgelezen waarde wordt vermenigvuldigd met 'resolutie'. Waarden voor spanning moeten in volt zijn, stromen in milliampère, vermogen in watt, energie in wattuur (Wh). Bij negatieve 'resolutie' kunt u een waarde inverteren als deze het tegenovergestelde teken heeft.
once: bool (true of false), indien true, wordt de waarde slechts eenmaal gelezen wanneer het apparaat wordt geïnitialiseerd, anders periodiek.
address: getal (Modbus) of string (HTTP/JSON), het Modbus registernummer of de HTTP URL van de te lezen waarde.
query: String, voor HTTP JSON de specificatie in de querytaal van de Charging Manager, waarmee hij de in te lezen waarde vindt in het JSON-antwoord.
order: String, voor Modbus de byte-volgorde, ofwel "hl" of "lh", waarin de waarde aanwezig is. length: getal, voor Modbus de lengte van een string in registers. Bij de variabelen "version" en "firmware_version" wordt "length" gebruikt om numerieke versies om te zetten in strings met punten. Voor 'lengte' zijn waarden van 2 of 4 toegestaan, die dan resulteren in de versieformaten a.b, en a.b.c.d. Voor 'lengte' 2 en type 'int16' scheidt de Charging Manager lage en hoge bytes door punten, voor int32 laag en hoog woord, voor 'int64' laag en hoog dword. Voor 'lenth' 4 en 'int32' splitst de Charging Manager de waarde in 4 bytes gescheiden door een punt. Voor 'int64' de 4 woorden dienovereenkomstig.
regex: String. Als een reguliere expressie wordt opgegeven, hoeft het antwoord van de teller niet in JSON te zijn. Bijgevolg wordt ofwel de volledige match van de reguliere expressie ofwel de eerste groep geëvalueerd. Alleen gebruiken als het apparaat geen JSON retourneert. Hier is de lijst met kenmerken van onze reguliere expressies:
elk char: .
named classes: \
anonieme klassen: [a-z0-9_], [^0-9], [^\d]
groepen met alternatieven: (ab|cd|ef)
niet-gevangen groepen: (?:ab|cd)
(greedy) veel of geen: a?, a???
(greedy) veel of geen: a*, a*?
(greedy) eenmalig of meer: a+, a+?
begin van string: ^
einde van string: $

Definitie van ingangen:

De Charging Manager kan tot 32 invoerwaarden van verschillende registers of JSON-elementen per apparaat bevragen. De eigenschap "Inputs" is een JSON-array. U moet voor elke ingang de volgende eigenschappen definiëren:
adres: Adres (Modbus register of URL).
tellen: Aantal ingangsbits dat met dit verzoek wordt gelezen.
query: Voor HTTP/JSON, zoektaal om de waarde in het antwoord te vinden.

De cFos Charging Manager leest bij elke update alle op deze wijze gedefinieerde ingangen en plaatst de bits intern in een array, die vervolgens kan worden opgevraagd met in formules, Input1..InputN..

Definitie van outputs:

De Laadmanager kan tot 32 uitgangen per apparaat schakelen. Uitgangen worden gedefinieerd in "outputs" als een JSON-array van uitgangsobjecten. Alle uitgangen worden geschakeld aan het einde van elke updatecyclus als de status van de respectieve uitgang is gewijzigd.
Voor elke uitgang moet je de volgende eigenschappen in het uitgangsobject definiëren:
adres: HTTP URL met optionele HTTP-methode, bijv. GET http://www.example.com?output1=${var1}. Om Modbus-registers in te stellen kun je de HTTP API van de cFos Charging Manager gebruiken. De Charging Manager detecteert overeenkomende toegangen op localhost en stuurt het verzoek door naar de interne handler, zodat er geen autorisatie nodig is zoals bij externe HTTP API-toegangen. Als de URL leeg is na alle vervangingen, wordt er geen uitvoer ingesteld. Je kunt bijvoorbeeld alleen uitvoer schakelen als bepaalde variabelen bestaan (zie formules: exists() functie). In het adres kun je aanvullend ${address} en ${id} opgeven. Dit is het huidige apparaatadres en Modbus ID zoals gedefinieerd in de instellingen. Adres en id worden voornamelijk gebruikt voor het gebruik van de Modbus API (zie hieronder).
body: Optionele HTTP body voor POST of PUT.
In de URL en body kun je ${expr} formules gebruiken die verwijzen naar globale Charging Manager variabelen of van de respectievelijke teller. De formule 'expr' wordt geëvalueerd bij het instellen van de uitvoer en vervangen in de tekst van de URL of de body. Als in het bovenstaande voorbeeld http://www.example.com?output1=1 de uitvoer instelt en http://www.example.com?output1=0 deze verwijdert, kun je een variabele 'var1' definiëren en deze naar wens op 1 of 0 zetten. Op deze manier kun je ook numerieke waarden schrijven om de geheugenprestaties in Modbus-registers te regelen die je eerder hebt opgeslagen in een variabele met behulp van een formule.
Als je in plaats van een numerieke waarde door te geven in de URL een tekst moet vervangen door een andere afhankelijk van de formule, zoals bij Shelly WLAN sockets, kun je het als volgt schrijven: ${if expr`text1`text2}. De 'apostrof' is een backtick (ASCII-code 96). Als de 'expr' != 0, wordt tekst1 ingevoegd, anders tekst2. Voor Shelly WLAN socket ziet de URL er dan als volgt uit: http://<ip-addr>/relay/0?turn=${if expr`on`off}, d.w.z. als expr != 0, dan roept de Charging Manager http://<ip-addr>/relay/0?turn=on aan, anders http://<ip-addr>/relay/0?turn=off.

Als u een relatief pad invoert als URL, neemt de Laadmanager het adres dat is geconfigureerd voor het respectieve apparaat. Als u 'localhost' opgeeft als domein, neemt de Laadmanager het adres van het apparaat waarop het draait. Als het een toegang tot zijn eigen API detecteert, gebruikt het de interne handler in plaats van een volledige HTTP-toegang uit te voeren, zodat je geen gebruikersnaam en wachtwoord hoeft op te slaan in de tellerdefinitie. Een URL die begint met een * zorgt ervoor dat de Laadmanager altijd een volledige HTTP-toegang uitvoert.

Uitgangen resetten: Naast een array "uitgangen" kun je ook een array met de naam "resets" definiëren die gestructureerd is zoals de array "uitgangen". Dit kan gebruikt worden om uitgangen terug te zetten naar hun beginwaarden wanneer het apparaat gedeactiveerd wordt. Hiermee kun je, in combinatie met door de gebruiker gedefinieerde variabelen en "once": true, het apparaat terugzetten naar de oorspronkelijke toestand.
Uitgangen periodiek schrijven: Voor sommige apparaten moeten de uitgangen periodiek worden geschreven, anders zet het apparaat de waarden terug naar "standaard". Het Kostal geheugen gebruikt bijvoorbeeld zijn standaardregels opnieuw als de geheugenbesturing een tijdje niet actief is geschreven. Om uitgangen periodiek in te stellen kun je het adres vooraf laten gaan door #xxx#, waarbij xxx aangeeft hoeveel seconden de uitgang wordt herschreven, zelfs als de te schrijven waarde hetzelfde is gebleven. Als het adres bijvoorbeeld /cnf?cmd=set_cm_vars&name=test&val=42 is, kun je #30#/cnf?cmd=set_cm_vars&name=test&val=42 gebruiken om ervoor te zorgen dat deze waarde elke 30 seconden wordt geschreven.

Definitie van query langage:

Momenteel kunnen ledennamen en de operatoren "." en "[]" worden gebruikt in de "query" zoekuitdrukkingen, voorbeelden:

testElement genaamd "test"
naam1.naam2Element genaamd "name2" in kindobject "name1"
naam[idx]Element "idx" van het objectelement "name". "idx" kan een getal zijn, b.v. voor arrays of een string
naam["u2"]Element "u2" van het objectelement "naam", komt overeen met "naam.u2"
naam[{"el1": "v1", "el2": 3}].waardeSelecteer het array-element dat voldoet aan de voorwaarde van de objectnotatie en evalueer het element met de naam 'waarde'. Hier wordt bijvoorbeeld in de array "name" het element geselecteerd dat als objectelementen "el1" met waarde "v1" en "el2" met waarde 3 heeft en vervolgens wordt de waarde van het element "value" uit dit object teruggegeven.

Global Charging Manager variabelen:

U kunt variabelen aanmaken in de configuratie van de Charging Manager. U kunt een vaste waarde of een formule als waarde gebruiken. Aan het einde van elke bijwerkingscyclus berekent de Charging Manager indien nodig de waarde van deze variabelen opnieuw. U kunt ze dan gebruiken in (bepaalde) Laadmanagerparameters, Laadregels of om uitgangen aan te sturen. U kunt ook Ex.member of Mx.member als variabelen schrijven. Hier zijn Exen Mxde apparaat-ID van een wallbox of meter die is ingesteld in de Charging Manager. member is een "door de gebruiker gedefinieerde" variabele die is opgeslagen in het betreffende apparaat. Sommige variabelen kunnen een speciale betekenis hebben: Voor KEBA is "out1" een schakeluitgang, voor ABB B23-meters zijn "out1" en "out2" schakeluitgangen (voor modellen die dit ondersteunen). Een 1 schakelt de uitgang, een 0 schakelt hem weer uit.

Als je apparaten hebt die onder bepaalde omstandigheden moeten worden ingeschakeld, maar dan een tijdje moeten draaien (bv. wasmachine, vaatwasser), kun je de variabele ook definiëren als een "trigger". De formule van de variabele is dan de voorwaarde waarmee de variabele op 1 wordt gezet. Na een instelbare tijd wordt hij dan weer op 0 gezet. Met een "retrigger-conditie" kan de tijd tot het uitschakelen (d.w.z. de variabele op 0 zetten) steeds opnieuw worden verlengd zolang aan de voorwaarde wordt voldaan.

Voor testdoeleinden kun je Charging Manager en meter variabelen weergeven, bijvoorbeeld de huidige Awattar-prijzen:


                        Schermweergave van tellervariabelen

Global Charging Manager Uitgangen:

In de Charging Manager configuratie kunt u globale uitgangen configureren zoals hierboven beschreven in de tellerdefinitie onder "Uitgangen". Deze worden aan het einde van elke bijwerkingscyclus ingesteld als hun status is gewijzigd. Als u schakeluitgangen in gebruikersgedefinieerde apparaten wilt aansturen, wordt bovenstaande conventie aanbevolen (zie Laadmanagervariabelen): U stelt variabelen in met namen "out1", "out2", enz. in de gebruikersgedefinieerde teller en stelt uitgangen in de gebruikersgedefinieerde teller in die de uitgang schakelen afhankelijk van de waarde van deze variabelen.

Globale Modbus API van de Charging Manager:

De Modbus API van de Charging Manager wordt gebruikt om Modbus apparaten aan te sturen die een Modbus RTU of TCP adres hebben (toegankelijk vanuit de Charging Manager). Voor Modbus RTU voert u COMx,bd,8,p,s in als adres, waarbij x het nummer van de COM-poort is, bd de baudrate, p de pariteit ('N', 'E' of 'O') en s het aantal stopbits (1 of 2), zoals in de configuratie van de afzonderlijke apparaten. Voor Modbus TCP is de geadresseerde het IP-adres van het apparaat in het netwerk van de Laadmanager, inclusief het poortnummer.
De URL (voor HTTP GET) van de Modbus API is:
/cnf?cmd=modbus_get of /cnf?cmd=modbus_set
De cFos Charging Manager ondersteunt de volgende aanvullende query parameters:
addr: Het bovengenoemde Modbus RTU of TCP apparaatadres.
func: Modbus functienummer, bijvoorbeeld voor lezen 3 of 4, voor schrijven 6 of 16.
id: Device ID van het Modbus apparaat.
reg: Het Modbus register nummer. De waarde kan worden opgegeven in decimaal of hex (met voorvoegsel 0x).
val: getal, de waarde die in het register moet worden geschreven. Weglaten bij het lezen.
type: 'w' 16bit (standaard), d = 32bit, f = float, q = 64bit, s = string.
cnt: getal, de maximale lengte van de string in registers, weglaten voor andere types of instellen op 1.
order: String, de byte-volgorde, ofwel "hl" of "lh".

Opmerking: Als uw 'teller' voornamelijk controletaken heeft, kunt u in de instellingen van deze tegel de optie 'Apparaat verbergen' aanvinken, zodat dit apparaat niet op de startpagina verschijnt.

Opmerking: Sommige meters die via HTTP worden uitgelezen vereisen een gebruikersnaam/wachtwoord als autorisatie. U kunt dit opgeven in het adres voor HTTP-toegang, bijvoorbeeld met http://username:password@192.168.2.111. Als uw gebruikersnaam of wachtwoord een "@" bevat, moet u deze vervangen door "%40".