Nätverk & systemintegration
/Kursinnehåll
SV
← Till kursöversikten
ÄMNE 12 / 13 · Integration

Krav, standarder och teknisk dokumentation

Samla krav, kod, API, testbevis och driftinstruktioner till ett spårbart underlag för din IoT-lösning.

18 min läsning5 kunskapsfrågorPraktisk övning
DET HÄR TAR DU MED DIG
  • Söka, använda och kritiskt granska information om nätverksprogrammering och systemintegration på svenska och engelska (F28).
  • Kommunicera tekniska koncept inom nätverksprogrammering och systemintegration på svenska och engelska (F29).
  • Skriva, läsa, strukturera, analysera, dokumentera och kommentera källkod inom nätverksprogrammering och systemintegration (F31).
  • Ta ansvar för och självständigt behandla innehåll inom nätverksprogrammering och systemintegration som leder till vidare lärande och professionell utveckling (KOM19).
  • Utveckla och optimera IoT-lösningar genom att integrera nätverkskommunikation och API:er enligt kravspecifikationer och standarder (KOM20).
Krav
Kod & API
Testbevis
Från krav till verifierat resultat · Ett förenklat flöde
01 — UTFORSKA

Lektion 2026-10-01: syfte och mål

Syfte: Samla kod, dokumentation och testbarhet till ett spårbart underlag för den integrerade IoT-lösningen.

Mål: Kunna dokumentera och kvalitetssäkra en IoT-lösning så att krav, kod, API och test är möjliga att följa och förstå.

Lektionens innehåll är kravspecifikationer, standarder, kodkommentarer och driftinstruktion; spårbarhet från krav till test, kod och API; samt svenska och engelska tekniska källor och begrepp. Laborationen är att färdigställa README, API-dokumentation och testprotokoll.

I föregående ämne dokumenterade du klientens felpolicy. Nu kopplar du policyn till krav, implementation och observerade testresultat. Dokumentationen blir ett gränssnitt mellan utvecklare, testare och drift: nästa person ska kunna förstå och verifiera lösningen.

02 — UTFORSKA

Gör kraven testbara

Systemet ska vara robust är svårt att verifiera. Ange i stället vilket villkor som utlöser beteendet och vilket resultat som ska kunna observeras. Ge varje krav ett stabilt ID, en källa, en prioritet och en verifieringsmetod.

Skilj funktion från kvalitet och begränsning. Publicera temperatur beskriver en funktion. Svar inom 2,0 sekunder beskriver kvalitet, men behöver även ange belastning och hur tiden mäts. MQTTS på port 8883 är en teknisk begränsning i ert krav, inte ett bevis för att hela lösningen är säker.

EXEMPEL
REQ-003 · Prioritet: ska
Källa: projektets kravspecifikation v1.0
Villkor: gatewayens brokeranslutning bryts i labbmiljön.
Resultat: efter att brokern åter är nåbar ska gatewayen
  återansluta inom 30 s och ha exakt en aktiv MQTT-klient.
Verifiering: T-07 bryter anslutningen och mäter med
  monoton klocka från återställd nåbarhet till MQTT-anslutning.
  Kontrollera klientantal och mottagen mätning efteråt.
Avgränsning: kravet lovar inte leverans av alla offline-mätningar.
03 — UTFORSKA

Standarder och kravord med rätt innebörd

En standard samlar gemensamma regler. En specifikation definierar tekniskt beteende eller format. Officiell produktdokumentation beskriver gränssnittet för en viss produktversion, medan en guide eller blogg ger tolkningar och exempel. Ange vilken källa och vilket avsnitt ert beslut bygger på.

I RFC 2119 anger MUST ett obligatoriskt krav, SHOULD en rekommendation där ett avsteg kräver att följderna förstås och vägs in, och MAY ett tillåtet alternativ. RFC 8174 förtydligar att orden har denna särskilda betydelse när de skrivs med versaler i dokument som använder konventionen. Bestäm och förklara motsvarande ska, bör och får i ert eget underlag.

Att använda TLS eller beskriva ett API med OpenAPI visar ett tekniskt val. Ett påstående om att följa en standard behöver knytas till relevanta krav och verifiering. Dokumentera också sådant ni ännu inte har kontrollerat.

04 — UTFORSKA

Granska källor på svenska och engelska

Börja med standarden eller specifikationen när frågan gäller protokollets regler. Använd officiell produktdokumentation för bibliotekets konkreta beteende och rätt version. Guider, forum och AI-svar kan hjälpa dig hitta vidare, men kontrollera påståendena mot ansvariga utgivare.

SIS ger en svensk introduktion till standarder. RFC 2119 och RFC 8174 beskriver kravord på engelska. OpenAPI-specifikationen beskriver hur HTTP-API:er kan dokumenteras. De kompletterande länkarna finns längst ned; SIS-introduktionen ersätter inte en teknisk protokollspecifikation.

  • Vem ansvarar för källan, och är den primär eller återberättad?
  • Vilken version, vilket datum och vilket avsnitt gäller? Spara även åtkomstdatum.
  • Vilket exakt påstående stöds av källan, och vad säger den inte?
  • Gäller exemplet er miljö och era beroenden? Dokumentera avgränsningar.
  • Behåll originalbegrepp vid risk för tvetydighet: krav (requirement), spårbarhet (traceability), testbevis (test evidence) och driftinstruktion (runbook).
EXEMPEL
Svenska: Gatewayen återansluter inom 30 s efter att
brokern åter är nåbar. Offline-leverans ingår inte i kravet.

English: The gateway reconnects within 30 s after the
broker becomes reachable again. Delivery of offline
readings is outside the scope of this requirement.
05 — UTFORSKA

Spåra från krav till drift och tillbaka

Spårbarhetskedjan är källa → krav → kontrakt → kod → test → bevis → drift. Följ den åt båda håll: från ett krav till dess testresultat och från en felrapport tillbaka till koden och kravet som styr beteendet.

En spårbarhetsmatris samlar hänvisningarna. Tabellen är ett exempel för en egen IoT-lösning; filnamnen och resultatet behöver ersättas med era verkliga underlag. Peka ut en version eller commit så att länkarna går att tolka även efter kodändringar.

  • Varje krav ska ha en verifieringsmetod och ett faktiskt resultat eller tydlig status som ej kört.
  • Kontrollera att hänvisningarna går till rätt kod, kontrakt och testversion.
  • Vid ändring: följ vilka testfall, API-beskrivningar och driftsteg som påverkas.
  • En automatisk luckkontroll kan hitta tomma fält. Att alla fält är ifyllda bevisar inte att kravet är uppfyllt.
Exempel: ett krav genom hela spårbarhetskedjan
KravKällaKontraktKodTestBevisDrift
REQ-003Kravspecifikation v1.0MQTT-policy v1.0gateway.cpp: reconnectT-07protokoll/T-07.md + loggRUN-04
06 — UTFORSKA

README som nästa person kan följa

README är ingången till lösningen. Beskriv syfte och arkitektur, beroenden med versioner, konfiguration, start, stopp och verifiering. Länka vidare till krav, API-dokumentation, testprotokoll och driftinstruktion i stället för att skapa motstridiga kopior.

Ange miljövariabler och exempelvärden utan riktiga lösenord, token eller privata nycklar. Markera kända begränsningar. Låt en annan grupp följa instruktionerna i en ren miljö så att saknade steg blir synliga.

EXEMPEL
# IoT-gateway
## Syfte och arkitektur
Sensor → MQTT-broker → gateway → HTTP-API
## Beroenden och versioner
Ange OS, verktyg, bibliotek och testad version/commit.
## Konfiguration
Beskriv variabler och hänvisa till en exempelkonfiguration.
Hemligheter tillförs lokalt och ingår inte i underlaget.
## Start och stopp
Skriv exakta kommandon, arbetskatalog och körordning.
## Verifiering
Beskriv normalfall, avsiktligt fel och förväntade resultat.
## Vidare dokumentation
Krav → docs/krav.md
API → docs/api.md
Testprotokoll → docs/testprotokoll.md
Drift → docs/drift.md
## Kända begränsningar
Beskriv vad som saknas och vad som ännu inte testats.
07 — UTFORSKA

API-dokumentation som styr klientens beslut

Beskriv metod, endpoint och autentisering; fält, typer, enheter och exempel; statuskoder och stabila felkoder; samt timeout, retry, idempotens, version och kompatibilitet. Ta med både giltiga och ogiltiga anrop.

OpenAPI kan strukturera ett HTTP-kontrakt för människor och verktyg. Ange vilken version av specifikationen ni använder och komplettera med beteenden som behöver förklaras i text. För MQTT behöver topics, payload, QoS, retained och återanslutningspolicy också dokumenteras.

Exemplet nedan är ett lokalt övningskontrakt. Koppla varje regel till ert verkliga API och verifiera att kodens svar motsvarar beskrivningen.

EXEMPEL
Kontrakt: temperatur-API v1.0
POST /api/readings · HTTPS · Bearer-token
Content-Type: application/json
{"sensorId":"temp-01","value":21.7,"unit":"C"}

sensorId: icke-tom sträng
value: ändligt tal i intervallet −50 till 100
unit: exakt C
201: mätningen har skapats
400: ogiltig mätning, stabil felkod invalid_reading
401: autentisering saknas eller är ogiltig

Klientpolicy: högst 4 000 ms totalt.
POST har inget dublettskydd i detta exempel.
Timeout: rapportera okänt utfall; inget automatiskt retry.
Versionering: dokumentera ändringar som bryter kompatibilitet.
08 — UTFORSKA

Testnamn behöver verkliga testbevis

T-07 finns i matrisen säger bara att ett test har identifierats. Beviset behöver visa version och miljö, teststeg och indata, förväntat och faktiskt resultat, tidpunkt, ansvarig samt hänvisning till logg eller rapport.

Skriv förväntat resultat innan körningen. Redovisa ej kört, godkänt eller underkänt utan att blanda ihop planerade test med observationer. Spara bevis även för avbrott och andra avsiktliga fel. En gammal godkänd körning bevisar inte att en ändrad version fungerar.

EXEMPEL
Test: T-07 · Krav: REQ-003
Version/commit: [fyll i]
Miljö och konfiguration: [fyll i]
Tidpunkt med tidszon och ansvarig: [fyll i]
Steg: bryt brokeranslutningen, återställ nåbarheten,
  mät tiden till MQTT-anslutning och kontrollera klientantal.
Förväntat: högst 30 s, exakt en aktiv MQTT-klient
  och en mottagen mätning efter återanslutningen.
Faktiskt: [uppmätt tid, klientantal och mottagen mätning]
Bevis: [länk till relevant logg eller rapport]
Status: ej kört
Avvikelse och beslut: [fyll i vid behov]
09 — UTFORSKA

Kodkommentarer och driftinstruktioner

Kommentera avsikt, risk och oväntade val när de inte framgår av koden. En hänvisning till ett krav kan förklara varför en budget eller begränsning finns. Håll kommentarerna uppdaterade tillsammans med implementationen.

Driftinstruktionen ska ange start, stopp, hälsokontroll, förväntade portar och beroenden, relevanta loggar, vanliga fel och säkra återställningssteg. Ange när felsökningen ska eskaleras och vem som ansvarar för nästa steg.

EXEMPEL
// REQ-004: begränsa försöken för att undvika en retry-storm.
// Gäller bara operationer som får upprepas enligt kontraktet.
for (int attempt = 1; attempt <= max_attempts; ++attempt) {
    // Utför försök med kontroll av återstående tidsbudget.
}

RUN-04 · Brokeravbrott
1. Kontrollera brokerstatus och dokumenterad port.
2. Följ gatewayens anslutningshändelser och klientantal.
3. Återställ brokern enligt miljöns startinstruktion.
4. Verifiera återanslutning och en mottagen mätning.
5. Om verifieringen misslyckas: spara relevanta loggar
   utan hemligheter och kontakta utsedd driftansvarig.
FRÅN KUNSKAP TILL HANDLING

Prova själv

Ta med ämnet in i ditt eget IoT-case. Dokumentera vad du upptäcker.

  1. Utgå från er integrerade IoT-lösning. Samla minst fem krav med stabila ID:n, källa, prioritet, villkor, observerbart resultat och verifieringsmetod. Ta med funktion, kvalitet och tekniska begränsningar.
  2. Granska minst en svensk och en engelsk källa. Anteckna utgivare, version eller datum, avsnitt, URL och åtkomstdatum samt vilket påstående källan stöder och dess begränsningar. Förklara viktiga begrepp och skriv en kort teknisk sammanfattning på båda språken.
  3. Färdigställ README med syfte, arkitektur, versionsangivna beroenden, konfiguration, start, stopp och verifiering. Länka till API-dokumentation, krav, testprotokoll och driftinstruktion utan att ta med hemligheter.
  4. Färdigställ API-underlaget med autentisering, format, typer, enheter, exempel, status- och felkoder, timeout, retry, idempotens och kompatibilitet. Dokumentera MQTT-kontraktet om det ingår i lösningen.
  5. Skapa en spårbarhetsmatris för de fem kraven med hänvisningar till kontrakt, kod, test, bevis och drift. Granska relevanta kodkommentarer så att de förklarar avsikt och risk.
  6. Kör testfallen och färdigställ testprotokollet. Dokumentera normalfall och avsiktliga fel med version, miljö, förväntat och faktiskt resultat, tidpunkt, ansvarig och bevis. Markera tydligt sådant som inte är kört eller inte klarar kravet.
  7. Låt en annan grupp följa README, API-underlaget och testprotokollet samt spåra ett krav åt båda håll. Anteckna deras frågor och anmärkningar, rätta luckor och upprepa påverkade test.
  8. Klart enligt presentationen: minst fem spårade krav, minst en svensk och en engelsk källa, README, API-underlag och testprotokoll som kan följas, granskning av en annan grupp samt kritiska anmärkningar som är åtgärdade eller har ett dokumenterat beslut med ansvarig.
DIN TUR

Testa dina kunskaper

Stanna upp en stund. Vad har fastnat?

01Vilket krav går att verifiera med ett avgränsat test?

02Hur ska SHOULD förstås i en specifikation som använder RFC 2119?

03En matris länkar REQ-003 till T-07, men saknar körresultat. Vad återstår?

04En guide hävdar att klientens timeout alltid avbryter serverarbetet. Hur granskar du påståendet?

05Alla fält i spårbarhetsmatrisen är ifyllda. Vad visar en automatisk luckkontroll?

Fortsätt vara nyfiken

Originalmaterial och utvalda källor för dig som vill gå djupare.

Föreläsningsbilder · Ämne 12Joakim Englund · Systementor AB · PDF på svenskaVad är en standard?Svenska institutet för standarder, SIS · SvenskaKravord: MUST, SHOULD och MAYIETF · RFC 2119 · EngelskaNär kravorden har särskild betydelseIETF · RFC 8174 · EngelskaBeskriv HTTP-API:er med OpenAPI 3.1.1OpenAPI Initiative · Engelska

Ett steg närmare helheten.

Markera ämnet när du känner dig redo.

Hitta nästa sak att förstå.

Introduktion & MQTTÄmne 1 · GrundernaPortar & socketsÄmne 2 · NätverkHTTP(S) & API:erÄmne 3 · IntegrationJSON, XML & datakontraktÄmne 4 · IntegrationSystemintegration & SOAÄmne 5 · IntegrationNätverk & segmenteringÄmne 6 · NätverkSäker kommunikationÄmne 7 · SäkerhetTrådar & återanslutningÄmne 8 · RobusthetLoggning & övervakningÄmne 9 · RobusthetNätverksprestanda & felsökningÄmne 10 · RobusthetAPI-konsumtion & robusta klienterÄmne 11 · RobusthetKrav, standarder och teknisk dokumentationÄmne 12 · IntegrationIntegrerad systemtest & teknisk kommunikationÄmne 13 · Integration