Quickstart

1. Install Java 8 or higher version.
2. Download SDS JavaPOS and place required JAR files under SupportJars directory.
3. Configure dls.properties and jpos.xml files with correct SSL/TLS configuration and JavaPOS device registry.
4. Launch the application using the SDS JavaPOS integration steps.

SSL/TLS Configuration

Certificate Setup

When AladdinSDS requires SSL/TLS communication (HTTPS and secure WebSocket), you need:

• A ca.crt certificate file
• A client PKCS12 file

Generating Client PKCS12 File

Use the following OpenSSL command to generate the client PKCS12 file:

openssl pkcs12 -export \
  -in client.crt \
  -inkey client.key \
  -certfile ca.crt \
  -out client.p12 \
  -name "client" \
  -legacy

note

The -legacy option is required for Java 8 compatibility. Without it, JavaPOS won't be able to load the client.p12 file for authentication.

The OpenSSL utility will prompt for a password to secure the client.p12 file.

dls.properties Configuration

Configure the following three settings in the dls.settings file:

Setting	Description	Example
TrustedCACrtFile	Full path to the CA certificate file	path/to/ca.crt
TrustedClientP12File	Full path to the client P12 file	path/to/client.p12
TrustedClientP12PWD	Password for the P12 file	what_ever_passwd_123

Example Configuration:

TrustedCACrtFile=path/to/ca.crt
TrustedClientP12File=path/to/client.p12
TrustedClientP12PWD=what_ever_passwd_123

tip

Use full paths for CA and P12 files to ensure SDS JavaPOS can locate them easily.

SSL/TLS Connection Behavior

• If settings are missing or incomplete: SDS JavaPOS will use HTTP and regular WebSocket connections
• If settings are configured incorrectly: The 'Claim' device action will fail
• If certificate files don't exist or are corrupted: The 'Claim' device action will fail
• If password is incorrect: The 'Claim' device action will fail
• If SSL/TLS not required but settings are present: Regular HTTP connection will fail, resulting in 'Claim' device action failure

warning

Ensure dls.settings contains correct information for all settings to avoid connection failures.

JPOS Device Registry Configuration

Overview

The JavaPOS device registry is utilized by both the OMG JavaPOS Reference (JPOS) and the Datalogic JavaPOS framework (see documentation). A new JposEntry Element called serialNumber is introduced for SDS communication.

Example Configuration

Below is an example JPOS device registry for SDS communication targeting a DL-Gryphon-D4300 device with USB COM interface:

<JposEntry logicalName="DL-Gryphon-D4300-SDS-USB-COM-Scanner">
  <creation
    factoryClass="com.dls.jpos.service.DLSScannerInstanceFactory"
    serviceClass="com.dls.jpos.service.DLSScannerService"/>

  <vendor name="Datalogic ADC Inc." url="http://www.adc.datalogic.com"/>
  <jpos category="Scanner" version="1.13"/>
  <product
    description="ScannerService"
    name="ScannerService"
    url="http://www.adc.datalogic.com"/>

  <!-- Vendor and bus-specific settings -->
  <prop name="baudRate" type="String" value="9600"/>
  <prop name="canAcceptConfigItems" type="String" value="True"/>
  <prop name="canAcceptStatisticsCmd" type="String" value="True"/>
  <prop name="canCompareFirmwareVersion" type="String" value="True"/>
  <prop name="canNotifyPowerChange" type="String" value="True"/>
  <prop name="canUpdateFirmware" type="String" value="True"/>
  <prop name="dataBits" type="String" value="8"/>
  <prop name="decodeData" type="String" value="False"/>
  <prop name="decodeType" type="String" value="standard"/>
  <prop name="deviceBus" type="String" value="SDS-COM"/>
  <prop name="deviceClass" type="String" value="RS232Scanner"/>
  <prop name="deviceDescription" type="String" value="DL-Gryphon-D4300-USB-COM Scanner"/>
  <prop name="deviceName" type="String" value="DL-Gryphon-D4300-USB-COM Scanner"/>
  <prop name="flowControl" type="String" value="None"/>
  <prop name="fullDisable" type="String" value="False"/>
  <prop name="ipAddress" type="String" value="127.0.0.1"/>
  <prop name="ipPort" type="String" value="9000"/>
  <prop name="parity" type="String" value="None"/>
  <prop name="rxPrefix" type="String" value="0"/>
  <prop name="rxTrailer" type="String" value="d"/>
  <prop name="serialNumber" type="String" value=""/>
  <prop name="singleCable" type="String" value="False"/>
  <prop name="stopBits" type="String" value="1"/>
  <prop name="usage" type="String" value="0"/>
  <prop name="useCOMxOnLinux" type="String" value="False"/>
  <prop name="useSunJavaxComm" type="String" value="True"/>
  <prop name="useVirtualPort" type="String" value="True"/>
  <prop name="WMIEnabled" type="String" value="False"/>
</JposEntry>

Critical Settings

The following four settings are specific to SDS and critical for proper operation:

1. deviceBus

Value must be: SDS-COM

This setting enables SDS JavaPOS to set up the correct transport and connect to the correct scanner.

<prop name="deviceBus" type="String" value="SDS-COM"/>

2. ipAddress

Value: The Aladdin SDS IP address (typically localhost)

<prop name="ipAddress" type="String" value="127.0.0.1"/>

3. ipPort

Value must be: 9000

This is the port number that Aladdin SDS uses for communication.

<prop name="ipPort" type="String" value="9000"/>

4. portName

The portName property is used to denote the serial port to attach to a device. Depending on the host operating system, this property may indicate a numeric port, a COM port or a physical path to a device mapped serial port. The type attribute is always set to String and the value attribute is set to either a COM port number, a COM port specification, or a device path to a serial port. When using USB-COM and virtual port mapping, the value attribute is ignored. The default value is 1 for COM1.

for Windows:

<prop name="portName" type="String" value="1"/>

for Linux/Ubuntu:

<prop name="portName" type="String" value="/dev/ttyS0"/>

Required Libraries

Support JAR Files

To successfully communicate with SDS through SDS JavaPOS, eight JAR files are included in the SupportJars directory:

• gson-2.8.6.jar
• kotlin-stdlib-1.9.0.jar
• kotlin-stdlib-common-1.9.0.jar
• kotlin-stdlib-jdk7-1.9.0.jar
• kotlin-stdlib-jdk8-1.9.0.jar
• okhttp-4.12.0.jar
• okio-3.6.0.jar
• okio-jvm-3.6.0.jar

These libraries provide support for HTTP, HTTPS, WebSocket (ws://), and secure WebSocket (wss://) connections, requests, and responses.

Applying Standard JavaPOS Tutorial

The standard JavaPOS tutorial at https://datalogic.github.io/javapos/develop/tutorial can be applied to SDS JavaPOS with one key difference:

Use the profile: DL-Gryphon-D4300-SDS-USB-COM-Scanner from jpos.xml

Or use a modified profile: DL-<your own scanner device>-SDS-USB-COM-Scanner

As long as the important settings are provided correctly and dls.settings are defined properly, the Label Reader Tutorial and Barcode Reader Example will work the same for SDS JavaPOS.