PoE camera discovery in a Docker bridge: connect by IP

Your camera list is empty the moment a container stops sharing the host's network stack, and the rest of your stack — a database, a message broker, a dashboard — needs the host stack left alone. The fix is not to fight over host mode. A Docker bridge network drops the UDP broadcast packets that camera discovery depends on, but it forwards unicast in both directions once a flow opens. Reserve the camera's address, connect to it by IP, and keep packet sizes inside the bridge's MTU, and a PoE camera runs like any other container. This guide gives you the address plan, the macvlan option, the bridge fallback, the packet-size arithmetic and the end-to-end checks.

Why a bridge network hides your cameras

A GigE Vision SDK finds cameras by sending a UDP broadcast to 255.255.255.255 on port 3956 and collecting each camera's reply. GenICam discovery runs on that subnet broadcast, which is why ping alone has never found a camera: GenICam discovery uses subnet broadcast: why ping is not enough. A bridge network translates the container behind the host and does not carry subnet broadcasts, so the question never reaches the camera LAN and the answers never come back. The same empty list with good ping shows up when a firewall passes ICMP but blocks broadcast, as in GigE Vision camera firewall: ping works, discovery fails.

What a bridge does carry is unicast. Open a TCP connection or a UDP flow to a known address and the translation handles packets in both directions for the life of the flow. That single fact is the whole strategy: give the camera a fixed address and open it directly instead of waiting for discovery. An Ethernet 3D camera in a Docker container hits the same split — discovery broken by the container, streaming fixed once the address path is right — and the steps below apply that logic to PoE cameras.

What you need

• A host with two Ethernet interfaces: one for the office network, one dedicated to cameras. Vision controllers bundle those ports, and often PoE, in one box:

All 3 share: Certification CE, KC. Values as printed in each product's data sheet; open a part for its drawing and full specifications.

• A PoE switch or injector on the camera LAN for cameras that draw power over the data cable. Cameras with a separate power lead do not need it.
• Camera data cables sized to the run. The LS-CBL-0199 is a 3 m high-flex GigE lead for the bench; the LS-CBL-0117 RJ45 cable with locking stud covers a 15 m fixed run:

• A reserved address for the camera, set in Step 1.
• Docker on the host and your SDK's container image.

Step 1: Fix the camera's address before touching Docker

Skip discovery later and the camera needs an address that never changes.

1. Reserve an address for the camera's MAC at the DHCP server, or set a static IP in the camera. Keep any static address outside the DHCP pool so the server never hands it to another device.
2. Keep the camera in the subnet the host's camera interface uses: 192.168.10.0/24 with the camera at 192.168.10.42 in the examples below.
3. Confirm from the host: ping 192.168.10.42. A reply in under 1 ms is normal on a switched LAN. No reply points to wiring, VLAN or PoE power; Docker is not involved yet.

A DHCP reservation beats a raw static IP because the camera keeps working from any host and the lease tells you the address. If a camera still reboots into an unknown address, finding a DHCP camera's IP after every reboot is the recovery path, and running one DHCP server for the camera LAN keeps the reservations authoritative.

Step 2: Choose macvlan or bridge by how the camera streams

If you cannot find a stream-destination setting in your SDK, assume UDP and pick macvlan. Reaching cameras on another subnet without broadcast shows the same rule on ordinary networks: unicast crosses, broadcast does not.

Step 3: Run the app on a macvlan network and keep discovery

A macvlan network pins the container to one physical interface and gives it its own address on that LAN, so broadcasts from the container behave exactly as they would from a second PC.

# example values: substitute your camera subnet, gateway and interface name
docker network create -d macvlan \
  --subnet=192.168.10.0/24 \
  --gateway=192.168.10.1 \
  --ip-range=192.168.10.224/27 \
  -o parent=enp3s0 \
  camnet

# .224/27 reserves a 32-address slice (.224-.255); keep it outside the DHCP pool
docker run -d --name inspect --network camnet --ip 192.168.10.230 your-app-image

1. From a shell in the container, ping 192.168.10.42. It answers on the first try.
2. Run your SDK's camera enumeration. The broadcast now leaves through the camera interface and the camera appears, discovery included.
3. Start the stream at the packet size the worked example below computes.

One macvlan limit to know: the host cannot open connections to 192.168.10.230 by default, because the kernel blocks traffic between a parent interface and its macvlan children. Your container-to-camera direction is unaffected. If a host-side service must reach the container, attach a second ordinary bridge network to the same container and use it for that traffic.

On a controller such as the MV-VC5525-256G70-NN, with 5+ LAN ports, the camera interface is one dedicated port and the office LAN stays on another.

Step 4: Bridge fallback — connect by IP and skip discovery

When macvlan is not available — a managed host, a network plugin that owns the interface — a plain bridge still carries control traffic and TCP streams end to end.

services:
  inspect:
    image: your-app-image
    network_mode: bridge
    ports:
      - "5000:5000/tcp"   # example: only needed for inbound TCP the app serves

Then skip discovery on purpose. Most GenICam-based libraries offer an open-by-address path next to enumeration; pass the reserved address, 192.168.10.42 here, and the SDK opens a unicast control session to UDP port 3956 through the translation. TCP-style streams ride the opened connection and work. UDP GigE Vision streams do not: the SDK directs packets at its own container address, the camera cannot reach it, and the stream never starts. That failure is your signal to go back to Step 3.

Set the camera packet size to the bridge MTU, 1500 bytes by default, before the first stream. The arithmetic below shows what that costs and when it matters.

Worked example: packet size for a 12 MP camera through a 1500-byte bridge

Inputs and where each comes from:

• Camera: the class of the LS-CMR-0053, a 12 MP GigE camera rated at 9 fps. At Mono 8 that is 12,000,000 pixels × 1 byte = 12 MB per frame.
• Link: 1 Gbit/s switch port and NIC.
• Bridge MTU: 1500 bytes, the Docker default.
• Wire overhead: 38 bytes per frame — 8 preamble + 14 Ethernet header + 4 frame check + 12 inter-frame gap.

The rule in words: a link of rate R carries frames of wire size W at R ÷ (W × 8) packets per second, and usable pixel data is that packet rate times the payload left after 28 bytes of IP and UDP headers.

The arithmetic:

• Frame demand: 12,000,000 bytes × 9 fps = 108 MB/s, × 8 = 864 Mbit/s.
• Wire frame at 1500-byte packets: 1500 + 38 = 1538 bytes = 12,304 bits.
• Packet rate: 1,000,000,000 ÷ 12,304 = 81,274 packets/s.
• Pixel budget: 81,274 × 1472 × 8 = 957,082,624 ≈ 957 Mbit/s.
• Headroom: 957 − 864 = 93 Mbit/s, about 10 percent of the link.

Decision: set the packet size to 1500 and this camera fits a 1 Gbit/s bridge with 93 Mbit/s spare — no MTU changes anywhere. The break-even sits at about 10 fps: each frame per second costs 96 Mbit/s (864 ÷ 9), and 957 ÷ 96 ≈ 10. Above it, raise MTU to 9000 end to end — switch ports, host NIC, and the Docker network at creation with -o com.docker.network.driver.mtu=9000 — then set packets to 9000, which lifts the budget to about 993 Mbit/s and the break-even to 10.3 fps. Past that, one camera fills a 1 Gbit/s port whatever the packet size: move to a 2.5 or 10 Gbit/s port, or cut the ROI or use binning.

Verify the stream end to end

1. Frame rate at the application: command 9 fps and average over 100 delivered frames; expect 9, not 8.7. A shortfall means the path is dropping packets.
2. MTU path from the container: ping with the do-not-fragment flag — ping -M do -s 1472 192.168.10.42 must succeed, since 1472 + 28 bytes of IP and ICMP headers make exactly 1500. On a jumbo path, ping -M do -s 8972 must succeed too.
3. Buffer completeness over a 10-minute run: no incomplete-buffer errors. The lost-packet fix for buffers that arrive incompletely and the stream-timeout checklist for packets, buffers and MTU cover the failures a container path adds.
4. Stability across hours: if the stream stalls, the watchdog-and-recovery pattern for PoE camera stream drops is the reference.

Frame rate held and buffers complete means the network is done; everything further is SDK tuning.

Common mistakes and their fixes

• Jumbo packets through a 1500-byte bridge: torn images and incomplete buffers. Set the camera packet size to 1500, or raise MTU end to end as in the worked example.
• Camera on unreserved DHCP: the address changes at the next power cycle and the container connects to a stale IP. Reserve first, always.
• Waiting for discovery on a bridge: the empty list is the expected signature, not a fault. Open by address; if the stream then fails, use Step 3.
• macvlan bound to the wrong parent: the -o parent= value must name the camera port, not the office port, or no camera ever appears.
• Two devices sharing one macvlan address: intermittent loss that looks like cable trouble. Give each container its own slice as in Step 3. Duplicate PoE camera discovery caused by host interfaces and network camera discovery troubleshooting for multiple cameras cover the multi-camera forms.
• PoE budget ignored: ports link while the switch cannot power every camera at boot. Add the cameras' draw and compare it with the switch budget before mounting.

Where to go next

Size the host around LAN port count and PoE before CPU: the system configurator walks camera, controller and extras in order. The rest of the work on broadcast, MTU and streaming sits on the systems topic page. If the container layout is the open question, contact the applications team with your camera list and service plan.