Skip to main content

Configuration

Configuration Files​

There are two configuration files that require additional information for SDS JavaPOS to function:

  1. dls.properties - Device and connection settings, see dls.properties Reference

  2. jpos.xml - JavaPOS device registry, see JPOS Device Registry Reference.

dls.properties configuration​

When Datalogic Connect requires SSL/TLS communication, three additional key-value pairs must be defined in the dls.properties file. When SDS JavaPOS uses HTTPS and secure WebSocket connections, you will need:

A CA certificate (ca.crt) A client PKCS#12 file (which can be generated using openssl)

Example Configuration:

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

Always use full paths for the CA and PKCS#12 files to ensure SDS JavaPOS can locate them correctly.

If these three key-value pairs are missing or incorrectly configured, SDS JavaPOS will fall back to HTTP and regular WebSocket connections.

  • If AladdinSDS requires SSL/TLS and these settings are incorrect, the Claim device action will fail.
  • If one or both certificate files are missing or corrupted, the Claim device action will fail.
  • If the password is incorrect, the Claim device action will fail.

Conversely, if SDS does not require SSL/TLS but these settings are present and both certificate files exist, the regular http:// connection will fail, resulting in a Claim device failure.

Important: Ensure that dls.properties contains accurate and valid configuration details.

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.

The openssl utility would prompt for a password input to generate this client.p12 file. Since Datalogic JavaPOS framework requires Java Platform as Java 8, the option, ‘-legacy’ is required. Without this option, JavaPOS won’t be able to load the client.p12 file for authentication.

There are also three key / value pairs that are configurable in the dls.properties file. These are TrustedCACrtFile, TrustedClientP12File, and TrustedClientP12PWD.

It’s recommended to provide the full path of ca.crt, p12 file so SDS JavaPOS can find the files easily.

JPOS Device Registry Reference​

The JavaPOS device registry is utilized by the OMG JavaPOS Reference (JPOS) and by Datalogic JavaPOS framework, see https://datalogic.github.io/javapos/configref/jposxml/. Below is an example of JPOS device registry for SDS communication, with a logicName of DL-Gryphon-D4300-SDS-USB-COM-Scanner. It targets the handheld device DL-Gryphon-D4300 with USB COM interface. A new JposEntry Element, serialNumber, is introduced in this JPOS device registry.

Critical Property pairs​

Most property pairs for the SDS JPOS Device Registry are generic, and already defined in Datalogic JavaPOS framework. There are three important property pairs which are specific. Any incorrect value of these three pairs will result in failure. These three pairs are deviceBus, ipAddress, and ipPort. In additional, there are three pairs are defined in Datalogic JavaPOS framework, and are crucial for SDS usage.

deviceBus​

It’s essential to set the value of the JposEntry Element, deviceBus, to be SDS-COM or SDS-OEM. With ‘SDS-COM’ or ‘SDS-OEM’, SDS JavaPOS will be able to set up the correct transport to createPort and the correct scanner.

when the scanner is set to USB-COM interface, the value of deviceBUS needs to be SDS-COM

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

or when the scanner is set to USB-OEM interface, the value of deviceBUS needs to be SDS-OEM

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

ipAddress​

Here, the value of ipAddress is the Aladdin SDS ip address. Usually the value is the localhost or 127.0.01.

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

or

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

ipPort​

The value of ipPort must be 9000. It contains the port number that Aladdin SDS uses.

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

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

useVirtualPort​

note

Windows only, USB COM interface only

The useVirtualPort property is used to denote whether to use the Datalogic USB-COM driver assiged virtual COM port for communication with the device. Setting this property to True will result in JavaPOS searching the Windows Registry for the location of the virtual COM port assigned to the device. The type attribute is always set to String and the value attribute may contain either True or False. The default value is False.

JPOS Device Registry Example​

    <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"/>
        <!--Other non JavaPOS required property (mostly vendor properties and bus specific properties i.e. RS232 )-->
        <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="localhost"/>
        <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="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>