NAV Navbar
JSON
  • Introduction
  • Communication Protocol
  • Configuration
  • Errors
  • How To (Features)
  • Introduction

    The purpose is to describe the configuration of Ampron LED display communication protocol.

    AmpronLED software

    AmpronLED software is designed to drive and monitor the status of Ampron LED displays. Our LED display hardware and AmpronLED software together combine the solution that we define as Smart LED Display System.

    Current API defines the ways of configuring and communicating with the software. The general approach, method, syntax and semantics are described in the following chapters.

    The communication protocol is defined to a level of technical detail which should assure a clear understanding of how to drive, monitor and manage the software and displays.

    Following is a structured in a way that at the left side you will see descriptions and at the right side are the example values.

    Communication Protocol

    This chapter is intended to describe the communication concept and protocol between Third Party Communication Module (TPCM) and AmpronLED software for the operational environment. The communication protocol is closely related to the configuration of AmpronLED software.

    Main Communication Process:

    PHASE1 - Third-Party Communication Module (TPCM) sends a control message to AmpronLED

    PHASE2 - AmpronLED sends data to the Smart LED Display System (SLDS)

    PHASE3 - SLDS reports back to AmpronLED with the status message

    General View

    The complete system is composed of the following components:

    Third-party communication module is responsible for sending control messages and receiving status messages.

    AmpronLED Software is responsible for receiving the control messages from TPCM, sending out status messages to TPCM and communicating with SLDS Unit(s).

    Note: as for generalization purposes, only Ampron standard software with its communication format, syntax and semantics are described.

    SLDS Display Units are the visualization units (LED displays) which provide the visual results of communication between Third Party communication module and AmpronLED software.

    Communication Network is considered to include all equipment and measures between TPCM, AmpronLED and SLDS Display Units.

    Ampron LED Communication Overview

    Method, Syntax and Semantics

    Method

    Messaging between TPCM and AmpronLED is performed by using HTTP GET method in both directions.

    Syntax

    Control message format between TPCM and AmpronLED is HTTP Request:

    GET http://ipaddress:port/mlds?nameX=valueX&nameY=valueY&nameZ=valueZ

    Message element Description
    http:// hypertext transfer protocol identifier, constant string
    ipaddress IP address of the server where AmpronLED Software or TPCM is installed
    :port communication port which is listened by TPCM or AmpronLED, integer 1025…65535
    /mlds? resource request, a constant string
    nameX=valueX message pairs/AreaData, predefined alphanumeric pairs
    & separator, constant character

    Semantics

    nameX = valueX - nameX is variable identifier and valueX is value of variable

    There are five types of variables:

    Please see the next chapter for details

    Variables and Requests

    Layouts

    Layouts are configurable views of LED displays. There can be multiple layouts for every single display. However, from the communications point of view, only one layout can be defined in a single GET request.

    Layouts are defined in config.json file, inside the block named “layout”.

    GET http://ipaddress:port/mlds?id=GATE_2&layout=vehiclenumber&nameZ=valueZ&inumber=XXXXX

    AreaData

    AreaDatas are configurable sections (Areas) in every Layout. There can be multiple Areas in one Layout. From the communications point of view, if there are nameX=valueX pairs in the GET request, which are not described in the configuration file, then the request will be disregarded as faulty. If there are no pairs or fewer pairs than defined in Area configuration, the request will be handled as a request for a blank screen or blank area respectively. There are 3 types of AreaData (static text, live text and images):

    GET http://ipaddress:port/mlds?id=GATE_2&layout=vehiclenumber&kiosk=21&plate=123ABC&inumber=XXXXX

    Status Responses

    Success

    AmpronLED software confirms the successful control message execution by responding with HTTP GET.

    GET http://ipaddress:port/mlds?confirm=1&inumber=XXXXX

    Failed

    AmpronLED software responds with unsuccessful control message execution by responding with HTTP GET.

    GET http://ipaddress:port/mlds?confirm=0&inumber=XXXXX

    Fault

    AmpronLED software responds to the faulty command by responding with HTTP GET.

    GET http://ipaddress:port/mlds?confirm=2&inumber=XXXXX

    Addressing

    There can be 99 MLDS units operated by one AmpronLED instance, usually, multiple instances are used:

    MLDS unit identifier -> variable nameX is “id”, value is string max 255 chars

    GET http://ipaddress:port/mlds?id=GATE_2&layout=vehiclenumber&kiosk=21&plate=123ABC&inumber=XXXXX

    Numbering

    The numbering is done by TPCM (Third Party Communication Module), AmpronLED answers with the string provided by TPCM:

    Instructions sequence number -> variable nameX is inumber, value is string of reasonable length

    GET http://ipaddress:port/mlds?id=GATE_2&layout=vehiclenumber&kiosk=21&plate=123ABC&inumber=XXXXX

    Encoding of URL Query Parameters

    Characters from the unreserved set are represented as-is without translation, other characters are converted to bytes according to UTF-8, and then percent-encoded. See Wikipedia Percent Encoding

    Configuration

    The main configuration is set in a config.json file. Other configuration items are defined in various files and are linked to the main file according to specific needs. After changes to configuration, files server needs to be restarted.

    Configurable Items

    {
        "port": "9199",
    
        "displays": {
            "GATE_OUT2": {
    
            "displayName": "anyname",
            "displayIp": "192.168.100.100",
                "displayPort": "9551",
                "controllerType": "T430",
    
                "confirmIp": "127.0.0.1",
                "confirmPort": "9098",
    
                "displayHeight": "160",
                "displayWidth": "96",
    
                "layout": {
                    "vehicle": {
                        "numberplate": {
                            "coordinates": "0 0 100 29",
                            "type": "text",
                    "align": "center",
                            "fontSize": "24",
                            "fontColor": "255 255 255"
                        },
                        "infotext": {
                            "coordinates": "0 30 100 69",
                            "type": "static",
                            "align": "center",
                            "fontSize": "24",
                            "fontColor": "255 255 255",
                            "params": {
                                "21": "Some static text"
                            }
                        },
                        "arrow": {
                            "coordinates": "0 70 100 100",
                            "type": "image",
                            "params": {
                                "S": "fwd.png",
                                "RE": "left.png"
                            }
                        }
                    },
                    "message": {
                        "all": {
                            "coordinates": "0 0 100 100",
                            "type": "image",
                            "params": {
                                "WAIT": "pleasewait.png",
                                "CLOSED": "closed.png"
                            }
                        }
                    }
                }
            }
        }
    }
    
    

    Listening Port

    
    "port":  "9090",
    
    

    Define the following value in config.json file:

    port -> Numerical value within the range of from 1025 up to 65535

    Displays Group

    "displays":
    

    displays Displays subgroup. Fixed value.

    Display ID

    "DISPLAYID"
    

    The first thing to do for adding new display is defining following value in config.json file:

    Display ID - String type unique value, up to 255 characters

    Replace default DISPLAYID with your own unique display ID name.

    Display IP and Port

    
    "displayIp":    "192.168.200.200",
    "displayPort":  "10000",
    

    Set the following value in config.json file:

    “displayIP“ -> In the form of standard IPv4 address “displayPort“ -> Numerical value according to the specification

    Display Metaname

    
    "displayName":  "anyname",
    

    Define the following value in config.json file:

    displayName -> String type value, up to 255 characters

    Display Controller Type

    "controllerType": "G20",
    

    Define the following value in config.json file:

    controllerType -> controller model

    Feedback Server IP and port

    
    "confirmIp": "127.0.0.1",
    "confirmPort": "9092",
    

    Define the following value in config.json file:

    confirmIp -> In the form of standard IPv4 address confirmPort -> Numerical value within the range 1025->65535

    Display Size

    "displayHeight":    "160",
    "displayWidth":     "96",
    

    Define the following values in config.json file:

    displayHeight -> Display height in pixels

    displayWidth -> Display width in pixels

    Display Layout Management

        "layout": {
            "layoutName": {
                "areaID": {
    
                                }
                        }
                    }      
    
    

    Define the following value in config.json file:

    layoutName -> String type value, up to 255 characters

    areaID -> String type of unique value, up to 255 characters

    Consider the values that make sense in your overall system configuration.

    Area Coordinates

    "coordinates": "0 0 100 100",
    

    Define the following values in config.json file:

    coordinates -> Area coordinates in pixels (x y X Y)

    x,y - square area upper left corner.

    X,Y - square area lower right corner.

    Area Types

    "type": "static",
    

    Define the following values in config.json file:

    type -> Possible values - static, text or image

    Static Text Variables

    "align": "center",
               "fontSize": "24",
               "fontColor": "255 255 255",
               "params": {
                            "TEXTID": "text"
                         }
    

    If the chosen area type was chosen static then define section texts and add following variables:

    align -> text alginment. Possible values center or left

    fontSize -> font size in pixels, must be smaller than area height

    fontColor -> font color in RGB

    params -> parameters subgroup. Fixed value.

    TEXTID -> String type value, up to 255 characters

    text -> Text to be displayed, up to 255 characters

    Picture Parameters

    "params": {
                "PICTUREID": "filename1.gif",
              }
    

    Add following values:

    PICTUREID -> String type unique value, up to 255 characters filename.gif -> String type value, up to 255 characters filename with the filename extension.

    All files must be located in the catalogue images/filename, relative to ampronled

    Freetext Parameters

    "align": "center",
    "fontSize": "24",
    "fontColor": "255 255 255"
    
    

    If the chosen area type was chosen text then define following variables:

    align -> text alginment. Possible values center or left. Valid only when text fits into area. fontSize -> font size in pixels, must be smaller than area height fontColor -> font color in RGB

    Monitoring and BITE

    Our information system has built-in monitoring that monitors communications to all displays that are added to the configuration file. It also monitors the successful forwarding of the information packages and has the feedback loop to a feedback IP address. Information system monitors the last sent package success. If the feedback was the same then information is not sent again. After server restart, all active displays receive the command to empty the content of the screen.

    Logging

    AmpronLED software logs all actions with timestamps. Logs are kept by default one month. Length may be set different according to specific needs.

    Errors

    Ampron API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The resource requested is hidden for administrators only.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access a resource with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    429 Too Many Requests -- You're requesting too many resource! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- Server temporarily offline. Please contact support.

    How To (Features)

    Brightness control

    It is possible to change the brightness of the display in 6 different ways:

    1. Automatic daylight

    This is the default mode, brightness is changed between 50% and 100% automatically. Time of change is defined by sunset and sunrise with an accuracy of 2 weeks, example: in the first half of May, the daytime starts later than in the second half of May and in the first half of June later than in the second half of May etc. Default sunset times are taken for local longitude and latitude.

    2. Automatic daylight, specific location

    With this mode, it is possible to define the sunrise and sunset times and also relevant brightness %, for each half months. To use this feature, it is needed to add a specific brightness-schedule.json file to ampronled directory (with X permissions), if the file is present then it is used, if not then default schedule is used).

    3. Manual brightness for a single screen

    To enable manual brightness setting feature, define the following parameter at "displayIP" level:

    "sensorBrightness": true,

    To use this feature send HTTP GET command to the ampronled software:

    http://ampronledIP:port/brightness/VALUE?id=DISPLAY_ID

    VALUE can be from 1 to 100

    4. Manual brightness for all screens

    To enable manual brightness setting feature, define the following parameter at "controllerIP" level to all screens:

    "sensorBrightness": true,

    To use this feature send HTTP GET command to the ampronled software:

    http://ampronledIP:port/brightness/VALUE

    5. Automatic brightness from HW sensor for a single screen

    To enable automatic brightness setting from HW sensor feature, the additional hardware unit should be installed inside every screen. The ambient lighting is measured at every screen and the brightness is adjusted automatically without server interference. Relevant configuration should also be done to screen controller and in the ampronled configuration file following parameter at "controllerIP" level to all screens shall be defined.

    6. Automatic brightness from separately located HW sensor or multiple sensors to all or some specific screens

    To enable automatic brightness setting from single or multiple HW sensors, the additional hardware unit/units should be installed. The ambient lighting is measured at a specific location(s) compared in accordance with the defined algorithm and then the brightness information is sent to all screens or specifically selected screens. Relevant configurations must be done to ampronled configuration file and HW sensor units, as well as agreed algorithms, defined. This is usually done by Ampron technicians during the design phase.

    7. Advanced automatic brightness management

    It is possible to manipulate different types of data to manage the brightness of screens eg.open web RSS feeds, parsing XML, using MODBUS/TCP etc. This feature requires additional Ampron Monitoring Module hardware unit and Ampron Monitoring Software.

    Configuration

    Description

    The main configuration is set in a config.json file. Other configuration items are defined in various files and are linked to the main file according to specific needs.

    AFTER CHANGES TO THE CONFIGURATION, THE FILE SERVER NEEDS TO BE RESTARTED FOR CHANGES TO TAKE EFFECT

    Configurable Items

    {
        "port": "9199",
    
        "displays": {
            "GATE_OUT2": {
    
            "displayName": "anyname",
            "displayIp": "192.168.100.100",
                "displayPort": "9551",
                "controllerType": "T430",
    
                "confirmIp": "127.0.0.1",
                "confirmPort": "9098",
    
                "displayHeight": "160",
                "displayWidth": "96",
    
                "layout": {
                    "vehicle": {
                        "numberplate": {
                            "coordinates": "0 0 100 29",
                            "type": "text",
                    "align": "center",
                            "fontSize": "24",
                            "fontColor": "255 255 255"
                        },
                        "infotext": {
                            "coordinates": "0 30 100 69",
                            "type": "static",
                            "align": "center",
                            "fontSize": "24",
                            "fontColor": "255 255 255",
                            "params": {
                                "21": "Some static text"
                            }
                        },
                        "arrow": {
                            "coordinates": "0 70 100 100",
                            "type": "image",
                            "params": {
                                "S": "fwd.png",
                                "RE": "left.png"
                            }
                        }
                    },
                    "message": {
                        "all": {
                            "coordinates": "0 0 100 100",
                            "type": "image",
                            "params": {
                                "WAIT": "pleasewait.png",
                                "CLOSED": "closed.png"
                            }
                        }
                    }
                }
            }
        }
    }
    
    

    Define different play-styles

    It is possible to define different playstyles for areas. The functionality comprises of two features, "dispEffect" and "clearEffect". dispEffect defines how the text enters into the area while clearEffect defines how it leaves eg. text enters from up to down and leaves the area from down and up again. there are 15 different entry and exit effects which can be combined.

    To enable different playstyles, define following parameters under "text" area in configuration file:

    "dispEffect":"VALUE1", VALUE1 - 1...15"clearEffect":"VALUE2", VALUE2 - 1...15

    VALUE1 and VALUE2 can be different

    Define text colour

    For "text" and "static" areas, it is possible to define font colour also with the GET request.

    http://ampronledIP:port/mlds?id=DISPLAY_ID&layout=LAYOUT_NAME&AREA_NAME=HELLO&fontColor[AREA_NAME]=0_255_255

    where 0_255_255 is the colour of the text in RGB

    Set and change scroll-speed

    Define parameter:

    "scrollSpeed": "VALUE", VALUE - 0...8, 0-fastest and 8-slowest

    if the parameter is not defined then default scroll speed is 4

    Set text background colour

    It is possible to define the background colour of "text" and "static" areas text.

    To set the background colour of text, define the following parameter under the relevant area:

    "backgroundColor": "0 255 255", whereas "0 255 255" is the color of text background in RGB.

    It is also possible to define an alpha channel for this feature, "backgroundColor": "0 255 255 127", whereas 127 is alpha channel value 0...127

    Windows command line options

    Usage: ampronled-mlds-2.1.35-win.exe [options] [command]

    Commands:

    start [options] - Start server.

    test - Testing.

    Options:

    -h, --help output usage information

    -V, --version output the version number