Page is loading ...
INSTALLATION GUIDE
ProBase Store 1
Installing JavaPOS™ and CPOS on Linux
January 2023
Systems Group Retail Products 3
Revision history
Version
Date
Author
Comment/Change
1.0
Nov. 2019
Mathias Janke
1st version
2.0
Nov. 2019
Mathias Janke
Typos corrected
3.0
Mar. 2020
Mathias Janke
Typos corrected; synchronized with user manual
4.0
April 2020
Denis Kuniß
Version corresponding to ProBase Store 1.1
5.0
Oct. 2020
Mathias Janke
Version corresponding to ProBase Store 1.2
6.0
April 2021
Mathias Janke
Version corresponding to ProBase Store 1.3
7.0
Dec. 2021
Denis Kuniß
Version corresponding to ProBase Store 1.4
8.0
April 2022
Denis Kuniß
Version corresponding to ProBase Store 1.5
9.0
Aug. 2022
Mathias Janke
Version corresponding to ProBase Store 1.6
10.0
Jan. 2023
Mathias Janke
Version corresponding to ProBase Store 1.7
Systems Group Retail Products 4
Contents
Introduction ........................................................................................................... 5
Installation ............................................................................................................. 6
Product installer variants ........................................................................................................... 6
Installation requirements .......................................................................................................... 6
Minimum precondition .................................................................................................................. 6
Supported Java Runtime Environments ........................................................................................ 6
Supported operating systems ........................................................................................................ 7
Package installation ................................................................................................................... 7
Update installation ..................................................................................................................... 7
Upgrade installation ................................................................................................................... 7
Uninstallation ......................................................................................................... 9
Logging ................................................................................................................. 11
Installation log .......................................................................................................................... 11
Uninstallation log ..................................................................................................................... 11
Configuration ....................................................................................................... 12
JavaPOS configuration ............................................................................................................. 12
Java VM configuration ............................................................................................................. 13
CPOS configuration .................................................................................................................. 13
UDM configuration .................................................................................................................. 13
UDM server configuration ........................................................................................................... 13
UDM client configuration for CPOS ............................................................................................. 14
D&S Platform T/SOP configuration .......................................................................................... 14
Verifying the installed configuration .................................................................... 15
Verifying the JavaPOS installation ........................................................................................... 15
Frequently asked questions (FAQs) ...................................................................... 17
Systems Group Retail Products 5
Introduction
ProBase Store 1 provides implementations for all programming platforms defined by the international
standard UnifiedPOS
1
. These are JavaPOS, OPOS, and POS for .NET. Additionally, an implementation
for C based applications called CPOS (not standardized in UnifiedPOS) is provided.
The current product installer for Linux operating systems bases on the Red Hat Package Manager
(RPM) and provides the programming platforms JavaPOS and CPOS only. RPM packages do not
provide an interactive installation mode and therefore the setup cannot be customized to user demands.
Instead of this, the product installer will always install the complete content, but not every installed
service or daemon will be configured to start automatically afterwards.
Internally, the product is organized in components. The product installer will ensure that all components
needed for the default programming platform JavaPOS are installed and configured. All dependencies to
other packages will be checked and if possible, solved by the RPM itself.
1
https://nrf.com/resources/retail-technology-standards/unifiedpos
Systems Group Retail Products 6
Installation
The ProBase Store product installer can run in silent mode but not in interactive mode.
Product installer variants
The installer are available as 32-bit (i386) and 64-bit (x86_64) versions for the WNLPOS operating
systems. The installer variants (32 or 64-bit) are based on the process architecture of the application
respectively on the Java Virtual Machine (Java VM) architecture to be used. This means that e.g., when
using a 32-bit application / Java VM on a 64-bit operating system, the 32-bit ProBase Store installer
needs to be used anyway.
The provided product installers follow the naming scheme:
• dn-probase-store.MAJOR.MINOR.BUILD-x86_64.exe
• dn-probase-store.MAJOR.MINOR.BUILD-i386.exe
Example:
dn-probase-store-1.7.32-x86_64.rpm
Installation requirements
The conditions described in this chapter apply to the installation process only. The requirements at
runtime, such as additional system drivers for the devices to be addressed, can be found within the
ProBase Store user manual or release notes
2
.
Note: The installation of ProBase Store requires root permissions.
Note: ProBase Store, as the successor to ProBase POS and ProBase Retail, conflicts with these
predecessors, which must be uninstalled in advance. For more details regarding the migration of
an older DN Middleware product to ProBase Store, please refer to the ProBase Store migration
guide.
Minimum precondition
The following software must already be installed on the target computer to run the ProBase Store setup
successfully:
• Java Virtual Machine (version 8)
For further information, see chapter Supported Java Runtime Environments.
Supported Java Runtime Environments
The installation of ProBase Store supports the following Java runtime environments (JRE):
• Oracle JRE (version 8)
• OpenJDK (version 8, 11)
2
provided with each ProBase Store version; to be found within the ProBase Store installation directory
Systems Group Retail Products 7
Note: All Diebold Nixdorf Linux pre-installations provide sufficient Java VM packages for ProBase
Store.
Supported operating systems
ProBase Store 1 supports and is released for the following Linux based operating systems:
• WNLPOS 3 (i386)
• WNLPOS 4 (i386/x86_64)
Package installation
The current ProBase Store installer is based on the RPM Package Manager, which is common on “Red
Hat”-based operating systems. Please note that RPM does not natively support an interactive user
mode.
The installation of ProBase Store can normally be started from the desktop with a double click on the
installation package or from the terminal console by using of the following command:
rpm -ihv dn-probase-store-<version number>-<architecture>.rpm
Example:
rpm -ihv dn-probase-store-1.7.32-x86_64.rpm
After the RPM Package Manager has solved all dependencies, the ProBase Store 1 components are
installed. The installation progress and further information will be displayed on the console or the
progress window.
Note: The product installer will always install the complete content including the Diagnostic and
Serviceability platform tool T/SOP, the Unified Device Manager (UDM) server and UDM C-client
with the CPOS API. To use the UDM server, CPOS and T/SOP, further configurations are
required.
Update installation
An already installed ProBase Store may be updated with a newer version as long as the major version
number between installed version and update does not differ.
The update can be done with the following command within a terminal console:
rpm –Uhv dn-probase-store-1.<minor version>.<build number>-
<architecture>.rpm
Note: Since ProBase Store strictly separates the installation files from user data, all customer-specific
configuration files (javapos.config.properties) are preserved. However, the derived JavaPOS
configuration will be updated by calling the JavaPOS Configurator as recommended after
changing the software components.
Upgrade installation
There is no upgrade mechanism for older Middleware installations like JavaPOS 1.7, ProBase POS or
ProBase Retail available. Therefore, it is recommended to remove all these preceding DN Middleware
versions before the installation of ProBase Store 1.x.
Systems Group Retail Products 8
For more details regarding the migration from a previous DN Middleware product to ProBase Store,
please refer to the ProBase Store migration guide.
Systems Group Retail Products 9
Uninstallation
In order to uninstall ProBase Store 1, the RPM Package Manager is used as in the installation. The
following command on the terminal console deletes all installed ProBase Store components and
services, even if they have been modified subsequently:
rpm –e dn-probase-store-1.<minor version>.<build number>-<architecture>
or
rpm –e dn-probase-store
Example:
rpm –e dn-probase-store-1.7.32-x86_64
WNLPOS 4
On WNLPOS 4 the system tool Software at Applications > System Tools can also be used to remove
ProBase Store. Search for the packages containing dn-pro, uncheck the ProBase Store package and
apply these changes to remove the ProBase Store package.
Figure 1: WNLPOS 4 system tool - Software
WNLPOS 3
On WNLPOS 3 the system tool is called Add/Remove Software and can be found under System >
Administration. Search for the packages containing dn-pro, uncheck the ProBase Store package and
apply these changes to remove the ProBase Store package.
Systems Group Retail Products 10
Figure 2: WNLPOS 3 system tool - Add/Remove Software
Systems Group Retail Products 11
Logging
Installation log
The current ProBase Store installer is based on RPM Package Manager, which does not provide
additional options to log the installer activities separately. All activities of the RPM package will be
registered within the /var/lib/rpm database. This database can be queried at any time and the output can
be formatted as needed and be saved to a dedicated file.
Note: As post installation action, the JavaPOS Configurator will be started to create an initial
configuration. This JavaPOS Configurator run will also be logged. The log files for the JavaPOS
Configurator are stored within /var/log/wn/javapos.
Uninstallation log
Like the installation, the uninstallation has the same logging mechanism. All activities of the ProBase
Store RPM package are registered or de-registered within the /var/lib/rpm database.
Systems Group Retail Products 12
Configuration
This chapter provides only some basic information regarding the configuration of ProBase Store. For
more details regarding the configuration, please refer to the related subsections within the ProBase
Store user guide.
JavaPOS configuration
ProBase Store provides an automated JavaPOS configuration generation to make integration with
JavaPOS applications easier and more convenient as well as to ensure that ProBase Store updates
become visible to the application environments immediately after the installation and restarting the
application. The automatic configuration is performed by the JavaPOS Configurator provided by
ProBase Store.
The JavaPOS Configurator is a small Java program that lists all JavaPOS files and paths, analyzes all
XML files (JavaPOS configuration files, peripheral configuration files), and generates the combined
JavaPOS system configuration jpos.xml and the file setenv.sh to set all necessary environment
variables.
At the end of the installation process of ProBase Store 1, the JavaPOS Configurator is automatically
started to generate an initial configuration for JavaPOS.
With config_javapos_startup.sh contained in the directory <ProBase Store installation directory>/bin, the
JavaPOS Configurator can be started manually, but must be executed with root privileges to write the
configuration successfully.
Note: If additional packages like ProBase Store add-ons or third party JavaPOS packages have been
installed or the installed packages and/or the customer specific configuration files have been
updated, it is necessary to rerun the JavaPOS Configurator manually.
Note: For this automated JavaPOS configuration generation to work, the involved packages must
follow the DN JavaPOS guideline
3
.
It is possible to customize the output of the JavaPOS Configurator by means of application-specific
configuration files named javapos.config.properties. Such a configuration file shall contain only the
application-specific adaptations that differ from the default configurations of the JavaPOS modules.
These are, for example, adjustments such as the selection of the devices used, the necessary COM port
settings for the RS232 devices if used, or generally all adjustments to JavaPOS configuration
parameters.
This application-specific configuration leads to a separately generated JavaPOS configuration file
jpos.xml.
Due to the JavaPOS configurator and the possibility of application-specific customization, it is not
necessary to change the original XML files in the <ProBase Store installation directory>/xml directory. In
addition, this configuration is maintained through update-installations of ProBase Store. Otherwise, the
changes to the original XML-files would be lost.
3
JavaPOS General Requirements for Linux; Diebold Nixdorf; Peter Duellings; version 1.6
Systems Group Retail Products 13
This customer-specific respectively application-specific configuration is hereinafter referred to as the
target configuration.
At each run, the JavaPOS Configurator checks all available JavaPOS-files (.jar, .xml) and the available
application-based configuration files javapos.config.properties and creates or replaces the existing files
jpos.xml and setenv.sh of the target configuration in /etc/opt/javapos.
Note: For reference and test purposes, the JavaPOS Configurator generates or updates an additional
set of configuration files containing all available JavaPOS devices, which are stored in the
directory /etc/opt/wn/javapos/all. This configuration is hereinafter referred to as the all device
configuration.
Java VM configuration
ProBase Store uses JavaPOS as the basis for all interfaces. Therefore, a Java VM is a runtime
requirement for ProBase Store. For more information regarding the runtime requirements please refer to
the ProBase Store user guide or the release notes.
All with ProBase Store provided Java tools will check whether a Java VM is installed. Afterwards, a
suitable Java VM version will be selected from all available Java VM versions. This requires that the
installed Java VM can be found.
If the installed Java VM cannot be found or to overrule the Java VM search algorithm, it is possible to
explicitly specify the Java VM to be used. To do so, the environment variable JAVAPOS_JAVA_HOME
must be defined.
Note: If the environment variable is defined then the JRE at the path defined by this variable is used
regardless of whether the path points to a valid JRE installation or not.
CPOS configuration
The CPOS interface does not have a separate configuration above the UDM server/client. Here, the
JavaPOS configuration is used.
Note: In order to use CPOS, the Unified Device Manager (UDM) server must be started in advance.
UDM configuration
ProBase Store uses the Unified Device Manager (UDM), a server-client architecture based on sockets,
to be able to provide the CPOS interfaces based on JavaPOS and, on the other hand, to provide a
remote capability. The configuration of the UDM is done on the UDM server side via call parameters at
the start of the UDM server. The CPOS UDM client, however, is configured via environment variables.
UDM server configuration
The UDM server delivered with ProBase Store is already configured and ready to use with default
settings for POS systems.
The UDM server can be started manually via udmStartServer.sh to be found under <ProBase Store
installation directory>/bin. The UDM server is then started as a process in the terminal console and can
be terminated by closing the terminal console.
Systems Group Retail Products 14
Alternatively, an UDM server daemon is also included. The UDM server can be started, stopped or
restarted via this service. Furthermore, the status of the service can also be queried. To do this, use the
following command from the terminal console
service wn-udm <start | stop | restart | status>
Example: Start of the UDM servers
service wn-udm start
If necessary, the settings for the UDM server can be changed by modifying the script files
udmStartServer.sh, stored within the directory <ProBase Store installation directory>/bin.
Further information can be found in the UDM User Guide under <ProBase Store installation
directory>/doc or the ProBase Store user guide.
UDM client configuration for CPOS
The UDM client for CPOS is already configured and ready for use with the standard settings for POS
systems.
If necessary, the default settings for the CPOS UDM client can be modified using environment variables.
For further information, please refer to the UDM User Guide under <ProBase Store installation
directory>/doc or refer to the ProBase Store user guide.
D&S Platform T/SOP configuration
The Diagnostics and Serviceability platform offers various setting and configuration parameters, which
are used to vary and control the behavior and the appearance of D&S and T/SOP.
The main parameters for the configuration are in the configuration file config.properties in the directory
<Diagserv installation directory>\configuration.
Note: The <Diagserv installation directory> is currently defined as /opt/dn/diagserv.
For more information, see the Diagnostics and Serviceability Platform Integration Manual with
INTEGRATIONMANUAL.pdf at <Diagserv installation directory>/doc.
Systems Group Retail Products 15
Verifying the installed configuration
Verifying the JavaPOS installation
The JavaPOS installation comes with a set of tools bunched by a graphical wrapper called JavaPOS
Tool Center. The JavaPOS Tool Center can be started with start_probaseToolCenter.sh located in the
directory <ProBase Store installation directory>/bin. It can also be started via the desktop icon called
JPOS Tool Center.
The JavaPOS Tool Center is then presented as follows:
Figure 3: Welcome screen of JavaPOS Tool Center
The most important functions/tools for verifying the JavaPOS installation would be:
• SwingSamples
• Toggle JavaPOS Configuration
Systems Group Retail Products 16
Toggle JavaPOS configuration
The Toggle JavaPOS configuration () button switches between the JavaPOS configurations all device
configuration and target configuration. The JavaPOS configuration selected is then loaded and all tools
started by the ToolCenter will then be restarted with the new configuration.
The JavaPOS configuration used by the POS application is not affected.
Note: When starting the ProBase Tool Center, the configuration “all devices” will be loaded as default
configuration.
SwingSamples
The tool JavaPOS SwingSamples is a basic test tool to test and visualize the basic communication as
well as class-specific basic methods with the peripheral devices via JavaPOS. The most important
UnifiedPOS properties, methods and events are used here.
Note: This tool does not claim to be a complete implementation of the UnifiedPOS specification.
A click to the button [SwingSamples] will start an interactive Java program for testing the access to and
some basic functions of the perihperals. It allows to select a category and an open name, to configure
the port and exposes the JavaPOS API as graphical interface.
Figure 4: JavaPOS Swing Samples
Systems Group Retail Products 17
Frequently asked questions (FAQs)
Q: I have a problem that I cannot solve by myself. Where can I get help?
A: Please contact our GSE team per email to retailswsuppo[email protected]m and append a
description about your hardware and software configuration as well as all of the created log files.
See chapter Logging for details if you are not sure where to find them. Providing all the log files is
important for solving your problem as quickly and accurately as possible.
Q: The installation finished successfully, but when trying to communicate with a device under
CPOS, I always get errors like “ERROR: cannot open XXX (device) – ResultCode = NO EXIST”.
What can I do?
A: Most probably, there is no Java VM present. Please install a Java VM (see chapter Minimum
precondition for the details), uninstall the product and then install it again.
/
