Nexus 3.0 Hardware Library - Entwicklerdokumentation

Systemübersicht

Die Nexus Hardware Library stellt eine Java-Schnittstelle für die Integration von Nexus 3.x Steuerplatinen in POS-Systeme bereit. Die Library abstrahiert die serielle Kommunikation und bietet typisierte APIs für Peripheriesteuerung, Strommanagement und Statusüberwachung in Kassensystemen.

Systemvoraussetzungen: Nexus 3.x Steuerplatine mit USB-Anschluss (VID: 0x0483, PID: 0x374B)

Kernfunktionen

Typisierte Java-API für POS-Hardware-Integration
Strommanagement für fünf Peripherietypen (Tablet, Drucker, Scanner, LED, EFT)
Vier schaltbare GPIO-Ausgänge
RGBW-LED-Controller mit programmierbaren Übergängen
Watchdog-System zur Systemstabilität
Thread-sichere Implementierung

Testtool

Das mitgelieferte Testtool ermöglicht die sofortige Evaluierung der Hardware-Funktionen ohne Programmieraufwand.

Testtool starten

# Linux/Mac:
java -cp "nexus-hardware-library-1.0.0.jar:jSerialComm-2.10.4.jar" \
  com.wirecube.retail.hardware.nexus.demo.NexusDemo /dev/ttyUSB0

# Windows:
java -cp "nexus-hardware-library-1.0.0.jar;jSerialComm-2.10.4.jar" ^
  com.wirecube.retail.hardware.nexus.demo.NexusDemo COM3

# Falls Demo-JAR verfügbar:
java -jar nexus-demo-1.0.0.jar COM3

Testtool-Kommandos

Demo-Sequenzen

nexus> run-demo        # Vollständige Hardware-Demo
nexus> advanced-demo   # LED-Controller Tests
nexus> help            # Kommando-Übersicht

Direkte API-Tests

nexus> api getBoardInfo              # Hardware-Information
nexus> api setOutput 1 true          # GPIO-Port 1 einschalten
nexus> api setLED1Red 6000 1000      # Rote LED mit Übergang
nexus> api setLED1Green 4000 500     # Grüne LED
nexus> api setLED1Blue 8000 2000     # Blaue LED
nexus> api setLED1White 6000 1000    # Weiße LED
nexus> api setLED1Off 500            # LED ausschalten
nexus> api setLED1 4000 0 4000 0 3000 # Vollständige RGBW-Kontrolle
nexus> api setLED2 8000 0 0 0 1000   # Traffic Light LED
nexus> api setPowerState TABLET true # Geräte-Stromversorgung
nexus> api getPowerStatus PRINTER    # Drucker-Status abfragen
nexus> api setHeartbeat true 300     # Watchdog aktivieren
nexus> api sendHeartbeat             # Manueller Heartbeat
nexus> api resetUSBHub               # USB-Hub zurücksetzen

Low-Level Hardware-Zugriff

nexus> raw CMD_GetInfo               # Hardware-Info direkt
nexus> raw CMD_SetOutput\t1\t1       # GPIO direkt schalten
nexus> raw CMD_SetLED1\t6000\t0\t0\t0\t1000  # LED direkt programmieren

Syntax-Hinweis: Raw-Commands benötigen TAB-Trennung (\t) zwischen Parametern

Häufige Probleme

Port nicht gefunden: Windows Device Manager oder Linux dmesg | grep tty prüfen
Permission denied (Linux): sudo usermod -a -G dialout $USER, dann neu anmelden
ClassNotFoundException: Beide JAR-Dateien im Classpath erforderlich
Hardware antwortet nicht: USB-Kabel prüfen, Gerät neu starten

Erste Schritte

Minimale Integration

import com.wirecube.retail.hardware.nexus.NexusDevice;
import com.wirecube.retail.hardware.nexus.exception.NexusException;
import com.wirecube.retail.hardware.nexus.model.*;

// Device erstellen und verbinden
NexusDevice device = new NexusDevice();
device.connect("COM3");

// Hardware-Information abrufen
String info = device.getBoardInfo();
System.out.println("Hardware: " + info);

// Verbindung schließen
device.disconnect();

GPIO-Steuerung

NexusDevice device = new NexusDevice();
device.connect("/dev/ttyUSB0");

// GPIO-Ausgänge schalten
device.setOutput(1, true);   // Port 1 einschalten
device.setOutput(2, false);  // Port 2 ausschalten

// Status aller Ausgänge lesen
OutputState outputs = device.getOutputs();
System.out.println("GPIO Status: " + outputs);

device.disconnect();

LED-Controller

NexusDevice device = new NexusDevice();
device.connect("COM3");

// Status-LEDs programmieren
device.setLED1Green(8000, 1000);   // Grün: System bereit
device.setLED1Red(8000, 500);      // Rot: Fehler
device.setLED1Blue(4000, 2000);    // Blau: Verarbeitung
device.setLED1Off(1000);           // LEDs ausschalten

// Vollständige RGBW-Programmierung
device.setLED1(4000, 0, 4000, 0, 3000);  // Lila mit 3s Übergang

device.disconnect();

Peripherie-Stromversorgung

NexusDevice device = new NexusDevice();
device.connect("COM3");

// Peripherie-Geräte schalten
device.setPowerState(DeviceType.PRINTER, true);
device.setPowerState(DeviceType.SCANNER, true);
device.setPowerState(DeviceType.EFT, false);

// Status einzelner Peripherie abfragen
PowerStatus printerStatus = device.getPowerStatus(DeviceType.PRINTER);
System.out.println("Drucker: " + printerStatus);

device.disconnect();

Watchdog-System

NexusDevice device = new NexusDevice();
device.connect("COM3");

// Watchdog aktivieren (5 Minuten Timeout)
device.setHeartbeat(true, 300);

// Manueller Heartbeat
device.sendHeartbeat();

// Watchdog deaktivieren
device.setHeartbeat(false, 0);

device.disconnect();

Fehlerbehandlung

NexusDevice device = new NexusDevice();

try {
    device.connect("COM3");
    device.setLED1Green(6000, 1000);
    device.setPowerState(NexusDevice.DeviceType.PRINTER, true);
    
} catch (NexusException e) {
    System.err.println("Hardware-Fehler: " + e.getMessage());
    
    // Detaillierte Fehleranalyse
    if (e.getCause() != null) {
        System.err.println("Ursache: " + e.getCause().getMessage());
    }
    
    // Spezielle Behandlung von Command-Fehlern
    if (e instanceof NexusCommandException) {
        NexusCommandException cmdEx = (NexusCommandException) e;
        System.err.println("Fehlercode: " + cmdEx.getErrorCode());
    }
    
} finally {
    try {
        device.disconnect();
    } catch (NexusException e) {
        // Disconnect-Fehler ignorieren
    }
}

Verbindungsabbruch handhaben

public void robustHardwareControl() {
    NexusDevice device = new NexusDevice();
    
    while (true) {
        try {
            if (!device.isConnected()) {
                device.connect("COM3");
                device.setHeartbeat(true, 300);
            }
            
            // Normal operations
            device.setLED1Green(6000, 1000);
            device.sendHeartbeat();
            
            Thread.sleep(10000); // 10 Sekunden warten
            
        } catch (NexusException e) {
            System.err.println("Verbindung verloren: " + e.getMessage());
            
            try {
                device.disconnect();
                Thread.sleep(5000); // 5 Sekunden warten vor Neuversuch
            } catch (Exception ex) {
                // Ignore
            }
        }
    }
}

Integration

Maven Integration

<dependency>
    <groupId>com.wirecube.retail.hardware</groupId>
    <artifactId>nexus-link-core</artifactId>
    <version>1.0.3</version>
</dependency>

<dependency>
    <groupId>com.fazecast</groupId>
    <artifactId>jSerialComm</artifactId>
    <version>2.10.4</version>
</dependency>

Gradle Integration

implementation 'com.wirecube.retail.hardware:nexus-link-core:1.0.3'
implementation 'com.fazecast:jSerialComm:2.10.4'

Standalone JAR

# Runtime-Dependencies herunterladen
wget https://github.com/Fazecast/jSerialComm/releases/download/v2.10.4/jSerialComm-2.10.4.jar

# Anwendung starten
java -cp "nexus-link-core-1.0.3.jar:jSerialComm-2.10.4.jar:your-app.jar" \
  com.yourcompany.YourMainClass

NexusDevice API

Zentrale Klasse für Hardware-Steuerung in POS-Umgebungen.

Verbindungsmanagement

boolean connect(String portName) throws NexusException

Initialisiert USB-CDC-Verbindung zur Nexus-Steuerplatine.

Parameter

Required portName: Serieller Port (Windows: "COM3", Linux: "/dev/ttyUSB0")

Return

true bei erfolgreicher Verbindung

Exceptions

NexusException - Verbindungsfehler, Port nicht verfügbar

void disconnect() throws NexusException

Schließt Verbindung und gibt Systemressourcen frei.

boolean isConnected()

Prüft Verbindungsstatus zur Steuerplatine.

String sendCommandRaw(String command) throws NexusException

Direkter Befehlszugriff für erweiterte Funktionen.

String getBoardInfo() throws NexusException

Liest Hardware-Informationen und Firmware-Version.

Watchdog/Heartbeat

Systemstabilität: Das Watchdog-System überwacht die Kommunikation zwischen POS-Software und Steuerplatine. Bei ausbleibendem Heartbeat wird automatisch ein Tablet-Neustart ausgelöst.

String sendHeartbeat() throws NexusException

Manueller Heartbeat-Trigger.

String setHeartbeat(boolean enabled, int timeoutSeconds) throws NexusException

Konfiguriert automatisches Watchdog-System.

Parameter

Required enabled: Watchdog aktivieren/deaktivieren
Required timeoutSeconds: Timeout-Intervall (10-100000 Sekunden)

GPIO-Steuerung

String getOutputs() throws NexusException

Liest Zustand aller GPIO-Ausgänge.

String setOutput(int port, boolean state) throws NexusException

Schaltet einzelne GPIO-Ausgänge.

Parameter

Required port: GPIO-Port (1-4)
Required state: Schaltzustand (true=HIGH, false=LOW)

boolean getInput() throws NexusException

Liest GPIO-Eingangsstatus.

Return

true wenn Eingang aktiv ist, false sonst

Peripherie-Stromversorgung

String setPowerState(DeviceType device, boolean enabled) throws NexusException

Schaltet Stromversorgung für POS-Peripherie.

Parameter

Required device: Peripherietyp (DeviceType.TABLET, DeviceType.PRINTER, etc.)
Required enabled: Stromversorgung ein/aus

PowerStatus getPowerStatus(DeviceType device) throws NexusException

Abfrage Stromversorgungsstatus einzelner Peripherie.

Parameter

Required device: Peripherietyp (DeviceType-Konstante)

Return

PowerStatus-Objekt mit detailliertem Gerätestatus

String configureBoot(String bootSequence) throws NexusException

Konfiguriert sequenziellen Boot-Prozess für Peripherie.

Constraint: TABLET muss als erstes Gerät in der Boot-Sequenz stehen.

LED-Controller

String setLED1(int red, int green, int blue, int white, int fadingTimeMs) throws NexusException

Programmiert interne LED-Streifen (RGBW-Controller).

Parameter

red, green, blue, white: Farbkanäle (0-8191)
fadingTimeMs: Übergangszeit (0-65535ms)

String setLED1Red/Green/Blue/White/Off(int brightness, int fadeMs) throws NexusException

Vereinfachte LED-Steuerung für häufige Farben.

String setLED2(int red, int green, int blue, int white, int fadingTimeMs) throws NexusException

Programmiert externe LED-Signale (Traffic Light).

Parameter

red, green, blue, white: Farbkanäle (0-8191)
fadingTimeMs: Übergangszeit (0-65535ms)

String setBothLEDs(int led1Red, int led1Green, int led1Blue, int led1White, int led1FadeMs, int led2Red, int led2Green, int led2Blue, int led2White, int led2FadeMs) throws NexusException

Programmiert beide LED-Controller synchron für koordinierte Lichteffekte.

Parameter

led1Red, led1Green, led1Blue, led1White: LED1 Farbkanäle (0-8191)
led1FadeMs: LED1 Übergangszeit (0-65535ms)
led2Red, led2Green, led2Blue, led2White: LED2 Farbkanäle (0-8191)
led2FadeMs: LED2 Übergangszeit (0-65535ms)

Hardware-Management

String schedulePowerCycle(String devices, int delaySeconds, int offTimeSeconds) throws NexusException

Plant Power-Cycle für spezifizierte Geräte mit konfigurierbaren Timing-Parametern.

Parameter

Required devices: Komma-getrennte Geräteliste ("TABLET,PRINTER")
Required delaySeconds: Verzögerung bis Power-Off (Sekunden)
Required offTimeSeconds: Dauer des Power-Off-Zustands (Sekunden)

String resetUSBHub() throws NexusException

Führt Hardware-Reset des integrierten USB-Hubs durch.

Achtung: USB-Reset unterbricht kurzzeitig alle USB-Verbindungen zu angeschlossenen Geräten.

Datentypen

NexusDevice.DeviceType

Typisierte Konstanten für Peripherie-Management.

Konstante	String-Wert	POS-Peripherie
DeviceType.TABLET	"TABLET"	Hauptrechner/Display
DeviceType.PRINTER	"PRINTER"	Bondrucker
DeviceType.SCANNER	"SCANNER"	Barcode-Scanner
DeviceType.LED	"LED"	Beleuchtungssystem
DeviceType.EFT	"EFT"	Kartenterminal

OutputState

Repräsentiert den Zustand aller GPIO-Ausgänge.

OutputState outputs = device.getOutputs();
System.out.println("GPIO Status: " + outputs.toString());

// Einzelne Ports prüfen
boolean port1Active = outputs.isPort1Active();
boolean port2Active = outputs.isPort2Active();
boolean port3Active = outputs.isPort3Active();
boolean port4Active = outputs.isPort4Active();

PowerStatus

Enthält detaillierte Statusinformationen für Peripherie-Geräte.

PowerStatus status = device.getPowerStatus(DeviceType.PRINTER);
System.out.println("Drucker-Status: " + status.toString());

// Status-Details auswerten
boolean isPowered = status.isPowered();
boolean isReady = status.isReady();
String statusMessage = status.getStatusMessage();

Fehlerbehandlung

NexusException

Einheitliche Exception-Klasse für sämtliche Hardware-Fehler.

try {
    device.connect("COM3");
    device.setLED1Green(6000, 1000);
    
} catch (NexusException e) {
    System.err.println("Hardware-Fehler: " + e.getMessage());
    
    // Root-Cause-Analyse
    if (e.getCause() != null) {
        System.err.println("Ursache: " + e.getCause().getMessage());
    }
}

Typische Fehlerszenarien

Verbindungsfehler: USB-Port nicht verfügbar, Treiber-Probleme
Kommunikations-Timeout: Hardware antwortet nicht (2s Timeout)
Parametervalidierung: Ungültige GPIO/LED-Parameter
Hardware-Fehler: Peripherie nicht ansprechbar

Deployment

Systemvoraussetzungen

Java 11+ Runtime (compiliert mit Java 11)
jSerialComm 2.10.4+ (externe Abhängigkeit)
USB-CDC-Treiber (meist automatisch)
Nexus 3.x Hardware (VID: 0x0483, PID: 0x374B)

Linux-spezifische Konfiguration

# Benutzer zu dialout-Gruppe hinzufügen
sudo usermod -a -G dialout $USER

# Neuanmeldung erforderlich oder:
newgrp dialout

# Port-Discovery
dmesg | grep tty
# oder
ls /dev/ttyUSB*

Windows-spezifische Konfiguration

# Port-Discovery über Device Manager
# oder PowerShell:
Get-WmiObject -Class Win32_SerialPort | Select-Object Name,DeviceID