GenTL node maps: when only the remote device has an XML

Your GenTL consumer enumerates the camera without complaint, then dies building the acquisition modules with 'The target port does not hold any URL.' The board is installed, the camera answers, and yet only one level of the standard System > Interface > Device > RemoteDevice chain — the remote device — ever publishes an XML. This guide is for anyone wiring a camera to a GenTL producer, through a frame grabber or a custom CTI. You will learn which levels may legitimately be empty, why the exception is expected behavior rather than a defect, and how to restructure enumeration, feature access and teardown so acquisition runs on a single node map. A bench test with numbers and a checklist of the code paths that break silently finish the job.

Why does acquisition stop with 'The target port does not hold any URL'?

The message means your consumer asked a GenTL port for its feature XML and the port returned an empty URL: in the System > Interface > Device > RemoteDevice chain the producer has published no XML at that level, and three of the four levels may legitimately be empty.

GenTL organizes every producer as a tree of modules. The System module stands for the producer itself, each Interface stands for one network adapter or capture board, each Device is one camera behind that adapter, and the RemoteDevice is the camera's own control port. Each module owns a port, and each port publishes the location of its XML as a URL string. A level with no features to expose simply carries an empty URL: nothing to download, nothing to parse, no node map.

Enumeration succeeds anyway, because listing modules reads only what the producer fills in itself. Construction is different: the consumer builds a node map for every module it creates, and a strict helper treats the empty URL as a logical error. Your traceback names it LogicalErrorException; a catch block written only for the GenICam base exception, GenericException, lets it escape, construction halts, and you never reach the first frame.

Which GenTL levels may hold no XML at all?

Three of the four levels — System, Interface and the local Device port — may hold no XML whatsoever; only the RemoteDevice port, which fronts the camera itself, must carry the node map that lists every feature you set, from ExposureTime to PixelFormat.

Read the table as a contract for your code: expect zero to three empty levels above the remote device, never an empty remote device. Producer features that do exist — a board's trigger routing, for example — stay reachable, behind a None guard that the next section builds. Camera-side settings live nowhere else: when your code writes Gain or switches PixelFormat, the RemoteDevice node map is the only legitimate address.

Is a camera with only a remote-device node map standards-compliant?

Yes — the arrangement is valid and every consumer has to cope with it: each GenTL module owns its port and an optional node map, nothing obliges a producer to publish XML at the local levels, and the camera's features are defined once, in the RemoteDevice XML.

The GenICam model splits features by where they execute, not by where you would like to find them. A camera that serves its own feature XML over the control protocol needs no help from the producer; the producer's job at the local levels is transport, not configuration. That is why a custom producer built around such a camera legitimately ships without System, Interface or local Device XML — and why your acceptance test for any producer should include a chain with empty local levels, not only the conventional full stack.

The URL behind the RemoteDevice node map points into that camera-side XML. Accessing GigE camera registers at runtime from your control code shows what the underlying register traffic looks like.

How do I make the consumer tolerate empty local node maps?

Catch the empty-URL condition at each level, set that level's node map to None, construct the module anyway, and route every feature call through the RemoteDevice node map — a four-level change, in this order: System, Interface, local Device, RemoteDevice.

1. Widen the catch at each level. Wrap the node-map build for every port in a handler that catches both GenericException and LogicalErrorException, the two classes the empty-URL path raises between them.
2. Log and continue. On the catch, record the level and the message at debug level — it is expected — then set that module's node map to None and construct the module object anyway; enumeration has already proved the module exists.
3. Require the remote node map. Build the RemoteDevice from the remote port last and let a failure there propagate: a missing camera XML is the separate failure covered at the end of this guide.
4. Validate once. Before the first stream opens, assert that the RemoteDevice node map is not None; optionally assert that it is the only non-empty one.
5. Point feature calls at the remote node map. ExposureTime, Gain, Width, Height and PixelFormat writes all go through the RemoteDevice node map from here on.

# Illustrative pattern - map the helper calls to your consumer's API.
# node_maps maps each level name to a node map object or None.
node_maps = {}
for level in ('system.port', 'interface.port', 'device.local_port'):
    try:
        node_maps[level] = build_node_map(level)      # your consumer's call
    except (GenericException, LogicalErrorException):
        node_maps[level] = None                       # expected: no URL here
remote_map = build_node_map('device.remote_port')      # must succeed
assert remote_map is not None, 'camera XML missing - separate failure'

If your consumer accepts patches, this catch-and-continue is the whole fix; if it does not, wrap construction the same way at your call site. The pattern costs nothing at run time: the empty levels are skipped once and never touched again.

Which other code paths break when the local node map is None?

Two code paths break once a local node map is None: the teardown path that disconnects the device node map, and any stream set-up code that reads producer features from the Device level — both must reference the RemoteDevice node map or skip cleanly.

Teardown is the one that surprises teams. A close routine written against the conventional chain ends with a call that disconnects the device node map; with the local Device node map set to None, that line now throws — usually during shutdown, where it hides. The connections that need releasing live on the camera's port, so the disconnect call belongs to the RemoteDevice node map.

Stream set-up is the second path. If opening a data stream reads stream parameters from the Device module's node map, guard the read: when the level is None, take the equivalent setting from the RemoteDevice node map or fall back to the consumer's standard value. A start-up routine that walks all four levels writing initial settings needs the same guard; None simply means skip.

If a guarded call still fails with a node-not-existing error, you are addressing a feature on the wrong level — GenICam node not existing: diagnose feature access errors walks that failure down. A write that raises on access state instead of existence is the sibling case in GenICam node not writable: check camera access state.

How do I test the fix on the bench?

Prove it with three checks: exactly one non-empty node map, the RemoteDevice's; one feature round-trip on that node map, writing ExposureTime and reading it back; and a grab of 100 consecutive frames with no acquisition errors.

1. Enumeration. Connect the camera through the producer and run the discovery update; the camera must appear, exactly as it did before the change.
2. Construction. Create the acquirer with the tolerant pattern; construction completes and the RemoteDevice node map is the only non-empty one.
3. Feature round-trip. Write ExposureTime = 5000 µs on the RemoteDevice node map and require a read-back of 5000 µs. ExposureTime carries microseconds as its unit in SFNC, so a mismatch means the write landed on the wrong node map or not at all.
4. Timed grab. Acquire 100 frames on a test camera running 30 fps.

The timed grab sets the software timeout by arithmetic:

Set the timeout to 10 s and expect the grab to finish near 3.3 s; a grab that drifts toward the timeout points at the stream, not at the node map chain. Finish by closing and reopening the acquirer twice in the same process: this exercises the guarded teardown path from the previous section, where the old code threw.

Which hardware stacks hit this most often?

You meet the pattern most often on capture-board stacks — Camera Link, CoaXPress and 10GigE boards whose producers carry board features or none at all — and with custom producers built around a camera that serves its own XML.

A network bench without a board runs the identical chain: the adapter-side producer sits at System and Interface level and the camera is the RemoteDevice, so the same tolerant construction covers GigE and USB3 stacks too. What changes between stacks is only which levels publish; the consumer code should not care.

Each board below walks the same System > Interface > Device > RemoteDevice chain on its way to the camera:

For a multi-camera GigE bench the chain runs through a PoE capture card instead:

When you are choosing the board itself, the frame grabbers category filters by interface and port count, the accessories finder lists the remaining adapters, and the system configurator assembles board, cable and camera into one parts list. Compatibility between a Camera Link camera and its board is a separate checklist — Camera Link camera and frame grabber compatibility: what must match — and if the bench is a laptop, check the whole interface chain first in laptop frame grabber compatibility.

When is an empty node map a real fault instead of the design?

An empty local node map is design, but an empty RemoteDevice node map is a failure: if the camera's XML also fails to load — wrong path, ZIP container, encoding — you have the separate XML-location family of problems, and acquisition stops for a different reason.

Sort the symptoms by what actually broke. Empty System, Interface and Device node maps with a working RemoteDevice is the conformant layout this guide fixes. A RemoteDevice node map that fails to load is different: the producer cannot find its camera description file, the file arrives as a ZIP the consumer cannot open, or the encoding trips the parser — each has its own walk-through in GenTL XML file location errors and in troubleshooting the GenTL XML file path during camera setup. A camera that enumerates but refuses configuration commands sits another rung away; start at camera configuration not responding: fix the frame grabber host PC.

Prevention is one log line. Print the node map state of all four levels at construction — system: none, interface: none, device: none, remote: OK — and keep it in every support bundle. With that line, a field issue takes seconds to sort: an unexpected none at remote level redirects you to the XML-path guides above, while the expected triple-none confirms the design is working as intended. The systems topic page collects the neighboring fixes at this level of the stack.

Building the stack now? The area scan cameras category and the camera finder filter by interface, resolution and shutter, and the camera-side configurator builds the rest of the chain around the sensor you pick. If your own producer still refuses to close the chain, bring the four-level log line to the contact page.