Nazlı

The general lesson worth carrying, because this will happen again with a different function: for a board package, the major version number is a compatibility boundary and the migration guide is the real documentation.

Espressif publish a migration document for the 2.x to 3.x change listing every removed and renamed API, and LEDC is only one entry. If your sketch uses timers, ADC, or the touch peripherals, you will meet the same wall a few compiles later.

Reading that document once is faster than solving each error as it appears, and it tells you in advance whether a rewrite is fifteen minutes or an afternoon.

The confusion in those guides is real and it comes from one fact: there are two things that can be in charge of an interface, and on a desktop install it is usually not the one the server guides assume.

The configuration format is the same either way — a YAML file describing the network — but it is handed to a renderer, and there are two:

• networkd, the default on server installs.
• NetworkManager, the default on desktop installs, because that is what the graphical settings drive.

A guide that writes a configuration and restarts the wrong one appears to do nothing. That is why half the tutorials seem broken.

So step one is finding out which renderer your machine uses. Look at the existing configuration files — the shipped one names the renderer, and a desktop install almost always names NetworkManager. Whatever you write must use the same one, or you must set it explicitly for your device.

The renderer can be set per device, which is the detail that unlocks this and is rarely mentioned:

network:
  version: 2
  ethernets:
    enp1s0:
      renderer: NetworkManager
      dhcp4: false
  bridges:
    br0:
      renderer: NetworkManager
      interfaces: [enp1s0]
      dhcp4: true
      parameters:
        stp: false
        forward-delay: 0

Two things worth knowing about that parameters block, because a bridge that works and then behaves strangely usually needs them.

forward-delay is a pause before the bridge starts passing traffic. With the default, a machine can come up, request an address, and get no answer because the bridge is still waiting. Setting it to zero fixes the boot-time race that makes a bridge look intermittent.

stp is the loop-prevention protocol. On a simple host bridge with one physical port there is no loop to prevent, and leaving it on adds delay.