NMOS IP Controller Software BETA

Advanced NMOS IP routing controller. Supports IS-04 (device, sender and receiver discovery), IS-05 (connection management and routing, including ST 2022-7 dual-path), IS-07 (tally and GPIO over WebSocket) and BCP-004-01 receiver capabilities, so a route is only offered where the receiver can actually take the sender.
Setup: Set the IP and port to those of your NMOS Registry's IS-04 Query API, then press Test Connection and, once it reports the registry and its nodes answering, Sync All Devices.
Security: HTTPS and IS-10 bearer token authorization are supported — the token is presented to the nodes as well as to the registry — with an explicit opt-in for certificates this machine cannot verify.
Discovery: the registry can be found over DNS-SD rather than typed in, on multicast DNS or through unicast DNS, reading version, scheme, authorization and priority from its TXT record.
Live: once synced, the device follows the registry's Query API over WebSocket, so equipment appearing or disappearing and routes changed by other control systems arrive on their own.
No registry: a plant without one can be read from the nodes directly, which is the usual Pro AV and IPMX case.
Note: this handler is in Beta. The IS-05 bulk API and scheduled activation are on the roadmap and not in this release.

This guide explains how to use the NMOS IP Controller handler.

There is a full illustrated guide to this handler. It covers NMOS from first principles, building X-Y panels, tally feedback, logical names, plants with no registry, and troubleshooting: Controlling an NMOS plant with Fantago →

Setup

Point the device at your NMOS Registry's IS-04 Query API (IP and port), tick Registry uses HTTPS if it is served over TLS, fill in an IS-10 Bearer Token if the deployment requires one, then press Test Connection followed by Sync All Devices. Only the registry's own scheme is configured here: every other address is published by the registry and followed as given, so a node registered as https:// is reached over TLS regardless. Where a certificate cannot be verified on this machine — an internal CA that is not installed, or a lab certificate — Accept self-signed certificates allows it, and is off by default. Every Sender and Receiver registered there is read in, and the format of each Sender is resolved from the Flow linked to it. The registry has to be found for you: see below.

Finding the registry

Find Registries looks for _nmos-query._tcp and lists what answers. The address is the least of what comes back: a registry announces api_ver, api_proto, api_auth and pri in its TXT record, which is four of the settings on the device page — which IS-04 version, HTTP or HTTPS, whether a bearer token is required, and which registry to prefer where there is more than one. Each of those is a chance to get it wrong, and the registry already knows every answer.

Multicast DNS and unicast DNS are both searched, because they are not alternatives: multicast works on the local link and does not cross a subnet, which suits a small flat plant, while a facility with routed media networks publishes the same records through its ordinary DNS. Whichever is in use, the other finds nothing and says so. Nothing announcing itself is not a fault either — many deployments publish no DNS-SD at all; type the address in that case and everything else behaves the same.

Beside each registry found is Use these settings, which fills the address, port, IS-04 version and scheme into the device form — only the settings the registry actually stated, so one it said nothing about is left as you had it rather than reset to a discovered-looking default. Nothing is saved until you save the device. A bearer token is never filled in: DNS-SD carries no secrets, so a registry that requires one says so and the token is pasted in by hand.

What can be routed into what

A Receiver publishes what it accepts — resolution, frame rate, colour sampling, bit depth, audio channel count — as BCP-004-01 capability sets, and both the Sender dropdown and the route itself are decided on those rather than on both sides merely being video. A UHD camera is not offered for a multiviewer window that tops out at 1080p50, and a button that no longer fits its plant says which parameter is the problem: "MV Window 1" cannot accept "CAM 4": its width is 3840 and the receiver accepts 1920 (1080p50).

Equipment that publishes no capabilities is taken at its word and accepts anything, as are parameters the Sender does not declare and constraints outside the set listed in the in-app guide. A route is refused only where a published constraint is positively broken: a Sender wrongly hidden from a dropdown is far harder to diagnose than one that fails loudly, so the benefit of the doubt goes to showing it.

The comparison needs Flow parameters, which are read by Sync All Devices. After updating the handler, run a sync once; until then there is nothing to compare against and the previous behaviour continues. The Sender dropdown says so in its own label while that is the case, so it cannot be mistaken for a filter that is working.

When equipment is replaced

A button stores two UUIDs and no names. Swap a failed unit for an identical one, or factory-reset it, and it registers under a new UUID, leaving every button aimed at something that no longer exists. It fails rather than misfires — UUIDs are never reused, so the wrong source cannot go to air — but it fails silently until somebody presses the button.

Each sync records what everything is called. When something disappears and exactly one registered resource carries the name it had, the two are matched: the buttons keep working, their feedback keeps lighting, and the sync says so. Where two resources share a name nothing is matched, because guessing between them is the one outcome worse than failing. For whatever is left, Check References walks every panel, Stream Deck profile and Logic Flow driving the device and lists what no longer resolves, with where each one lives and the closest registered name as a hint.

X-Y: one row of destinations, one row of sources

A button per pair is twenty destinations times twenty sources: four hundred buttons. X-Y is forty. Put Select Destination (X-Y) on the destination buttons and Route Source to Selected Destination on the source buttons; both feedback rules are filled in for you. The source rule reads the route variable of whichever destination is selected, so one rule is right for all of them.

The selection is kept per surface and per device: each panel has one, each physical Stream Deck has one, and the device prefix keeps two routers apart. A network trigger, schedule, Logic Flow or API call has no surface and uses a shared selection, which a panel or deck that has chosen nothing yet falls back to. {device_prefix}selected_destination_name holds the readable name for a label above the source row.

Names of your own

A button normally points straight at a Sender and a Receiver by UUID. It can point at a name instead — a name of this installation's, kept in a table on the device page: PGM OUT to a receiver, CAM 1 to a sender.

Suggest Logical Names fills the table in from the plant. Every row starts out repeating the name the equipment registered, so the work is editing the Name column to what the installation actually calls things and deleting the rows you have no use for. The names then appear in every Sender and Receiver dropdown alongside the equipment, each shown as itself — PGM OUT — rather than being grouped, since the Panel Builder sorts a dropdown alphabetically. One rule tells the two apart: equipment carries its format in brackets, [VIDEO] MV Window 1, and a name of yours does not. A row is offered only where it resolves to something in that list, so a row whose equipment has left the plant is offered nowhere — it stays in your table, and the sync names it every time it runs.

Two things follow. When equipment is replaced or repatched you correct one row and every button that used that name follows — feedback included, which is the half that is easy to get wrong. And a panel built entirely out of these names is transportable: take it to another installation, remap the table, and it works there. On a plant that travels, that is the difference between a panel designed once and one designed per job.

Optional and mixable: a button pointing straight at a Receiver behaves exactly as it always has, both kinds can sit in one panel, and a device with an empty table is the device as it was. The table is yours rather than the registry's, so a sync leaves it alone. A logical name is resolved to a UUID and then followed like any other, so everything above about replaced equipment still applies underneath it.

Working without a registry

A registry is the normal architecture of a broadcast facility and stays the default. Much Pro AV and IPMX equipment ships without one: six devices on a switch and nothing aggregating them. Set Where the plant is read from to the nodes themselves and the device asks each node for its own inventory and puts the answers together.

Nodes are found over DNS-SD — the same search, with _nmos-node._tcp in place of _nmos-query._tcp — or typed in, which is what a routed network needs since multicast does not cross a subnet. The search is held for five minutes rather than repeated on every re-read, and can be switched off entirely where the nodes are typed in. Everything downstream is unchanged: capabilities, IS-05 routing, IS-07 tally, logical names, the reference check.

Two differences follow from there being nothing to subscribe to. The plant is re-read on a timer rather than pushed to you, and that interval is a setting. And a node that stops answering keeps the equipment it published last time, because nothing else is holding it — dropping it would break every button aimed at that node for what may be a switch rebooting. The sync names the nodes that went quiet.

Following the registry live

Once synced, the device subscribes to the registry's IS-04 Query API and is told what changes rather than being asked to go and look. Equipment racked during a rehearsal is in the dropdowns without a sync, and — the part that matters more day to day — a receiver switched by another control system arrives here too, because a receiver carries the sender it is connected to in its own registration. The panel follows without Refresh All Route Statuses having been pressed.

It also costs less than asking. A subscription opens with the current state of every receiver, the connected sender included, so the startup sweep that asked each receiver in turn — one HTTP request per receiver, a few hundred on a real installation — is not run while the registry is being followed.

The subscriptions come back when the server restarts and are rebuilt if the registry does; a reconnection is always followed by a full re-read, since whatever changed while the link was down was never sent. A registry that is not answering yet when Fantago starts — the two are usually switched on together, and Fantago tends to win the race — is retried, so the link establishes itself a few seconds later with nothing pressed. A registry that does not offer subscriptions at all costs nothing: the device behaves exactly as it did before, on sync and on the status sweep.

The checkbox works in both directions while the server runs. Clearing Follow the registry live and pressing Sync All Devices closes the subscription; ticking it and syncing opens it again.

Key Actions

• route — connect a Sender to a Receiver. Parameters: dest (receiver UUID) and srce (sender UUID). The SDP manifest is fetched from the Sender and PATCHed into the Receiver's IS-05 staged endpoint with immediate activation.
• disconnect — drop the connection on a Receiver. Parameter: dest.
• check_all_routes — re-read every Receiver's active connection.
• refresh_discovery — re-read the registry.
• test_connection — diagnostics, no parameters. Reports which IS-04 versions the registry offers, what is registered on it, and whether the nodes answer at the addresses the registry published — a registry that answers while its equipment does not is the usual sign of the controller being on a different network from the plant, and nothing else makes that visible until a route fails to activate.
• suggest_logical_names — no parameters. Fills the Logical Names table in from the plant, adding only what is missing and leaving edited names alone.
• discover_registries — no parameters. Searches multicast and unicast DNS-SD for _nmos-query._tcp and reports what answers, ordered by the priority each registry announces.
• check_references — no parameters. Lists every panel button, Stream Deck key and Logic Flow node driving this device whose Sender, Receiver or tally source the registry no longer holds, with where it lives and the nearest registered name.
• set_gpo — drive an IS-07 tally / GPIO output. Parameters: target (tally source UUID) and state (true or false).

Real-time Variables

• <device>_route_<receiver_id>: UUID of the Sender currently routed to that Receiver, or empty when it is disconnected.
• <device>_tally_<sender_id>: ON or OFF for an IS-07 tally source.

A button that shows the route and the tally together

They answer different questions: the route variable says is this destination connected to this source and Fantago writes it when it routes; the tally says is this camera on air and comes from the production switcher over IS-07. Neither implies the other, and a source-selection button usually wants both.

A panel button has two feedback rules. Rule 1 is filled in for you when you choose the Receiver and Sender. Rule 2 is added by hand — condition Variable EQUALS Custom Text, and the field takes the variable and value together, {device_prefix}tally_tally_cam_1=ON — because nothing in IS-04 says which tally source belongs to which camera. They are separate resources with separate UUIDs, often on a different node, and this handler will not guess the pairing on your behalf.

A tally source publishes under its UUID, under its label with anything that is not a letter or digit turned into an underscore, and under its logical name if it has one. NMOS Explorer lists every tally source with the whole rule beside it, ready to copy, and Browse beside the field shows what each variable holds right now.

Buttons that name themselves

Every Sender, Receiver and tally source also publishes its registered name: <device>_sender_label_<sender_id>, <device>_receiver_label_<receiver_id> and <device>_tally_label_<sender_id>.

Put one of those in a button's text rather than typing the name, and the button says whatever the registry says. Rename a camera on the equipment and at the next sync every button showing it follows, with nothing to open. On a plant where sources are renamed per production, that is the difference between a panel rebuilt each time and one built once. The names are also written under the identity a button was built with when equipment has been replaced, so a repaired button keeps its face as well as its function. The UUID to use is the one the button already routes to, listed beside each name in the device page's NMOS Explorer.

Integration Examples (assuming device name "NMOS_CTRL")

Via HTTP GET:

http://<FantaGo_IP>:<HTTP_PORT>/sendTo/NMOS_CTRL?cmd=route&action_params={"dest":"receiver-uuid","srce":"sender-uuid"}

http://<FantaGo_IP>:<HTTP_PORT>/sendTo/NMOS_CTRL?cmd=disconnect&action_params={"dest":"receiver-uuid"}