OnAirScreen API / UDP / HTTP / MQTT Commands

OnAirScreen can receive API commands via UDP (default port 3310), HTTP (default port 8010), or MQTT.\ Here is an easy UDP example on how to control a local OnAirScreen instance on a linux system.

Set LED1 Text to "FOO" and switch LED1 on:

echo "CONF:LED1:text=FOO" > /dev/udp/127.0.0.1/3310
echo "LED1:ON" > /dev/udp/127.0.0.1/3310

To remotely control an OnAirScreen from Windows, use the oas_send.exe which is part of the OAS Windows License:

oas_send.exe --ip 192.168.23.5 "LED1:ON"

There is also a special version of oas_send that doesn't need a console to run, so it produces no output and doesn't open a cmd window. Please use it like this:

oas_send-noconsole.exe --ip 192.168.23.5 "LED1:ON"

HTTP API

You can also pass commands to OAS via HTTP. Strings need to be urlencoded.

curl http://127.0.0.1:8010/?cmd=LED1:ON
curl http://127.0.0.1:8010/?cmd=NOW:You%20are%20listening%20to%20Queen%20-%20Show%20must%20go%20on

REST-style API

OnAirScreen also provides REST-style API endpoints:

Status Endpoint:

curl http://127.0.0.1:8010/api/status

Returns JSON with current LED status, AIR timer status, text field values, version, and distribution information.

Command Endpoint:

curl "http://127.0.0.1:8010/api/command?cmd=LED1:ON"

Sends commands and returns JSON response with status confirmation.

Web-UI

OnAirScreen provides a complete web-based remote control interface accessible via your browser.\ Simply open http://127.0.0.1:8010/ (or the IP address of your OnAirScreen instance) in any modern web browser.

The Web-UI provides:

• Real-time status display for LEDs, AIR timers, and text fields (NOW/NEXT/WARN)
• Real-time updates via WebSocket (with HTTP polling fallback)
• Dark Mode support with automatic theme persistence
• Warning priority system: Display NTP warnings and user warnings with priorities (Normal, Medium, High)
• Delete warnings directly from status display with X button
• LED control buttons with toggle functionality
• AIR timer controls with start/stop and reset buttons
• Text input controls for NOW, NEXT, and WARN messages
• Compact, organized layout for better space efficiency
• Version and distribution information display
• Connection error handling with modal dialog

MQTT API

OnAirScreen can be controlled via MQTT and integrates seamlessly with Home Assistant using MQTT Autodiscovery.\ Configure MQTT settings in the OnAirScreen settings dialog (Server, Port, Username, Password, Device Name).

Base Topic: The MQTT base topic is automatically generated from onairscreen + a unique device ID (last 6 hex characters of the MAC address). This ensures each OnAirScreen instance has a unique topic, even when multiple instances are running on the same network. For example: onairscreen_a1b2c3.

Home Assistant Integration: OnAirScreen automatically publishes device configurations to Home Assistant, creating:

• LED Switches (LED1-4): Control LEDs on/off
• AIR Timer Switches (AIR1-4): Start/stop timers
• AIR Timer Sensors (AIR1-4 Time): Display elapsed time in seconds
• Reset Buttons (AIR3/AIR4 Reset): Reset timers to 0:00
• Text Entities (NOW, NEXT, WARN): Set and display text fields

MQTT Topics: All commands use the same format as UDP/HTTP API commands, published to:

{base_topic}/led{1-4}/set          → ON/OFF/TOGGLE
{base_topic}/air{1-4}/set          → ON/OFF/TOGGLE
{base_topic}/air{3-4}/reset        → PRESS (button)
{base_topic}/text/now/set          → TEXT
{base_topic}/text/next/set         → TEXT
{base_topic}/text/warn/set         → TEXT

Status updates are automatically published to:

{base_topic}/led{1-4}/state         → ON/OFF
{base_topic}/air{1-4}/state         → ON/OFF
{base_topic}/air{1-4}/time          → seconds (integer)
{base_topic}/text/{now|next|warn}/state → TEXT

Example using mosquitto_pub: The base topic is automatically generated (e.g., onairscreen_a1b2c3). Replace {base_topic} with your actual base topic:

mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/led1/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/led1/set -m "TOGGLE"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air1/set -m "TOGGLE"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/set -m "TOGGLE"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/reset -m "PRESS"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/text/now/set -m "Current Song"

API Commands

Remote Configuration Commands

CONF:General:stationname=TEXT
CONF:General:slogan=TEXT
CONF:General:stationcolor=COLOR
CONF:General:slogancolor=COLOR
CONF:General:replacenow=[False|True]
CONF:General:replacenowtext=TEXT
CONF:LED[1-4]:used=[False|True]
CONF:LED[1-4]:text=TEXT
CONF:LED[1-4]:activebgcolor=COLOR
CONF:LED[1-4]:activetextcolor=COLOR
CONF:LED[1-4]:autoflash=[False|True]
CONF:LED[1-4]:timedflash=[False|True]
CONF:Timers:TimerAIR[1-4]Enabled=[False|True]
CONF:Timers:TimerAIR[1-4]Text=TEXT
CONF:Timers:AIR[1-4]activebgcolor=COLOR
CONF:Timers:AIR[1-4]activetextcolor=COLOR
CONF:Timers:AIR[1-4]iconpath=PathToIcon
CONF:Timers:TimerAIRMinWidth=PIXELS
CONF:Clock:digital=[True|False]
CONF:Clock:showseconds=[True|False]
CONF:Clock:secondsinoneline=[True|False]
CONF:Clock:digitalhourcolor=COLOR
CONF:Clock:digitalsecondcolor=COLOR
CONF:Clock:digitaldigitcolor=COLOR
CONF:Clock:logopath=PathToLogo
CONF:Clock:logoUpper=[True|False]
CONF:Network:udpport=PORT
CONF:Network:tcpport=PORT
CONF:CONF:APPLY=TRUE

COLOR: can be in the form of Webcolors (#00FF00) or in hex notation (0x00FF00) or one of the SVG named colors (https://www.w3.org/TR/SVG11/types.html#ColorKeywords)