Systemdokumentation

Video med forklaring til kapitlet

Inden man kommer til at dokumentere sin software, så er det en god ide at dokumentere hvordan hardwaren er koblet op og hvordan den grundlæggende funktion af det man bygger er tænkt.

Kodeeksempler

Til dette kapitel er der nogle kodeeksempler man kan anvende. De er samlet i en ZIP-fil.

Blokdiagram

Ideen med et blokdiagram er at skitsere den overordnede sammenhæng i en opstilling/kredsløb. Blokdiagrammet skal være med til at give et overblik over funktionen og må derfor ikke være for detaljeret. Som vist i figur 1 er de enkelte funktionsdele skitseret som nogle firkanter og signalvejen gennem opstillingen er vist med pile mellem blokkene.

Figur 1 Eksempel på et blokdiagram - her er det en vejrstation.

Blokdiagrammet der er anvendt som eksempel i figur 1 er på grænsen til at være for kompliceret, da det faktisk viser to opstillinger; til højre en indendørs vejrstation, hvor sensorere, tastatur, lagring og display er vist, og til venstre en udendørs opstilling med sensorer, der så kan kommunikere ind til den indendørs opstilling via trådløst netværk. Det kan dog stadig give god mening at have de to dele sammen, da de funktionelt angiver en samlet enhed.

Til ethvert blokdiagram hører noget forklaring, da blokdiagrammet kun kan udtrykke sammenhængen, men ikke kan vise den egentlige funktion af blokkene. Til eksemplet i figur 1 kan der uddybende forklares hvilke faktorer man måler udendørs - temperatur, luftfugtighed, barometertryk, lys, nedbør mv. og der forklares hvordan de målte størrelser pakkes sammen og sendes via den trådløse forbindelse. Tilsvarende skal der forklares resten af funktionen i den indendørs enhed.

Grænseflader

Når man har opstillet en blokdiagram der forklarer den overordnede opbygning af opstillingen, så vil det være en god ide at gå mere i detaljer med hvilke signaler der overføres mellem de forskellige blokke, og måske også en beskrivelse hvordan signalet udtrykker det signal der kommer over.

Det kunne fx. være at et barometer skal have +5V og GND, samt at aflæsningen sker på to signaler SCK og SDA der fungerer ved hjælp af I2C protokollen, og at de skal have forbindelse til A4 og A5 på Arduinoen. Det giver et godt overblik at dokumentere dette i en tabel.

Signal navn	Barometer ben	Arduino ben	Funktion
SCK	1	A5	Clock
SDA	2	A4	Data
GND	3	GND	Stel
+5V	4	+5V	Forsyning

Tabel 1

Tilsvarende kunne en temperatur måles med en LM35, der skal have +5V og GND, og signalet fra LM35 skal ind på en analog indgang, det kunne være A2, og at den har temperaturen angivet med 10mV/°C. Her ville det også være en god ide med en tabel.

Tilsvarende skal alle grænseflader mellem modulerne beskrives i større eller mindre detaljeringsgrad.

For at bevare overblikket når man skal programmere sin software, så er det en god ide at lave en samlet tabel over benfunktionerne på Arduinoen:

Arduino ben	Modul	Signal navn	Funktion
0	Serial Monitor	Rx	Serial Receive
1	Serial Monitor	Tx	Serial Transmit
2	Transmitter	Data	Wireless Data
A0	LM35	Temperatur	Analog temperatur
A4	I2C moduler	SDA	I2C Data
A5	I2C moduler	SCL	I2C Clock

Tabel 2

Diagrammer

For at dokumentere sin opstilling vil diagrammer være den bedste måde at beskrive opstillinger på som vist i figur 2.

Figur 2 Diagram-udsnit fra en tilfældig opstilling.

Diagrammet giver den teoretiske opkobling af hvordan opstillingen er lavet. Dette spring kan tit være svært for elever i teknologi, og man kan derfor med fordel starte i noget der giver den mere praktiske opkobling.

Fritzing

Fritzing er et system der tager udgangspunkt i den praktiske opstilling, som man typisk vil starte med at opbygge på et fumlebræt. Det kunne fx være en opstilling som vist i figur 3.

Figur 3 Eksempel på opstilling opbygget på fumlebræt.

Fritzing kan downloades fra projektets hjemmeside Fritzing Download hvor man får mange standard komponenter med, og kan opbygge rigtigt meget omkring Arduino, også med shields og andre processorboards.

Til mindre komplicerede opstillinger giver denne måde at dokumentere god mening, specielt når man er ved at lære elektronik, men det er stadig en god ide at bevæge sig hen mod diagrammer

Programmet Fritzing holder samtidigt styr på hvilke komponenter der er sat sammen, så programmet kan også tegne et diagram over kredsløbet, som vist i figur 4.

Figur 4 Diagram over opstillingen lavet i Fritzing.

Simulering

I Fritzing er der også en mulighed for simulering af Arduino kode, men man skal her være opmærksom på at den sidste opdatering af Fritzing er sket tilbage i juni 2016, så man kan sagtens opleve at der er dele af sproget som Fritzing ikke forstår.

Fitzing har dog fordelen at der er mange komponenter i biblioteket, så man kan bygge ret mange kredsløb, og hvis man kan “knække” teknikken i det, så kan man også bygge egne komponenter, som man kan anvende i sine kredsløb.

Et alternativ, hvis man ønsker at lave simulering med en Arduino er Tinkercad, der stadig bliver opdateret.

Ideen er at man “bygger” sit kredsløb som vist i figur 5 og indlæser sin kode, så man kan få en ide om hvordan kode og kredsløb virker sammen.

Figur 5 Opbygning af kredsløb til Arduino simulering.

Simuleringen ser ud til at fungere ganske udmærket, og man kan for eksempel opbygge et system der viser at man kan aflæse en ultralyds-afstandsmåler, og sende værdien til en servomotor, som vist i figur 6.

Figur 6 Simulerings-opstilling med en Arduino, med Afstand og Servomotor.

For at få opstillingen til at simulere, så skal man have koden skrevet ind i Code som vist i figur 7. Koden kan også hentes i denne ZIP-fil

Figur 7 Toppen af kode-vinduet hvor man kan vælge Code og Start Simulation.

Den samlede kode ser ud som følger:

#include "Servo.h"

Servo myservo;
const int pingPin = 4;

void setup()
{
  myservo.attach(5);
}

void loop()
{
  long duration, inches, cm;
  int degree;

  pinMode(pingPin, OUTPUT);
  digitalWrite(pingPin, LOW);
  delayMicroseconds(2);
  digitalWrite(pingPin, HIGH);
  delayMicroseconds(5);
  digitalWrite(pingPin, LOW);

  pinMode(pingPin, INPUT);
  duration = pulseIn(pingPin, HIGH);

  cm = microsecondsToCentimeters(duration);
  degree = map(cm, 20, 300, 0, 180);
  myservo.write(degree);
  delay(100);
}

long microsecondsToCentimeters(long microseconds) {
  return microseconds / 29 / 2;
}

Funktionen af koden er at der sættes et Servo-objekt myservo op til ben 5. På pingPin (ben 4) laves der en kort puls ved at sætte benet som output, sikre at den er lav, sætte den høj i 5 mikrosekunder og trække den lav igen.

Som denne version af afstandsmåleren fungerer, så skal pulsen aflæses på samme ben, så det sættes op som input, og der læses længden af pulsen i mikrosekunder. Denne tid konverteres først til et antal cm. Herefter mappes den afstand med et område på 20-300 cm (som simuleringen har det bedst med) over til en vinkel på 0-180 grader, som skrives til servoen.

I praksis skal omgivelserne have lyden til at dø ud, så der ventes 100 ms inden næste loop afvikles. Når man klikker på Start Simulation, så vil man kunne se at man kan klikke på afstandsmåleren, og når man ændrer på afstanden så flytter servoen sig.

Elektrisk simulering

En ting der måske ligger lidt uden for disse dokumenters område er at man også kan simulere elektriske komponenter med forskellige simuleringsværktøjer.

Et sted som Falsted simulering kan simulere elektriske komponenter, og har en god visuel visning af strømme og spændinger, så man kan få en god fornemmelse for hvad der sker i kredsløbet.

Pulsplaner

For at beskrive funktionen af software vil der i mange sammenhænge indgå en tidsmæssig beskrivelse/sammenhæng af de signaler der indgår i opstillingen.

Til at dokumentere hvordan tidssammenhængen skal være, så er Pulsplaner et godt redskab til at illustrere med, som vist i eksempel i figur 8.

Figur 8 Eksempel på en pulsplan for et lyskryds.

Som det er vist i figur 8 angiver en pulsplan en sammenhæng mellem forskellige signaler i en tidsmæssig sammenhæng. Her er det hvordan Rød, Gul og Grøn signalerne i de to veje i et lyskryds forløber. Der er her ikke taget stilling til hvor lange de enkelte perioder er, men det kunne også angives i sekunder på tidsaksen.

Eksempler

Det er altid farligt at komme med et eksempel på en dokumentation, da det kan blive for voldsomt i en læringsproces når man ser en færdig dokumentation.

Det kan også være farligt at man kan komme til at betragte sådan en rapport som en skabelon, hvor et anderledes projekt måske slet ikke passer ind i.

Her er alligevel et bud, som kan være dækkende for flere fag, men slet ikke fuldstændig opremsning af alle dokumentationsformer.

Rapport om et Ur med TV-timer bygget omkring Arduino Rapporten har fokus på flere fags dokumentationstraditioner, Teknologi B, Programmering C og Teknikfag A

Referencer

Kom i gang med Arduino
Grundlæggende forståelse for Arduino	Arduino Hardware - Arduino Prototype Print - Blink Eksempel - Overblik - Serial Monitor - Simple Komponenter - Software og Udviklingsmiljø
Programmering af Arduino	Anvendelse af Eksempler - Klasser og Objekter - Programafvikling i Arduino - Test af Programmer
Dokumentationsformer	Dokumentation med Kode og Flowchart - Dokumentation med State-machines - Flowchart - Pseudokode - Program-kommentarer - Systemdokumentation - Syntaksfarvning - Blokdiagram - Pulsplaner - UML
Opkoblinger til Arduino	Moduler og Biblioteker - Driver - Opkobling af Hardware - Simple Komponenter - Tips til anvendelse af ben på Arduino UNO
Kompliceret Programmering	Arduino kombineret med Processing - Kommunikation fra Arduino til Processing - Kommunikation fra Processing til Arduino - CopyThread Multitasking - Dokumentation med State-machines - Tid og Samtidighed i Software - Arduino Memory
Kompliceret Hardware	I2C - Andre Processorboards - Internet of Things (IoT)
Oprindelige Dokumenter	PDF-Version - Forfattere
Software Udviklingsteknikker	Agile metoder - Brugertest - SCRUM Fasemodellen - Kravspecifikation - Databasedesign - Struktur eller Arkitektur - Softwaretest
Projekter	Afstand programforslag - Lysmåling - Projektforslag - Prototyper
Undervisningsforløb	4t Valgfag til Folkeskolen - Læsevejledning 4t Valgfag - Materialer til 4t Valgfag - Undervisningsnoter 4t Valgfag - Undervisningsplan 4t Valgfag - Slides til Undervisning Kort Valgfag til Folkeskolen - Læsevejledning Kort Valgfag - Materialer til Kort Valgfag - Undervisningsnoter Kort Valgfag - Undervisningsplan Kort Valgfag