Controlling an NMOS plant with Fantago

01What this replaces

A router control panel for a plant that no longer has a router.

In an SDI facility there is a router, and in front of it a control panel: a row of buttons for the destinations, a row for the sources, and a crosspoint made when you press one and then the other. The panel is a piece of hardware from the router manufacturer, it speaks that manufacturer's protocol, and it does one job well.

An ST 2110 plant has no router in that sense. The switch fabric carries multicast streams, each device puts its own essences on the network, and "making a crosspoint" means telling a receiver which stream to join. NMOS — a set of open specifications from AMWA — is how a controller finds out what exists on the network and tells it what to do. The Fantago NMOS IP Controller handler is that controller, and a Fantago panel is that control panel: the same two rows of buttons, built by you, running on a browser, a touchscreen, a Stream Deck or all three at once.

Everything else Fantago does is available in the same panel. A button that routes a camera to a multiviewer window can, in the same press, cut the production switcher, arm a recorder and fire a graphic — because they are all just actions, and NMOS is one more device among them.

02Five minutes to a working route

The short path, for a plant that has a registry. Every step has a section of its own later.

1. Add the device. Dashboard → Devices → new device, handler NMOS IP Controller. Put the address and port of your registry's IS-04 Query API in the IP and Port fields — or press Find Registries and let it fill them in. Save.
2. Press Test Connection. It answers in four lines: the registry, what is registered on it, whether the nodes themselves answer, and how the connection is secured. Read the third line in particular — a registry that answers while its equipment does not is the classic sign of a controller sitting on the wrong network, and it stays invisible until a route fails.
3. Press Sync All Devices. Fantago reads every sender, receiver and tally source and caches them. You should see a green line counting what it found.
4. Build a button. Panel Builder → new panel → drop a button → Actions → Device Command → your NMOS device → Route: Connect Sender to Receiver. Choose the Receiver first, then the Sender: the sender list is filtered to what that receiver can actually accept. The feedback rule that lights the button is written for you.
5. Open the panel and press it. The button lights from the route's real state, read back from the receiver — not from the fact that you pressed it.

03The ideas you need

Five of them, and one distinction that causes more confusion than everything else put together.

Control plane and media plane

Two separate things travel on the network. The media plane carries the essences — video, audio, ancillary data — as multicast RTP streams between devices. The control plane is ordinary HTTP and WebSocket traffic: a controller asking what exists and telling a receiver what to join. NMOS lives entirely in the second one, and so does Fantago.

Nodes, senders and receivers

Every piece of equipment that speaks NMOS is a node: a camera, a multiviewer, a gateway, a software processor. Each node publishes what it offers and what it can take:

• A Sender is an essence the node puts on the network — a camera's video, one audio group, a data stream. A single camera typically has several.
• A Receiver is an input the node can point at a sender — a multiviewer window, a monitor feed, a switcher input.

"Routing" is pointing one receiver at one sender. Nothing is reserved and nothing is exclusive: the same sender can feed twenty receivers at once, because on a multicast network they simply all join the same stream.

The registry

Nodes register themselves with an NMOS registry, which holds the directory of the whole plant and answers questions about it through the IS-04 Query API. This is what Fantago points at. A registry is the normal architecture of a broadcast facility; a plant without one is read node by node instead, which is section 9.

The specifications, in one line each

Why everything is a UUID

Every sender, receiver, node and tally source is identified by a UUID, and names are only labels attached to them. This is deliberate: two devices may be called "CAM 1", a device may be renamed between productions, and a label is not a safe thing to route on. So a Fantago button stores UUIDs, which means it cannot ever send the wrong source to air — and it also means that when equipment is replaced the button points at something that no longer exists. That is section 8, and there is machinery for it.

A tally is not a route

A camera can be routed to a multiviewer window without being on air, and it can be on air while that window is showing something else. They are separate questions about the same camera, and an operator panel usually wants to answer both at once — the button filled in because this is the source currently feeding the destination, outlined in red because that camera is live.

There is one more consequence, and it catches people: nothing in NMOS says which tally source belongs to which camera. They are separate resources, with separate UUIDs, frequently on a different node altogether. Fantago will not guess the pairing on your behalf — you state it once, when you build the button, and section 5 shows how.

04Finding the registry, and proving you can reach the plant

Two buttons that between them answer most of the questions a commissioning engineer has.

Find Registries

A registry usually announces itself over DNS-SD as _nmos-query._tcp. Find Registries searches for it and lists what answers — and what comes back is worth more than an address. A registry publishes api_ver, api_proto, api_auth and pri in its TXT record, which is four of the settings on this 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 be wrong, and the registry already knows every answer.

Both transports are searched, because they are not alternatives. Multicast DNS works on the local link and does not cross a subnet, which suits a small flat plant with no DNS server. Unicast DNS is how 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. The unicast half needs a domain: this machine's own search domain is used unless DNS-SD domain is filled in.

Nothing is saved by pressing Use these settings: the fields are filled and left dirty, so you can read them, correct anything that needs it, and then save. A bearer token is never among them — DNS-SD carries no secrets — so a registry that requires one says so, and the token is pasted in by hand.

Test Connection

The four rows answer four different questions, and they fail independently:

Sync All Devices, and following the registry live

Sync All Devices reads the whole inventory into Fantago. You need it once at the start and after a plant change; the rest of the time the device keeps itself up to date, because once synced it subscribes to the registry's Query API and is told what changes instead of being asked to go and look. Two things follow:

• Equipment appearing and disappearing. A camera racked during a rehearsal is in the dropdowns without a sync; one switched off leaves them.
• Routes changed by something other than Fantago. A receiver carries the sender it is connected to in its own registration, so another control system switching it arrives here and the panel follows on its own.

It also costs less than asking. A subscription opens with the current state of every receiver, so the startup sweep that would otherwise ask each receiver in turn — one HTTP request per receiver, a few hundred on a real installation — is not run at all while the registry is being followed. Refresh All Route Statuses remains, and is now mostly a way of asking the equipment directly rather than believing the registry's account of it.

A registry that does not offer subscriptions costs nothing: the log says so once and the device behaves as it did before. Reconnection after a dropped link is always followed by a full re-read, because whatever changed while the link was down was never sent.

05Building panels

One button, then forty buttons instead of four hundred, then making them light correctly.

A single route button

In the Panel Builder — or the Stream Deck Builder, which works the same way — give a button an action of type Device Command, choose the NMOS device, and pick Route: Connect Sender to Receiver. Two dropdowns appear. Choose the Receiver first: the Sender list is then filtered to the senders that receiver can actually take (section 7).

The other actions on the same list:

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

A button per pair on a plant with twenty destinations and twenty sources is four hundred buttons. The X-Y arrangement is forty: one row that chooses which destination you are working on, one row that acts on whichever is chosen.

The selection is kept per surface and per device. Each panel has its own, and so does each physical Stream Deck, so two operators — or a panel on a laptop and a deck on the desk — each work on their own destination without moving the other's. And because the variable carries the device's prefix, two routers driven from one panel do not share a selection either. A network trigger, a schedule, a logic flow or the HTTP API has no surface of its own, so those share one selection, and a panel that has chosen nothing yet falls back to it rather than refusing.

Feedback rules — making a button light

A Fantago button has two feedback rules, each comparing a variable and applying a style. For an NMOS source button that is exactly right: one rule for the route, one for the tally.

Rule 1 — the route (written for you)

Choose the action, pick the receiver and sender, and the rule arrives with the button: condition Variable EQUALS Button Value, the variable being the receiver's route variable, and the button's Value being the sender.

Rule 2 — the tally (added by you, once)

Nothing in IS-04 states which tally source belongs to which camera, so this is the one pairing you declare yourself. Condition Variable EQUALS Custom Text, and in the field the variable and the value together in one string:

nmos_ip_controller_tally_cam_2_tally=ON

You do not have to work that line out. NMOS Explorer — click the device's name on the Dashboard — lists every tally source with the whole rule beside it, ready to copy:

The Receivers table does the same for routes, so there is never a need to work out how a variable name is built:

The variables, for reference

A tally source publishes its state under three names and any of them works: its UUID, its registered label with anything that is not a letter or a digit turned into an underscore (Tally CAM 1 → tally_cam_1), and its logical name if you have given it one.

Buttons that name themselves

Put {{nmos_ip_controller_sender_label_<uuid>}} in a button's text instead of 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 and nothing to remember. On a plant where cameras are renamed per production, that is the difference between a panel rebuilt each time and one built once.

06Names of your own

Optional, and the single feature most likely to save a rebuild later.

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.

Press Suggest Logical Names to have the table filled in from the plant. Every row starts out repeating the name the equipment registered, so nothing is decided yet: the work is editing the Name column to what this installation actually calls things, and deleting the rows you have no use for. Then save the device.

The names then appear in every Sender and Receiver dropdown alongside the equipment itself, each one saying what it is:

[VIDEO] MV Window 1     the receiver, as the registry has it
PGM OUT                 your name for it

One rule, no exceptions to remember: equipment carries its format in brackets, a name of yours does not. So a bare entry is always one of yours, including a row you have not renamed yet. They are not grouped or listed first, because the Panel Builder sorts a dropdown alphabetically.

What it buys you

• One correction instead of many. When equipment is replaced or repatched you correct one row, and every button that used that name follows — including its feedback, which is the half that is easy to get wrong.
• A transportable panel. A panel built entirely out of these names can be taken 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.
• Readable feedback. State is published a second time under the logical name — PGM OUT becomes {prefix}route_pgm_out — and the logical variable holds the logical name of the connected sender, so remapping the table moves the feedback with it rather than leaving buttons dark.

A row is offered only where it resolves to something in that list: a row naming a receiver is not offered among the senders, and a row whose equipment has left the plant is not offered anywhere, since a button built on it could only fail. The row stays in your table — it is yours — and the sync counts it every time it runs, so it is reported rather than hidden.

The names are yours, so they survive a sync: syncing rewrites the inventory and leaves the table alone.

07What can be routed into what

Why a source you expected is not in the list — and why that is the list being right.

A receiver publishes what it is able to accept — resolution, frame rate, colour sampling, bit depth, audio channel count — as BCP-004-01 capabilities. Both the Sender dropdown and the route itself are decided on those, rather than on both sides merely reading as "video". A UHD camera is not offered for a multiviewer window that tops out at 1080p50.

The same check runs again when the button is pressed, because a button can outlive the plant it was built against: a receiver replaced by a lesser one still holds its UUID in the button, and a sender that fitted last month may not fit now. The refusal names the parameter:

"MV Window 1" cannot accept "CAM 4 (UHD)": its width is 3840
and the receiver accepts 1920 (1080p50).

Where a receiver's capabilities exclude everything on the plant, the dropdown says so in place of being empty — "None of the 6 senders match this receiver's capabilities" — because a receiver nothing fits and a registry that returned nothing look identical otherwise.

The benefit of the doubt

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 ones listed above. A route is refused only where a published constraint is positively broken. This is deliberate: a sender wrongly hidden from a dropdown is much harder to diagnose than one that fails loudly with a reason.

08When the plant changes

Replaced units, factory resets, repatching — and the two tools that keep a panel true.

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

Automatic repair, where it is safe

Each sync records what everything is called. When something disappears and exactly one registered resource now carries the name it had, the two are matched up: the buttons keep working, their feedback keeps lighting, and the sync says so in its result and in the log. Where two resources share a name, nothing is matched — guessing between them is the one outcome worse than failing — and where the name is gone entirely there is nothing to match against.

Check References

For everything that could not be repaired, Check References walks every panel, Stream Deck profile and logic flow that drives this device and lists what no longer resolves: where each one lives, and the closest registered name as a hint. It prevents nothing; it puts the whole set in one place, at a moment of your choosing, rather than one at a time during a show. Run it after a plant change, once the sync is done.

It also separates two faults that look alike and have different fixes: a button naming a logical row that does not exist, and a logical row pointing at equipment that is gone. The first is repaired in the button, the second in one row of the table.

09Working without a registry

The usual Pro AV and IPMX case: six devices on a switch and nothing aggregating them.

A registry is the normal architecture of a broadcast facility and stays the default. A great deal of Pro AV and IPMX equipment ships without one. Set Where the plant is read from to the nodes themselves and Fantago asks each node for its own inventory and puts the answers together — which is what a registry would otherwise have done.

Where each address goes

The addresses that matter here are the nodes', and they go in Nodes — or are left to DNS-SD. The device's own IP and Port describe a registry, and there is none, so nothing above depends on them. The form requires an address all the same, which leaves the question of what to type:

In particular this is not a case for localhost. That would mean the equipment runs on the same machine as Fantago, which is only ever true of a simulator.

Nodes are found over DNS-SD, the same search that finds a registry with _nmos-node._tcp in place of _nmos-query._tcp. Multicast DNS does not cross a subnet, so on a routed network type them into Nodes instead — 172.16.1.80:8011, 172.16.1.81:8011. Typed-in nodes and announced ones are both used; the same node reached both ways is one node.

Everything downstream is unchanged: capabilities decide what may be routed where, IS-05 carries the route, IS-07 carries tally, logical names and the reference check work exactly as they do against a registry. Two things are different, and both follow from there being nothing to subscribe to:

• The plant is re-read on a timer rather than pushed to you, so How often to re-read the nodes is the freshness of both the inventory and the route state. Set it to 0 to re-read only when Sync All Devices is pressed.
• A node that stops answering keeps the equipment it published last time, because there is no registry still holding it. Dropping it would empty the dropdowns and break every button aimed at that node for what may be a switch rebooting. The sync says which nodes went quiet and how much is being kept.

The DNS-SD result is held for five minutes rather than repeated on every pass: a multicast search waits for its whole timeout, and doing that every twenty seconds would put a stall into each read for an answer that changes when equipment is racked, not between one read and the next. Where the nodes are typed in and nothing needs finding, set DNS-SD search time to 0 and no search runs at all. Typed-in nodes are never cached — they are settings, and a setting that has just been changed takes effect at once.

Test Connection reports each node separately — found how, answered or not, what it holds, whether it publishes an IS-05 control — because on a routed network "nothing was found" and "nothing is switched on" look identical from a panel.

10Security

HTTPS, IS-10 bearer tokens, and an honest account of what is not protected.

HTTPS

Registry uses HTTPS sets the scheme for the registry only. Every other address comes from the registry itself and is followed as published, so a node registered as https:// is reached over TLS whatever that checkbox says — which is the correct behaviour in a mixed deployment.

IS-10 bearer token

Leave it empty where the deployment is open. Where it is not, the token is presented to every API in the deployment, the nodes included, because under IS-10 a controller holds one token rather than one per device. It is stored with the device's configuration in Fantago's database and is never sent anywhere except to the plant it belongs to; a registry found over DNS-SD never supplies one, since DNS-SD carries no secrets.

Certificates this machine cannot verify

Accept self-signed certificates is off by default and worth leaving off. Tick it only for a registry whose certificate this machine has no way to verify — an internal CA that is not installed here, or a lab certificate. It disables verification for this device's connections, which trades a real protection for convenience.

What is not encrypted

NMOS secures the control plane. The media plane is ST 2110 over the fabric and is unaffected by any of these settings — protecting it is a matter of network design, not of the controller. And the panels themselves are Fantago's own surface: who may open them, and from which machines, is governed by Fantago's users and its security settings, which apply to an NMOS panel exactly as to any other.

11What this touches, and what it does not

For the engineer who has to approve a controller pointing at a live plant.

The handler writes to the plant in four places, and nowhere else:

Everything else is read-only on the equipment: Test Connection, Sync All Devices, Refresh All Route Statuses, Find Registries, Check References and Suggest Logical Names all ask questions and write nothing. The subscription is marked non-persistent, so the registry discards it by itself if Fantago goes away.

Not in this release

The handler is in beta, and two things on the roadmap are worth stating plainly rather than leaving to be discovered:

• The IS-05 bulk API and scheduled activation. Routes are made one receiver at a time, immediately. A button that switches several destinations at once is built today as several actions on one button, which works and is not the same thing as an atomic salvo.
• Setting a GPO is outside what IS-07 promises. The specification describes /state as something to read, with updates published by whoever owns the source. Writing it over REST is accepted by some equipment and ignored by other equipment. Reading tally is fully standard; setting one depends on the device.

12Troubleshooting

Symptoms in the order they tend to appear, each with the check that settles it.

The registry answers but nothing routes

Read the Nodes line of Test Connection. A registry reachable while its equipment is not means the control machine is on a different network from the plant, or a firewall sits between them — the registry publishes the nodes' addresses, and Fantago has to reach those addresses directly to route anything.

A source is missing from the Sender dropdown

Almost always receiver capabilities: that receiver cannot accept that sender, and the list is right (section 7). If the dropdown's own label says the list was read before the capability check existed, run Sync All Devices once.

The button routes, but stays dark

Routing and feedback are separate mechanisms, so one working proves nothing about the other. Check that rule 1 is Variable EQUALS Button Value, that the variable is the receiver's route variable exactly as NMOS Explorer gives it, and that the button's Value is the sender's UUID. Browse beside the variable field also shows what each variable holds right now, which answers the question that usually comes next: whether the rule is wrong or the state is simply not what you assumed.

The tally rule never lights

The tally rule is not built like the route rule. Condition must be Variable EQUALS Custom Text, and the field holds the variable and the value together — …tally_cam_2_tally=ON — not the variable alone. Copy the whole string from the Tally sources table in NMOS Explorer and it is correct by construction.

Both rules were fine separately, and now one of them is not

They are two rules on one button, not one rule that does two things. Rule 1 watches the route variable and compares against the button's Value; rule 2 watches the tally variable and compares against a fixed string. Editing one must not change the other — if the route stopped lighting when the tally was added, the route rule's condition or Value was changed with it.

A tally that never goes out, or never comes on

Tally state arrives over IS-07 from whoever owns the source, and the variable holds the last state published. Check the Connection line of Test Connection, then use Browse to watch the variable while the state is changed at the source: a variable that moves proves the chain, and leaves only the rule to fix.

Routes changed elsewhere do not appear on the panel

That is what following the registry live is for; the Connection line of Test Connection says whether it is running. Where the registry offers no subscriptions, use Refresh All Route Statuses, which asks every receiver directly.

A button that used to work now fails

Something was replaced or reset and came back with a new UUID. Run Sync All Devices — which repairs what it can match by name — and then Check References for the rest (section 8).

Find Registries finds nothing

Multicast DNS does not cross a subnet, and many deployments publish no DNS-SD at all. Fill in DNS-SD domain if the registry is published in unicast DNS, or simply type the address and port — nothing else depends on discovery.

When you need to send it to us

The Test Connection and Check References reports are written to be copied and sent as they stand: between them they say what answered, what is registered, what is reachable and what no longer resolves. Fantago's own log, under userData/logs/, carries every request the handler made, in order.