README.md

## KIT-Card Reader  

Voraussetzung zur Nutzung dieser Software ist ein [ELATEC Multitech oder Mifare TWN4](https://www.elatec-rfid.com/de-de/produktdetail/twn4-multitech) und das zugehörige [Dev-Kit](https://www.elatec-rfid.com/de-de/twn4-dev-pack). Die Kosten für einen Leser liegen bei ca 100 € zzgl MwSt (Stand Juli 2021).
Das Dev-Kit muss installiert sein, der Leser über USB angeschlossen. Das Dev-Kit ist nur unter Windows nutzbar. Die Programmierung des Leser muss damit immer unter Windows erfolgen, auch dann, wenn die Nutzung des Lesers unter Linux erfolgen soll.
Der KIT-Card Reader kennt zwei Modi:

- reader mode --> USB Tastatur (HID Device, engl. Tastaturlayout)
- serial mode --> Serial device (über VCOM Treiber)

In beiden Fällen muss der Leser an einen Rechner angeschlossen sein. Ein Stand-Alone Betrieb ist nicht möglich, auch dann nicht, wenn der Leser so programmiert ist, dass er die Funktionen eigenständig ausführt. Die Treiber für beide Varianten werden von Windows und Linux mitgeliefert. Eine Treiber-Installation ist in der Regel nicht erforderlich. Vor dem Übersetzen müssen in `make.bat` die `init`-Parameter entsprechend der lokalen Installation gesetzt werden.<br />
Zur Übersetzung und zum Laden der Firmware wird `make.bat` aufgerufen. Folgende Parameter können angegeben werden:

```
USAGE:
  make.bat [flags] "serial|reader"

  -?, --help                   shows this help
  -v, --version                shows the version
  -e, --verbose                shows detailed output
  -d, --debug                  debug messages on
  -s, --secure                 set secure mode
 -ek, --english_keyboard       set keyboard emulation mode in reader mode to english (default is german)
  -r, --reader_action "action" set the reader action
                               This option is mandatory in reader mode
```
> Defines:<br />
> READER_ACTION --> Standardfunktion, die ausgeführt werden soll, wenn eine Karte aufgelegt wird. Dabei ist zu beachten, dass im reader mode nur Funnktionen angegeben werden können, die nur Daten ausgeben.<br />
> SECURE --> Nur im serial mode verfügbar. Damit werden nur Funktionen im SECURE-Mode freigeschaltet (siehe unten). Funktionen im Normalmodus (<100) können nicht mehr ausgeführt werden.<br />
> GERMAN_KEYBOARD --> Nur im reader mode verfügbar. Stellt den Reader auf deutsche Tastatur (Standard ist englische Tastatur).

Im serial mode kennt der Leser folgende Befehle, die über die serielle Schnittstelle an den Leser übergeben werden. Die seriellen Parameter sind:

    baudrate=9600,
    parity=NONE,
    stopbits=ONE,
    bytesize=EIGHTBITS
Unter Windows wird der Leser mit "comx" angesprochen unter Linux unter "/dev/ttyACMx", wobei x der Nummer der Schnittstelle entspricht.
Alle Befehle werden mit `0x0D`abgeschlossen. Zeichen dahinter werden ignoriert.
Alle Angaben sind als Zeichen zu übermitteln, wenn nichts anderes vermerkt ist.

Im serial mode werden alle Befehle direkt ausgeführt. Sollte zum Zeitpunkt der Ausführung keine Karte aufliegen, so kommt die Meldung "09,no card for action 1". Das heißt die Anwendung muss selbst die Warteschleife implementieren.
Fehlermeldungen haben immer folgenden Aufbau: 
`<fehlernummer>,<Erläuterungen zum Fehler>`
|Befehl| App | Return | Parameter
|--|--|--|--|
| 1 | bwCard old (becaad) | bwCard-Nummer |
|10|bwCard old (becaad)|bwCard-Nummer encrypted (Hex)
|11|bwCard old (becaad)|bwCard-Nummer;readerUID (Hex)
|12|bwCard old (becaad)|cardUID (Hex);readerUID (Hex)
|13|bwCard old (becaad)|bwCard-Nummer encrypted (Hex)>;<readerUID (Hex)
|14|bwCard old (becaad)|read file 1; bwCard-Nummer;\<Text from file\>
|15|bwCard old (becaad)|write file 1: String (max 64 chars)|Ex: 15,\<Text to write\>
|16|bwCard old (becaad)|read file 1; UID;\<Text from file\>
|20|Success Beep|Kein Returnwert
|20|Success Beep|Kein Returnwert
|20|Success Beep|Kein Returnwert
|21|Special Success Beep|Kein Returnwert
|30|Error Beep|Kein Returnwert
|31|Special Error Beep|Kein Returnwert
|50|read device UID|readerUID (Hex)
|51|Generate Login Data for secure mode|token for secure mode
|60| bwCard (F58860) | bwCard-Nummer |
|61|bwCard (F58860)|bwCard-Nummer encrypted (Hex)
|62|bwCard (F58860)|bwCard-Nummer;readerUID (Hex)
|63|bwCard (F58860)|cardUID (Hex);readerUID (Hex)
|64|bwCard (F58860)|bwCard-Nummer encrypted (Hex)>;<readerUID (Hex
|65|bwCard (F58860)|bwCard-Nummer;Scope;UID;ESCN
|70|OSS/SIPORT (F51773)|create OSS App  --> 0,app created *)
|71|OSS/SIPORT (F51773)| OSS Info File

*)Liest die bwCard Nummer (aus 0xbecaad oder 0xcc1580), legt die OSS App an, falls erforderlich und schreibet die bwCard Nummer in die OSS APP

#### Secure Mode
Zusätzlich zu obigen Funktionen ist noch eine "SECURE-Mode" implementiert. Im Secure Mode folgen die Befehle dem in der Abbildung gezegten Modus.
![coding_sequence](https://www.plantuml.com/plantuml/svg/bLHHJy8m47xlhxXtDL4UIJGa86IIg468ZwQkvsWOLsmxa7zlrurQnc1nJzlTztrtzrsxWR5SssATGwg4fEp3u7U1b29ZmrmYMRXvW27NOePSe8O-9C_9d4MHPbwx5vZYlWmsSPLY7nufrVkDHG4BWth4BO-glQ7UUgLSPP9QmJN4WSlFJsxGmOTBJ5VmfRJ7iP299SiCl4mZWP2Q8A7c5i6g5T9j10bjFxtFOIVj4XBX0jBkgsbHBwI0Ay3GQ2rnni4J76CyjN9R5gyeB5Tg0vAabJm7WyP8HSa8xl_gNLVaEnUhLS0zBIwgpRWW9w_88recpuucxpLWaSF6AjsDcg25LwxNnaDErz1W1dSz1pZLjlGYdxpfrRoDCO-C_O_2-GCiq9DgjOZebV47qy9vrR3rWbxi6d03XBiBdHpS2AtFq1IvZVhedTjq5wLrMvdRLeJfN5UeTh2fAjPrQ5fHOLXTDPoGkxrhxar54anWyruCNDZzh7u1 "coding_sequence")

Die implementierten Befehle im Secure Mode werden auf Nachfrage beschrieben.