IAMMETER Wi-Fi-energiamittari: paikalliset API:t ja avoimet rajapinnat

IAMMETER Wi-Fi-energiamittari: paikalliset API:t ja avoimet rajapinnat

IAMMETER Wi-Fi-energiamittarit tukevat IAMMETER-Cloudia sekä paikallisia ja kolmannen osapuolen integraatioita.

Käytettävissä olevat rajapinnat:

• Paikallinen HTTP-API lähiverkossa
• MQTT- ja MQTTS-julkaisu
• Modbus TCP
• TCP/TLS-lähetys
• HTTP/HTTPS-lähetys
• Itsenäinen paikallinen toiminta

Näiden rajapintojen avulla IAMMETER-mittarit voivat toimia avoimina tietolähteinä seuraaville:

• Home Assistant ja muut älykotialustat
• Node-RED-automaatio
• Itse ylläpidetyt kojelaudat
• PLC- ja SCADA-järjestelmät
• Mukautetut energianhallintajärjestelmät (EMS)
• Mukautetut kiinteistönhallintajärjestelmät (BMS)
• Kolmannen osapuolen datapalvelimet

Tämä opas kuvaa ensin nykyisen laiteohjelmiston ja WebUI:n. Vanhemman laiteohjelmiston kuvakaappaukset ja määritystavat on säilytetty lopussa olevassa Legacy-osiossa.

Valmiiksi käytettävää sovellusta varten katso Home Energy Monitoring, Solar Energy Monitoring tai paikallinen valvonta ilman Internet-yhteyttä.

1) Päivitä uusimpaan laiteohjelmistoon

IAMMETERin laiteohjelmistoa päivitetään jatkuvasti. Tarkista ennen integraation määritystä nykyinen julkaisu ja malliyhteensopivuus:

• IAMMETERin laiteohjelmistojen julkaisusivu

Uusimman laiteohjelmiston WebUI tarjoaa yleisesti käytetyt määritysvaihtoehdot suoraan. Tässä artikkelissa myöhemmin säilytetyt manuaaliset määritys-API-kutsut ovat hyödyllisiä lähinnä vanhempien asennusten ylläpidossa.

2) Valitse toimintatila nykyisestä WebUI:sta

Valitse toimintatila sen mukaan, mihin mittarin tulisi lähettää dataa tai miten sen tulisi toimia paikallisesti.

Toimintatila ohjaa datan lähetyskäyttäytymistä. Paikallisen API:n ja Modbus TCP:n saatavuus tulee silti tarkistaa mittarimallin, laiteohjelmiston ja valitun integraation osalta.

3) Miksi avoimet rajapinnat ovat tärkeitä

Avoimet rajapinnat antavat käyttäjille mahdollisuuden päättää, missä sähködata käsitellään ja tallennetaan.

Tyypillisiä syitä ovat:

• Mittausten pitäminen paikallisessa verkossa
• Telemetrian lähettäminen olemassa olevaan palvelimeen
• Energiadatan yhdistäminen Home Assistantiin tai Node-REDiin
• Mukautettujen kojelautojen ja hälytysten rakentaminen
• Sähködatan yhdistäminen tariffiin, aurinkoenergiaan tai kuormanohjauslogiikkaan
• Toiminta kohteessa, jossa Internet-yhteys on rajoitettu tai epäluotettava

Cloud- ja paikalliskäyttö eivät välttämättä sulje toisiaan pois. Sopiva arkkitehtuuri riippuu siitä, tarvitseeko projekti IAMMETER-Cloudin raportteja, paikallista alustaa, kolmannen osapuolen palvelinta vai näiden yhdistelmää.

4) Datan lähettäminen kolmannen osapuolen palvelimeen

4.1 TCP ja TLS

IAMMETER voi lähettää mittaridataa TCP- tai TLS-päätepisteeseen.

Nykyisessä WebUI:ssa:

1. Valitse TCP-toimintatila.
2. Anna kohdeosoite.
3. Määritä lähetysväli.
4. Tallenna asetukset ja varmista datan vastaanotto palvelimella.

Käytä TCP-palvelimelle:

{domain-or-ip}:{port}

Esimerkki:

abc.com:12345

Käytä TLS-palvelimelle:

tls://{domain-or-ip}:{port}

Esimerkki:

tls://abc.com:12345

Nykyisen laiteohjelmiston yleiskatsaus dokumentoi 2 sekunnin vähimmäislähetysvälin. Varmista nykyinen laiteohjelmisto ja vastaanottopalvelimen kapasiteetti ennen lyhyen välin valitsemista.

4.2 MQTT ja MQTTS

IAMMETER voi julkaista telemetriaa suoraan tavalliselle MQTT-välittäjälle tai käyttää MQTTS:ää salattuun siirtoon tuetuissa laiteohjelmistoissa.

Nykyisessä WebUI:ssa:

1. Valitse MQTT-toimintatila.
2. Anna välittäjän IP-osoite tai verkkotunnus ja portti käyttäen sopivaa MQTT- tai MQTTS-muotoa.
3. Anna välittäjän käyttäjänimi ja salasana, kun todennus vaaditaan.
4. Määritä lähetysväli.
5. Tallenna ja varmista, että viestit saapuvat välittäjälle.

Tavallisessa MQTT:ssä anna välittäjän osoite ja portti ilman mqtt://-etuliitettä:

192.168.11.163:1883

MQTTS:ssä sisällytä mqtts://-etuliite:

mqtts://{mqtt-broker-address}:{port}

Esimerkki:

mqtts://broker.example.com:8883

MQTTS-tuella, joka on dokumentoitu marraskuun 2025 laiteohjelmistopäivityksessä, on seuraavat nykyiset rajoitukset:

• Tukee TLS 1.2:ta ja sitä vanhempia.
• Mukautetun CA-varmenteen lataamista ei tueta.
• Isäntänimen vahvistusta ei tueta.
• Asiakaspuolen varmenteita molemminpuoliseen TLS-todennukseen ei tueta.

Nämä rajoitukset ovat tärkeitä välittäjää valittaessa ja käyttöönoton turvallisuusvaatimuksia arvioitaessa.

Nykyisen laiteohjelmiston yleiskatsaus dokumentoi 2 sekunnin vähimmäislähetysvälin.

Home Assistant MQTT Discovery on Home Assistantin lisätoiminto laitteiden löytämiseen; sitä ei vaadita jokaiseen MQTT-integraatioon. Katso:

• IAMMETER MQTT -integraatio-opas
• MQTT Discovery Home Assistantissa

Muuta uploadInterval etänä MQTT/MQTTS:n kautta

Marraskuun 2025 päivityksessä kuvatulla laiteohjelmistolla MQTT-tilassa toimiva mittari tilaa automaattisesti:

device/{sn}/config

Julkaise seuraava JSON toisesta MQTT-asiakkaasta muuttaaksesi lähetysvälin etänä:

{"uploadInterval": 10}

Korvaa 10 halutulla välin pituudella sekunteina ja {sn} mittarin sarjanumerolla aiheessa.

Tämä etäinen MQTT-määritys eroaa vanhemmasta paikallisesta /api/uploadinterval-menetelmästä, joka on säilytetty Legacy-osiossa.

4.3 HTTP ja HTTPS

IAMMETER voi lähettää dataa mukautettuun HTTP/HTTPS-palvelimeen.

Nykyisessä WebUI:ssa:

1. Valitse HTTP-toimintatila.
2. Anna palvelimen osoite ja portti.
3. Määritä lähetysväli.
4. Tallenna ja varmista pyynnöt palvelimella.

Nykyinen laiteohjelmisto tukee sekä oletusarvoista HTTPS-porttia että mukautettua HTTPS-porttia.

Käytä jotakin näistä muodoista:

• Tavallinen HTTP ilman erillistä porttia: {address} — oletusportti 80.
• Tavallinen HTTP mukautetulla portilla: {address}:{port}.
• HTTPS ilman erillistä porttia: https://{address} — oletusportti 443.
• HTTPS mukautetulla portilla: https://{address}:{port} — käyttää määritettyä porttia.

https://-etuliite valitsee HTTPS:n. Portti 443 ei ole enää ainoa HTTPS:lle käytettävissä oleva portti.

Esimerkkejä:

api.example.com
api.example.com:8080
https://api.example.com
https://api.example.com:8443

Katso Uusi laiteohjelmisto lisää MQTTS:n, etämäärityksen ja mukautetun HTTPS-portin laiteohjelmiston julkaisutiedoista.

Palvelinpuolen datan käsittelyä varten katso myös IAMMETERin integrointi kolmannen osapuolen palvelimeen.

5) Datan lukeminen paikallisesti HTTP:n kautta

Liitä mittari lähiverkkoon ja pyydä dataa sen paikallisesta IP-osoitteesta. Nämä pyynnöt eivät vaadi IAMMETER-Cloudia.

Testaa API:t vuorovaikutteisesti: Avaa IAMMETER Local API Explorer, syötä mittarin paikallinen IP-osoite ja valitse WEM API -testisivu. Swagger-tyylinen selain luettelee käytettävissä olevat paikalliset API:t ja antaa sinun lähettää testipyyntöjä suoraan selaimesta. Selain ja IAMMETER-mittari on oltava samassa lähiverkossa.

5.1 GET /api/monitorjson

Palauttaa reaaliaikaiset sähkömittaukset.

Vakiodata sisältää arvoja kuten:

• Jännite
• Virta
• Pätöteho
• Etu-/tuontikWh
• Taka-/vientikWh
• Taajuus
• Tehokerroin

Esimerkkivastaus:

{
  "method": "uploadsn",
  "mac": "B0F8933C4F94",
  "version": "i.75.97.9",
  "server": "em",
  "SN": "3E0BAF87",
  "Datas": [
    [220.0, 9.99, 2198, 11.337, 11.201, 49.99, 1.00],
    [222.5, 9.99, 1100, 11.039, 10.908, 49.99, 0.50],
    [263.5, 9.99, 1213, 10.975, 10.846, 49.99, 0.55]
  ]
}

Mittausjonojen määrä riippuu mittarimallista ja kanavamäärästä.

Jos loistehomittaus on käytössä tuetussa mallissa/laiteohjelmistossa, vastausmuoto voi sisältää lisäkenttiä. Katso Loistehomittauksen datamuoto.

5.2 GET /api/monitor

Palauttaa laajennetun reaaliaikaisen vastauksen, joka sisältää myös Wi-Fi-tietoja, kuten:

• ssid — yhdistetyn tukiaseman nimi
• sig — Wi-Fi-signaalin voimakkuus

Käytä tätä päätepistettä, kun integraatio tarvitsee sekä sähkömittauksia että perustason Wi-Fi-tilan.

5.3 GET /api/wifidata

Palauttaa laiteohjelmisto-, laite- ja verkkokokoonpanotiedot.

Esimerkki:

{
  "version": "i.75.97.9",
  "SN": "3E0BAF87",
  "mac": "B0F8933C4F94",
  "type": "PM",
  "ssid": "example-wifi",
  "ip": "192.168.11.62",
  "netmask": "255.255.255.0",
  "gw": "192.168.11.1",
  "dns": "192.168.11.1",
  "dhcp": 1,
  "runMode": "tcp",
  "uploadinterval": 60
}

Älä julkaise vastauksia, jotka sisältävät laitteen sarjanumeroita, MAC-osoitteita, sisäisiä osoitteita tai Wi-Fi-tietoja, ellei arvoja ole anonymisoitu.

6) JSON-muoto lähetystiloissa

IAMMETER käyttää yhtenäistä JSON-mittausrakennetta HTTP-, TCP-, MQTT- ja paikallisissa API:issa. Tämä vähentää työtä, kun yksi vastaanottojärjestelmä tukee useita siirtotapoja.

Siirtotapa ja kehys voivat silti vaikuttaa siihen, miten vastaanotin yhdistää, todentaa tai kehystää viestin. Toteuta vastaanottojärjestelmä valitun tilan dokumentoidun muodon mukaisesti.

• IAMMETER-energiamittarin JSON-datan määritelmä

7) Modbus TCP

IAMMETER-mittarit tukevat Modbus TCP:tä suoraa lähiverkkointegrointia varten yhteensopivien asiakkaiden kanssa.

Tyypillisiä asiakkaita ovat:

• Home Assistant
• PLC:t
• SCADA-järjestelmät
• Teollisuusyhdyskäytävät
• Mukautetut Modbus-sovellukset

Viitteet:

• IAMMETER Modbus TCP -yleiskatsaus
• Home Assistant -integraation yleiskatsaus

Varmista mittarimalli, laiteohjelmisto, rekisterimääritelmä, kyselyväli ja asiakkaan käyttäytyminen ennen käyttöönottoa.

8) Integraatioskenaariot

9) Nykyisten rajapintojen yhteenveto ja resurssit

Lisäresursseja:

• Uusin laiteohjelmisto
• MQTTS- ja mukautettu HTTPS-portti -laiteohjelmistoilmoitus
• Video-opastukset
• JSON-datan määritelmä
• Modbus TCP -yleiskatsaus
• Kehitä oma järjestelmäsi
• Valvonta ilman Internet-yhteyttä

IAMMETERin paikalliset API:t ja avoimet protokollat mahdollistavat aloittamisen reaaliaikaisella valvonnalla ja myöhemmin mukautetun EMS:n, itse ylläpidetyn kojelaudan tai automaatiotyönkulun lisäämisen.

10) Vanhan laiteohjelmiston sivut ja määritystavat

Seuraava materiaali on säilytetty vain mittareille, joissa on edelleen vanhempi laiteohjelmisto, tai käyttäjille, jotka ylläpitävät olemassa olevaa integraatiota. Uutta asennusta varten päivitä uusimpaan laiteohjelmistoon ja käytä nykyistä WebUI:ta aina, kun vaadittu vaihtoehto on saatavilla.

10.1 Vanhan laiteohjelmiston toimintatilasivu

Vanhempi laiteohjelmisto käytti seuraavaa toimintatilan valintasivua:

Asettelu ja vaihtoehtojen nimet eivät välttämättä vastaa tässä oppaassa aiemmin esitettyä nykyistä WebUI:ta.

10.2 Vanhan laiteohjelmiston TCP/TLS-sivu

Vanhemmat laiteohjelmistointegraatiot voivat viitata tähän TCP/TLS-määrityssivuun ja liittyvään oppaaseen:

• Vanha kolmannen osapuolen palvelimen integraatio-opas
• Vanha lähetys-palvelimelle-video

10.3 Vanhan laiteohjelmiston MQTT-sivu

Vanhempi MQTT-dokumentaatio käytti tätä määrityskäyttöliittymää:

Käytä nykyisessä työnkulussa tämän artikkelin aiemmin esitettyjä nykyisen WebUI:n ohjeita ja päivitettyä MQTT-integraatio-opasta.

10.4 Vanhan laiteohjelmiston HTTP/HTTPS-sivu

Vanhempi laiteohjelmisto käytti seuraavaa HTTP/HTTPS-kohdesivua:

Vanha integraatio-opas on säilytetty kohdassa Lähetys HTTP/HTTPS:n kautta.

Tässä vanhemmassa työnkulussa HTTPS liitettiin oletusporttiin 443 eikä https://-etuliitettä vaadittu. Nykyinen laiteohjelmisto sen sijaan käyttää https://-etuliitettä HTTPS:n valintaan ja tukee joko oletusporttia 443 tai erikseen määritettyä mukautettua porttia.

10.5 Vanhat määritys-API:t

Seuraavat paikalliset API-kutsut esiintyivät aiemmissa määritystyönkuluissa. Nykyisessä laiteohjelmistossa vastaavat asetukset tulee normaalisti määrittää WebUI:n kautta, kun vaihtoehto on saatavilla.

/api/uploadinterval?x=<seconds>

Vanha menetelmä ei-Cloud-lähetysvälin asettamiseen.

/api/mqtt

Vanha menetelmä MQTT-tunnistetietojen määrittämiseen.

/api/netmetring

Vanha menetelmä nettolaskutusmittaustilan (Net Energy Metering) käyttöönottoon tai poistamiseen.

• Net Energy Metering -viite

/api/ctcratio

Vanha menetelmä dokumentoidun C-vaiheen kertoimen soveltamiseen tietyissä kaksivaihe- tai tasapainotetuissa tilanteissa.

• CTC-suhteen viite

/api/reactive

Vanha menetelmä loistehon ja loistehoenergian mittauksen käyttöönottoon tai poistamiseen tuetuissa laiteohjelmistoissa/malleissa.

• Loistehon viite

/api/ratio — vain WEM3046T

WEM3046T käyttää ulkoisia virtamuuntajia (CT), joiden toisiovirta on 5 A. Vanhemmat määritysohjeet asettivat CT-suhteen seuraavasti:

/api/ratio?x={ct_ratio}

Esimerkki:

/api/ratio?x=400

Tämä päätepiste on ominainen WEM3046T:lle eikä ole voimassa muille IAMMETER-malleille. Nykyisessä laiteohjelmistossa käytä mallin nykyistä WebUI-määritystä, kun se on saatavilla.

Vanha materiaali säilytetty taaksepäin viittaamista varten; nykyisten asennusten tulee noudattaa uusimman laiteohjelmiston WebUI:ta.