Gastro-MIS GmbH

Die Swissbit-TSE wird zusammen mit einem SDK sowie einer API-Beschreibung ausgeliefert. Beide können Sie nach Erwerb des Implementierungskits über den nicht öffentlichen Bereich des Shops herunterladen. 

Um die TSE am Kassensystem zu betreiben muss im Falle der Formfaktoren microSD und SD ein entsprechender Leser genutzt werden. 

Das SDK, derzeit erhältlich für Windows, Linux und Android muss in die Kassenapplikation integriert (verlinkt) werden. 

Falls mehrere Threads auf eine TSE zugreifen können, muss dies auf Kassenseite synchronisiert sein!

Ist die TSE gemountet (Unter Windows stellt sich die TSE als gewöhnliches Laufwerk dar) sollte man sich den Laufwerksbuchstaben merken, da dieser in der Applikationslösung normalerweise konfiguriert werden muss. Das Implementieren einer Erkennungsroutine bleibt jedem selbst überlassen. 

Konfiguration einer TSE Einheit

Passwörter

Der PIN und der PUK funktionieren wie bei einem Handy. Wird der PIN zu oft falsch eingegeben, dann muss er mit dem PUK (Admin User) entsperrt werden. Wird der PUK zu oft falsch eingegeben, kann die TSE Einheit nicht mehr genutzt werden. PIN und PUK können geändert werden. 

Zusätzlich benötigt man den Credential-Seed, ohne welchen man die Karte nicht initialisieren kann. Dieser ist bei uns „SwissbitSwissbit“, andere Händler können aber einen anderen CredentialSeed haben!

Schlussendlich benötigt man noch die Client-ID, welcher die Kassenseriennummer darstellt. Es können mehrere Client-IDs auf einer TSE angelegt werden. Diese Client-ID benötigt man, um zum Beispiel Transaktion durchzuführen.

Einrichten einer TSE Einheit

Initialisieren: worm_Init : Parameter : Laufwerksbuchstabe

Wurde die Karte noch nicht aktiviert, muss ein SETUP durchgeführt werden. Dabei werden alle Daten wie PIN, PUK, Client-ID,…… gesetzt. Hierfür benötigt man den Credential-Seed.

ACHTUNG! Falls im Credential-Seed ein Typo drinnen ist (vor allem Groß- und Kleinschreibung beachten) und dieser 3 Mal durchgeführt ist, ist die TSE blockiert (da versucht wird den PUK zu ändern, was aber fehlschlägt)!

Daher den Credential-Seed am besten fix vorgeben, damit nichts passieren kann.

Zusätzlich sollte davor kontrolliert werden, ob der PIN/PUK bereits geändert wurde. Über das Programm wormCli.exe kann mit Hilfe des info-Befehls abgefragt werden ob die TSE noch uninitialisiert ist, sowie PIN und PUK noch nicht geändert wurden.

Der nächste Fall kann nur eintreten, falls Sie die TSE von einem anderen Händler beziehen, welcher schon vorher den PIN und PUK geändert hat oder etwas beim Setup schief gelaufen ist (TSE wurde vor Beenden abgezogen,...)

Wurde der PIN/PUK geändert und wurde die TSE noch nicht initialisiert, darf auf keinen Fall der Setup durchgeführt werden, da dann wiederum der PUK blockiert werden kann. Um die TSE dann zu initialisieren wird der Admin-Pin benötigt und die letzten Schritte müssen händisch durchgeführt werden: 

1. Als Admin einloggen,

2. einen Client registrieren(registerClient),

3. einen SelbstTest (runSelfTest) mit diesem Client durchführen,

4. das CTSS (ctss_enable) aktivieren,

5. schlussendlich die TSE initialisieren (tse_initialize).

Setup durchführen

• worm_tse_runSelfTest (Es kommt ein Fehler zurück, muss aber trotzdem ausgeführt werden)
• worm_tse_setup (Der Setup wird durchgeführt)

Die Setup-Methode ist eine Hilfsmethode die folgenden Aufrufe beinhaltet:

• worm_user_change_puk
• worm_user_change_pin
• worm_tse_ers_enable
• worm_tse_registerClient
• worm_tse_runSelfTest
• worm_tse_initialize

Kontrolle ob TSE Einheit richtig konfiguriert wurde:

Die Funktionen müssen folgende Werte zurückgeben.

• worm_info_isErsInterfaceActive = 1
• worm_info_initializationState = 1
• worm_info_hasPassedSelfTest = 1

enum WormInitializationState {
    Uninitialized = 0,
    Initialized = 1,
    Decommissioned = 2
}

PEM Datei auslesen

Die PEM Datei kann mit dem Befehl ausgelesen werden

worm_getLogMessageCertificate

Dieser gibt das Zertifikat zurück, dass man benötigt, um die Signaturen und zu überprüfen. Da sich das Zertifikat für eine TSE nicht ändert, müssen diese Daten nur einmal gelesen werden. Mittlerweile gibt es auch eine Funktion um de PublicKey direkt auszulesen, man muss diesen also nicht mehr aus dem Zertifikat extrahieren.

Starten (TSE wurde erfolgreich konfiguriert)

Wurde die TSE erfolgreich konfiguriert, dann muss nach dem WormLogin zyklisch die Zeit gesetzt werden.

• worm_init (mit Laufwerk Buchstabe)
• worm_tse_runSelfTest (sollte als 1. Kommando nach dem worm_init gesendet werden)
• worm_user_login (mit Pin und Type ( 1= Admin, 2=TimeAdmin))
• worm_tse_ers_enable (damit überhaupt Transaktionen gemacht werden. Default Wert ist nicht aktiv. Wird nicht resettet, muss also nur gemacht werden, falls er auf inaktiv ist)
• worm_info_new (Neues worm_info wird erstellt)
• worm_info_read (Um das Zeitintervall zu bekommen)
• worm_info_maxTimeSynchronizationDelay (Gibt das Intervall zurück in welchem worm_tse_updateTime aufgerufen werden muss)
• Timer Thread starten(welcher alle x Sekunden worm_tse_updateTime aufruft)
• Nun kann es vorkommen, dass ein Fehler zurückkommt, dass ein SelbstTest durchgeführt werden muss. Das passiert in dem Fall, dass die TSE länger als 25 Stunden an der Kasse gehangen ist, die Software aber nicht gelaufen ist (die Zeit nicht gesetzt hat). Das hat den Grund, dass der erste SelbstTest durchgelaufen ist, die Zeit aber um mehr als 25 Stunden nach vorne gesetzt wurde und somit wieder ein SelbsTtest nötig ist. Danach sollte nochmal die Zeit gesetzt werden.
  
  

Transaktionen

Die Transaktionen sind der Hauptbestandteil der TSE. Diese sollten immer nach dem gleichen Schema ablaufen. Die Transaktion wird ohne Daten gestartet und danach mit Daten geschlossen.

Um Transaktionen durchzuführen benötigt man folgende Funktionen aus der API:

• worm_transaction_response_new (Um Platz für die Informationen aus einer Transaktion zu machen)
• worm_transaction_start (Daten sind immer leer, es werden Infos in die TransactionResponse geschrieben)
• worm_transaction_finish (Hier werden die benötigten Daten übertragen, es werden Infos in die TransactionResponse geschrieben)
• worm_transaction_response_logTime (Die Zeit der Transaktion)
• worm_transaction_response_serialNumber (Die Seriennummer der TSE auf welchem die Transaktion durchgeführt wurde)
• worm_transaction_response_signatureCounter (Der neue Signaturzähler)
• worm_transaction_response_signature (Die Signatur)
• worm_transaction_response_transactionNumber (Die Transaktionsnummer)

Es wird für jede worm_transaction_start und für jede worm_transaction_end eine eigene LogNachricht in der TSE geschrieben. Das heißt, man muss die Informationen direkt nach einem erfolgreichen Aufruf der worm_transaction_start lesen und wieder bei einem erfolgreichen Aufruf der worm_transaction_end.

Es gibt drei verschiedene Transaktionstypen:

Bestellung, Kassenbeleg und sonstiger Vorgang (ist hier irrelevant).

Wie die jeweiligen Datensätze für worm_transaction_finish aussehen ist in „Anlage zur DSFinV-K“ ersichtlich.

Eine Bestellungs-Transaktion wird durchgeführt, nachdem einer oder mehrere Artikel boniert wurden. Die Kassenbelegs-Transaktion wird durchgeführt, sobald die Rechnung gedruckt wird.

Notwendige Informationen auf der Rechnung

Auf der Rechnung werden diverse Informationen benötigt, welche man nach der worm_transaction_start bzw. worm_transaction_finish gelesen hat.

• TSE-Signature - Finish-Transaktion (worm_transaction_response_signature)
• TSE-Transaktionsnummer - Finish-Transaktion (worm_transaction_response_transactionNumber)
• TSE-Start Zeitpunkt - Start-Transaktion (worm_transaction_response_logTime )
• TSE-Stop Zeitpunkt - Finish-Transaktion (worm_transaction_response_logTime)
• TSE-Seriennummer - Finish-Transaktion (worm_info_tseSerialNumber-Diese Seriennummer muss als octet dargestellt werden)
• TSE-sigcount - Finish-Transaktion (worm_transaction_response_signatureCounter)
• TSE-starttimefirstorder (LogTime der ersten Bestell-Transaktion auf diesem Tisch (logTime der Start-Transaktion))
• TSE-ZeitFormat - bleibt für TSE gleich (Kann aus den Logs gelesen werden oder einfach als Konfiguration eingetragen werden)
• TSE-PublicKey – bleibt für TSE gleich (Kann aus dem Zertifikat gelesen werden)
• TSE- Signatur Algorithmus - bleibt für TSE gleich

QR Code

Der QR-Code enthält nochmals alle Daten der Rechnung im vorgegebenen Format (dieses ist auch in „„Anlage zur DSFinV-K“ ersichtlich“). Ein Beispiel:

V0;SwissbitDemo;KassenBeleg-V1;Beleg^6.90_0.00_0.00_0.00_0.00^6.90:Bar;25;125;2019-07-30T14:40:33.000Z;2019-07-30T14:40:34.000Z;SHA256withECDSA;unixTime;MEQCIHQRwSL6tvG3DoffVxVVR7ylGLrCRrlsgO08xls019QuAiBO2Qx3mHC1XdajX13Y7PNQ4TXmf3e4g4iagoxqpuaTLg==;BKRaS+BAaTnwCJPHLFUY1UYk88UXNFOPOjelUVSh1vBCRBNefihVIejklN4n9bIPBdFbnY265YgzxUq9ys9hXig=

Probleme und Lösungen

PIN und PUK Probleme

Hier kann man ein Factory-Reset durchführen. Im Auslieferungszustand steht die Funktionen Factory-Reset nicht mehr zur Verfügung.

Problem mit der MicroSD Karte

Wird bei dem Laufwerk mit dem Namen „SWISSBIT“ ein SD-Card-Icon in der Laufwerksübersicht angezeigt, so wird die TSE-Verbindung nicht funktionieren. Ist dies der Fall, so muss im Gerätemanager der USB-Controller „USB-Root-Hub (USB 3.0)“ deinstalliert werden. Sollte eine Abfrage zum komplett Löschen des Treibers aufgehen, so bestätigt man diese. Anschließend muss der PC neu gestartet werden

Lösung:

Diesen Treiber und die Treibersoftware löschen:

Und dann auch noch die Treibersoftware für diese Gerät löschen. Wird die SD Karte dann wieder in den USB Port gegeben soll es ohne Icon dargestellt werden.

Die SD Karte funktioniert ohne weiter Aktionen, sofern sie richtig konfiguriert wurde.