Differences

This shows you the differences between two versions of the page.

--- oas:api [02.01.2023 22:09] – admin
+++ oas:api [20.09.2026 00:27] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-<markdown>
+====== OnAirScreen API / UDP / HTTP / MQTT / OSC ======
-# OnAirScreen API / UDP / HTTP Commands
-OnAirScreen can receive API commands via UDP default port 3310 or HTTP default port 8010\\
+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.
-Here is an easy UDP example on how to control a local OnAirScreen instance on a linux system.
-</markdown>
+Complete manuals: [[onairscreen:manual-en|User Manual]] §7 · [[onairscreen:manual-de|Bedienungsanleitung]] §7 · [[onairscreen:mib-en|SNMP MIB]] · [[oas:funktionstasten|Hotkeys]]
 <WRAP center round info 60%>
-Replace the IP address with the IP address of your OnAirScreen. This will be shown in the first footer line of OnAirScreen after start.
+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).
 </WRAP>
-<markdown>
+===== UDP (port 3310) =====
-Set LED1 Text to "FOO" and switch LED1 on:
+Set LED1 text and switch it on:
-```
+<code>
 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
-```
+</code>
-To remotely control an OnAirScreen from Windows, use the oas_send.exe which is part of the OAS Windows License:
+On **Windows**, shop builds include ''oas_send.exe'' (UDP client):
-```
+<code>
 oas_send.exe --ip 192.168.23.5 "LED1:ON"
-```
+</code>
+''oas_send-noconsole.exe'' does the same without opening a console window (use it from playout scripts):
+<code>
+oas_send-noconsole.exe --ip 192.168.23.5 "LED1:ON"
+</code>
+===== HTTP (port 8010) =====
+Strings must be URL-encoded:
+<code>
+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"
+</code>
+===== REST =====
+**Status** (JSON: LEDs, AIR timers, NOW/NEXT/WARN, silence, loudness I+LRA, instance, version):
+<code>
+curl http://127.0.0.1:8010/api/status
+</code>
+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:**
+<code>
+curl "http://127.0.0.1:8010/api/command?cmd=LED1:ON"
+</code>
+**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 |
+<code>
+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"
+</code>
+===== 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.
+<code>
+python3 utils/oas_osc_send.py /oas/led1
+python3 utils/oas_osc_send.py /oas/led1 1
+</code>
+===== 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''.
-##### HTTP API
+{{tablelayout?rowsHeaderSource=Auto&tableSort=1&tableSearch=1}}
-You can also pass commands to OAS via HTTP. Strings need to be urlencoded.
+^ 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''.
-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
-```
-##### API Commands
+{{tablelayout?rowsHeaderSource=Auto&tableSort=1&tableSearch=1}}
-</markdown>
+^ 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 |
-| UDP Command         | Function |
+''CONF:Audio:unit=lufs'' is still accepted as an alias that sets layout to ''lufs'' (L/R unit stays ''dbtp'').
-| `LED1:[ON/OFF]`     | switch LED1 on/off |
-| `LED2:[ON/OFF]`     | switch LED2 on/off |
-| `LED3:[ON/OFF]`     | switch LED3 on/off |
-| `LED4:[ON/OFF]`     | switch LED4 on/off |
-| `NOW:TEXT`               | set TEXT in first footer line |
-| `NEXT:TEXT`              | set TEXT in second footer line |
-| `WARN:TEXT`              | set TEXT and switch on red warning mode |
-| `AIR1:[ON/OFF]`          | start/stop Mic Timer |
-| `AIR2:[ON/OFF]`          | start/stop Phone Timer |
-| `AIR3:[ON/OFF/RESET/TOGGLE]` | start/stop/reset/toggle Radio Timer |
-| `AIR3TIME:seconds`            | set Radio Timer to given value in seconds |
-| `AIR4:[ON/OFF/RESET]`        | start/stop/reset Stream Timer |
-| `CMD:REBOOT`                  | OS restart |
-| `CMD:SHUTDOWN`                | OS shutdown |
-| `CMD:QUIT`                    | quit OnAirScreen instance |
-<markdown>
+**Colors:** web hex (''#00FF00''), ''0x00FF00'', or [[https://www.w3.org/TR/SVG11/types.html#ColorKeywords|SVG named colors]].
-##### 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: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`
-</markdown>
-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)
+===== 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).