Nexus 3.0 Hardware Library - Developer Documentation

System Overview

The Nexus Hardware Library provides a Java interface for integrating Nexus 3.x control boards into POS systems. The library abstracts serial communication and offers typed APIs for peripheral control, power management, and status monitoring in retail environments.

System Requirements: Nexus 3.x control board with USB connection (VID: 0x0483, PID: 0x374B)

Core Features

Typed Java API for POS hardware integration
Power management for five peripheral types (Tablet, Printer, Scanner, LED, EFT)
Four switchable GPIO outputs
RGBW LED controller with programmable transitions
Watchdog system for system stability
Thread-safe implementation

Demo Tool

The included demo tool enables immediate hardware evaluation without programming effort.

Starting the Demo Tool

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

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

# If demo JAR available:
java -jar nexus-demo.jar COM3

Demo Tool Commands

Demo Sequences

nexus> enterprise-demo # Complete hardware demo
nexus> retail-demo     # Retail environment simulation
nexus> help            # Command overview

Direct API Tests

nexus> api getBoardInfo              # Hardware information
nexus> api setOutput 1 true          # GPIO port 1 on
nexus> api setLED1Red 6000 1000      # Red LED with transition
nexus> api setLED1Green 4000 500     # Green LED
nexus> api setLED1Blue 8000 2000     # Blue LED
nexus> api setLED1White 6000 1000    # White LED
nexus> api setLED1Off 500            # Turn off LED
nexus> api setLED1 4000 0 4000 0 3000 # Full RGBW control
nexus> api setLED2 8000 0 0 0 1000   # Traffic light LED
nexus> api setPowerState TABLET true # Device power supply
nexus> api getPowerStatus PRINTER    # Query printer status
nexus> api setHeartbeat true 300     # Enable watchdog
nexus> api sendHeartbeat             # Manual heartbeat
nexus> api resetUSBHub               # Reset USB hub

Low-Level Hardware Access

nexus> raw CMD_GetInfo               # Hardware info direct
nexus> raw CMD_SetOutput\t1\t1       # GPIO direct control
nexus> raw CMD_SetLED1\t6000\t0\t0\t0\t1000  # LED direct programming

Syntax Note: Raw commands require TAB separation (\t) between parameters

Common Issues

Port not found: Check Windows Device Manager or Linux dmesg | grep tty
Permission denied (Linux): sudo usermod -a -G dialout $USER, then log in again
ClassNotFoundException: Both JAR files required in classpath
Hardware not responding: Check USB cable, restart device

Getting Started

Minimal Integration

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

// Create device and connect
NexusDevice device = new NexusDevice();
device.connect("COM3");

// Get hardware information
String info = device.getBoardInfo();
System.out.println("Hardware: " + info);

// Close connection
device.disconnect();

GPIO Control

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

// Control GPIO outputs
device.setOutput(1, true);   // Port 1 on
device.setOutput(2, false);  // Port 2 off

// Read status of all outputs
OutputState outputs = device.getOutputs();
System.out.println("GPIO Status: " + outputs);

device.disconnect();

LED Controller

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

// Program status LEDs
device.setLED1Green(8000, 1000);   // Green: system ready
device.setLED1Red(8000, 500);      // Red: error
device.setLED1Blue(4000, 2000);    // Blue: processing
device.setLED1Off(1000);           // Turn off LEDs

// Full RGBW programming
device.setLED1(4000, 0, 4000, 0, 3000);  // Purple with 3s transition

device.disconnect();

Peripheral Power Supply

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

// Control peripheral devices
device.setPowerState(DeviceType.PRINTER, true);
device.setPowerState(DeviceType.SCANNER, true);
device.setPowerState(DeviceType.EFT, false);

// Query individual peripheral status
PowerStatus printerStatus = device.getPowerStatus(DeviceType.PRINTER);
System.out.println("Printer: " + printerStatus);

device.disconnect();

Watchdog System

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

// Enable watchdog (5 minute timeout)
device.setHeartbeat(true, 300);

// Manual heartbeat
device.sendHeartbeat();

// Disable watchdog
device.setHeartbeat(false, 0);

device.disconnect();

Error Handling

NexusDevice device = new NexusDevice();

try {
    device.connect("COM3");
    device.setLED1Green(6000, 1000);
    device.setPowerState(DeviceType.PRINTER, true);
    
} catch (NexusException e) {
    System.err.println("Hardware error: " + e.getMessage());
    
    // Detailed error analysis
    if (e.getCause() != null) {
        System.err.println("Cause: " + e.getCause().getMessage());
    }
    
    // Special handling of command errors
    if (e instanceof NexusCommandException) {
        NexusCommandException cmdEx = (NexusCommandException) e;
        System.err.println("Error code: " + cmdEx.getErrorCode());
    }
    
} finally {
    try {
        device.disconnect();
    } catch (NexusException e) {
        // Ignore disconnect errors
    }
}

Handling Connection Loss

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); // Wait 10 seconds
            
        } catch (NexusException e) {
            System.err.println("Connection lost: " + e.getMessage());
            
            try {
                device.disconnect();
                Thread.sleep(5000); // Wait 5 seconds before retry
            } 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

# Download runtime dependencies
wget https://github.com/Fazecast/jSerialComm/releases/download/v2.10.4/jSerialComm-2.10.4.jar

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

NexusDevice API

Central class for hardware control in POS environments.

Connection Management

boolean connect(String portName) throws NexusException

Initializes USB CDC connection to Nexus control board.

Parameters

Required portName: Serial port (Windows: "COM3", Linux: "/dev/ttyUSB0")

Return

true on successful connection

Exceptions

NexusException - Connection error, port not available

void disconnect() throws NexusException

Closes connection and releases system resources.

boolean isConnected()

Checks connection status to control board.

String sendCommandRaw(String command) throws NexusException

Direct command access for advanced functions.

String getBoardInfo() throws NexusException

Reads hardware information and firmware version.

Watchdog/Heartbeat

System Stability: The watchdog system monitors communication between POS software and control board. When heartbeat is missing, an automatic tablet restart is triggered.

String sendHeartbeat() throws NexusException

Manual heartbeat trigger.

String setHeartbeat(boolean enabled, int timeoutSeconds) throws NexusException

Configures automatic watchdog system.

Parameters

Required enabled: Enable/disable watchdog
Required timeoutSeconds: Timeout interval (10-100000 seconds)

GPIO Control

OutputState getOutputs() throws NexusException

Reads state of all GPIO outputs.

Return

OutputState object with current output states

String setOutput(int port, boolean state) throws NexusException

Controls individual GPIO outputs.

Parameters

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

boolean getInput() throws NexusException

Reads GPIO input status.

Return

true if input is active, false otherwise

Peripheral Power Supply

String setPowerState(DeviceType device, boolean enabled) throws NexusException

Controls power supply for POS peripherals.

Parameters

Required device: Peripheral type (DeviceType.TABLET, DeviceType.PRINTER, etc.)
Required enabled: Power supply on/off

PowerStatus getPowerStatus(DeviceType device) throws NexusException

Query power supply status of individual peripheral.

Parameters

Required device: Peripheral type (DeviceType constant)

Return

PowerStatus object with detailed device status

String configureBoot(String bootSequence) throws NexusException

Configures sequential boot process for peripherals.

Constraint: TABLET must be the first device in the boot sequence.

LED Controller

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

Programs internal LED strips (RGBW controller).

Parameters

red, green, blue, white: Color channels (0-8191)
fadingTimeMs: Transition time (0-65535ms)

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

Simplified LED control for common colors.

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

Programs external LED signals (Traffic light).

Parameters

red, green, blue, white: Color channels (0-8191)
fadingTimeMs: Transition time (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

Programs both LED controllers synchronously for coordinated light effects.

Parameters

led1Red, led1Green, led1Blue, led1White: LED1 color channels (0-8191)
led1FadeMs: LED1 transition time (0-65535ms)
led2Red, led2Green, led2Blue, led2White: LED2 color channels (0-8191)
led2FadeMs: LED2 transition time (0-65535ms)

Hardware Management

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

Schedules power cycle for specified devices with configurable timing parameters.

Parameters

Required devices: Comma-separated device list ("TABLET,PRINTER")
Required delaySeconds: Delay until power-off (seconds)
Required offTimeSeconds: Duration of power-off state (seconds)

String resetUSBHub() throws NexusException

Performs hardware reset of the integrated USB hub.

Warning: USB reset briefly interrupts all USB connections to connected devices.

Data Types

DeviceType

Typed constants for peripheral management.

Constant	String Value	POS Peripheral
DeviceType.TABLET	"TABLET"	Main computer/display
DeviceType.PRINTER	"PRINTER"	Receipt printer
DeviceType.SCANNER	"SCANNER"	Barcode scanner
DeviceType.LED	"LED"	Lighting system
DeviceType.EFT	"EFT"	Card terminal

OutputState

Represents the state of all GPIO outputs.

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

// Check individual ports
boolean port1Active = outputs.isPort1Active();
boolean port2Active = outputs.isPort2Active();
boolean port3Active = outputs.isPort3Active();
boolean port4Active = outputs.isPort4Active();

PowerStatus

Contains detailed status information for peripheral devices.

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

// Evaluate status details
boolean isPowered = status.isPowered();
boolean isReady = status.isReady();
String statusMessage = status.getStatusMessage();

Error Handling

NexusException

Unified exception class for all hardware errors.

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

Typical Error Scenarios

Connection errors: USB port not available, driver issues
Communication timeout: Hardware not responding (2s timeout)
Parameter validation: Invalid GPIO/LED parameters
Hardware errors: Peripheral not accessible

Deployment

System Requirements

Java 11+ Runtime (compiled with Java 11)
jSerialComm 2.10.4+ (external dependency)
USB CDC drivers (usually automatic)
Nexus 3.x hardware (VID: 0x0483, PID: 0x374B)

Linux-Specific Configuration

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Re-login required or:
newgrp dialout

# Port discovery
dmesg | grep tty
# or
ls /dev/ttyUSB*

Windows-Specific Configuration

# Port discovery via Device Manager
# or PowerShell:
Get-WmiObject -Class Win32_SerialPort | Select-Object Name,DeviceID