For avancerede brugere

Avanceret integration

Lokal HTTP- og MQTT-integration for egne klienter, broker-baserede flows og automationer omkring NOFOS-ladeboksen.

HTTP API MQTT RAPI
Kom godt i gangInstallation, opsaetning og de vigtigste sikkerheds- og brugsforhold. Brug af laderenDenne side er et teknisk tillaeg til den daglige guide om laderen.
01

Avanceret integration

Alt det vigtige fra integrationsdokumentationen samlet paa en dedikeret side.

Til avancerede brugere: Dette dokument beskriver de lokale integrationsflader, som laderens firmware eksponerer til brugere, der vil bygge deres egen klient eller automation.

Omfang

Ladeboksen eksponerer to lokale integrationsmekanismer:

  • En lokal HTTP-server paa port 80
  • En MQTT-klient, som forbinder fra ladeboksen til din broker

HTTP API'et er det nemmeste sted at starte. MQTT er bedre, hvis du vil have en broker-centreret integration med telemetry skubbet ud automatisk og kommandoer leveret gennem topics.

Base URL og autentificering

Brug laderens lokale hostname eller IP-adresse:

  • http://nofos-<id>.local/
  • http://<charger-ip>/

Eksemplerne i denne guide bruger:

http://<charger-ip>/

Hvis der er konfigureret web-legitimationsoplysninger, kraever den lokale HTTP-server HTTP-authentication for baade API-requests og statiske sider. Naar laderen koerer i AP-only mode, haandhaeves authentication ikke.

De lokale HTTP-handlers sender ogsaa tilladende CORS-headere:

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Headers: *
  • Access-Control-Allow-Methods: *

HTTP-endpoints med integrationsfokus

Dette er de endpoints, som er mest nyttige til en custom integration.

GET /status

Returnerer laderens nuvaerende live-state som JSON.

Typiske felter omfatter:

  • Netvaerk og connectivity: mode, wifi_client_connected, eth_connected, net_connected, ipaddress
  • Service-state: mqtt_connected, nofos_connected
  • Runtime-metrics: free_heap, largest_free_block, min_free_heap
  • EVSE telemetry: amp, amp1, amp2, amp3, voltage, v1, v2, v3, pilot, wh, state, temp1, temp4, srssi
  • Taellere: elapsed, wattsec, watthour, gfcicount, nogndcount, stuckcount
  • Tid: time, offset
  • OTA/debug-state: ota_update, comm_sent, comm_success, rapi_connected

Eksempel:

curl http://<charger-ip>/status

/status feltreference

Felter inkluderes fra flere subsystemer. Nogle valgfrie felter er kun til stede, naar det relaterede subsystem har gyldige data.

  • mode: aktiv netvaerksmode. En af Wired, STA, AP eller STA+AP.
  • wifi_client_connected: 1 naar station-interface er forbundet, ellers 0.
  • eth_connected: 1 naar Ethernet er forbundet, ellers 0.
  • net_connected: 1 naar en aktiv netvaerksvej er forbundet, ellers 0.
  • ipaddress: nuvaerende lokal IP-adresse som streng.
  • mqtt_connected: 1 naar den lokale MQTT-klient er forbundet til sin broker, ellers 0.
  • free_heap: nuvaerende fri heap i bytes.
  • largest_free_block: nuvaerende stoerste sammenhaengende ledige heap-blok i bytes.
  • min_free_heap: mindste fri heap siden boot, i bytes.
  • comm_sent: antal RAPI-kommandoer sendt til EVSE-controlleren.
  • comm_success: antal succesfulde RAPI-udvekslinger med EVSE-controlleren.
  • rapi_connected: 1 naar gatewayen vurderer EVSE-controlleren som forbundet, ellers 0.
  • nofos_connected: 1 naar nofos MQTT-path er forbundet, ellers 0.
  • amp: maalt fase-1 stroem i ampere.
  • amp1: samme vaerdi som amp.
  • amp2: maalt fase-2 stroem i ampere.
  • amp3: maalt fase-3 stroem i ampere.
  • voltage: maalt fase-1 spaending.
  • pilot: aktuelt annonceret pilotstroem i ampere.
  • wh: akkumuleret energi i watt-timer.
  • v1: maalt fase-1 spaending.
  • v2: maalt fase-2 spaending.
  • v3: maalt fase-3 spaending.
  • temp1: ekstern temperaturvaerdi eller false, hvis sensoren ikke er gyldig.
  • temp4: valgfri MCP9808-temperaturvaerdi eller false, hvis utilgaengelig. Kun til stede, naar sensorunderstoettelsen er kompileret ind.
  • state: aktuel EVSE-statekode.
  • freeram: fri heap i bytes fra EVSE telemetry-blokken.
  • srssi: Wi-Fi RSSI i dBm.
  • elapsed: forloebet opladningstid i sekunder for den aktuelle session.
  • wattsec: sessionsenergi i watt-sekunder.
  • watthour: akkumuleret energitotal i watt-timer.
  • gfcicount: GFCI-triptaeller.
  • nogndcount: no-ground-triptaeller.
  • stuckcount: stuck-relay-triptaeller.
  • charge_rate: nuvaerende charge-rate vaerdi i ampere.
  • ota_update: 1 mens en firmware OTA-opdatering koerer, ellers 0.
  • time: nuvaerende UTC timestamp formatteret som ISO 8601, fx 2026-03-10T12:34:56Z.
  • offset: nuvaerende UTC offset-streng fra strftime("%z").
  • crash_seq: sekvensnummer for den senest gemte crashlog-record.
  • boot_count: total boot-taeller registreret i crashlog-storage.
  • reset_reason: numerisk ESP reset reason-kode for seneste reboot.
  • reset_reason_str: strengrepræsentation af reset_reason, fx poweron, software, panic eller brownout.
  • prev_uptime_ms: seneste heartbeat uptime fra forrige boot, i millisekunder.
  • prev_free_heap: senest registrerede fri heap fra forrige boot, i bytes.
  • prev_largest_free_block: senest registrerede stoerste ledige blok fra forrige boot, i bytes.
  • prev_min_free_heap: senest registrerede minimum fri heap fra forrige boot, i bytes.
  • prev_unix_time: senest registrerede Unix-tid fra forrige boot.
  • crash_recorded_unix_time: Unix-tidspunktet hvor den nuvaerende crashlog-record blev gemt.

GET /config

Returnerer den aktuelle konfiguration som JSON.

Dette inkluderer baade generelle settings og understoettede optionslister som:

  • mqtt_supported_protocols
  • http_supported_protocols
  • nofos_network_profiles

Responsen er beregnet til maskinforbrug. Secret values skjules i serialiseret output.

Eksempel:

curl http://<charger-ip>/config

/config feltreference

GET /config returnerer:

  • Controller- og gateway-metadata tilfoejet af handleConfigGet()
  • Statiske capability-lister
  • Serialiserede persistente konfigurationsfelter fra app_config.cpp

Nogle secret fields kan vaere blanke eller redigerede i responsen, fordi endpointet serialiseres med secret-hiding aktiveret.

Controller- og gateway-metadata

  • firmware: EVSE-controllerens firmwarestreng rapporteret over RAPI.
  • protocol: EVSE-controllerens RAPI-protokolversionsstreng.
  • espflash: flashchip-stoerrelse i bytes.
  • identifier: langt device identifier.
  • version: gateway-firmwareversionsstreng.
  • diodet: diode-check enabled-flag fra EVSE-controlleren.
  • gfcit: GFCI self-test enabled-flag fra EVSE-controlleren.
  • groundt: ground-check enabled-flag fra EVSE-controlleren.
  • relayt: stuck-relay-check enabled-flag fra EVSE-controlleren.
  • ventt: vent-check enabled-flag fra EVSE-controlleren.
  • tempt: temperature-check enabled-flag fra EVSE-controlleren.
  • service: aktivt serviceniveau som rapporteret af controlleren.
  • scale: current-sensor scale-vaerdi fra $GA.
  • offset: current-sensor offset-vaerdi fra $GA.
  • amplimit: current ampacity-relateret limit-vaerdi laest fra token 2 af $GC. I upstream OpenEVSE-kommentarerne er dette token den hardwaremaksimale stroem.

Capability-lister

  • mqtt_supported_protocols: array med understoettede MQTT-transportstrenge. Aktuelt ["mqtt","mqtts"].
  • http_supported_protocols: array med understoettede HTTP-transportstrenge. Aktuelt ["http","https"].
  • nofos_network_profiles: array med understoettede nofos network profile labels. Aktuelt ["Disabled","GSM only","GSM with fallback to WiFi","WiFi only","WiFI with fallback to GSM"].

Persistente konfigurationsfelter

  • ssid: konfigureret Wi-Fi SSID.
  • pass: konfigureret Wi-Fi password. Secret field.
  • www_username: HTTP-authentication brugernavn til den lokale webserver.
  • www_password: HTTP-authentication password. Secret field.
  • hostname: konfigureret enhedshostname.
  • sntp_hostname: konfigureret SNTP-serverhostname.
  • time_zone: konfigureret POSIX- eller udvidet timezone-streng.
  • mqtt_server: MQTT-brokerhostname eller IP.
  • mqtt_port: MQTT-brokerport.
  • mqtt_topic: MQTT-basetopic brugt til telemetry og kommandoer.
  • mqtt_user: MQTT-brugernavn.
  • mqtt_pass: MQTT-password. Secret field.
  • mqtt_vrms: eksternt MQTT-topic brugt som line voltage-input.
  • mqtt_announce_topic: retained announce-topic brugt til connect/disconnect presence-payloads.
  • nofos_network_profile: valgt nofos network profile-ID.
  • flags: ra bitfield som gemmer flere service- og behavior-flags.
  • mqtt_enabled: true naar den lokale MQTT-klient er aktiveret.
  • mqtt_reject_unauthorized: true naar MQTT TLS certificate validation haandhaeves.
  • sntp_enabled: true naar SNTP time sync er aktiveret.
  • pause_uses_disabled: true naar pause-operationer bruger $FD i stedet for $FS.
  • mqtt_protocol: MQTT-transportstreng. Aktuelt mqtt eller mqtts.

POST /config

Opdaterer konfiguration med en JSON-body.

Dette er det foretrukne write-interface til custom integrationer, fordi det understoetter delvise opdateringer og eksponerer flere settings end de aeldre form-endpoints.

Typiske felter:

  • HTTP auth: www_username, www_password
  • MQTT: mqtt_enabled, mqtt_protocol, mqtt_server, mqtt_port, mqtt_topic, mqtt_user, mqtt_pass, mqtt_reject_unauthorized, mqtt_vrms, mqtt_announce_topic
  • Charge behavior: pause_uses_disabled
  • Tid/netvaerk: sntp_enabled, time_zone, hostname, sntp_hostname, nofos_network_profile

Eksempel: aktiver MQTT

curl -X POST http://<charger-ip>/config \
  -H "Content-Type: application/json" \
  -d '{
    "mqtt_enabled": true,
    "mqtt_protocol": "mqtt",
    "mqtt_server": "192.168.1.10",
    "mqtt_port": 1883,
    "mqtt_topic": "charger/nofos-1234",
    "mqtt_user": "mqtt-user",
    "mqtt_pass": "mqtt-pass",
    "mqtt_reject_unauthorized": true
  }'

Responses:

  • 200 med {"msg":"done"} ved succes
  • 400 med {"msg":"Could not parse JSON"} ved ugyldig JSON

GET /r og GET /rapi

Sender en RAPI-kommando til EVSE-controlleren.

Brug query parameters:

  • rapi: kommandoen der skal sendes
  • json: valgfri; 1, true, eller til stede uden vaerdi returnerer JSON i stedet for HTML

Eksempel:

curl "http://<charger-ip>/r?json=1&rapi=\$GS"

Succesfuld JSON-respons:

{"cmd":"$GS","ret":"$OK ..."}

Fejl-JSON-respons:

{"cmd":"$GS","error":"RAPI_RESPONSE_TIMEOUT"}

Brug dette endpoint til low-level EVSE-kommandoer, naar der ikke findes et hoejere niveau config-felt.

GET /crashlog

Returnerer nyere crash-historik som JSON.

Valgfri query-parameter:

  • count: antal events der skal returneres, 1 til 10

Eksempel:

curl "http://<charger-ip>/crashlog?count=5"

GET /scan

Returnerer synlige Wi-Fi-netvaerk som JSON.

POST /apoff

Slukker access point kort tid efter requestet returnerer.

GET /reset

Nulstiller gemt konfiguration og genstarter.

GET /restart

Genstarter uden at slette konfiguration.

GET /debug

Returnerer den buffrede debug-console som plain text.

GET /evse

Returnerer den buffrede EVSE serial-console som plain text.

Anbefalet HTTP-brugsmoenster

For en ekstern integration er det praktiske moenster:

  1. Laes GET /status for live-state
  2. Laes GET /config ved opstart, hvis din klient har brug for capability discovery
  3. Skriv POST /config for understoettede settings
  4. Brug kun GET /r?json=1&rapi=... til controller-kommandoer, som ikke er repræsenteret i /config

RAPI-kommando-reference for GET /r og GET /rapi

GET /r og GET /rapi videresender en ra RAPI-kommandostreng til OpenEVSE-controlleren. Firmwaren hardcoder ikke en allowlist i HTTP-handleren; den sender videre, hvad du leverer. Listen nedenfor dokumenterer de RAPI-kommandoer, der eksplicit bruges, wrappes eller special-cases i dette repository.

Hvor en kommando kun er udledt af brugen og repository'et ikke indeholder den upstream protokolbeskrivelse, er det naevnt eksplicit.

Query- og statuskommandoer

  • $GV: hent EVSE firmwareversion og RAPI-protokolversion.
  • $GS: hent EVSE-status. Bruges til at laese nuvaerende state og forloebet sessionstid.
  • $GT: hent controllerens RTC-tid.
  • $GG: hent charging current og voltage.
  • $GP: hent temperaturmaalinger.
  • $GU: hent energy usage counters.
  • $GF: hent fault counters.
  • $GE: hent EVSE-settings, inklusive pilot current og flags.
  • $GC: hent current-capacity-information, inklusive minimum, pilot, configured max og hardware max.
  • $GD: hent delay timer schedule. Firmwaren emulerer ogsaa $GD i HTTP-handleren, naar den underliggende controller returnerer $NK.
  • $GA: hent current-sensor calibration values. Udledt fra kode: token 1 er current scale og token 2 er current offset.

Konfigurations- og kontrolkommandoer

  • $SC <amps> [V|M]: saet current capacity. V saetter en volatil current limit. M gemmer en maksimumgrænse i EEPROM. Uden suffix behandles den som compatibility fallback for aeldre controllere.
  • $SV <millivolts>: saet den spaending der bruges til power-beregninger.
  • $S1 <yy> <mm> <dd> <hh> <mm> <ss>: saet controllerens RTC-tid.
  • $ST <start_hour> <start_minute> <end_hour> <end_minute>: saet delay timeren.
  • $FE: aktiver opladning / vaek EVSE.
  • $FS: saet EVSE i sleep mode.
  • $FD: deaktiver EVSE.
  • $FR: genstart EVSE-controlleren.
  • $FF <feature> <0|1>: aktiver eller deaktiver en controller-feature. 0 deaktiverer og 1 aktiverer. Understoettede feature IDs dokumenteret i dette repository er B, D, E, F, G, R, T og V.
  • $F0 <0|1>: deaktiver eller aktiver LCD display updates.
  • $FB <color>: saet LCD backlight color.
  • $FP <x> <y> <text>: tegn tekst paa LCD.
  • $SY <interval> <current>: aktiver heartbeat supervision.
  • $SY: send et heartbeat pulse.
  • $SY 165: acknowledge et mistet heartbeat pulse.
  • $F1: emuler et front-panel button press.
  • $S4 0|1: toggle controller lock state. Udledt fra nofos_mqtt.cpp: 1 laaser, 0 laaser op.
  • $SB: ryd den haarde amperage limit gemt i controllerens EEPROM. Dette beskrives eksplicit i nofos_mqtt.cpp som "Wipe hard amperage limit in EEPROM."

Praktiske eksempler

Hent controller-version:

curl "http://<charger-ip>/r?json=1&rapi=\$GV"

Hent nuvaerende EVSE-state:

curl "http://<charger-ip>/r?json=1&rapi=\$GS"

Hent current-capacity-information:

curl "http://<charger-ip>/r?json=1&rapi=\$GC"

Saet current limit til 13 A:

curl "http://<charger-ip>/r?json=1&rapi=\$SC%2013"

Deaktiver EVSE:

curl "http://<charger-ip>/r?json=1&rapi=\$FD"

Genstart EVSE-controlleren:

curl "http://<charger-ip>/r?json=1&rapi=\$FR"

MQTT-overblik

Ladeboksen er en MQTT-klient. Den koerer ikke en broker lokalt. Du peger den mod din egen broker, og den vil:

  • Forbinde til broker
  • Publicere charger state og events
  • Subscribe til udvalgte kommando- og telemetry-topics

Understoettede protokoller:

  • mqtt
  • mqtts

MQTT-setup

Den foretrukne setup-vej er POST /config.

Minimumskonfiguration:

{
  "mqtt_enabled": true,
  "mqtt_protocol": "mqtt",
  "mqtt_server": "192.168.1.10",
  "mqtt_port": 1883,
  "mqtt_topic": "charger/nofos-1234",
  "mqtt_user": "mqtt-user",
  "mqtt_pass": "mqtt-pass",
  "mqtt_reject_unauthorized": true
}

Noter:

  • mqtt_reject_unauthorized=true haandhaever certificate validation for mqtts
  • Det gamle POST /savemqtt-endpoint kan ikke saette mqtt_vrms eller mqtt_announce_topic
  • Efter gemning af MQTT-konfiguration genstarter firmwaren MQTT-forbindelsen automatisk

MQTT-topics brugt af ladeboksen

Antag:

  • mqtt_topic = charger/nofos-1234
  • mqtt_announce_topic = openevse/announce/abcd

Outbound topics publiceret af ladeboksen

Announcement topic

Ved connect publicerer laderen et retained JSON-payload paa mqtt_announce_topic:

{
  "state": "connected",
  "id": "<device-id>",
  "name": "<hostname>",
  "mqtt": "charger/nofos-1234",
  "http": "http://<charger-ip>/"
}

Laderen saetter ogsaa en retained last-will message paa samme topic:

{
  "state": "disconnected",
  "id": "<device-id>",
  "name": "<hostname>"
}

Telemetry- og event-topics

For hvert JSON-felt i et emitted event document publicerer firmwaren en MQTT-besked til:

<mqtt_topic>/<field>

Eksempler:

  • charger/nofos-1234/amp
  • charger/nofos-1234/voltage
  • charger/nofos-1234/state
  • charger/nofos-1234/pilot
  • charger/nofos-1234/wh

Den vigtigste periodiske publish sker hvert 30. sekund og inkluderer de standard live EVSE-felter som:

  • amp, amp1, amp2, amp3
  • voltage, v1, v2, v3
  • pilot
  • wh
  • state
  • freeram
  • srssi

Yderligere event-drevne felter kan ogsaa blive publiceret, herunder:

  • charge_rate
  • available_current
  • smoothed_available_current

Inbound topics subscribed til af ladeboksen

RAPI command input

Laderen subscriber til:

<mqtt_topic>/rapi/in/#

For at sende en RAPI-kommando skal du publicere til et topic, som slutter med kommandonavnet begyndende med $.

Eksempler:

charger/nofos-1234/rapi/in/$GS
charger/nofos-1234/rapi/in/$SC

Hvis kommandoen har et argument, skal argumentet ligge i payload.

Eksempel: saet charging current til 13 A

Topic:

charger/nofos-1234/rapi/in/$SC

Payload:

13

Laderen publicerer RAPI-responsen til:

<mqtt_topic>/rapi/out

MQTT-eksempler

Subscribe til alt for en charger:

mosquitto_sub -h 192.168.1.10 -u mqtt-user -P mqtt-pass -t 'charger/nofos-1234/#'

Anmod om EVSE-state med RAPI:

mosquitto_pub -h 192.168.1.10 -u mqtt-user -P mqtt-pass \
  -t 'charger/nofos-1234/rapi/in/$GS'

Laes derefter responsen:

mosquitto_sub -h 192.168.1.10 -u mqtt-user -P mqtt-pass \
  -t 'charger/nofos-1234/rapi/out'

Saet current limit til 13 A:

mosquitto_pub -h 192.168.1.10 -u mqtt-user -P mqtt-pass \
  -t 'charger/nofos-1234/rapi/in/$SC' \
  -m '13'

Anbefalet MQTT-brugsmoenster

For de fleste broker-baserede integrationer:

  1. Konfigurer MQTT gennem POST /config
  2. Laes det retained payload paa mqtt_announce_topic for at discovere laderen
  3. Subscribe til <mqtt_topic>/#
  4. Brug <mqtt_topic>/rapi/in/$..., naar du har brug for en controller-kommandovej gennem broker

Praktisk anbefaling

Hvis du bygger en ny integration fra bunden:

  • Foretraek HTTP til konfiguration og direkte queries
  • Foretraek MQTT til pushed telemetry, eventstroemme og broker-styrede automationer
  • Brug POST /config i stedet for de aeldre /save...-endpoints, naar det er muligt