ESLS, PRODUCTS, TEMPLATES

The ESL server operates on several types of objects:

• ESL - defines the device which shows any information on its screen

• Product - defines the information which is shown on the ESL device

• Template - defines the format which defines how product information will be shown on the ESL device.

 All objects have an integer property called “id” which uniquely defines them.

Server uses ESL object to associate it with product and template thus defining what and how will be shown on its screen.

Daily system operation mainly consists of sending product information to the server in order to get ESL screen updated.

Registering ESLs, creating templates, assigning product and templates to the ESL are usually done using esl-manager software - a GUI for configuring and administering the server. But user can define its own software for doing everything the esl-manager software does.

 

Besides mentioned objects there there are several other objects:

• Image - defines a picture which can be referenced from the objects above. Although from API point of view images are operated as stand-alone object they have meaning in the context of other objects.

• RBS - defines the device acting as a gateway between server and ESL devices. RBS devices uses ethernet connection towards server and radio connection towards ESLs.

• User - defines the clients who can login into the system.

• Firmware - defines the software modules for RBS and ESLs used for their upgrading

• Event - defines log journal entries describing the events happened inside the server.

 

These objects usually are not used for integration and used by esl-manager software for configuring/administering the system.

 

Depending on the software version other objects may be introduced.

 

In order to get information about the basic concept of using ESL system see The Getting Started Guide.

This document is about using the Application Programming Interface (API) between ESL server and its clients. The API is done in the form of protocol over TCP connection. I.e. it does not need any software library. This is a simple and independent way of operating the server from different software platforms.

 

The document is intended for software developers / integrators who aims to integrate the ESL system into their software solutions.

 

The esl-manager - the GUI software shipped with the system also uses this interface.

 

 

CONNECTING TO THE SERVER

 

The server listens for clients using tcp port 9126. The client have to make a tcp connection using this port.

 

Communication between clients and server are performed by sending messages. The messages sent from clients are called requests. The answer messages to these requests from the server are called responses. Besides requests and responses server also can send asynchronous messages without any request. These messages are called events.

 

COMMON FORMAT FOR THE MESSAGES

 

All messages are sent as UTF8 encoded json texts. The texts are case-sensitive. All messages have mandatory “type”, “command” and “arg” fields.

 

• “type” - defines the type of the messages. It has 3 possible values: “request”, “response” and “event” corresponding to the message type.

• “command” - defines the name of the message sent from one party to another.

• “arg” - defines the arguments of the message. If there is no argument, the “arg” object is empty (does not have any fields)

 

In addition to these fields response messages have extra “isOk” field:

• “isOk” - a boolean value informing about the correctness of the request previously received. The possible values are true and false. If the message was correct (i.e. with proper syntax and values), the value is true.

 

So the common formats for all three types of messages are:

 

The format of the request:

 

{

"command": "message name",

"type": "request",

"arg": {

...

},

}

 

The format of the response:

 

{

"command": "message name",

"type": "response",

“isOk”: true or false

"arg": {

...

},

}

 

The format of the event:

 

{

"command": "message name",

"type": "event",

"arg": {

...

},

}

 

The order of the fields are is not strict. For example, the “command” field can be sent or received after the “arg” field in the above examples.

TESTING THE PROTOCOL

The standard telnet client can be used for testing the protocol. Copy/pasting the requests will send them to the server, the server responses and events will be printed back to the terminal.

 

For example, in the terminal window (command window in Windows system if telnet client is available) type:

 

telnet 192.168.1.45 9126

 

Here 192.168.1.45 is the IP address of the server and 9126 is the tcp port the server is listening. In case of the demo software the server is embedded into the client, so typing on the same computer

 

telnet localhost 9126

 

will connect the telnet session to the server.

 

 

LOGIN INTO THE SERVER

 

After successful connection the client have to authenticate itself by sending a login request. Server will accept other requests or send events only to successfully authenticated clients.

 

The format of the login request is:

 

{

"command": "login",

"type": "request",

"arg": {

"userName": "user name",

"password": "md5 sum of the password”

}

}

 

For example if the user name is “test” and password is “123test”, then the login request is:

 

{

"command": "login",

"type": "request",

"arg": {

"userName": "test",

"password": "abe45d28281cfa2a4201c9b90a143095”

}

}

 

Login response

 

The format of the response from the server to the login request is:

 

{

"arg": {

"authSuccess": true or false

},

"command": "login",

"isOk": true,

"type": "response"

}

 

The example of successful authentication response:

 

{

"arg": {

"authSuccess": true

},

"command": "login",

"isOk": true,

"type": "response"

}

 

Unsuccessful authentication response:

 

{

"arg": {

"authSuccess": false

},

"command": "login",

"isOk": true,

"type": "response"

}

 

 

GETTING THE LIST OF ESL DEVICES

 

In order to get the list of all registered ESL devices the client have to send the following request:

 

{

"command": "esl",

"type": "request",

"arg": {

"spec": {

}

}

}

 

The format of the server response is:

 

{

"arg": {

"eslList": [

{

"id": device id,

"macAddress": mac address,

"type": "device type",

"advertisementPeriod": advertisement period,

"batteryVoltage": battery voltage,

"currentImageId": current image id,

"pendingImageId": pending image id,

"firmwareVersion": firmware version,

"status": "device status",

"rbsId": rbs id,

"productId": product id,

"templateId": template id

},

...

],

"success": true

},

"command": "esl",

"isOk": true,

"type": "response"

}

There can be additinal fields too depending on the version of the software. The application should be capable to ignore the additional undocumented here fields.

• id - an integer value.
  This is the identifier of the ESL device inside the database. The server uses it as a reference for client-server operations.

• mac address - a 32-bit integer value
  A unique device identifier. The server uses it for procedures with radio base stations (RBS).

• type - a string value.
  The type of the device usually defined by its e-ink model. This value is defined in the following form:
  <size> <color variant>.
  Here <size> can be 2.1”, , 2.9”, 4.2” etc.
  <color variant> can be B/W (blue/white), B/R/W (blue/red/white) or B/Y/W (blue/yellow/white). This list can be extended further.
  The example device types are: "4.2\" B/R/W", "2.9\" B/Y/W". Note the “\” symbol for escape sequencing of the " symbol.

• advertisement period - an integer value in seconds.
  In order to save the battery ESL devices sleeps most of the time and periodically wake up in order to establish a connection to the server. This period defines how many seconds the device will sleep between wake ups.

• battery voltage - an integer value in milli volts.
  The voltage of the battery reported by the ESL device during last wake up.

• current image id - an integer value of the id.
  The id of the image shown currently on the screen of the ESL device. It is possible to get this image by requesting (see Getting Images section below).

• pending image id - an integer value of the id.
  The id of the image is going to be sent to the device. If there is no pending image this id is 0. After successful sending of the image the value of this field is assigned to the current image id and the field is set to the 0.

• firmware version - an integer value.
  The version number of the firmware running in the ESL device.

• status - a string value
  The value shows the status of the device from the server point of view. The possible values are:
  “Lost” - there is no sign of device activity during long time
  “Idle” - the device is alive and can be updated
  “Queued” - the new image is scheduled to be sent to the device and waiting for connection.
  “Updating” - the connection to the device established and data is sent
  “Failed” - error occured during last connection session and device is ready for new connection.
  Note that additional status values can be present depending on the software version.

• rbs id - an integer value
  This is the id of the RBS device which served this device last time, i.e. server made connection to the device through this RBS.

• product id - an integer value
  The id of the product in the server database. When there is some changes on this product server generates a new image according to the template (see template id) for this device and compares it with current image shown on the screen of it (see current image id). If the images differ the server schedules the new image for the device to update it.

• template id - an integer value
  The id of the template in the server database. The template describes how the product data is shown on the screen of the device (see product id).

Besides “id” and “macAddress” fields the most important fields from application point of view are “productId” and “templateId”. User application uses these fields to assign product and templates to this device (see Assigning product and templates to the device below).

 

This is the sample dialog between the client and server. The green message is sent from the client and the blue one is returned from the server.

 

{

"arg": {

"spec": {

}

},

"command": "esl",

"type": "request"

}

{

"arg": {

"eslList": [

{

"advertisementPeriod": 30,

"batteryVoltage": 3164,

"currentImageId": 63,

"firmwareVersion": 3,

"id": 1,

"macAddress": -736440223,

"pendingImageId": 0,

"productId": 10,

"rbsId": 1,

"status": "Idle",

"templateId": 4,

"type": "4.2\" B/R/W"

},

{

"advertisementPeriod": 30,

"batteryVoltage": 3291,

"currentImageId": 64,

"firmwareVersion": 3,

"id": 2,

"macAddress": -61145057,

"pendingImageId": 0,

"productId": 11,

"rbsId": 1,

"status": "Idle",

"templateId": 4,

"type": "4.2\" B/Y/W"

},

{

"advertisementPeriod": 30,

"batteryVoltage": 3220,

"currentImageId": 60,

"firmwareVersion": 3,

"id": 3,

"macAddress": -210239072,

"pendingImageId": 0,

"productId": 12,

"rbsId": 1,

"status": "Idle",

"templateId": 4,

"type": "2.9\" B/Y/W"

}

],

"success": true

},

"command": "esl",

"isOk": true,

"type": "response"

}

 

According to the answer from the server there are 3 registered ESL devices of type 4.2” B/RW, 4.2” B/Y/W and 2.9” B/Y/W with assigned products and templates. Statuses of these devices are Idle. Note that mac addresses is shown as signed integer which have negative values. Application should interpret them as unsigned 32 values and present them as hexadecimal values for conveniency.

 

Instead of getting the list of all ESL devices it is possible to narrow the list and get only the interested devices using specifications. The “spec” object in the request message allows to select particular ESLs using the combination of the following parameters (for more details on parameters see esl parameters description above):

 

• id - esl device id

• macAddress - the 32-bit MAC address of ESL device

• type - the device type

• productId - the id of the product assigned to this device

• templateId - the id of the template assigned to this device

 

Depending on the version of the software additional specification parameters can be present. This is an example of the request where the device with id=30 is requested:

 

{

"arg": {

"spec": {

"id": 30

}

},

"command": "esl",

"type": "request"

}

 

The server will retreive a response with the parameters of the esl with id 30. If there is no such device a response with empty list returned.

The following request asks the server to return all 4.2” B/W devices in combination with the template id 123:

 

{

"arg": {

"spec": {

"type": "4.2\" B/W",

"templateId": 123

}

},

"command": "esl",

"type": "request"

}

 

This is an example with the empty esl list response, where server cannot find the ESL item according to the search criteria:

 

{

"arg": {

"eslList": [

],

"success": true

},

"command": "esl",

"isOk": true,

"type": "response"

}

 

ASSIGNING PRODUCTS AND TEMPLATES TO AN ESL DEVICE

 

In order to assign product to an esl device the following request is used:

 

{

"arg": {

"spec": {

"id": device id,

"productId": product id

}

},

"command": "updateEsl",

"type": "request"

}

 

• device id - an integer value defining the id of the ESL device in the server database

• product id - an integer value defining the id of the product in the server database assigned to this device.

 

The response message from the server is in the following format:

 

{

"arg": {

"id": device id,

"success": success value

},

"command": "updateEsl",

"isOk": true,

"type": "response"

}

 

• device id - an integer value of ESL id

• success value - a boolean value showing the result of the operation

 

An example session is shown below:

 

{

"arg": {

"spec": {

"id": 1,

"productId": 11

}

},

"command": "updateEsl",

"type": "request"

}

{

"arg": {

"id": 1,

"success": true

},

"command": "updateEsl",

"isOk": true,

"type": "response"

}

Client sends a request for assigning product with id 11 to the device with id 1. Server sends a response about successful result.

 

Assigning a template to an ESL device is performed in the same way. The syntax of the request is:

 

{

"arg": {

"spec": {

"id": device id,

"templateId": template id

}

},

"command": "updateEsl",

"type": "request"

}

 

• device id - an integer value defining the id of the ESL device in the server database

• template id - an integer value defining the id of the template in the server database assigned to this device.

 

The response from the server is as same as assigning product case:

 

{

"arg": {

"id": device id,

"success": success value

},

"command": "updateEsl",

"isOk": true,

"type": "response"

}

 

This is is an example session:

 

{

"arg": {

"spec": {

"id": 2,

"templateId": 4

}

},

"command": "updateEsl",

"type": "request"

}

{

"arg": {

"id": 2,

"success": true

},

"command": "updateEsl",

"isOk": true,

"type": "response"

}

 

Here the client sends a request for assigning template with id 4 to the device with id 2. Server sends a response about successful result.

 

 

It is possible to assign both product and template at the same time by defining both parameters (for the description of the argument see Assigning products and templates to an ESL device section above).

 

{

"arg": {

"spec": {

"id": device id,

"productId": product id

"templateId": template id

}

},

"command": "updateEsl",

"type": "request"

}

 

The example session below tries to assign product with id 14 and template with id 1 to a device with id 3:

 

{

"arg": {

"spec": {

"id": 3,

"productId": 14,

"templateId": 1

}

},

"command": "updateEsl",

"type": "request"

}

{

"arg": {

"id": 3,

"success": true

},

"command": "updateEsl",

"isOk": true,

"type": "response"

}

 

In case of incorrect device, product or template id the server sends an error response describing the reason using “errorStr” field. In the following example the device with id 30 does not exist:

{

"arg": {

"spec": {

"id": 30,

"templateId": 10

}

},

"command": "updateEsl",

"type": "request"

}

{

"arg": {

"errorStr": "ESL not found",

"id": 30,

"success": false

},

"command": "updateEsl",

"isOk": true,

"type": "response"

}

 

GETTING THE LIST OF THE PRODUCTS

 

Products are the objects which describe what information is shown on the ESL device screen. Despite the name “product” it can be used for all types of information. Products consist of properties. Properties are specific for the particular product, i.e. every product can have its own set of properties. There are three properties which are present in all products:

• id - the unique integer number defining a product in the server database

• name - the optional string value defining the name of the product defined by the user

• description - the optional string value defined by user

 

Besides these three properties additional user defined properties can be present. These properties are defined in the propertyList array. User defined properties themselves have three three fields:

 

• name - a string value, the name of the property

• value - a string value, defining the content (value) of the property

• type - a string value defining the type of property. This field tells how to interpret the “value”. The possible values of this field is:
  text - the value interpreted as is - string,
  number - the value interpreted as a number,
  image - the value is interpreted as an id referencing to an image in the server database.

 

In order to request the list of all available products the message format is:

 

{

"arg": {

"spec": {

}

},

"command": "product",

"type": "request"

}

 

The server response format is:

 

{

"command": "product",

"isOk": true,

"type": "response",

"arg": {

"success": true,

"productList": [

{

"id": product id,

"name": product name,

"description": product description,

"propertyList": [

{

"name": property name,

"type": property type,

"value": property value

},

...

]

}

...

]

}

}

 

• product id - an integer value, describing the unique id of the product

• product name - a string value, shows the name of the product

• product description - a string value, shows additional information about the product

• property name - a string value, shows the name of the property

• property type - a string value, the type of the property (mentioned above)

• property value - a string value, the value of the property.

 

This is an example for product requeset and response. In order to save space the product list was reduced and changed with “...” :

 

{

"arg": {

"spec": {

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

{

"description": "Slim AC-DC converter",

"id": 1,

"name": "5V 40A Adaptor",

"propertyList": [

{

"name": "currency",

"type": "text",

"value": "$"

},

{

"name": "image",

"type": "image",

"value": "3"

},

{

"name": "price",

"type": "number",

"value": "9.75"

},

{

"name": "unit",

"type": "text",

"value": "piece"

}

]

},

{

"description": "Brightness sensor",

"id": 2,

"name": "Brightness sensor",

"propertyList": [

{

"name": "currency",

"type": "text",

"value": "$"

},

{

"name": "price",

"type": "number",

"value": "2.12"

},

{

"name": "unit",

"type": "text",

"value": "piece"

}

]

},

{

"description": "Digital ambient sensor with built-in controller",

"id": 3,

"name": "Temperature sensor",

"propertyList": [

{

"name": "currency",

"type": "text",

"value": "$"

},

{

"name": "price",

"type": "number",

"value": "2.54"

},

{

"name": "unit",

"type": "text",

"value": "piece"

}

]

},

...

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

 

Here it can be seen that different products are able to have different set of properties. For example product with the id = 1 has an image property but others do not.

 

As with ESL device it is possible to filter the search result using “spec” parameter. The combination of the following fields can be used in the spec field:

• id – the id of the product. If this field is present and is not set to zero the single product with this id will be returned.

• name – the name of the product. If this field is present and is not empty the products which name field contains this value will be returned.

• description – the description of the product. If this field is present and is not empty the products which description field contains this value will be returned.

• propertyList – the array of the properties which is used for searching. If this list is not empty then products having exactly specified keys and values listed here will be returned. Note that there is not need to provide type information as it is ignored during searching.

 

If no product fullfills the search critera the empty list will be returned.

 

In the following example products are filtered by id.

 

{

"arg": {

"spec": {

"id": 2

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

{

"description": "Brightness sensor",

"id": 2,

"name": "Brightness sensor",

"propertyList": [

{

"name": "currency",

"type": "text",

"value": "$"

},

{

"name": "price",

"type": "number",

"value": "2.12"

},

{

"name": "unit",

"type": "text",

"value": "piece"

}

]

}

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

 

This is an example of filtering using property:

 

{

"arg": {

"spec": {

"propertyList" : [

{

"name": "price",

"value": "2.54"

}

]

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

{

"description": "Digital ambient sensor with built-in controller",

"id": 3,

"name": "Temperature sensor",

"propertyList": [

{

"name": "currency",

"type": "text",

"value": "$"

},

{

"name": "price",

"type": "number",

"value": "2.54"

},

{

"name": "unit",

"type": "text",

"value": "piece"

}

]

}

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

 

Here is an example of empty product list:

 

{

"arg": {

"spec": {

"id": 20000

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

 

CREATING A NEW PRODUCT

 

The simplest way of creating a product is the following json request:

 

{

"arg": {

"product": {

}

},

"command": "addProduct",

"type": "request"

}

 

Here all parameters for product are left empty. The ESL server will create a new product with empty name, description, property list and return the id of the created product:

 

{

"arg": {

"id": id of the product,

"success": true

},

"command": "addProduct",

"isOk": true,

"type": "response"

}

 

Check the following sample session:

 

{

"arg": {

"product": {

}

},

"command": "addProduct",

"type": "request"

}

{

"arg": {

"id": 23,

"success": true

},

"command": "addProduct",

"isOk": true,

"type": "response"

}

{

"arg": {

"spec": {

"id": 23

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

{

"description": "",

"id": 23,

"name": "",

"propertyList": [

]

}

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

 

Here client sends a request to the server for creating a product without specifying any parameter. Server creates a products with id=23 and sends a response to the client about it. Next, client sends a request about the product with id=23 to see all its parameters. The server returns the response about the product with id=23. Using this id a client can later modify the product adding/removing properties and setting them.

 

It is also possible to define properties when a product is created. The syntax for the request will be in the following form:

 

{

"arg": {

"product": {

"name": product name

"description": product description,

"propertyList": [

{

"name": property name,

"type": property type,

"value": property value

},

...

]

}

},

"command": "addProduct",

"type": "request"

}

 

• product name – the optional name of the product. If this field is omitted the name will be an empty string.

• product description – the optional description of the product. As with the name field an empty string will be created for this field if this field is omitted.

• “propertyList” is an array consisting of property objects. Please see the GETTING THE LIST OF THE PRODUCTS section about properties.

 

Let’s assume that we want to create a product with a name Pencil, which has empty description, with properties price=3.71, currency=”TL”, barcode="4800063", origin="Turkey". The request for this is:

 

{

"arg": {

"product": {

"name": "Pencil",

"propertyList": [

{

"name": "price",

"type": "number",

"value": "3.71"

},

{

"name": "currency",

"type": "text",

"value": "TL"

},

{

"name": "barcode",

"type": "text",

"value": "4800063"

},

{

"name": "origin",

"type": "text",

"value": "Turkey"

}

]

}

},

"command": "addProduct",

"type": "request"

}

 

MODIFYING A PRODUCT

 

It is possible to modify all properties of the product except id which is a immutable handle of the product and assigned by the system during creating. The json syntax for updating a product is very similar to the one for creating a product. The only difference is a mandatory id field:

 

{

"arg": {

"product": {

“id”: product id,

"name": product name,

"description": product description,

"propertyList": [

{

"name": property name,

"type": property type,

"value": property value

},

...

]

}

},

"command": "updateProduct",

"type": "request"

}

 

For description of the fields please see CREATING A PRODUCT section.

Note: be aware that if you omit any field, for example name, it will be cleared, because an absent field is interpreted as an empty one. In the same way, if you omit any field for inside propertyList array, that field will be removed from the product. If you omit propertyList array itself, all properties will be deleted.

 

Let’s assume that the id of the pencil we created previously is 10. And we want to update its price from 3.71 to 4.00 and remove the “currency” property. The following dialog demonstrates how updating products work:

 

{

"arg": {

"spec": {

"id": 10

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

{

"description": "",

"id": 10,

"name": "Pencil",

"propertyList": [

{

"name": "barcode",

"type": "text",

"value": "4800063"

},

{

"name": "currency",

"type": "text",

"value": "TL"

},

{

"name": "origin",

"type": "text",

"value": "Turkey"

},

{

"name": "price",

"type": "number",

"value": "3.71"

}

]

}

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

{

"arg": {

"product": {

"id": 10,

"name": "Pencil",

"propertyList": [

{

"name": "price",

"type": "number",

"value": "4.00"

},

{

"name": "barcode",

"type": "text",

"value": "4800063"

},

{

"name": "origin",

"type": "text",

"value": "Turkey"

}

]

}

},

"command": "updateProduct",

"type": "request"

}

{

"arg": {

"id": 10,

"success": true

},

"command": "updateProduct",

"isOk": true,

"type": "response"

}

{

"arg": {

"spec": {

"id": 10

}

},

"command": "product",

"type": "request"

}

{

"arg": {

"productList": [

{

"description": "",

"id": 10,

"name": "Pencil",

"propertyList": [

{

"name": "barcode",

"type": "text",

"value": "4800063"

},

{

"name": "origin",

"type": "text",

"value": "Turkey"

},

{

"name": "price",

"type": "number",

"value": "4.00"

}

]

}

],

"success": true

},

"command": "product",

"isOk": true,

"type": "response"

}

 

First the product with id=10 was requested. System returned the product data. Next updateProduct request was sent where price was changed and currencty property was removed. System returned a success result. Then the product with id=1 was requested again and system returned the modified product data.

 

REMOVING A PRODUCT

 

The following request is used for removing a product from the system:

 

{

"arg": {

"id": product id

},

"command": "removeProduct",

"type": "request"

}

 

If everything is ok the response of the system will be:

 

{

"arg": {

"id": product id,

"success": true

},

"command": "removeProduct",

"isOk": true,

"type": "response"

}

 

In case of an error the following response will be returned:

 

{

"arg": {

"id": product id,

"success": false,

“errorStr”: error text

},

"command": "removeProduct",

"isOk": true,

"type": "response"

}

 

Here error text is a human readable string value describing the error. See the following sample dialog:

 

{

"arg": {

"id": 3

},

"command": "removeProduct",

"type": "request"

}

{

"arg": {

"id": 3,

"success": true

},

"command": "removeProduct",

"isOk": true,

"type": "response"

}

{

"arg": {

"id": 3

},

"command": "removeProduct",

"type": "request"

}

{

"arg": {

"errorStr": "Product not found",

"id": 3,

"success": false

},

"command": "removeProduct",

"isOk": true,

"type": "response"

}

 

WORKING WITH IMAGES

 

Also images can be created and deleted as stand-alone objects, they are not used independently. Images are used in the following contexts:

 

• Property of the product. Assigned by the user using the id.

• Frame value of the template. Assigned by the user either as an id of the image or as an expression which returnes the id of the image (details about it will be discussed late when templates are described).

• Pending and current images of the ESL screen. These images are generated and assigned by the server automatically during updating of ESLs.

 

Images are referenced only by id. It is the responsibility of the user not to forget the id of the images and assign them to the product and templates. If an image is not referenced any more they are deleted later automatically by the garbage collector, so there is no need of removing images explicitly. The time of the garbage collecting is adjustable, it is once a day at 02.00AM by default.

 

The server can understand and work with the most common file formats: PNG, JPEG, BMP, GIF and a few more. These files are uploaded and downloaded as base64 strings. For example, in order to upload a file “foo.png” it should be converted to base64 first and then used in json requests. Server holds the image data as the same base64 string and returns it when requested. The following examples show how to convert the file “foo.png” to base64 depending on operating system:

 

Linux

Encode a data file to Base64

base64 foo.png > foo.b64

 

Decode a Base64 file

base64 -d foo.b64 > foo.png

Windows

Encode a data file to Base64

certutil -encode foo.png tmp.b64 && findstr /v /c:- tmp.b64 > foo.b64

 

Decode a Base64 file

certutil -decode data.b64 foo.png

macOS

Encode a data file to Base64

base64 -i foo.png -o foo.b64

 

Decode a Base64 file

base64 -D -i foo.b64 -o foo.txt

Creating an image

 

The syntax for creating an image is:

 

{

"arg": {

“image”: {

“value”: base64 coded string

}

},

"command": "addImage",

"type": "request"

}

 

Here base64 coded string is a base64 encoded string of the image file. The response of the server is:

 

{
    "arg": {
        "id": image id,
        "success": true
    },
    "command": "addImage",
    "isOk": true,
    "type": "response"
}

Here image id is the id of the image created by the server.

 

As an example, let’s assume that we want to add the following image file called nosmoke.gif to the system:

 

 

 

The request for adding this image to the system and possible result will be:

 

{
    "arg": {
        "image":
        {
            "value": "R0lGODlhAAECAaEDAAACAP4AAP3//P///ywAAAAAAAECAQAC/pSPqcvtD6OctNqLs968+w+G4kiW
                5omm6sq27gvH8kzX9o3n+s73/g8MCofEoiWATCqXzKXxCdU0p9QqM4rNCqzcrlcL5nnH5HH4/Cqr
                1120u8SOy63vunSOzzftfIj+D+jUN2gQaHhIWHe4yJgIxgjZ6PgUWSk5GWSpeYm5s/nJ2VkDShoq
                mlaaingKo+q6yqryOgsbS0KLa2h7m9sLuPvhKxwIvDF8/Fd8gQxyrEzRyxL9/EBLY0298Crmmo2g
                KgTuXQpFTk2qhV4M+vYJ7M63aSufSN+pKYqPaTlfOem/LlI9SNkAxiPobQtCRabGNUz30OEiNxET
                FqoFEaNF/m0ay3XcyOBjEZEgORLDQrKkyV8eWaqskJKbrpdHTg6pSLOBzXA4c67Mc1OgT2gufegb
                KmGnJ3tI/SQzCq+pUz09UkmdClRHt6sOnubYxlUnVRyzcgI4exYrnhu4SqJ9C1ds1lFtE8K9G/en
                HLq5vOVV8DfB2BnCqL2NcFjB4FbDlCVGjFbx4hZUYyaKTOHxgcnSslrug9lC6M1zO68lrRTT6Aqr
                L85B9VrwzE6tWaeVfXoFZ4WpB2nG0Ho3nNySe/OpLfo27r2yiOstDVo5B+nfYqeA/tx5HeTAqbtm
                fgJ7yNnbvW9Arn2E+PGG8LoHMOR3B/O8wfOynvTQ+/0//rhroF8fG+HhN8Ei+/G3g3//wceefSKk
                F0FMCN6gYAb+QdgBhhGSBwFeNlRoIYABCqgegTUZ18BdNIAYolprlOggBp8hoGIMLF4AookZ6rgM
                hxIExsKNyTHoohoPxngHig4AmYKQQ+aHZJJxeHDWREMSqYKTtmFZJBkh8HjljAnIVwKZVIqYnZfB
                RLnlbT7+iOYHZs4XZ5pfeKAhnKO92aGWONYZIpdQkrjjlOfJJ6YBfm5pwqIjloEnm3rSl+icdAoK
                gqOPqmmMpJBdyGeKgP6JqZyjNvgiB2B+GqeYmj7w6pKxrjpoqt0BOmOsDOi6q660dmlGoKWiKhxg
                vNJ4/uqThRIqo6ewAoqWlX0Oe2ujyVbjbFfZ9oomXp8dK4Clh1Lbo6HNMqvsAgdaBi64Y14L7J3l
                opuZeQcuV+wBx7r7Lrnn2noivROs9p62SvLKL7L+/gswUQJPqq+HGxZl7MLTWmvxvA0XaK6yEjvs
                VcXTJawovCAbqTGkpLqXwZuxirtgxi13zDHNA7PcKcXhmqxwmSRX9zC2QU8Lc80h7yyzujx/et22
                QG98M7+zFS1q0ow2NzSxnLZpda1ZaUo1qaZBLTTZRA/XHs9hp4u12XK5LSsKBsbs89Ipbz0x3Evq
                FurFdbvg9Hco/5BoxF1HDZve+KoMROFrX5344HlL/k543xUfznQMgQd+jeU9k/D4lzYbrPiHALBr
                97OYR5r106WvGK3lPyPdeeuu491DXCKFjnjtr2/aBhB/dcQ7xL5TXjbjuf+m0c/FH2k7asjnwCTw
                9s0+O0yjax0sD5augn3qor/OeZAVGig+t1pFbz0X3rM4N+jZ3y1vvO5Tv3bhUa+O9vTc11+D6iUv
                X3RbCvm2BwMBDpCAYpOJ/+x0vwCGLnaeqxf/BnRA9p1AgVVLi/6Ulr77PLA4v6vbtYZXQdVdEIMj
                XBzuXMBBEK7mg4ZrHPvKJ4LH1ciFeZLVCuV2QwRmSUg7hKAGa5gJDQqxSaP62NuOdjYbKvGIISia
                /hMX2EPD/RCIUyxhFeN0xckxsGRb5OLvlrhBEYXRaFAUWVC66EVTDauIDMvX/MZ3RjT+7XIh/Mjz
                GAPHFmKMj2VsH9T+CMg8UlGOWIphHbFzR+gpMo5yJGPCqkSeSEpSkLd74QoKNoJoGRJlmtykJ5+o
                vBes8UwMQl8UyodDRobQjdL7QyHHxkkeAhCGiKwaCdv4Ri/GkpW9pOUv15NEKg7zUnQs4P+WKQNY
                6lF+aWlmtbAIzcjlspOnTGMje5mjFLJlmsfs5iAVtrQb0VCb5kRlO6kpw2uycYw2iGU2V8Ytq4Vu
                nXwjpy53ycQ5OmlR/GyaP7nZPfMJ9FSaKigL/rdpxCqoUo0s8pWSCLPMX+XQPyA6ljgpk9F7XqmD
                KnQkNg/aNkoKDqKM9GFJcaa9i7IzoY9850YBxNED7fOjZlRpLVlKzFJxR6erdGcWUwrUctr0pvai
                DygnJEZ69jSp/wRoQFuD1cMwaKtQlZW0NCdSjVJTMwRLDJG0CtOqBWCUVF0TSp8ZPBup6Dd5+aYW
                Yxgah9Z0qSe1qkKd+JezRqar/arqIpflU6XSNIEwpSNRBVgbvcb0sHCNK+zMGhrlDPaxxjRsYgNG
                2crSAQeYxYxmBavTwpIOmCL8rGIXS6HSIu02j/2mvyTbV8uy7q1XpS1qa5tZXPF0r37NGW8x/oZZ
                SwLXtzLDbURHa8q2mvBdyl3uTmUqpdDmNoISrI11QQlaZKpKrMQtbgsm9N20Tpa12XWtUVPJWP6k
                t6heO+rJ3Lta/AqLkKa1LmLFG179ipa7E6VWjfy7W6naT7f9O+7IwFvd5eJRwe/la3sFvL+uzje6
                5K2weSes3VsRFZ21bS2At0vgh4b4SiWOMGHdqrP6YhjF0B0igmd7LxPo78Qcli6LgXtX9ZqYxwiF
                r0FFyqrvutik/yUyW1OM1BUnWck4tmaD6elkGHVYWBuucil/2kMKg9jBk+qykPvJXjH32MdTpjJ9
                pwoh9qIZyR00M5N1nBo5z5nOMrTzlz0M/jA945LP/EXwn/N7mhiDVc0ZTu9syaILQYOU0WVW8qFp
                bI6vSHpl851lMxpjwCz/mMoOrEup7TtqCUOlL6umNNFu3GqwVG7TqU4tT2Q9a1rX+syxVsetdc01
                CBNhK8F0daUvDeOoDBu7CfH1SJzrCGUb4as5OcoroT0QoWSB2jTRdkaYXRBub1vcFlkIGsxd7p5c
                m9zKQHc73P0OeL9b3dH29iAMEgt8Z1vehOBHPvxdb33vw9p2YMoppH0GhB+cHY9geEAcTgmIP8Mq
                v5b4OcQR6kynG9fRLItKpjFojHe7MFpm9VCQcYWogvoqKG/5jP/t8phLNCyelfnKaV5kcpuTHOcD
                1jmxeQ5on2sc6JgWOr+J3nOjYxspSnc20unXdHA/vehR//DUoV51C199vVmH7dbX3HUlfB1wYd/D
                2Bfd9bOP0+hq77Uz2l5sbMAdJUOfO0WGa/e8633vfO+73/8O+MALfvCEL7zhD4/4xKOgAAA7"
        }
    },
    "command": "addImage",
    "type": "request"
}
{
    "arg": {
        "id": 6,
        "success": true
    },
    "command": "addImage",
    "isOk": true,
    "type": "response"
}

Here the value field is base64 encoded string of the image file and the server creates an image with id=6.

 

The user should use and assign this id value to a product or template before it is garbage collected. Let’s assume that we want to create a product with name “Social advertisement” and assign this id to a property called picture. The request for this is (see Creating a product section):

 

{

"arg": {

"product": {

"name": "Social advertisement",

"propertyList": [

{

"name": "picture",

"type": "image",

"value": "6"

}

]

}

},

"command": "addProduct",

"type": "request"

}

 

Now there is a reference to the image so it is and it is possible to show this image by using the picture property of the product. Using the image with templates for showing them on the screen of the device will be discussed later with templates.

 

-----------------------------------------------

Getting list of templates

Filtered searching using “spec”

Creating a template

Modifying a template

Removing a template

Test rendering of a template