Connect a camera only when subscribed to free the GigE link

Three GigE cameras, one 1 GbE switch: two stream cleanly, and the third pushes the link past what it can carry. The fix is not a bigger switch — it is to stop streaming what nobody is reading. Connect a camera when a node subscribes to its image topic and disconnect it when the last subscriber leaves, and the idle camera contributes zero bytes to the link. You will set one driver parameter, prove the stream is down with netstat and tcpdump, and budget the link with three numbers. The guide is for anyone running several GigE area scan cameras through one switch or one network interface.

Why a third camera breaks a link that two shared

A 1 Gbit/s link moves 125 MB/s at the wire: 1,000 Mbit/s ÷ 8 bits per byte. GigE Vision wraps every image fragment in a UDP/IP datagram inside an Ethernet frame, and headers plus inter-packet gaps cost roughly 5-8% of that gross rate. Plan on about 118 MB/s of usable image payload per 1 GbE link, counting only cameras that are connected at the same moment. The constraint is simultaneous demand, not an average.

When the sum goes over, the switch drops packets and the symptoms arrive together: blank or torn frames, retransmissions and buffer overflow errors in the driver. GigE Vision stream packet loss: diagnose blank frames treats the symptom side; if your logs show buffer faults, this GigE camera buffer overflow walkthrough covers the same failure from the capture side. How much frame rate one camera may claim from a link is its own sum: GigE Vision for a high speed camera: how much frame rate fits works it through.

Most cameras that hit this ceiling are 5 MP class running near full rate; a 2.5 MP sensor halves the per-camera load. The MV-CU020-90GC is a 2.5 MP color GigE camera with a 1/1.7" sensor, C-mount and global shutter.

What subscriber-gating changes

Subscriber-gating moves connect and disconnect out of your application code and into the driver. The driver watches the subscriber count on the image topic: the first subscriber starts the camera, the last unsubscribe stops it. The node, the topic and the publisher stay advertised throughout, so a viewer that comes back receives frames without a launch restart. The camera keeps its IP address and its control channel; only the UDP image stream closes.

Two consequences matter. First, the idle camera costs nothing: no packets on the link, and the driver process falls to essentially zero CPU, which is the fastest signal that the stream is really down. Second, every subscribe cycle runs the SDK's start and stop paths, and those are the heaviest paths a camera driver has. If a driver has ever hung on shutdown for you, the same fragility is in play — camera crash when stopping acquisition: isolate the cause walks that failure down. Gating is also not the same as pausing frames inside a live session: pause and resume camera acquisition in a vision system covers stopping acquisition while the camera stays connected, which suits one camera with a duty cycle rather than a saturated shared link.

Turn the setting on

The parameter is driver-side and defaults to False, so nothing changes until you set it. One ROS 2 camera driver implements the pattern as connect_while_subscribed; set it in the launch file, not in the parameter yaml.

parameters = {
    'connect_while_subscribed': True,
}

1. Check the build. Set the parameter and judge behavior, not launch output: if the camera still streams with zero subscribers, your build predates the feature. Update the driver first — an outdated clone behaves exactly like a correct one from the launch file.
2. Set the flag where it lives. Pass connect_while_subscribed: True in the parameters block of the camera node's launch entry, as above. The yaml needs no edit.
3. Restart the launch and subscribe from a viewer; frames should arrive as before.
4. Drop the subscriber. Close the viewer, then run the checks in the next section before you trust the setting.
5. Soak it. Run a couple of weeks of open-and-close cycles before the rig goes into service. Start and stop is the code path that breaks first.

Prove the stream actually stopped

Publisher count will not help you — it stays at 1 by design. Work down this list instead; the whole check takes two minutes.

1. ros2 topic info /camera/image_raw — you want Subscription count: 0. Publisher count: 1 is the healthy resting state.
2. ros2 node info on the driver and on anything that ever opened the topic. A forgotten recorder or viewer keeps the camera connected.
3. Watch the driver process's CPU. It should fall to near zero with no subscribers, because frames stop at the SDK boundary.
4. Run netstat -ap on the host: a UDP listener appears when the camera connects and disappears when it disconnects. A missing listener is the direct proof that the stream is closed.
5. Run tcpdump -i eth0 host 192.168.1.50 (your interface and camera IP) while the camera streams, then after the last unsubscribe: packets while connected, silence after.

If subscriber-gating is on and CPU stays high with zero subscribers, the connection did not close. That is the build problem from step 1, not a network problem.

Worked example: three 5 MP cameras on one 1 GbE switch

Inputs, with where each comes from:

• Cameras: three 5 MP GigE models in mono8, so 1 byte per pixel — the camera class behind the "two run, three do not" case.
• Frame rate: 10 fps each, set in software, because that is all an operator display needs.
• Link: one 1 GbE switch — 125 MB/s gross, about 118 MB/s usable payload.

The rule in words: a connected GigE camera sends at its set frame rate continuously, so the sum of simultaneously connected streams must stay below the usable link rate, with headroom for bursts.

Result: two cameras fit with roughly 15% headroom, which is why that pair ran clean. The third adds 50 MB/s to a link with about 18 MB/s left, so the switch drops roughly a fifth of the demand — and you see blank frames, not a subtle loss.

Decision: never connect the third camera while two are streaming. Cycle which pair is live through subscriptions and let gating hold the idle camera at 0 MB/s. Design to a working limit of about 100 MB/s of simultaneous stream on a 1 GbE link (≈85% of usable) and treat 118 MB/s as the hard ceiling. To run all three continuously instead, each camera drops to about 7 fps: 5,000,000 × 7 × 1 ÷ 1,000,000 = 35 MB/s, and 3 × 35 = 105 MB/s, about 89% of usable.

Common mistakes

• The flag is set but nothing changes. Your driver build predates the feature; an outdated clone is indistinguishable from a correct one at the launch file. Update, restart, then judge by CPU and netstat, not by logs.
• Trusting the publisher count. Publisher count: 1 is the resting state, not proof of streaming. Subscription count: 0, near-zero CPU and a missing UDP listener are the signals that matter.
• A forgotten subscriber. One recorder, diagnostic node or open viewer holds the camera open. ros2 node info on every node in the system finds it.
• Putting the flag in the yaml. It belongs in the launch file's parameter block; the yaml needs no change.
• Reaching for a software trigger instead. Setting trigger_mode to "Software" changes when frames are captured, not whether the camera is connected, and it hands you the pacing job that gating does automatically.

When gating is the wrong fix

Gating fits displays and occasional checks, not continuous inspection: a line that needs every frame cannot have one camera disconnected. For those cases change the numbers instead. Cut frame rate or crop the ROI until the sum fits the 118 MB/s budget, enable jumbo frames to shave overhead, or stop sharing one interface. A controller with 5+ LAN ports gives every GigE camera its own NIC, and PoE camera ports carry data and power over one cable. For switch sizing and per-port budgeting across a whole cell, see GigE camera network planning: switch ports and bandwidth.

The vision controllers below take that path: choose by LAN port count first, then by CPU for the image processing you run alongside the streams.

The decision, per case

• Two display cameras on one 1 GbE link: run them straight. You sit near 85% utilization with nothing to configure.
• Three or more cameras used one or two at a time: enable connect_while_subscribed, cycle subscriptions from your viewers, and keep the two-minute verification in your commissioning checklist.
• All cameras needed at once, continuously: shrink frame rate or ROI until the sum fits about 100 MB/s, or give each camera its own port on a multi-LAN controller. Jumbo frames recover a few percent more.
• The link still saturates after all that: move one camera off the shared link. The camera finder filters by interface, so a USB3 or 10GigE model ends the contention without touching the network design.

If you are sizing the rig from scratch, work out the network budget before the camera list and step through the camera configurator. More multi-camera networking work lives on the systems topic page, and layout questions reach the team through the contact page.