Vermogensrichting en antwoordvelden

Eenheden, positief en negatief vermogen, null-waarden en de betekenis van apparaattelemetrie.

Eenheden en ontbrekende waarden

Actief vermogen is in watt (W), energie en batterijcapaciteit in wattuur (Wh), spanning in volt (V), stroom in ampère (A), frequentie in hertz (Hz) en temperatuur in graden Celsius (°C). Deel W of Wh door 1.000 om kW of kWh te krijgen. Schijnbaar vermogen gebruikt VA; reactief vermogen gebruikt var.

De batterijvelden soe (energieniveau), soh (batterijgezondheid), minSoe en maxSoe, en het boilerveld pwmPercent gebruiken percentages: 50 betekent 50%, niet 0.5.

Elk beschreven veld wordt teruggegeven, maar veel waarden kunnen null zijn. Niet-ondersteunde PV-ingangen, fasen en sensoren zijn vaak null. Null betekent dat er geen bruikbare waarde is; 0 is een gemeten nul. Datums zijn ISO 8601-teksten met een UTC-offset, of null. Controleer lastSeenDate van elk apparaat: het antwoord bevat de laatst bekende gegevens, ook van offline apparaten, en is geen gelijktijdige meting van de hele installatie.

Positief en negatief vermogen

Er is geen enkele tekenconventie die voor alle apparaattypen geldt. De volgende regels gelden voor de velden uit getInstallationDevices.

Apparaat en veld	Positief	Negatief
Netmeter: `powerAc`, `powerAcL1`–`powerAcL3`	Teruglevering aan het net	Afname van het net
Productiemeter: `powerAc`, fasevermogens	Productie naar de installatie	Omgekeerde stroom op het meetpunt
Omvormer: `powerAc`, fasevermogens	Levering aan de AC-zijde van de installatie vanuit PV en/of een ontladende batterij	Opname van de AC-zijde, bijvoorbeeld voor laden of stand-byverbruik
Batterij: `powerDc`	Laden van de batterij	Ontladen van de batterij
Omvormer: `powerDc`	Apparaatafhankelijk: netto DC-invoer voor AC-omzetting, of PV-productie	Omgekeerde omzetting van AC naar DC bij apparaten die netto DC-omzetting melden
Omvormer: `powerDcPvTotal`, `powerDcPv1`–`powerDcPv6`	PV-productie naar de omvormer	Geen vastgelegde betekenis voor laden/afname
Omvormer: `backupPowerAc`	Voeden van back-up-/EPS-verbruikers	Omgekeerde stroom naar de back-upuitgang, indien gemeld
Laadpaal: `powerAc`, fasevermogens, `powerDc`	Verbruik voor het laden van een voertuig	Geen ondersteunde betekenis voor ontladen/V2G in deze API-versie
Boiler: `powerAc`, fasevermogens	Elektriciteitsverbruik voor verwarming	Geen vastgelegde betekenis voor productie/teruglevering

Bij batterij-currentDc met een richtingsteken betekent positief eveneens laden en negatief ontladen. Gebruik bij voorkeur powerDc voor de vermogensrichting. De tekens van AC-stroom, reactief vermogen en vermogensfactor kunnen per apparaat verschillen. Leid actieve afname/teruglevering niet uit die tekens af.

Het meetpunt van de meter is belangrijk

De array energyMeters kan netmeters, productiemeters en verbruiksmeters bevatten. Elke meter bevat options: tekst of null die de functie/opties beschrijft. GridSense herkent deze waarden:

`options`	Meterfunctie
`Export+Import`	Hoofdnetmeter voor afname en teruglevering.
`Boiler consumption`	Boilerverbruiksmeter.
Tekst met `Production ext`	Externe productiemeter.

Dit veld bevat vrije tekst, geen vaste enum. Null-bytes en omringende witruimte worden verwijderd; een lege tekst blijft leeg. Controleer bij null, lege of onbekende waarden de meterfunctie en bekabeling. De positie in de array bepaalt niet welke meter de netmeter is. Meerdere meters kunnen dezelfde aansluiting meten; optellen kan vermogen dubbel tellen.

Bij een bekende netmeter betekent powerAc: -2500 een afname van 2,5 kW en powerAc: 2500 een teruglevering van 2,5 kW. Het interne energiestroomoverzicht van GridSense gebruikt het tegengestelde teken voor gridPower, teruggegeven door getInstallationCurrentEnergyFlow.

totalImportAc, totalExportAc, dailyImportAc en dailyExportAc zijn energietellers in Wh. De richting staat in de veldnaam. Maak een afnameteller dus niet negatief omdat het actuele vermogen van de netmeter negatief is. Het dagelijkse resetmoment hangt af van het apparaat; deze API garandeert daarvoor geen universele tijdzone.

Omvormervermogen is geen net- of batterijvermogen

Een omvormer die 3.000 W produceert kan lokale verbruikers voeden terwijl de installatie nog steeds stroom van het net afneemt. Gebruik een bekende netmeter om de netstroom van de installatie te bepalen. Het AC-uitgangsvermogen van een omvormer kan bovendien zowel PV- als batterijvermogen bevatten.

batteries[].powerDc: 1500 betekent dat de batterij laadt met 1,5 kW; -1500 betekent ontladen met 1,5 kW. Bij werking op alleen de batterij is dit teken tegengesteld aan het AC-uitgangsvermogen van de omvormer. Door omzettingsverliezen hoeven de groottes niet gelijk te zijn.

Omvormer-powerDc wordt overgenomen uit de integratie. Sommige apparaten gebruiken dit voor PV-productie; SolarEdge gebruikt netto DC-omzetting, inclusief mogelijke batterijstroom. Bij die SolarEdge-integraties wordt PV-vermogen afgeleid van het DC-vermogen van de omvormer plus het laadvermogen van de batterij, met nul als ondergrens. Gebruik powerDcPvTotal voor zonneproductie en de eigen powerDc van de batterij voor laden/ontladen. Pas deze SolarEdge-berekening niet universeel toe en neem niet aan dat powerDc zonneproductie is als powerDcPvTotal null is.

De huidige API meldt supportsBiDirectionalCharging: false voor laadpalen. Negatief laadpaalvermogen is geen ondersteunde voertuig-naar-netfunctie.

Geaggregeerde energiestroom van de installatie

Actuele energiestroom opvragen geeft { valid, installationId, data } terug. Alleen online omvormers, batterijen, meters, laadpalen en boilers tellen mee; relais niet. Als geen daarvan online is, is data gelijk aan null. Anders zijn alle negen velden aanwezig, maar kunnen ze afzonderlijk null zijn. De metingen zijn niet gesynchroniseerd.

Veld	Betekenis
`inverterPower`	AC-vermogen van omvormers plus externe productiemeters, in W. Positief = levering; negatief = opname.
`solarPower`	Geschat zonnevermogen in W uit DC-vermogen van omvormers, integratiespecifieke batterijcorrecties en externe productiemeters. Niet simpelweg de som van PV-telemetrie.
`batteryPower`	Som van DC-batterijvermogen in W. Positief = laden; negatief = ontladen.
`batterySoe`	Rekenkundig gemiddelde van `soe` van online batterijen in procent, niet gewogen naar capaciteit. Ontbrekende metingen tellen als nul in dit gemiddelde.
`gridPower`	Negatief gemiddelde van online `Export+Import`-metervermogen in W. Positief = afname; negatief = teruglevering, tegengesteld aan ruwe meterwaarde `powerAc`.
`housePower`	Geschat verbruik in W: net- plus omvormervermogen, min laadpaal- en boilerverbruik, begrensd op minimaal nul.
`evChargerPower`	Som van laadpaalvermogen in W, per laadpaal bij voorkeur de DC-meting en anders AC. Positief = laadverbruik.
`boilerPower`	Som van beschikbare AC-boilermetingen in W, met absolute metingen van `Boiler consumption`-meters als terugval alleen wanneer geen boilerapparaatmeting beschikbaar is.
`lastUpdated`	Nieuwste tijdstempel van de opgenomen online apparaten, niet het verzoektijdstip of de oudste meting.

Bijvoorbeeld: gridPower: -1200 betekent 1,2 kW terugleveren, terwijl batteryPower: 800 laden met 800 W betekent. Bij inverterPower: 4200, evChargerPower: 600 en boilerPower: 400 is housePower gelijk aan 2.000 W.

De aggregatie kan ontbrekende metingen in nul omzetten. gridPower is null als geen meters online zijn, maar nul als wel meters online zijn zonder een Export+Import-meter. Nul bewijst dus geen evenwicht op de netaansluiting. Bekijk het apparaatendpoint en meteropties options bij onvolledige gegevens.

Groepen antwoordvelden

De installatiedocumentatie en apparaatdocumentatie beschrijven elk veld in de antwoordschema's, inclusief typen, null-waarden en eenheden. Klap onder Antwoordinhoud het elementschema van een array open om de apparaatvelden te zien.

Object	Teruggegeven informatie
Installatie	ID, naam, particulier/zakelijk type, adres, tijdzone, coördinaten, hoogte en aanmaakdatum.
Alle apparaten	ID, installatie-/gateway-ID's, fabrikant, model, firmwareversie, serienummer en eerste/laatste waarneming. Gekoppelde ID's kunnen null zijn.
Omvormer	SunSpec-status en fabrikantstatus, los-van-net-indicatie, laad-/ontlaadlimieten, totale en fase-AC-metingen, schijnbaar/reactief vermogen en vermogensfactor, back-up-AC-vermogen, DC-/PV-metingen voor maximaal zes ingangen en temperatuur.
Batterij	Gekoppeld omvormer-ID, numerieke status, DC-vermogen/-spanning/-stroom, energie-/gezondheidspercentages, pakket-/celtemperaturen, celspanningen, capaciteiten, beschikbare energie, continue vermogenslimieten en energiepercentagelimieten.
Energiemeter	Functie/opties (`options`), totaal en fase-AC-vermogen, fasespanningen/-stromen, frequentie en afname-/teruglevertellers.
Laadpaal	Modus, autorisatievereiste, bidirectionele ondersteuning, ingestelde/actuele laadstroomlimieten, status, aangeboden vermogen, AC-/DC-metingen en temperatuur.
Relais	Aantal kanalen en arrays met huidige en gewenste toestanden.
Boiler	Status en modus, AC-metingen, vier temperatuursensoren, temperatuurdoelen, beschikbaar/effectief maximaal vermogen, fabrikantbedrijfsstatussen, apparaat-/relaistoestand, belastingstoestand en PWM-percentage.

Status en limieten

Omvormer-status is een genormaliseerd object met rawValue en name. De API-waarden blijven in beide talen hetzelfde:

`rawValue`	`name`	Betekenis
1	Off	Uit
2	Sleeping	Slaapstand
3	Starting	Opstarten
4	MPPT	Maximum power point tracking
5	Throttled	Begrensd
6	Shutting Down	Uitschakelen
7	Fault	Storing
8	Standby	Stand-by

Een onbekende omvormerstatus is null. Statuscodes van batterijen en boilers en statusomschrijvingen van laadpalen zijn apparaatafhankelijk; de API biedt daarvoor geen gemeenschappelijke enum. Ook boiler-operationMode, operationState en loadState zijn fabrikantspecifieke numerieke waarden.

Vermogenslimieten en aangeboden vermogens (maxChargePower, maxDischargePower, continue batterijvermogenslimieten, powerOffered, availablePower, effectiveMaxPower) zijn groottes zonder richtingsteken, geen actuele metingen. Laadpaal-currentMaxChargingCurrent wordt berekend uit de modus/het schema en kan afwijken van maxChargingCurrent. Batterij-ratedEnergy gebruikt de ingestelde capaciteitscorrectie als die bestaat.

Relaisarrays gebruiken kanaalindexen vanaf nul. true betekent aan en false uit. Een null-element in desiredState betekent automatische regeling/geen handmatige overschrijving; de volledige array kan ook null zijn. De gewenste toestand kan afwijken van de werkelijke toestand en bevat niet het berekende resultaat van automatisering.