AmpronLED NextGen API

How it works

AmpronLED NextGen software runs inside each Smart LED or LCD Display System (SLDS). A Third-Party Communication Module (TPCM) — your backend, script, or PLC — sends HTTP GET requests to the display's IP address and port to control what is shown.

PHASE 1 — TPCM sends a control message (HTTP GET) to AmpronLED NextGen. PHASE 2 — AmpronLED NextGen renders the content on the display. PHASE 3 — AmpronLED NextGen makes status information available for polling at /info.

URL format

All display control uses HTTP GET requests. The URL has four fixed parts: protocol, IP address, port, the /mlds resource path — plus query parameters that specify what to show.

The id and layout parameters are always required. Additional parameters correspond to named areas defined in the layout configuration.

Complete example

This example activates the 'vehicle' layout on display 'GATE_2', sets the numberplate area to '123ABC', and triggers the arrow area to show the forward image (mapped to key 'S' in config).

Only one id can be specified per GET request. If you need to update multiple virtual displays simultaneously, send separate requests to each.

URL encoding

Characters from the unreserved set (A–Z, a–z, 0–9, -, _, ., ~) are used as-is. Other characters must be percent-encoded (UTF-8 byte values, prefixed with %).

Spaces become %20. Special characters in text values must be encoded. Most HTTP client libraries handle this automatically.

id — Virtual display identifier

id is the identifier of a virtual display within a physical display unit. A single physical display can contain multiple virtual displays (id values), each controllable independently.

Virtual displays can overlap on the physical screen, but tracking their state becomes harder when they do. The first defined id is the MAIN display — brightness and other display-level parameters must be set through it.

layout — Active layout

layout activates a named layout on the target display. Layouts define which areas are shown and what type of content each area accepts. Only one layout can be active per GET request.

Layouts are defined per display in config.json. Switching layouts changes the entire visual configuration of the display instantly.

AreaData — Content parameters

AreaData parameters are the key=value pairs after id and layout. Each key matches a named area in the active layout's configuration. The value is what gets displayed in that area.

For text and freetext areas, the value is the text string. For static, image, video, and audio areas, the value is a key that maps to a filename defined in the config. Unknown keys are silently ignored.

If fewer area parameters are provided than defined in the layout, unmatched areas show blank or their configured defaultValue.

Status endpoints

AmpronLED NextGen exposes several HTTP endpoints for monitoring. These are readable without any authentication and return plain text or JSON.

/info shows the last received command per id, configuration status, system time, software version, and current resolution. /status provides a shorter machine-readable status. /screenshot returns a JPEG image of the current screen.

Pushing status via HTTP POST

Status information can be pushed automatically to any URL via HTTP POST. Configure a cron entry with type sendInfo and set the value to your backend endpoint. AmpronLED NextGen will POST the display status (same content as /info) to that URL at the defined interval.

This enables passive monitoring — your backend receives status updates without polling the display.

Command acknowledgement

AmpronLED NextGen responds synchronously to each GET request with a 'command received' confirmation if the request is valid and contains no forbidden elements. This does not guarantee content is visually updated — layout or parameter errors may silently discard the request.

Faults in layout name, area keys, or parameter values are reported synchronously and the request is discarded. Check /info after a failed update to see the error message.

Reload configuration

Configuration is re-checked every 3000 seconds automatically. To force an immediate reload after a config change, send the reload_config command.

Configuration files must be valid JSON. Errors are shown on the /info page. Note: some mistakes (font too large for area) are not caught as errors — verify visually.

config.json structure

All display behaviour is defined in config.json. This file is stored on the display unit and specifies the listening port, cron tasks, pollers, and display layouts.

The configuration is hierarchical: top-level → port/crons/pollers/displays → display id → layout name → area id → area properties. Only the displays object is required; other sections are optional.

Uploading configuration

Option 1 — SSH: Log in to the display unit, edit config.json directly, save the file, then send the reload_config command.

Option 2 — HTTP: Download the current config from /load_config. Edit locally. Zip the config files and host them on a reachable URL. Load the new config via load_config?url= pointing to your zip.

Listening port

The port value sets which TCP port AmpronLED NextGen listens on for incoming HTTP GET requests. Must be in range 1025–65535.

This is the port you include in all control message URLs. The same port serves /info, /status, /screenshot, /reload_config, and all other endpoints.

Crons — Scheduled tasks

Crons are scheduled tasks that AmpronLED NextGen runs automatically. Each cron has a type, an optional value, and a 6-field cron schedule (seconds resolution).

Types: sendInfo — HTTP POST of status to your URL. data — localhost control command. loadLastRequest — replay the last received command. url — background GET to any URL.

The cron field uses standard 6-field format: seconds minutes hours day-of-month month day-of-week. Example: '30 * * * * *' runs at 30 seconds past every minute.

Polling for commands

Pollers allow the display to pull control commands from a remote URL at a set interval, instead of waiting for your system to push commands via GET. Useful for IoT setups without inbound network access to the display.

The poller fetches the URL and interprets the response body as a control command in the same format as a GET request query string.

Display ID and name

Each virtual display has a unique string ID (the key in the displays object) and an optional human-readable displayName. The ID is what you use in the id= parameter of control messages.

You can define multiple display IDs for a single physical unit — each controlled independently. The first defined ID is the MAIN display.

Display size and controller

displayHeight and displayWidth define the display resolution in pixels. These must match the physical display's actual pixel dimensions.

controllerType identifies the LED or LCD controller model (e.g. T430, G20). This is used by AmpronLED NextGen for hardware-specific communication. The correct value is provided by Ampron with the display unit.

infoScreenTtl sets how long (in seconds) the IP address is shown on boot before the display switches to content.

Boot actions

startScreen configures what happens when the display boots: whether to show a logo image, how long to show it, and whether to reload the last received command automatically.

completeUrls: URL to visit in the background after boot completes. loadLastRequest: if true (default), the last command is replayed after boot. image: logo file to show. imageTtl: seconds to show the logo.

Brightness settings

sensorBrightness controls how brightness is managed. Set to 'true' to enable manual brightness control via HTTP or sensor input. Set to 'false' to use the internal automatic schedule.

brightnessUrl (supported from v1.5.2): URL of a plain text file containing a brightness value 0–100. The display polls this URL to set its brightness level. Useful for centrally managing brightness across multiple displays.

Area definition

Each layout contains one or more named areas. An area defines a rectangular region of the display, the type of content it shows, and the parameters for that content.

Areas are defined by their coordinates (pixel rectangle), type, and type-specific parameters. Areas in the same layout can overlap — useful for composite display arrangements, but harder to manage.

Coordinates

coordinates defines the rectangle where content is drawn, in pixels: x y X Y — where (x, y) is the upper-left corner and (X, Y) is the lower-right corner.

All values are in pixels relative to the display's pixel dimensions. Areas must physically fit within the display dimensions and ideally should not overlap.

TTL and defaultValue

ttl (time-to-live) is the number of seconds after which the area content is cleared or replaced by the defaultValue. Set ttl to clear content automatically if no new command arrives — useful for ensuring displays don't show stale data.

defaultValue defines what to show after TTL expires: a text string for text-type areas, or an image filename (e.g. 'logo.png') for image-type areas.

Available area types

static — predefined text strings mapped to parameter keys. Renders a fixed label from a lookup table.

text — freetext input. The GET parameter value is displayed directly as text, with optional scrolling.

dynamic — similar to text but updated without resetting the scroll position.

image — image file mapped to a parameter key. Supported: PNG, JPG, GIF.

video — video file mapped to a parameter key. Supported: MP4.

date — live clock/date display using the device's system time.

audio — audio file mapped to a parameter key, played in loop.

web — renders a URL in a browser viewport cropped to the area.

Static area — predefined strings

A static area shows text from a predefined lookup table. The GET parameter value is a key; the corresponding text string from params is displayed. This prevents arbitrary text input — only approved strings appear on screen.

Use for areas where the content is one of a fixed set: 'OPEN'/'CLOSED', 'PROCEED'/'HOLD', bay identifiers, etc.

Text styling

align — text alignment within the area. Values: center, right, left.

font — filename of the .ttf font in the /fonts directory on the device.

fontSize — font size in pixels. Recommended to be smaller than the area height.

fontColor — RGB colour as three space-separated values (0–255).

backgroundColor — optional background colour. Add a fourth value for alpha channel (0–127).

Freetext area — arbitrary text input

A text area accepts any string value directly from the GET request. The value is displayed as-is. Use for areas where the content changes freely: vehicle numbers, names, messages.

Text that fits within the area width is shown statically. Longer text scrolls horizontally at a configurable speed.

Scroll settings

textFromStart — if true, scrolling restarts from the beginning when a new value is received.

textLiveUpdate — if true, text content updates on the fly without resetting the scroll position.

headToTail — number of spaces to insert between the end of the scrolling text and its next repetition.

scrollSpeed — scroll speed 0–8, where 0 is fastest and 8 is slowest. Default is 4.

Image area — file lookup

An image area displays an image file from a lookup table. The GET parameter value is a key; config maps it to a filename. Supported formats: PNG, JPG, GIF. All image files must be in the /images directory on the device.

Use for arrows, icons, status indicators — any graphic that has a finite set of possible states.

Video area — file lookup

A video area plays a video file from a lookup table. The GET parameter value is a key; config maps it to an MP4 filename. All video files must be in the /images directory on the device.

Video plays in a loop. To stop playback, send a command with an empty value for the area.

Date area — live clock

A date area shows the live system clock of the display device. No GET parameter is needed to update it — it updates continuously. Configure format, timezone offset, font and colour.

dateOffset — hours offset from UTC (e.g. +2 for EET). dateFormat — format string using Java DateTimeFormatter symbols.

Date format symbols

Common format symbols: y — year (yyyy = 2024), M — month (MM = 01, MMM = Jan), d — day in month (dd), H — hour 0–23 (HH), h — hour 1–12, m — minute (mm), s — second (ss), E — day of week (EEE = Mon), a — AM/PM marker.

Combine symbols to build any format. Literal text in the format string should be wrapped in single quotes.

Audio area — file lookup

An audio area plays an audio file from a lookup table. The GET parameter value maps to an audio filename. Supported formats: MP3, WAV. Files must be in the /images directory on the device.

Audio plays in a loop. To stop playback, send an empty value for the audio area.

Web area — browser viewport

A web area renders a URL inside a browser viewport cropped to the area's coordinates. The URL value comes from a lookup table in config. Multiple URLs can be defined.

Web area functionality is offered as-is — verify compatibility with your specific display hardware and the target URL. Be aware of GDPR consent banners and check compatibility after any site updates.

xy sets the pixel offset into the source page (useful for cropping away navigation or headers from a URL that you cannot control).

1. Automatic daylight (default)

Default mode. Brightness automatically transitions between 50% and 100% based on local sunrise/sunset times, calculated to 2-week accuracy from the device's configured longitude and latitude.

No configuration required — this is active when sensorBrightness is 'false' and no brightnessUrl is defined.

2. Custom brightness schedule

Place a brightness-schedule.json file in the AmpronLED directory. If present, it overrides the default schedule. Allows you to define sunrise/sunset times and brightness percentages for each half-month period.

Contact Ampron for the brightness-schedule.json format and examples.

3. Manual brightness via HTTP

Enable manual brightness by setting sensorBrightness to true for the MAIN display ID. Then send brightness commands via HTTP. Value range: 1–100.

Important: disable internal scheduler first, otherwise it overrides manual values.

4. Brightness polling from URL

Supported from AmpronLED NextGen v1.5.2. The display polls a plain text file at brightnessUrl and applies the value (0–100) as its brightness level.

The text file should contain only a number. Update the file on your server to change the brightness across all displays that poll it.

Override font colour in GET request

For text and static areas, you can override the configured font colour on a per-request basis by including a fontColor[AREA_ID] parameter. Colour is specified as RGB values joined by underscores.

This lets a single layout show text in different colours without changing the configuration file.

Override font size in GET request

Font size can also be overridden per-request for text and static areas. Add fontSize[AREA_ID]=value to the GET request. Value is in points.

Text background colour

For text and static areas, a background colour can be set in config. The background fills the full area behind the text. Add an alpha value (0–127) for a semi-transparent background.

This is a config-only setting — it cannot be overridden per GET request.

Scroll speed

Scroll speed for text areas is configurable via scrollSpeed. Range: 0–8, where 0 is fastest and 8 is slowest. Default is 4 if not defined.

This is a config-file setting. All text that exceeds the area width will scroll at this speed.

Network configuration

To change the display unit's IP address or enable/disable DHCP, use the setethernetconfig endpoint. Important: this should only be used when a single id is defined in config.json. Verify the new settings at getethernetconfig.

Note: network parameter management is not available for Box MediaPlayers.