Page 1
Quick Start
Guide
Applies to software version 1.4.0 or higher
Last change: 07.09.2015
Author: Kurt Haller-Walzl
Page 2
Quick Start Guide imagotag GmbH
[Introduction] 4
1 Electronic Shelf Labeling – A brief introduction 4
2 The G1 label family 5
2.1 Key Features 5
3 What’s in your Smart Box? 6
[Getting Started] 7
1 Latest Software and Documentation 7
2 Install software 7
2.1 System requirements 7
2.2 Installation process 7
2.3 Customer Portal 9
3 Start Server and Client 10
3.1 Starting ESLServer 10
3.2 Starting ESLClient 11
3.3 Activating License 12
4 Connect and configure Access Point AP-2010 14
4.1 Connect and configure 14
4.2 Necessary configuration over the AP-2010 web management interface 15
4.3 Necessary configuration at the ESL Client 16
4.4 Selecting channels 17
4.5 The Status LED 17
5 Setup Security 18
5.1 General encryption features and how does it work 18
5.2 Set the encryption key 18
6 Register labels 19
6.1 General procedure 19
6.2 What's on the label? 19
6.3 Handheld terminals, USB barcode scanner and iOS-App 21
6.4 Encryption status 21
6.5 Unlocking labels 22
7 Start tagging 23
7.1 What can I do now? 23
7.2 Sending pictures to labels 23
7.3 Article management 24
7.4 Matchings 24
7.5 Set filters for enums 26
Page 2 of 36
Page 3
Quick Start Guide imagotag GmbH
7.5 Templates 27
8 Integration 31
8.1 Webservice integration 31
8.2 Plugins 31
8.3 Custom integration 31
[Troubleshooting] 32
1 FAQ 32
1.1 Running the ESLServer as a background service 33
1.2 Where can I find the license file for my SmartBox? 33
1.3 Deleting the demo articles 33
1.4 Establish a network configuration when no DHCP is available – Step by step 33
1.5 AP discovering with Bonjour Services 34
1.6 What can I do if the Status LED of the AP-2010 access point doesn’t turn blue? 34
1.7 Labels don’t come online 34
1.8 The encryption does not work 35
1.9 Unlocking labels 35
1.10 Starting Java applications 35
1.11 Encoding problems 36
1.12 Further documentation 36
Page 3 of 36
Page 4
Quick Start Guide imagotag GmbH
[Introduction]
1 Electronic Shelf Labeling – A brief introduction
An electronic shelf label is a device that shows article data and price information on its display. In
comparison to printed labels the information is automatically updated if price or article data
changes.
l Cost reduction through elimination
of manual price changes
l Fully automatic price updates from
the headquarters to the branch
stores within seconds
l Process security and price integ-
rity – 100% correlation between
cash point and shelf
l Increased flexibility in price design
and immediate reaction to market
situation Image gain due to use of
highly modern technology
l Simplified processes for store per-
sonnel
l Enhanced sales & price prof-
itability maximize price performance and profit opportunities
FIGURE 1-1: Electronic Shelf Labeling
Page 4 of 36
Page 5
Quick Start Guide imagotag GmbH
2 The G1 label family
The imago G1 electronic shelf label family offers high-quality display options, operating with a
replaceable battery and thus working with any external power supply. The G1 red family is
capable of changing all pixels to black, white or red.
The current line-up has display sizes from 2 inch to 7.4 inch. They may be used in landscape and
portrait mode and can be customized with changeable front covers.
(missing or bad snippet)
2.1 Key Features
l 2.4 GHz bi-directional MSK proprietary radio
l Radio coverage: up to 25 meters
l Return Signal: yes
l 11 available communication channels
l Ultra-low power consumption
l Customer-replaceable battery
l Full graphical e-Ink display with paper-like readability
l Changeable and customizable front covers
l Super wide viewing angle (nearly 180 degrees)
l Flexible mounting options available
l May be used in landscape and portrait mode
l Fast response time (less than 15 seconds)
l Water resistant
l 128-bit AES encryption with secure key exchange
l Multiple pages support with preloading and fast page switching
l Integrated NFCtag as an option
Page 5 of 36
Page 6
Quick Start Guide imagotag GmbH
3 What’s in your Smart Box?
l
2x G1 2.7 Labels / 1x G1 4.4 Label
o
The G1 electronic shelf label family offers high-quality display options, operating
with a replaceable battery and thus working with any external power supply. Thanks
to the perfect readability of the e-Ink displays and our outstanding wireless data
transmission technology you can implement all your sales, marketing, and logistic
strategies.
l
1x Access Point AP-2010 incl. Antenna
o
The AP-2010 by imagotag is the communication center in the store that transmits
price information to the labels. Up to 10 000 labels can be managed per access
point and the self-organizing network allows automatic roaming of labels without
manual handling. It supports 11 selectable ESLchannels.
l
1x Installation Guide with USB Stick
o
ESLServer: The ESLServer is a Java software that is required to manage the imag-
otag access points and electronic shelf labels.
o
ESLClient: The ESLClient is also Java based software. It’s a graphical user interface
(GUI) for monitoring and for the configuration of the ESLServer. The ESLClient con-
nects to the ESLClient. The server may be installed on the same machine or any
other machine that is accessible over the network.
o
Template Editor: To render images from article records on the ESLServer, the layout
must be predefined in a template file. Therefor an editor to create and edit template
files with live preview based on example records is also on the imagotag USB stick.
o
Other documentation: Developer Reference, Image Rendering Reference and
CSV/XML Import Plugin
l
1x Mounting Plate
o
Metal Mounting Plate for Mounting the AP-2010 on Walls, Ceilings or other MountingRails.
l
2x Caddy Clips
o
With our system you’re able to mount your labels almost wherever you want.
l
1x Power Plug
o
Power Plug to supply power for the AP-2010 (Power over Ethernet is also available).
Page 6 of 36
Page 7
Quick Start Guide imagotag GmbH
[Getting Started]
1 Latest Software and Documentation
At the Customer Portal https://portal.imagotag.com you can view all your shipments, get access
to registration- and unlock codes, check the warranty status of your labels, download your
license files and access the latest software releases and documentation from this site.
2 Install software
There’s several software you’ll have to install in order to configure and setup your ESL system.
You’ll just have to extract the following 3 archives in a location of your choice:
1. ESL Server <server.zip>
2. ESL Client <client.zip>
3. Template Editor <template.zip>
2.1 System requirements
l Server hardware: Pentium 4 (2 GHz or higher), 2 GB RAM
l Java Runtime Environment Version 6, Update 36
l Windows XP, Windows 7, Windows Server 2008 (R2), Suse Enterprise Linux 11, Ubuntu 12
(all 32/64-bit versions)
l imagotag Server/Client applications (2x .zip archives)
l imagotag AP-2010
l imagotag Labels and license files
2.2 Installation process
Please unpack the zip-archives <server.zip>, <client.zip> and <template.zip> on your machine e.g. under C:\imagotag\.
Note: To unpack the zip-files you can either use the windows internal archive-unpacker (see
screenshots) or an unpack tool of your choice (e.g. the free tool 7zip – www.7zip.org).
FIGURE 1-2: Unpack/Install imagotag Software FIGURE 1-3: Unpack/Install imagotag Software #2
Page 7 of 36
Page 8
Quick Start Guide imagotag GmbH
#1
Page 8 of 36
Page 9
Quick Start Guide imagotag GmbH
After unpacking all 3 archives, your folder should look something like this:
FIGURE 1-4: Unpacked imagotag software folder
The imagotag software is now installed and you can step forward to point Start Server and Client
- Start Server and Client.
2.3 Customer Portal
At the Customer Portal you can view all your shipments, get access to registration- and unlock
codes, check the warranty status of your labels, download your license files and access the latest
software releases and documentation from this site.
After user registration and activation you will have access to documentation and you can
activate, manage and download your imagotag software licenses see Activating License on page
12. Your user account will not be assigned to a customer account yet. If assigned, you have
access to all shipments here including lists of label IDs, registration codes and unlock codes. To
get access there must be a completed order and your account needs to be verified (existing
customer account required).
Page 9 of 36
Page 10
Quick Start Guide imagotag GmbH
3 Start Server and Client
3.1 Starting ESLServer
In order to start the ESL Service with the default configuration, just execute the jar file “server.jar”
as described in [Troubleshooting] and wait for the small service GUI to show up (if the window
doesn’t show up after all, make sure your Java installation and configuration is correct).
FIGURE 1-5: ESLServer web management interface
The service will listen to TCP connections on Port 8000 and 8001 and UDP
connections on Port 8000. Please make sure that there is no firewall issue
and/or interference with other systems.
After start of the service you can check the web-GUI of the server:
URL: http://<host|ip>:8000
Login: admin/admin
During the first start the ESLServer will automatically create a Derby1database. If another
database connection is needed or preferred, the connection parameters should be validated by
imagotag.
Note: As you can see there are several level numbers, by default the server instance will start in
level 3. You can find the description of the different levels in the Developer Reference (which is
also available at the Customer Portal) under “Integration Levels”.
3.1.1 Example articles
For easier usage some example articles can be preloaded at the time you start the ESLServer.
You can find the corresponding XMLarticle data here: C:\imagotag\server\data\fixtures\.
To enable and disable the preloading of these fixtures go to the system configuration and set the
corresponding property "importFixtures"true or false.
Note: The article records are based on the XML-standard.
Page 10 of 36
1
Apache Derby, an Apache DB subproject, is an open source relational database implemented entirely in
Java
Page 11
Quick Start Guide imagotag GmbH
3.2 Starting ESLClient
Go to the extracted client directory and execute the “client.jar” file.
FIGURE 1-6: Starting ESL Client
The client is configured to connect to a server on the local machine per default. In order to
change this to a remote machine in a network you have to start the client with an additional
parameter:
Windows
l Create a shortcut/Edit existing short cut
l Append “ --host hostnameOrIPAddress” at the end of the “Target” field. (Note: The text to
append starts with an space and there are 2 hyphens to add!)
Linux
l Append “ --host hostnameOrIPAddress” at the end of command (e.g. “java -jar client.jar -
-host 192.168.1.100” Note: The text to append starts with an space and there are 2
hyphens to add!)
FIGURE 1-7: Starting ESL Client with parameter
Page 11 of 36
Page 12
Quick Start Guide imagotag GmbH
3.2.1 ESLClient Login
l Username: admin
l Password: admin
FIGURE 1-8: ESLClient Login
3.3 Activating License
After starting the ESLServer and Client it's necessary to activate the license which is included in
the "Software License Document". To view your current license status there's a License status
dialog. You can find it in the ESLClient under "Help - License status". Since no license is
activated/imported yet the window should look similar to this:
FIGURE 1-9: License Status Dialog
Copy the "System serial" to the clipboard and then click the "License activation". You'll be
automatically redirected to the imagotag Customer Portal https://portal.imagotag.com.
Please log in (or register a new user). After log in, you can see a summary of already activated
licenses and / or activate a new license. Click "activate new license".
Fill in "License key", copy/paste the "System serial"(from the "License Status"dialog), add a
Comment (optional) and click the "Activate"button.
Page 12 of 36
Page 13
Quick Start Guide imagotag GmbH
FIGURE 1-10: Activate License (imagotag Customer Center)
Download the generated license file and complete the licensing process by importing the license
file to your ESLsystem. With the successful activation of your SmartBox demo license you're
now able to register and use up to five labels and one access point.
FIGURE 1-11: Import of license file downloaded before
Note: Press "F5"(after 15 seconds) to update the license status after license file import.
Page 13 of 36
Page 14
Quick Start Guide imagotag GmbH
4 Connect and configure Access Point AP-2010
The AP-2010 by imagotag is the communication center in the store that transmits price
information to the labels. In order to ensure the communication between ESLServer, access
point AP-2010 and the labels the access point has to be configured at the start of the
ESLServer.
One way to configure the access point is on the client.
FIGURE 1-12: ESL Client Access Point Configuration
4.1 Connect and configure
Before labels are able to communication with the server at least one access point needs to be
configured. In standard configuration the AP-2010 should get an IP-address via DHCP
(recommended) and is accessible via imagotag AP-2010 web management interface:
URL: http://<host|ip>:8080
Login: admin/admin
Important Note: In this part of the Quick Start Guide it is assumed that a DHCP server is present
(you can find the steps to discover the access point without DHCP in the Troubleshooting
section at points Establish a network configuration when no DHCP is available – Step by step and
AP discovering with Bonjour Services).
Page 14 of 36
Page 15
Quick Start Guide imagotag GmbH
4.1.1 Discover the Access Point
Before you can configure the access point it’s necessary that the server will discover it.
The following points have to be observed:
l Connect your machine to the same network as the AP
l Plug in the power supply of the access point
l During the boot process of the access point, start the ESLServer software on the computer
l When the access point is booted up, the server will discovery it with an IP address (Note:
The discovering process may take up to 2 minutes)
l Use the ESLClient to connect to your ESLServer
l Under System – Access Point Status – the AP should be listed as discovered (after suc-
cessful boot sequence)
l One Column of the AP should show now the IP address
l Now you’re able to configure the access point via AP-2010 web management interface
under http://<DHCP-IP-address> or a right click on the discovered AP –> Open in
browser…
In the status overview you get some details about the AP-2010:
FIGURE 1-13: AP-2010 Status overview
It’s recommended for the demo installation not to use the “Auto-Config” feature and configure
the AP manually.
4.2 Necessary configuration over the AP-2010 web management interface
The following actions need to be performed over the web-GUI
1. Deactivate Auto-Config: Administration -> Auto-Config
2. Set up network details (or leave DHCP): Administration -> Network
3. Set up a wireless channel: Administration -> Wireless
Page 15 of 36
Page 16
Quick Start Guide imagotag GmbH
The AP-2010 supports 11 wireless channels. It’s recommended to choose one of
the recommended channels: 3, 5, 8, 9 or 10. These channels do not interfere with
standard Wi-Fi channels 1, 6, 11 and are scanned by the labels more often For
further information about selecting channels see point Connect and configure
Access Point AP-2010.
4.3 Necessary configuration at the ESL Client
After the configuration in the AP-2010 web management interface it’s necessary to add this AP
via the ESL Client: System – Access Point Configuration – New …
FIGURE 1-14: ESL Client AP configuration - System -> Access Pont Configuration -> New
Choose “Manual Configuration” if you don’t use Auto-Config and enter Access Point ID (AP ID)
and IP address (Host).
Note: After the basic configuration in the AP-2010 web management interface, it is also possible
to fill in AP-ID and AP-IP-Address automatically. For this choose "Create Configuration..." under
System – Access Point Status - Right click on the discovered and configured Access Point.
After saving the AP configuration you should see the AP under System – Access Point Status as
ONLINE. In addition the AP status LED should turn BLUE.
Page 16 of 36
Page 17
Quick Start Guide imagotag GmbH
4.4 Selecting channels
For a working installation a channel must be selected on each access point in the network. There
are 11 non overlapping ESL channels reserved for the communication with the labels. Five of
these channels do not interfere with typical Wi-Fi installations and should therefore be favored.
These are the ESL channels 3, 5, 8, 9 and 10 and they should be selected if there is a Wi-Fi
installation on the Wi-Fi channels 1, 6 and 11.
FIGURE 1-15: Comparison between common used Wi-Fi and ESLchannels
If there is a Wi-Fi installation operating at 2.4 GHz (IEEE 802.11b/g/n) or any other radio
frequency (RF) technology that uses the 2.4 GHz ISM band make sure to select the ESL channels
that are least overlapping with the existing installation. If there is no ESL channel without any
overlapping both the ESL and existing installation should still work but there might be a reduced
overall speed in both installations.
Warning: Do not select the same channel on two access points within one area. This will cause
interferences and avoids labels from joining the network. The same channel may only be selected
on two access points if it can be guaranteed that every label is within the range of only one of
these access points.
4.5 The Status LED
There are several LED colors that indicates the main status of the access point.
Color Description Note
Red
Blue
Yellow
Red (blinking)
If there are any problems regarding the access point please see chapter [Troubleshooting].
Boot process
Normal mode --Operational, but not
connected to any server
or no channel selected
Running Firmware Update
Can take about 2 minutes, if it takes much
longer, the device is defective and there is a
need for service.
---
During this time there is no connection to the
electronic label
Page 17 of 36
Page 18
Quick Start Guide imagotag GmbH
5 Setup Security
The security concept is based on individual registration codes for each label. Not only that the
new concept simplifies installations, it also provides stronger encryption and a secure key
exchange with individual communication key derived from a user defined network key.
5.1 General encryption features and how does it work
l Solid improved safety
l Encrypted data type AES128 (Advanced Encryption Standard)
l User defined 128 bit network key for each installation
l Key is distributed to labels automatically
The new system requires a user defined 128 bit network key for each installation. The key is
derived from a passphrase that is defined by the customer and stored in the ESLServer and used
by all access points connected to that server to encrypt data communication to the labels.
A per-label communication key is transmitted to the labels during the registration of them. Each
label is assigned an individual registration code (it combines label ID and PIN code and it’s an
alphanumeric case-sensitive code with 11 characters). The ESLServer will than automatically
start the key exchange with the label secured by the PIN extracted from the registration code.
5.2 Set the encryption key
First step is to set the parameter “encryptionPassphrase“ under System – Configuration (you can
choose the encryption Passphrase on your own).
FIGURE 1-16: Set encryption key
Note: Do not change encryption passphrase if labels are already connected and encrypted (if
you want to change the encryption passphrase you’ll first have to unlock all labels – see
[Troubleshooting] on page 32).
Page 18 of 36
Page 19
Quick Start Guide imagotag GmbH
6 Register labels
In order that labels can join the network it is necessary to register them first.
6.1 General procedure
Via the ESL Client under File – Register Labels it’s possible to register your labels manually with
the registration code shown on each single label or you could import a CSV file with your
registration codes. In order to refresh the entries press the refresh button shown in the next
figure.
Important Note: After the registration it could last a certain time until all registered labels are
joined to the network (from 30 minutes up to two hours, depending on configured access point
channels). After this you can send images to each label (see Start tagging on page 23).
FIGURE 1-17: Add/Delete Label and refresh entries
6.2 What's on the label?
All labels will arrive with its registration code (11-digit alphanumeric)shown on the display of the
label. The code is printed as a 2D QR code, as a 1D Code128 barcode and as human readable
text. The registration process for the customer is easy – he has only to scan one of this
barcodes. The ESLServer will than automatically start the key exchange with the label secured by
the PIN extracted from the registration code.
The two relevant codes:
1.
The label ID (8-digit hexadecimal) to identify the label (it's also the radio address which is
similar to a MAC address).
2.
The registration code (11-digit alphanumeric) is required to activate the encryption. This
code also contains the label ID and a random PIN code.
Page 19 of 36
Page 20
Quick Start Guide imagotag GmbH
6.2.1 Labels before and after registration
Page Layouts G1 4.4
Layout when shipped
Registration Page Layout
Note:The label ID can only be read and will not be
displayed as barcode in this layout.
Layout after successful registration
Reset Page Layout
Note: After successful registration, the AES key is
exchanged for encryption and the label switch to a page
where only the label ID is displayed as 1D Code128
barcode.
The sticker (on the bottom and on the back) always contain only the label ID and therefore should
not be used for registration. They are only intended for the later article assignment (matching
process).
Here you can see the registration dialog in the ESLClient where one single label has been entered
with the registration code and the other one with the label ID (for old label versions < 3.0.0).
FIGURE 1-18: Register labels dialog (registered with registration code and label ID)
Page 20 of 36
Page 21
Quick Start Guide imagotag GmbH
Note: New versions of the ESLServer, ESLClient and AP-2010 (≥ 1.3.0) will also support old
labels that do not come with a pre-programmed PIN code. New labels (≥ 3.0.0) will also work in
old installations together with old labels but the ESLServer will not accept registration codes
during the registration process. To register the labels it is required to scan the barcode with the
label ID from the backside or the bottom edge of the label. As the server will not start the key
exchange all data is transmitted unencrypted to the labels.
6.3 Handheld terminals, USB barcode scanner and iOS-App
It’s also possible to register labels with a commercial USB barcode scanner (2D/1D). You can
also use our iOS-App (for iPhone and iPod touch, only available on request).
Handheld terminals are mobile devices that are used to manage the ESL installation. If the
handheld provides a barcode scanner, it may be used easily to link articles and labels by
scanning the article barcode (usually EAN, UPC or GTIN) and the unique ID of the label.
Here you can see some screenshots of our iOS-App:
FIGURE 1-19: ESL-App HomeScreen
6.4 Encryption status
Here are the encryption status a label could have:
l
AES: Communication with label is encrypted with 128 bit AES
l
No PIN: Could not set encryption key as no PIN (registration code) was provided
o
Solution: Re-register label with registration code
l
Keyunset: Communication is NOT yet encrypted
o
Solution: Set encryption key as described in section Setup Security - Setup Security
l
Unsupported: Encryption is not supported by label firmware
l
Unknown: Security status is not determined yet
FIGURE 1-20: ESL-App Registration
Page
FIGURE 1-21: ESL-App Matching
Page
Page 21 of 36
Page 22
Quick Start Guide imagotag GmbH
FIGURE 1-22: Encryption status
6.5 Unlocking labels
If the label was registered and a communication key was set it will no longer work in other
networks using a different network key passphrase. To unlock this labels for other networks an
unlock code is required. The unlock code is similar to the registration code - it is a combination
of the label ID and a 128 bit PUK code.
Via ESLClientselect File – Unlock labels and enter the unlock key.
FIGURE 1-23: Unlock Labels Dialog
Note: The unlock-code for the specific labels is enclosed in the Smart Box (in an envelope).
Page 22 of 36
Page 23
Quick Start Guide imagotag GmbH
7 Start tagging
7.1 What can I do now?
As soon as labels are online you can do several things:
l Send image to label
l Assign tags
l Show the current image
l Ping label
l Reset label (reset display to show label ID and label ID barcode)
l Refresh display
l Switch to a preloaded page
l Create a new matching
l Set filters
l …
7.2 Sending pictures to labels
1. Right click on one or more labels -> Send image…
2. Select a picture (Note: Display size must match the resolution of the image)
A. In the right pane, a priority (currently not relevant) could be set for the task, as well as
the Page to which the image should be sent and whether the image is preloaded.
B. When preloading, the image is placed in the memory of the label, but not yet dis-
played. The image change will only be performed after the change to the relevant
page. This allows for each label that images are cached on the various pages and be
accessed quickly by switching to the relevant page.
3. By clicking on “open” the corresponding task(s) for the label(s) will be created and the
transfer begins.
FIGURE 1-24: Send image to label
Page 23 of 36
Page 24
Quick Start Guide imagotag GmbH
7.3 Article management
For complete management of your articles select Articles – All Articles in the ESLClient. Here
you’re able to create/delete and edit your articles.
The Smart Box comes with 4 predefined articles which you can see here. You can add some
more demo articles, edit the existing ones or just step further to the next point Matchings.
FIGURE 1-25: Article management
7.4 Matchings
The logical link between an article and the label that shows the article information and price of
this article is called matching. With a matching the layout of the image rendered for the label is
also defined by specifying the name of a template.
In a more technical way a matching is the triple of:
l Label ID
l Article number or GTIN
l Name of the template file
Note: Only one matching per label is allowed but a single article may be matched to more than
one label.
Select File – New matchings to open the dialog where you can select the desired data records
and create a number of matchings at the same time.
Page 24 of 36
Page 25
Quick Start Guide imagotag GmbH
FIGURE 1-26: New matchings dialog
Another way to create/edit matchings is under “Matchings – All Matchings”:
l
Select the desired data records (Label ID, Article Number) in the following window “New
Matching Record“ (either manually or with the magnifying glass symbol). Select an appro-
priate template via “Template” that should be used to generate the image.
l Confirm your choice by clicking Save. After that, the generated image is sent to the selec-
ted label.
FIGURE 1-27: Create a matching
Page 25 of 36
Page 26
Quick Start Guide imagotag GmbH
It’s also possible to create Matchings with ESLClient under Labels and Articles, for this just select
the desired article or label, right-click on it and select “New matching…” (the new matching
dialog will be pre-filled with the article or label information).
7.5 Set filters for enums
It's possible to set and combine several filters. Click on the drop down menu to see the different
choices.
FIGURE 1-28: ESLClient filter options
7.5.1 Filter options
The following operators are available:
Operator Description
<
>
<=
>=
!
=
:
Less than
Greater than
Less than and equal
Greater than and equal
Negation (Not)
Equals
Defines a range (e.g. RSSIfilter -65:-75 shows all labels with current
RSSIvalue within -65 and -75) Doesn't apply to date and text.
Page 26 of 36
Page 27
Quick Start Guide imagotag GmbH
7.5 Templates
The template is used to specify the fields, which should be rendered into the image. The
ESLServer can handle multiple templates.
7.5.1 General information about templates
The image rendering process is based on XSL (EXtensible Stylesheet Language) templates. The
individual image for the label is then generated by applying the template to a XML, which is
based on the properties of the label and is expanded by a custom XML from the user.
The following steps are executed when processing a template:
l Generating a record XML based on the label/task information and custom information
provided by the user
l Applying the template (XSL) on the generated record XML. This results in a document con-
taining the fields, specified in this reference and values referenced from the XML
l Rendering the image (*.PNG) based on the previous output
FIGURE 1-29: Input and result of the rendering process
7.5.2 Template Editor
In order to use our rendering engine you must know our template language which is basically
XSL. We do also have a Template Editor with live preview, but you need a little bit time to setup
everything and get familiar with it. Therefore we suggest to send pre-rendered images to labels
(right-click on a label -> send image) which you can create with every image manipulation
software you want (e.g. Gimp, Photoshop, Paint, …). You can even take some pre-rendered
images from us for each label type with the correct resolution as a template – you’ll find some in
the client’s directory under data/images.
Page 27 of 36
Page 28
Quick Start Guide imagotag GmbH
7.5.2.1 Starting Template Editor
Navigate to the unpacked template directory (see point Installation process on how to unpack
the software package) and execute the “template.jar” file (see [Troubleshooting] on page 32).
FIGURE 1-30: Starting the Template Editor
7.5.2.2 Open default template-file and load records from server:
l Open the Template Editor by clicking the “template.jar” file located in the template-dir-
ectory (In our example it should be C:\imagotag\teamplate\).
l Next step is to create a new template file or to open an existing one (The default.xsl tem-
plate file is located in the server-directory under C:\imagotag\server\data\template\).
l To get a live preview you’ll have to load some records, in our case we load the demo article
records from our running server, see the following figure.
FIGURE 1-31: Load Records from Server
Page 28 of 36
Page 29
Quick Start Guide imagotag GmbH
After these steps your Template Editor window should look something like this:
FIGURE 1-32: Template Editor with loaded records from server and default.xsl template file
7.5.2.3 Design Mode
You can enable the graphical Template Editor by selecting Settings – Configuration – tick
Enable Design Mode and finally the Save-button.
FIGURE 1-33: Enable Design Mode in Template Editor
Page 29 of 36
Page 30
Quick Start Guide imagotag GmbH
After enabling the Design Mode a new tab will show up.
FIGURE 1-34: Template Editor Design Tab
7.5.2.4 Enable and show color red
As there are new label types which are capable of showing the color "red"there's a short
description how to enable this inside the xsl template file.
l
Optional: Query whether it is a "red" label
l
<xsl:when test="Label/DisplayWidth = XXX and Label/DisplayHeight = XXX
and Label/DisplayColors = 'BLACK_WHITE_RED'">
l Add colors option to image tag:
l
<image width="XXX" height="XXX" colors="true" font-family="XXX">
l Show something in color red, e.g. text:
l
<text font-size="XXX" condense="XXX" font-weight="XXX" color=”red”>
7.5.2.5 Help Content
There’s a link to the Help content for the Template Editor, open it by clicking Help – Help Content
in the Template Editor or open the file index.html located in C:\imagotag\template\help\.
Also you can find further information on the USB Stick under Documentation - Image Rendering
Reference.
Page 30 of 36
Page 31
Quick Start Guide imagotag GmbH
8 Integration
8.1 Webservice integration
The ESL server provides access to its interfaces methods through a RESTful web service API. The
web service is designed according to the “Representational State Transfer” (REST) architectural
pattern.
The ESL server listens for incoming HTTP web service requests on the TCP port 8001 by default.
You can find further information and documentation about the webservice integration online
under https://portal.imagotag.com/get/documentation
8.2 Plugins
We provide several plug ins which are used for importing article information into the ESL Server.
You can find further information and documentation about our integration plug ins online under
https://portal.imagotag.com/get/documentation
8.3 Custom integration
For custom integration we provide a Plugin-Interface. Software development service is available
from imagotag software development team or third-party integration partners.
For pricing get in touch with our sales agents ([email protected]).
Page 31 of 36
Page 32
Quick Start Guide imagotag GmbH
[Troubleshooting]
1 FAQ
If you run into any errors during connecting or sending images to labels, please refer to the
documentation included in the server. This documentation can be found in the AP-2010 web
management interface of the server under “Documentation”.
l For problems updating the labels (error code column in labels window) refer to “Update
Error Codes” or (task status column in labels window) refer to “Task Status”
l For connection status problems refer to “Connection Status”
l For label hardware errors (label error column in labels window) refer to “Label Error Codes”
Code Problem Solution
1 Label not licensed
3 Label not registered
10
11 Error during image rendering Check template (wrong or faulty)
12 Error during image conversion
13 Invalid page
14
20 Template not found Check template directory for missing template file
21 Error during template parsing Correct template file (Invalid content found)
22
30
62
80
92 Task type not supported Upgrade AP software to process this kind of task
Image does not match display
size
Could not process task because
there are unfinished tasks waiting
for this label
Error during content document
creation
Could not send update because
label has insufficient power to
perform the update
HTTP communication error with
the access point
Error while writing task to
database
The label is not licensed. Import the proper license
file for the label or check for typos in the label id.
The label may have been deleted or has never been
registered at all. Register label.
The size of the image does not match the label’s
display size. Please check the width and height of
your image and look up the display size in pixels
for the label. These sizes have to be equal.
Change format of the image to standard format
(e.g. PNG or BMP)
Page not supported by label type, choose a
different page
Abort task or wait until unfinished tasks are
finished
Check server and article record configuration
The power status of the label is “Bad”, which
means it is very low on battery that in may not
accomplish the display update. Replace the battery
of the label.
The server was not able to send the task to the
Access Point. Please make sure that the Access
Point is not offline (System -> Access Point Status)
and there is an established network connection
between Access Point and Server.
Check database connection
Page 32 of 36
Page 33
Quick Start Guide imagotag GmbH
1.1 Running the ESLServer as a background service
The ESL server may be started as a normal application, but on a productive system it is usually
required to have it automatically started without a user logged in. To achieve this the ESL server
can be registered as a Windows service. It is than started automatically without any graphics user
interface.
To install the ESL server as a Windows service the batch file install_service.bat is provided. If this
file is executed with administrator privileges (Right click – Run as Administrator) it will install the
ESL server installation from the same directory as a Windows service with the name ESL_
SERVICE.
The file uninstall_service.bat will remove the Windows service if executed with administrator
privileges.
If you have any problems regarding the background service:
l Check if you have installed the correct JAVAversion corresponding to your system
(x86/x64)
l If the ESLServer is already installed as a Windows service you have to uninstall it first (unin-
stall_service.bat) and reinstall it again (install_service.bat).
1.2 Where can I find the license file for my SmartBox?
You find the license file (which has to be activated at the imagotag Customer Portal enclosed in
the SmartBox in a "License Envelope".
1.3 Deleting the demo articles
In order to prevent the example articles from being re-added to the server, go to "System Configuration"and set the "importFixtures"variable to false.
1.4 Establish a network configuration when no DHCP is available – Step by step
1. Set a laptops Ethernet adapter to DHCP
2. Turn off all other network adapters (Wi-Fi)
3. Connect to the same network as the AP-2010 (use a common Ethernet cable to connect
your device directly with the AP-2010)
4. Start local ESL Server on laptop
5. Use the ESL client to connect to your local server
6. Under System – Access Point Status – the AP should be listed as discovered (after successful boot sequence – may take up to 2 minutes)
l Press F5 on your keyboard or the refresh button in the ESL client to refresh the
access point status (the Client doesn’t refresh the status automatically!)
7. One Column of the AP should now show the IP address
8. Open a browser, type in http://<discovered-ip>:8080 or
l at the ESL client perform a right click on the discovered access point – Open in
browser – Maintenance – Status
Note: Restart your access point if discovering process takes more than 2 minutes.
Page 33 of 36
Page 34
Quick Start Guide imagotag GmbH
FIGURE 1-35: Restart and Factory Defaults button
1.5 AP discovering with Bonjour Services
You still got problems to find your AP in your network? There's another workaround: You can use
Apple's "Bonjour Print Services".
Download and install “Bonjour Print Services“ for Windows (pre-installed under OSX):
http://support.apple.com/kb/DL999
Note: After installation there’s no reboot required.
If the access point is connected directly to the system where the “Bonjour Service” is installed
(or on a network with running “Bonjour Service”) you can find the access point by typing the
following in the browser of your choice:
http://ap-<ID>.local:8080 (e.g. http://ap-12724.local:8080)
Note: You can reach older versions of the AP with http://imagotag-ap.local:8080 (custom
hostnames are only available on newer versions of the access point)
1.6 What can I do if the Status LED of the AP-2010 access point doesn’t turn blue?
l Check the AP status
l Check AP configuration
o
No Channel set
l Check network reachability of AP
l AP registered to Server?
l Reboot AP
1.7 Labels don’t come online
After the registration it could last a certain time until all registered labels are joined to the
network (up to two hours, depending on number of access points and the channels used.
l Up to 30 minutes with channels 3, 5, 8, 9 and 10
l Up to 2 hours with channels 0, 1, 2, 4, 6 and 7
Warning: A label must not be registered to multiple ESL server installations at the same time. It
will only connect to one of this installations.
Page 34 of 36
Page 35
Quick Start Guide imagotag GmbH
1.8 The encryption does not work
Check the encryption passphrase in Server Configuration (System – Configuration).
If label was already registered with a different passphrase you’ll have to unlock the label first in
order to register it on the server.
1.9 Unlocking labels
If the label was registered and a communication key was set it will no longer work in other
networks using a different network key passphrase. To unlock this labels for other networks an
unlock code is required.
Select File – Unlock labels and enter the unlock key.
The unlock-code for the specific labels is enclosed in the Smart Box (in an envelope).
If you have any problems (the unlock code wasn't included or you can't find it) please contact the
imagotag support ([email protected]).
1.10 Starting Java applications
Before starting a Java application, make sure you have Java Runtime Environment Version 6 or
higher installed and you have set the necessary environment variables.
If the .jar file extension is known and associated with Java, just double-click the jar file to start
the application. Otherwise if the extension is not recognized:
Windows:
Create a shortcut of the jar file, right-click on it and open properties. Prepend “javaw.exe –jar“ to
the path in the “Target” field. Double-click the shortcut.
Linux:
Navigate via command line to the directory where the jar file lies and execute “java –jar
<filename>.jar”
In case your environment variables are not set properly (e.g. javaw.exe/java command could not
be found) do the following steps:
1. Locate your installation directory of your Java Runtime Environment
2. Set JAVA_HOME Variable
Under Windows:
l
Right-click on “My Computer” and select “Properties”
l
Click the advanced tab
l
Click the “EnvironmentVariables” button
l
Under “SystemVariables”, click New.
l
Enter the variable name as JAVA_HOME
l Enter the variable value as the installation directory of your Java Runtime Environment
l
Click OK
l
Look for the Path variable in “SystemVariables” and edit it
l Append a semicolon (;) and %JAVA_HOME%\bin to it
Page 35 of 36
Page 36
Quick Start Guide imagotag GmbH
l
Click OK
l
ApplyChanges
Under Linux:
l Use the “export” command to set your variables
l
export JAVA_HOME=<pathToJRE>
l
export PATH=$PATH:<pathToJRE>/bin
l
In order to make these changes persistent, write them into your .bash_profile file and use
“source ~/.bash_profile” to apply the changes
1.11 Encoding problems
Per default, UTF-8 encoding is used. If you have any problems regarding encoding you can force
any java application to use UTF-8. By setting the (Windows) environment variable JAVA_TOOL_
OPTIONS to -Dfile.encoding=UTF8, the (Java) System property will be set automatically every
time a JVM is started.
1.12 Further documentation
Please contact the support for further documentation:
l Developer Reference (Web Service)
l Image Rendering Reference
l CSV/XML Import Plugin
l FAQ
Page 36 of 36
Loading...