GigE camera on link local address: open it by IP from Linux

You connected a new GigE camera straight into a Linux host, enumeration lists it with a 169.254.x.x address, and opening it by that address fails while opening it by name works. The camera is healthy and so is your code: the interface has no address in 169.254.0.0/16, so the kernel has no route to the camera and refuses the send before any packet leaves the machine. This troubleshooting guide traces the failure from the GigE Vision boot sequence down to the route table, gives the exact commands that put a link-local address on the NIC under NetworkManager, systemd-networkd or plain iproute2, and shows the addressing arithmetic that proves the repair. Ten minutes on the host beats an hour of swapping SDKs.

The symptom you can reproduce

Fresh camera, one shielded copper lead into a spare NIC, host side 192.168.1.1/24. Three commands tell the whole story:

# arv-tool-0.8
My-Cam (169.254.112.30)

# arv-tool-0.8 -a "169.254.112.30"
Can't connect to device at address '169.254.112.30'

# arv-tool-0.8 -n "My-Cam"
My-Cam        # opens, reads the GenICam XML, streams

The wildcard * behaves like the name while this camera is the only one connected. With debug output (-d all:3) the address attempt logs one discovery socket per interface, then Error: Error sending message: Invalid argument from the interface layer. That line appears immediately, not after a timeout: the stack rejected the send outright.

What happens before that refusal varies between stacks: some enumerate the camera, some enumerate nothing, and a third group enumerates it but cannot open it. For the wider tree — nothing enumerates at all, the wrong interface is selected, services are missing — start from Linux GigE Vision camera discovery troubleshooting.

The failure is generic to the GigE Vision protocol, not to one sensor or one SDK, and it shows up on the bench with any camera you unpack:

Why the name works and the address does not

Every GigE Vision camera climbs the same address ladder at boot: a configured persistent IP if one is set, otherwise DHCP, otherwise a self-assigned address somewhere in 169.254.0.0/16. A camera from the box has no persistent IP, and a bench link has no DHCP server, so it lands on link-local — which is why nearly every new camera enumerates at 169.254.x.x.

The 169.254.0.0/16 block is link-scoped: routers never carry it, and a Linux host transmits into it only from an interface that itself holds an address in the block. A NIC sitting on 192.168.1.1/24 gives the kernel neither a source address nor a route for 169.254.112.30.

Enumeration and opening travel different paths:

• Discovery is a UDP broadcast to port 3956 on each interface's broadcast address. A broadcast crosses mismatched subnets on a direct copper link, and most camera stacks answer it, so the name lookup succeeds.
• Opening by address is unicast: a packet addressed to 169.254.112.30. The socket is bound to 192.168.1.1, the kernel cannot pair that source with that destination, and the send is refused on the spot.

Whether a given camera answers a broadcast aimed at a foreign subnet varies between stacks, which is why some SDKs list it and others stay silent. None of them can open it by address until the host owns an address inside the block.

Fix the host, not the camera

1. Identify the NIC and its connection name:

ip -br addr                # eth1 UP  192.168.1.1/24
nmcli connection show      # "Wired connection 1"

2. Under NetworkManager, keep DHCP and turn link-local on:

nmcli connection modify "Wired connection 1" ipv4.method auto ipv4.link-local enabled
nmcli connection up "Wired connection 1"

On releases without that property, configure both addresses through the manual method:

nmcli connection modify "Wired connection 1" ipv4.method manual \
  ipv4.addresses "192.168.1.1/24, 169.254.100.1/16"
nmcli connection up "Wired connection 1"

3. Under systemd-networkd, give the camera NIC its own .network file — no DHCP, link-local only:

[Match]
Name=eth1

[Network]
DHCP=no
LinkLocalAddressing=ipv4

Then run networkctl reload && networkctl reconfigure eth1. With DHCP=yes, networkd assigns the link-local address after DHCP yields nothing, which also works on a bench link.

4. To prove the diagnosis in thirty seconds, skip persistence entirely:

sudo ip addr add 169.254.100.1/16 dev eth1

The address is live immediately and disappears at the next reboot, so nothing else on the host changes.

Pick the host address once and keep it: any value in the block that is not the camera's own, always with the /16 mask. A /24 mask on 169.254.100.0 would leave the camera's randomly drawn third octet outside your subnet and reproduce the original refusal.

Worked example: one camera, one NIC, the numbers

Camera fresh from the box, enumerating at 169.254.112.30. Host eth1 on 192.168.1.1/24. Before the fix:

ip route get 169.254.112.30
# either: via 10.0.0.1 dev eth0    (the corporate side takes it)
# or:     RTNETLINK answers: Network is unreachable

Add the address and check the maths:

Same network, distinct host parts — a legal pair. After the change:

ip route get 169.254.112.30
169.254.112.30 dev eth1 src 169.254.100.1

That single line is the whole repair: the kernel now has an output interface and a valid source. arv-tool-0.8 -a "169.254.112.30" returns the camera, and the name path behaves identically. Control packets flow on UDP 3956 from 169.254.100.1 to 169.254.112.30, both inside the block.

The /16 holds 65,534 usable addresses (2 to the 16th, minus network and broadcast), so a fixed 169.254.100.1 colliding with a camera's random pick is not a realistic event. Glance at the enumeration output before choosing anyway.

Verify it worked

Four checks, in this order:

1. ip addr show eth1 lists inet 169.254.100.1/16 beside 192.168.1.1/24.
2. ip route get 169.254.112.30 names dev eth1 with src 169.254.100.1.
3. arv-tool-0.8 -a "169.254.112.30" prints the camera and its feature tree.
4. A short acquisition runs with frames arriving and no resend storm.

If the open now succeeds but streaming misbehaves, addressing was the only routing problem and the next suspects are host-side: set the GigE camera packet size before starting acquisition, and on embedded boards the GigE camera buffer timeouts fixed by socket buffer tuning. A local firewall that drops UDP 3956 produces a near-identical stall at the open step; the firewall case where ping works but discovery fails lists the ports to open.

Move the camera off link-local for production

Link-local is a bench convenience, not a commissioning plan. In a running cell, put the camera on a subnet you control:

1. Open the camera by name once.
2. In the GenICam feature tree, set GevCurrentIPConfigurationPersistentIP to true, GevPersistentIPAddress to 192.168.1.10 and GevPersistentSubnetMask to 255.255.255.0. Set GevPersistentDefaultGateway only if the controller lives off that link.
3. Power-cycle. The camera boots straight to the persistent address, and the host needs no link-local address at all.

A small DHCP server on the camera NIC reaches the same outcome through the second rung of the boot ladder. The GigE Vision protocol also defines a broadcast force-IP packet that overrides the address until the next power cycle — useful to recover a camera parked on a forgotten subnet, but it is a rescue move, not configuration.

When the interface already has 169.254 and it still fails

The fix above covers the common case. If ip addr already shows a 169.254.x.y/16 address on the right NIC and the open still fails:

1. Several NICs in the host: the SDK binds one socket per interface and may pick the wrong one for this camera. The duplicate PoE camera discovery diagnosis of host interfaces walks the split.
2. Firewall again: UDP 3956 blocked on the camera zone looks exactly like a routing gap from the SDK side.
3. Stale forced address: a force-IP from an earlier set-up survives until power cycle, so the address you type is not the address the camera holds. Enumerate with the wildcard and read the truth.
4. Camera at 0.0.0.0: it is still waiting on DHCP. With no server on the link, one power cycle moves it onto link-local.

Checklist: camera on a link-local address

• ip -br addr — the camera NIC carries a 169.254.x.y/16 address alongside its normal one.
• ip route get <camera-address> — routes via that NIC with a 169.254 source.
• Firewall — UDP 3956 open on the camera zone.
• Enumeration — wildcard first, note the real address, then open by address.
• Production — persistent IP set, gateway only where needed, power cycle done.
• Lead — seated both ends, link LEDs up; no address repairs a dead cable.

A high-flex lead is the one to standardize on when the camera rides a moving carrier:

With the host fixed, adding the next camera becomes configuration instead of debugging. Run the camera finder for the sensor you need, or start at the camera step of the system configurator. Every GigE area scan camera climbs the same address ladder on first boot, so keep the link-local enable in your imaging-host build script. For a cell with many cameras and one controller, bring the NIC and address plan to the contact page and the applications team will review it with you.