Deze handleiding geeft stap voor stap weer hoe de P1-monitor internet API geactiveerd kan worden.

Deze optie is beschikbaar in P1-monitor versie later dan 20210618 V1.3.1.

Deze API is een extra optie die niet nodig is voor normaal gebruik en staat daarom standaard ook uit.

Er zijn twee redenen om de API te activeren:

A: De toekomstige versies van Android en iOS apps zullen gebruik maken van de API als je buiten bereik bent van je Wifi netwerk. Dat wordt aangeven als de app uitkomt. Momenteel wordt daar nog Dropbox voor gebruikt.

B: Je wilt de P1 monitor data op afstand beschikbaar stellen aan andere gebruikers.

Hieronder staan de voorwaarden en stappen die je door moet lopen voor het activeren. De details van elke stap worden verderop in de tekst in detail toegelicht. Vrijwel alle instellingen kunnen via de P1-monitor gebruikersinterface worden ingesteld. Het lijkt wellicht ingewikkeld maar door de stappen consequent door te lopen is het relatief eenvoudig. Deze opzet gaat uit van een normale thuissituatie waar je de router van de Internet Service Provider (ISP) van bijvoorbeeld KPN of Ziggo gebruikt om te verbinden met het internet.

1: Instellen van een vast IP adres van de Raspberry Pi (Rpi)

2: Het aanmaken van een FQDN domeinnaam.

3: Het forwarden van poort 80 en 443 op je router.

4: Het aanmaken van het HTTPS certificaat.

5: Het aanmaken van API tokens.

6: Het testen van de API.

1: Instellen van een vast IP adres van de Raspberry Pi (Rpi)

Om de Rpi te kunnen bereiken over je thuisnetwerk moet het internetadres van je router via port fowarding naar het IP adres van de RPI worden gerouteerd. Dit kan alleen betrouwbaar als het IP adres van de Rpi vast staat ( een zogenaamd static IP adres) en niet wijzigt. Het vast instellen van de het IP adres van Rpi kan op twee manieren:

De voorkeur methode is static binding via de DHCP server van je router. Deze optie werkt altijd en voorkomt fouten in de configuratie. Zie hier een link van een voorbeeld voor KPN.

Als je de voorkeuroptie niet wil gebruiken dan kan je het IP adres via de P1 monitor instellen op de pagina config-netwerk.php pagina. Voordat je de IP adressen instelt moet je een aantal zaken controleren en weten.

Het(de) IP adres(sen) dat je wil gebruiken als je Rpi via een kabel is aangesloten (eth0) en/of Wifi (wlan0). Beide kunnen tegelijk worden gebruikt maar moeten uiteraard wel een andere IP adres zijn. Deze IP adressen moeten vrij zijn en bij voorkeur niet door de DHCP server worden gebruikt. Je kunt een vrij adres controleren door ping te gebruiken. Als de host geen antwoord geeft dan is het adres niet in gebruik.  En dan is dit IP adres dus te gebruiken oftewel vrij.

C:\Users\SecBro>ping 192.168.2.226
Pinging 192.168.2.226 with 32 bytes of data:
Reply from 192.168.2.28: Destination host unreachable.

Het IP adres van je router en je DNS server. In de meest gevallen is de thuis situatie is DNS server gelijk aan de router.  

In onderstaande voorbeeld wordt gebruikt gemaakt van de KPN router die werkt met 192.168.2.0/24 als netwerk range. In jouw geval kan het anders zijn. De P1 monitor geeft standaard in het grijs aan wat de adressen van de router/dns server zijn en kunnen gebruikt worden als indicatie.

Waarschuwing: als je een fout maakt met de IP adressen dan kun effectief je zelf buiten sluiten omdat de Rpi niet meer bereikbaar is. Controleer de adressen dus extra voordat je deze opslaat. Een ander nadeel van deze optie is als je ISP een ander IP adres range gaat gebruiken of je wisselt van ISP dat je hoogst waarschijnlijk een nieuw IP adres range gaat gebruiken. Alle apparatuur die via DHCP een adres krijgen zullen werken maar de Rpi is niet meer te bereiken.

Kies de optie opslaan en dan zal het nieuwe IP adres worden ingesteld. Dit duurt normaal maar 10 a 15 seconden.

2: Het aanmaken van een FQDN domeinnaam.

Een FQDN ‘Fully Qualified Domain Name) is een volledig domeinnaam adres, inclusief hostnaam en een top level domein, zoals bijvoorbeeld mijn.p1-monitor.nl is de naam waar de API onder te vinden is op het Internet. Je kunt die zelf regelen als je al een FQDN hebt die gekoppeld is aan je Internet adres dat je van je ISP krijgt. Voorbeelden van dergelijk diensten zijn DuckDns, No-Ip, dynu.com. De P1-monitor heeft ondersteuning voor DuckDns ingebouwd.

Hoe je de FQDN ook regelt de naam moet ingesteld worden zoals hieronder aangeven. Ook als je een andere dienst gebruikt dan DuckDNS. Deze FQDN wordt voor het https TLS certificaat gebruikt.

Een DuckDns FQDN aanmaken

Ga naar https://www.duckdns.org/ en meld je aan via Google of op een van de andere manieren die worden aangeboden.

Vul in het veld domain de naam van je site. Het verstandig om hier een niet te herleiden naam te gebruiken. Dus niet P1-monitor.duckdns.org maar een abstracte naam zoals bijvoorbeeld kj2021m.duckdns.org. Klik op add domein. Doe deze actie vanuit je eigen netwerk dan wordt je publieke ISP IP adres meteen goed ingesteld.

Hiermee is je FQDN aangemaakt. Om te testen of deze ook correct werkt kun je het FQDN via ping uitproberen. Als alles goed gaat dan krijg je de volgende respons.

C:\Users\SecBro>ping kj2021m.duckdns.org

Pinging pt2109.duckdns.org [<je ISP IP>] with 32 bytes of data:
Reply from <je ISP IP>: bytes=32 time<1ms TTL=64
Reply from <je ISP IP>: bytes=32 time=1ms TTL=64
Reply from <je ISP IP>: bytes=32 time=1ms TTL=64
Reply from <je ISP IP>: bytes=32 time<1ms TTL=64

Ping statistics for <je ISP IP>:
  Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
  Minimum = 0ms, Maximum = 1ms, Average = 0ms

Het kan zijn dat dit niet meteen werkt en dat het even duurt voordat de DNS naam nog niet verwerkt is. Over het algemeen werkt dit binnen 5 minuten, maar het kan ook wel een uur duren. Als dit niet werkt dan moet dit probleem eerste opgelost worden voordat je verder gaat.

Je ziet hier meerdere FQDN namen, dit is voor testwerk je hoeft maar een regel aan te maken.

Omdat je publieke ISP IP adres kan wijzigen moet DuckDNS op de hoogt gebracht worden. Dit gebeurt automatisch als in het token veld de token waarde uit het DuckDNS veld wordt overgenomen en de optie actief wordt geactiveerd. Eventueel kun je als een nieuwe ISP adres de periodieke automatische update forceren met de optie forceer update. Deze actie werkt alleen als de eerder genoemd ping test succesvol verliep.

3: Het forwarden van poort 80 en 443 op je router.

Dit is essentieel voor de correct werking en moet worden ingesteld in je router. Hieronder wordt het voorbeeld gegeven voor een KPN Experia V10A router. Voor andere routers moet je de handleiding raadplegen of zoeken op het Internet. Zoek op port forwarden.

Voorbeeld van de KPN router:

Deze routers zijn overigens ondingen. Als het niet lukt om in te loggen dan helpt een power cycle (spanning er af en weer op) meestal wel voor een dag of wat.

A: Login op je de V10A router

B: Kies op het tabblad network -> NAT -> Port mapping.

C: Kies de optie Add rule en maak twee regels voor poort 80 en 443 voor het vaste IP adres van je Rpi. In dit voorbeeld 192.168.2.226

Als alles goed is ingevoerd dan ziet de port mapping er als volgt uit.

D: Log uit op de router.

In het voorbeeld wordt poort 443 gebruikt en dit kan. Maar het verstandiger een ander dan de standaard poort 443 te gebruiken. Apple App gebruikt standaard poort 22721 of je kunt een eigen poort kiezen als deze maar overeen komt met de App.  In de afbeelding wordt dan de “public port” 22721.

4: Het aanmaken van het HTTPS TLS certificaat.

Ga naar de pagina config-API.php en vul in het blok Internet API het email adres in en set de API via het Internet actief adres op aan. Het email adres is nodig om eventuele SSL/TLS certificaten te kunnen herstellen. Als dit ingevuld is kies dan voor opslaan. Na een paar minuten zal het scherm als hieronder uit zien als alles goed gaat.  Heb geduld het kan beste even duren!

Je kunt het testen door in een browser je FQDN in te voeren. Als voorbeeld http://kj2021m.duckdns.org/ Als onderstaande melding komt dat werkt port forwarding en is de API bereikbaar.

Met activeren van het Internet API worden de volgende acties uitgevoerd. De nginx webserver configuratie wordt aangepast. Er wordt een Lets Encrypt TLS certificaat gemaakt dat gekoppeld is aan de FQDN. Het certificaat wordt automatisch vernieuwd voordat het verloopt. Dit gebeurt dagelijks.

Waarschuwing: je kunt het API uitschakelen en daarmee wordt tevens het Lets Encrypt TLS certificaat verwijderd. Mocht je bedenken en de API weer willen activeren dat kan dat maximaal 7 keer per week. Daarna moet je een week wachten voordat Lets Encrypt het aanmaken van certificaat weer toestaat voor die FQDN. Als je het binnen de 7 dagen stuk hebt gemaakt en niet kunt wachten dan moet je een nieuwe FQDN aanmaken en kan het proces weer opnieuw worden uitgevoerd. Let op als je dat te vaak doet dan kan Lets Encrypt je ISP IP adres blokkeren. Waarmee je deze optie niet meer te gebruiken is.

Testen van het TLS certificaat. Je kunt via ssllabs ( https://www.ssllabs.com/ssltest/index.html) de url invoeren. In dit voorbeeld kj2021m.duckdns.org. Na een paar minuten krijg je dan de veiligheid score.

5: Het aanmaken van API tokens.

De API is beveiligt met toegang tokens. Een token is een soort wachtwoord voor API toegang. Je kunt een token toevoegen over verwijderen op de API config-API.php pagina. Zoals hieronder weergeven

Als de nieuwe versie van de app uitkomt dan moet het token in de app worden ingevoerd.

6: Het testen van de API.

Je kunt de werking van de app ook testen met tools zoals curl. Hieronder een voorbeeld van een test met het token F12A05A9CEBA4D8E3AD6 het resultaat geeft aan hoelang de Rpi actief is.

curl -X GET -H "X-APIkey: F12A05A9CEBA4D8E3AD6" https:// kj2021m.duckdns.org /api/v1/status/19
[[19, "23:12:58", "Tijd verstreken sinds de laatste herstart:", 0]]

Als je meerder gebruikers van de API wil toepassen dat is het beste om voor elke gebruiker een eigen token te maken.  Mocht je de toegang dan willen ontzeggen dan kun je dat specifieke token verwijderen.  Minder dan 100 tokens hebben geen effect op de snelheid van de API.

Hiermee is de API actief en kan worden gebruikt voor de app of andere toepassingen.

Poort 80

Poort 80 moet worden ge-forward zodat Lets Encrypt automatisch het certificaat kan vernieuwen. Als je na het succesvol opzetten van een certificaat de poort dicht zet dan zal verloop het certificaat verlopen en niet meer werken.  Idealiter zou deze poort dicht staan maar dit is dus niet mogelijk. En omdat de forwarden op de router plaats vindt en niet op de Rpi kan de P1-monitor software de instellingen niet beïnvloeden.