Quickstart

This page configures SDS JavaPOS after Installation. The full sequence is:

Install Java 8 or later.
Download SDS JavaPOS and place the required JAR files under the SupportJars directory.
Configure the dls.properties and jpos.xml files with the SSL/TLS settings and the JavaPOS device registry.
Launch the application as described in Applying Standard JavaPOS Tutorial.

SSL/TLS Configuration

Certificate Setup

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

A ca.crt certificate file
A client PKCS#12 file

Generating Client PKCS#12 File

Use the following OpenSSL command to generate the client PKCS#12 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.properties 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	`<your-p12-password>`

Example Configuration:

TrustedCACrtFile=path/to/ca.crt
TrustedClientP12File=path/to/client.p12
TrustedClientP12PWD=<your-p12-password>

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 is not required but settings are present: Regular HTTP connection will fail, resulting in Claim device action failure

warning

Ensure dls.properties 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 the AladdinSDS communication; it identifies the scanner.

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.14"/>
  <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="portName" type="String" value="1"/>
  <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="<your-scanner-serial>"/>
  <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 three settings are specific to SDS and critical for proper operation. The portName property of the Datalogic JavaPOS framework is also required, see below.

deviceBus

Value: SDS-COM for a scanner on the USB-COM interface, SDS-OEM for a scanner on the USB-OEM interface, see deviceBus.

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"/>

ipAddress

Value: The AladdinSDS IP address (typically 127.0.0.1)

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

ipPort

Value: 9000 by default

This is the port number that AladdinSDS listens on.

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

portName

portName names the serial port of the device: a COM port number on Windows, a device path on Linux. With USB-COM and virtual port mapping the value is ignored, but the property must be present. See portName and the JPOS Device Registry Reference.

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 AladdinSDS 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 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.properties is defined properly, the Label Reader Tutorial and Barcode Reader Example will work the same for SDS JavaPOS.

SSL/TLS Configuration​

Certificate Setup​

Generating Client PKCS#12 File​

dls.properties Configuration​

SSL/TLS Connection Behavior​

JPOS Device Registry Configuration​

Overview​

Example Configuration​

Critical Settings​

deviceBus​

ipAddress​

ipPort​

portName​

Required Libraries​

Support JAR Files​

Applying Standard JavaPOS Tutorial​