# Dokumentation zur LED-Matrix

An dieser Stelle wird beschrieben, wie du mit dem LED-Matrix-Display arbeiten kannst.

## Die LED-Matrix
Die LED-Matrix besteht aus 8 Reihen und 8 Zeilen. Du kannst die LEDs einzeln ansteuern oder ganze Bilder auf das Display "malen". Die LEDs sind in einem Koordinatensystem angeordnet.
Die LED ganz unten links hat die Koordinaten (0,0).

```
y
^
|
|
|
|
|
|
|
|
+--------> x
```

## Basisfunktionen des Displays

Um das Display zu programmieren weren diverse Funktionen in sogenannten Bibliotheken bereitgestellt.  Ein einfaches Basisprogramm, welches den Lauftext "Hallo Welt!" anzeigt ist im folgenden zu sehen.

```python
from time import sleep, time, ticks_ms
from machine import Timer

from myfrabuled import WEMOSMatrixLEDShield
from font8x8 import letter
from pictures import *
from animations import *

shield = WEMOSMatrixLEDShield()

while True:
    scroll("Hallo Welt!",5,30)

```

In den ersten sieben Zeilen werden alle Bibliotheken eingebunden, die du benötigst. In der neunten Zeile wird die Display-Objekt angelegt.
In der while-Schleife läuft das eigentliche Programm ab. Hier wird eine vordefinierte Animation aufgerufen.

### update
Usage:
```python
shield.update()
```
Liest das Bild im Speicher und zeigt es auf dem Display an.

### clear()
Usage:
```python
shield.clear()
```
Löscht das aktuelle Bild im Speicher.

### brightness
Usage:
```python
shield.brightness()
```

Setzt die Helligkeit des Displays. Darf Werte zwischen 0 und 7 annehmen.

### power_on()
Usage:
```python
shield.power_on()
```

Schaltet das Display an.

### power_off()
Usage:
```python
shield.power_off()
```

Schaltet das Display an.

### get(i: int, j: int)
Usage:
```python
shield.get(3,5)
```

Gibt den aktuell gesetzten Werte im Speicher wieder.

### set(i: int, j: int, state: bool)
Usage:
```python
shield.set(3,5,1)
```

Setzt im Speicher den Bildpunkt (3,5) auf an.

### on(i: int, j: int)
Usage:
```python
shield.on(3,5)
```

Schaltet den angegebenen Bildpunkt im Speicher an.

### off(i: int, j: int)
Usage:
```python
shield.off(3,5)
```

Schaltet den angegebenen Bildpunkt im Speicher aus.

### toggle(i: int, j: int)
Usage:
```python
shield.toggle(3,5)
```

Invertiert den angegebenen Bildpunkt im Speicher. Aus 1 wird 0, aus 1 wird 0.

## blit
```ython
blit(source: list[list[int | bool]], source_offset: tuple[int, int] = (0, 0), dest_offset: tuple[int, int] = (0, 0))
```
* source - Die Bitmatrix die in den Speicher geschrieben werden soll
* source_offset - Wird benutzt, wenn nur ein Ausschnitt aus der Bitmatrix verwendet werden soll. Gibt des Startpunkt an [Optional]
* dest_offset - Wird benutzt, wenn nur ein Teil des Speichers geschrieben werden soll. Gibt es Startpunkt an [Optional]

Codebeispiel:
```python
picture = [[0,0,0,0,0,0,0,0],
           [0,1,1,0,0,1,1,0],
           [0,1,1,0,0,1,1,0],
           [0,0,0,0,0,0,0,0],
           [0,0,0,0,0,0,0,0],
           [0,1,0,0,0,0,1,0],
           [0,0,1,1,1,1,0,0],
           [0,0,0,0,0,0,0,0]]

shield.blit(picture)
```

Bilder bestehen aus einer sogenannten Bitmap. Das sind zwei verschachtelte Listen, die nur Nullen und Einsen enthalten. Eine 1 steht dabei für eine eingeschaltete LED, eine 0 für eine ausgeschaltete LED.
Mit der Funktion wird die Bitmatrix in den Speicher geschrieben. 

## Vordefinierte Bilder und Annimationen

### Vordefinierte Bilder
Die Funktion **get_picture** liefert die Bitmatrix von bereits definierten Bildern. 
Folgende Bilder sind bereits definiert:
* clear
* heart
* smiley
* cross
* diamond
* r_arrow
* l_arrow
* u_arrow
* d_arrow

Um ein Bild anzuzeigen muss der folgende Code verwendet werden.

```python
picture = get_picture("heart")
shield.blit(picture, (0, 0))
shield.update()
sleep(0.8)
```
#### Buchstaben
Eine spezielle Form der Bilder sind Buchstaben. Dies könnt ihr ebenso anzeigen lassen. Die Funktion ***letter*** gibt euch die Bitmatrix eines Buchstabens wieder.
Das folgende Code-Beispiel zeigt dir, wie du z.B. den Buchstaben R anzeigen lassen kannst.
```python
shield.blit(letter("R"), (0, 0))
shield.update()
sleep(0.8)
```

### Vordefinierte Annimationen
Neben den vordefinierten Bilder, gibt es auch schon ein paar vordefinierte Annimationen, die du verwenden kannst.

#### scroll(message, duration=5, speed = 15)

Mit der Funktion kannst du eine Textnachricht anzeigen lassen. 
* message - Dies ist der Text, der angezeigt wird
* duration - Dies ist die Dauer, wie lange der Text angezeigt werden soll [Optional]
* speed - Dies ist die Scroll-Geschwindigkeit des Texts [Optional]
Codebeispiel:
```python
scroll("Hallo Welt!",10)
```

#### random(duration=5, speed = 100):
Mit der Funktion werden die Bildpunkt zufällig ein- oder ausgeschaltet 
* duration - Dies ist die Dauer, wie lange der Text angezeigt werden soll [Optional]
* speed - Dies ist die Geschwindkeit [Optional]
Codebeispiel:
```python
random(10)
```

#### rustle(duration=5, speed = 10)
Mit der Funktion erzeugt ein Bildrauschen 
* duration - Dies ist die Dauer, wie lange der Text angezeigt werden soll [Optional]
* speed - Dies ist die Geschwindigkeit [Optional]
Codebeispiel:
```python
rustle(10)
```
#### arrows(duration=5, direction = "right", speed = 10):
Mit der Funktion können Pfeile angeigt werden die sich bewegen. 
* duration - Dies ist die Dauer, wie lange der Text angezeigt werden soll [Optional]
* direction - 
* speed - Dies ist die Geschwindigkeit [Optional]
Codebeispiel:
```python
arrows(1, "left", 30)
```
### Eigene Annimationen
Ihr könnt natürlich auch eigene Annimationen entwerfen. Annimationen sind eine abfolge von Bildern. Um die Sach für euch zu vereinfachen gibt es ein paar Funktionen, die euch helfen können

Die Funktionen ***shift_up***, ***shift_down***, ***shift_left*** und ***shift_right *** verschieben das Bild um eine Reihe bzw. Spalte in die gewünschte Richtung.
Codebeispiel:
```python
row = [0,1,1,0,0,1,0,1]
shift_up(bitmap, row)
```
Der erste Parameter gibt das Bild an, das verschoben werden soll. Dadurch wird auf der anderen Seite eine Reihe bzw. eine Zeile frei. Mit dem zweiten Parameter könnnt ihr angeben, was dort angezeigt werden soll.
Gebt ihr den zweiten Parameter nicht an, dann wird eine leere Zeile bzw. Spalte eingefügt.


Mit den Funktionen ***get_row*** und  ***get_column*** könnt ihr den Inhalt einer Spalte bzw. Zeile zurückgeben lassen. Der erste Parameter ist die Bitmap, der zweite Parameter die Zeilen bzw. Spalten-Nummer.
**Denkt daran, dass beim Zählen mit der 0 begonnen wird.**

Beispiel für eine eigene Annimation:
```python
heart = get_picture("heart")
    for i in range(8):
        shield.blit(heart, (0, 0))
        shield.update()
        shift_down(heart)
        sleep(0.5)
```
Die Basis für die Annimation ist das Herz. Mit **shift_down** wird das Herz nach unten verschoben. Ihr seht als ein Herz, das nach unten verschwindet.