====== OnAirScreen API / UDP / HTTP / MQTT / OSC ======
OnAirScreen accepts the same command strings over **UDP** (default port **3310**), **HTTP** (default port **8010**), **MQTT**, **OSC**, **SNMP**, and the **Web UI**. Raspberry Pi GPIO and Axia Livewire GPIO map mixer contacts to the same LED/AIR commands locally; they are not a network API.
Complete manuals: [[onairscreen:manual-en|User Manual]] §7 · [[onairscreen:manual-de|Bedienungsanleitung]] §7 · [[onairscreen:mib-en|SNMP MIB]] · [[oas:funktionstasten|Hotkeys]]
Replace the IP address with the IP of your OnAirScreen. It is shown in the first footer line after start (press **I** to show it again).
===== UDP (port 3310) =====
Set LED1 text and switch it on:
echo "CONF:LED1:text=FOO" > /dev/udp/127.0.0.1/3310
echo "CONF:CONF:APPLY=TRUE" > /dev/udp/127.0.0.1/3310
echo "LED1:ON" > /dev/udp/127.0.0.1/3310
On **Windows**, shop builds include ''oas_send.exe'' (UDP client):
oas_send.exe --ip 192.168.23.5 "LED1:ON"
''oas_send-noconsole.exe'' does the same without opening a console window (use it from playout scripts):
oas_send-noconsole.exe --ip 192.168.23.5 "LED1:ON"
===== HTTP (port 8010) =====
Strings must be URL-encoded:
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 =====
**Status** (JSON: LEDs, AIR timers, NOW/NEXT/WARN, silence, loudness I+LRA, instance, version):
curl http://127.0.0.1:8010/api/status
For AIR3, ''topOfHour'' is the Top-of-Hour countdown and ''countDown'' is true while the radio timer is counting down. ''silence'' is independent of the on-screen WARN. ''lufsI'' and ''lra'' are ''null'' until enough audio has been measured.
**Command:**
curl "http://127.0.0.1:8010/api/command?cmd=LED1:ON"
**Web settings** (optional PIN via ''X-Settings-Token'' after ''POST /api/settings/auth''): see the manuals. HTTP ''CMD:REBOOT'' / ''CMD:SHUTDOWN'' require that PIN when one is set. UDP, MQTT, OSC, GPIO, and SNMP stay unauthenticated.
===== Web UI =====
Open ''http://127.0.0.1:8010/'' (or the instance IP) in a browser.
* Live status for LEDs, AIR timers, NOW/NEXT/WARN, silence, and loudness I+LRA
* WebSocket updates (HTTP polling fallback; WebSocket port is HTTP **+ 1**, default **8011**)
* Dark mode, warning priorities, LED/AIR/I+LRA controls, Top-of-Hour, AIR3 time input
* Keys ''1''–''4'' toggle LEDs (ignored while typing)
* Settings overlay (optional PIN), Livewire/AES67 pickers, presets
* Connection badge (Live / Polling / Offline)
===== MQTT / Home Assistant =====
Configure MQTT under **Settings → Network** (server, port, username, password, device name).
The **base topic** is ''onairscreen'' plus the last 6 hex characters of the MAC address, e.g. ''onairscreen_a1b2c3''. Autodiscovery creates LED and AIR switches, AIR time sensors, AIR3/AIR4 reset, AIR3 Top-of-Hour, NOW/NEXT/WARN text, Warning/Silence binary sensors, instance sensor, and loudness I+LRA switch/reset/sensors. The Home Assistant device name becomes ''OnAirScreen (Studio-1)'' unless the instance name is already in the MQTT device name.
**Command topics** (payload as shown):
^ Topic ^ Payload ^
| ''{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'' |
| ''{base_topic}/air3/toh'' | ''ON'' / ''OFF'' / ''TOGGLE'' |
| ''{base_topic}/lufs/integrated/set'' | ''ON'' / ''OFF'' / ''TOGGLE'' / ''RESET'' |
| ''{base_topic}/lufs/integrated/reset'' | ''PRESS'' |
| ''{base_topic}/text/now/set'' | text |
| ''{base_topic}/text/next/set'' | text |
| ''{base_topic}/text/warn/set'' | text |
**Status topics** (published automatically):
^ Topic ^ Payload ^
| ''{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}/air3/toh/state'' | ''true'' / ''false'' |
| ''{base_topic}/text/{now,next,warn}/state'' | text |
| ''{base_topic}/warning/active'' | ''true'' / ''false'' |
| ''{base_topic}/silence/active'' | ''true'' / ''false'' |
| ''{base_topic}/lufs/integrated/state'' | ''ON'' / ''OFF'' |
| ''{base_topic}/lufs/i'' | I in LUFS (empty if unknown) |
| ''{base_topic}/lufs/lra'' | LRA in LU (empty if unknown) |
| ''{base_topic}/instance/state'' | instance name |
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/led1/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/air3/toh -m "TOGGLE"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/lufs/integrated/set -m "ON"
mosquitto_pub -h mqtt-broker -t onairscreen_a1b2c3/text/now/set -m "Current Song"
===== Bitfocus Companion =====
The [[https://github.com/bitfocus/companion-module-astrastudio-onairscreen|astrastudio OnAirScreen module]] drives Stream Decks over HTTP (''GET /api/command'') and live status over WebSocket (HTTP port + 1) with poll fallback to ''/api/status''. OSC is not required. See the manuals §7.6. Generic OSC remains a fallback.
===== OSC (port 8000) =====
Enable OSC under **Settings → Network**. Prefix is ''/oas''. Integers ''1''/''0'' mean ON/OFF; no argument means TOGGLE. Text uses a string argument. Full address list: manuals §7.7.
python3 utils/oas_osc_send.py /oas/led1
python3 utils/oas_osc_send.py /oas/led1 1
===== SNMP (port 1161) =====
Enable SNMP under **Settings → Network**. SNMPv2c and SNMPv3 (SHA-256, AES-128). Default listen port **1161**. MIB, OIDs, and SET/trap notes: [[onairscreen:mib-en|onairscreen:mib-en]].
===== Command reference =====
These strings work on UDP, HTTP ''?cmd='', REST ''/api/command'', MQTT (via the mapped topics or raw command), OSC ''/oas/command'', and SNMP ''oasCommand''.
{{tablelayout?rowsHeaderSource=Auto&tableSort=1&tableSearch=1}}
^ Command ^ Function ^
| ''LED{1-4}:[ON/OFF/TOGGLE]'' | Switch LED |
| ''NOW:TEXT'' | Set NOW (first footer line) |
| ''NEXT:TEXT'' | Set NEXT (second footer line) |
| ''WARN:TEXT'' | Warning, priority 0 |
| ''WARN:1:TEXT'' | Warning, priority Medium |
| ''WARN:2:TEXT'' | Warning, priority High |
| ''WARN:'' | Clear priority 0 |
| ''WARN:1:'' | Clear priority 1 |
| ''WARN:2:'' | Clear priority 2 |
| ''AIR1:[ON/OFF/TOGGLE]'' | Microphone timer |
| ''AIR2:[ON/OFF/TOGGLE]'' | Phone timer |
| ''AIR3:[ON/OFF/RESET/TOGGLE]'' | Radio timer |
| ''AIR3TIME:seconds'' | Set radio timer (seconds) |
| ''AIR3TOH:[ON/OFF/TOGGLE]'' | Top-of-Hour countdown on AIR3 |
| ''AIR4:[ON/OFF/RESET/TOGGLE]'' | Stream timer |
| ''LUFSI:[START/STOP/TOGGLE/RESET]'' | Programme I + LRA (reset restarts if running, hides I+LRA if stopped) |
| ''FULLSCREEN:[ON/OFF/TOGGLE]'' | Main window fullscreen |
| ''CMD:REBOOT'' | OS reboot (HTTP requires Web Settings PIN when set) |
| ''CMD:SHUTDOWN'' | OS shutdown (HTTP requires Web Settings PIN when set) |
| ''CMD:QUIT'' | Quit OnAirScreen |
===== Remote configuration (CONF) =====
Format: ''CONF:GROUP:PARAMETER=VALUE''. Changes are applied and saved only after ''CONF:CONF:APPLY=TRUE''.
{{tablelayout?rowsHeaderSource=Auto&tableSort=1&tableSearch=1}}
^ Command ^ Description ^
| ''CONF:General:stationname=TEXT'' | Station name |
| ''CONF:General:instancename=TEXT'' | Instance name (DNS label) |
| ''CONF:General:slogan=TEXT'' | Slogan |
| ''CONF:General:stationcolor=COLOR'' | Station color |
| ''CONF:General:slogancolor=COLOR'' | Slogan color |
| ''CONF:General:replacenow=[True/False]'' | Replace IPs after 10 s |
| ''CONF:General:replacenowtext=TEXT'' | Replacement text |
| ''CONF:LED[1-4]:used=[True/False]'' | Enable LED |
| ''CONF:LED[1-4]:text=TEXT'' | LED text |
| ''CONF:LED[1-4]:activebgcolor=COLOR'' | LED active background |
| ''CONF:LED[1-4]:activetextcolor=COLOR'' | LED active text |
| ''CONF:LED[1-4]:autoflash=[True/False]'' | Autoflash |
| ''CONF:LED[1-4]:timedflash=[True/False]'' | 20-second flash |
| ''CONF:Clock:face=FACE'' | ''digital'', ''analog'', ''analog_numbers'', ''analog_studio'', ''analog_railway'', ''analog_24h_smooth'', ''analog_24h_ticking'' |
| ''CONF:Clock:digital=[True/False]'' | Digital / classic analog (legacy) |
| ''CONF:Clock:showseconds=[True/False]'' | Show seconds |
| ''CONF:Clock:secondsinoneline=[True/False]'' | Seconds on one line |
| ''CONF:Clock:staticcolon=[True/False]'' | Static colon |
| ''CONF:Clock:digitalhourcolor=COLOR'' | Hour color |
| ''CONF:Clock:digitalsecondcolor=COLOR'' | Seconds color |
| ''CONF:Clock:digitaldigitcolor=COLOR'' | Digit color |
| ''CONF:Clock:logopath=PATH'' | Logo path |
| ''CONF:Clock:logoupper=[True/False]'' | Logo on top |
| ''CONF:Network:udpport=PORT'' | UDP port |
| ''CONF:Network:tcpport=PORT'' | HTTP port |
| ''CONF:Audio:enabled=[True/False]'' | Audio meters on/off |
| ''CONF:Audio:source=[device/livewire/aes67]'' | Audio source |
| ''CONF:Audio:input_device=DEVICE_NAME'' | Local input device |
| ''CONF:Audio:livewire_channel=N'' | Livewire channel |
| ''CONF:Audio:livewire_iface=IP_OR_EMPTY'' | AoIP interface IP |
| ''CONF:Audio:aes67_id=ORIGIN_HASH'' | AES67 stream id |
| ''CONF:Audio:aes67_addr=MULTICAST'' | AES67 multicast |
| ''CONF:Audio:aes67_port=PORT'' | AES67 RTP port |
| ''CONF:Audio:aes67_name=NAME'' | AES67 display name |
| ''CONF:Audio:aes67_codec=[L16/L24]'' | AES67 codec |
| ''CONF:Audio:aes67_rate=48000'' | AES67 sample rate |
| ''CONF:Audio:aes67_channels=2'' | AES67 channel count |
| ''CONF:Audio:aes67_manual=[True/False]'' | AES67 pasted SDP |
| ''CONF:Audio:unit=[dbfs/dbtp/bbc_ppm]'' | L/R display unit |
| ''CONF:Audio:layout=[lr/lufs/both]'' | Meter layout |
| ''CONF:Audio:display_style=[solid/bargraph]'' | Meter style |
| ''CONF:Audio:meter_width=79'' | Meter width (pixels) |
| ''CONF:Audio:lufs_reference_preset=PRESET'' | LUFS preset |
| ''CONF:Audio:lufs_reference=-23.0'' | LUFS target |
| ''CONF:Audio:peak_hold=[True/False]'' | Peak hold on/off |
| ''CONF:Audio:peak_hold_seconds=1.5'' | Peak hold duration |
| ''CONF:Audio:tooloud=[True/False]'' | TooLoud on/off |
| ''CONF:Audio:tooloudtext=TEXT'' | TooLoud text |
| ''CONF:Audio:tooloud_threshold_dbtp=-1.0'' | TooLoud threshold |
| ''CONF:Audio:tooloud_action=[warning/led]'' | TooLoud action |
| ''CONF:Audio:tooloud_led=[1/2/3/4]'' | TooLoud LED |
| ''CONF:Audio:silence=[True/False]'' | Silence Detection |
| ''CONF:Audio:silence_warn=[True/False]'' | Silence WARN on/off |
| ''CONF:Audio:silence_on_absent=[True/False]'' | Absent as silence |
| ''CONF:Audio:silence_text=TEXT'' | Silence WARN text |
| ''CONF:Audio:silence_threshold_dbfs=-50.0'' | Silence threshold |
| ''CONF:Audio:silence_duration_s=10.0'' | Silence duration (s) |
| ''CONF:Audio:silence_recovery_s=2.0'' | Silence recovery (s) |
| ''CONF:Audio:silence_http_url=URL'' | Silence HTTP GET URL |
| ''CONF:Timers:TimerAIR[1-4]Enabled=[True/False]'' | Enable AIR |
| ''CONF:Timers:TimerAIR[1-4]Text=TEXT'' | AIR label |
| ''CONF:Timers:TimerTOTHText=TEXT'' | TOTH timer label |
| ''CONF:Timers:AIR[1-4]activebgcolor=COLOR'' | AIR active background |
| ''CONF:Timers:AIR[1-4]activetextcolor=COLOR'' | AIR active text |
| ''CONF:Timers:AIR[1-4]iconpath=PATH'' | AIR icon path |
| ''CONF:Timers:TimerAIRMinWidth=PIXELS'' | AIR minimum width |
| ''CONF:CONF:APPLY=TRUE'' | Apply configuration |
''CONF:Audio:unit=lufs'' is still accepted as an alias that sets layout to ''lufs'' (L/R unit stays ''dbtp'').
**Colors:** web hex (''#00FF00''), ''0x00FF00'', or [[https://www.w3.org/TR/SVG11/types.html#ColorKeywords|SVG named colors]].
===== Current title from playout =====
HTTP GET or UDP ''NOW:'' / ''NEXT:'' — see the howtos on [[start|the wiki start page]] (mAirList, Myriad, PlayoutONE, ProppFrexx, RadioBOSS, RadioDJ, StationPlaylist, RCS Zetta).