lwIP Wiki

DHCP from an application perspective[]

To enable DHCP, you must make sure to compile and link in DHCP. You can do this by defining the LWIP_DHCP option in lwipopts.h to 1, which also then adds a field to netif for a pointer to a dhcp struct. The dhcp struct will be allocated during dhcp_start(). In addition, LWIP_UDP must be non-zero, since DHCP is a protocol that runs on UDP.

On a simple setup, you will just call


after initializing your interface. Then, to correctly handle leases, DHCP has a couple timed functions that need to be called. However, since some time ago (1.4.0 ?), you only have to call a single function which will handle all timers for all protocols in the stack, so add this to your main loop or equivalent:


Then, you should check your interface for ->dhcp->state == DHCP_BOUND, then you are ready to go.

For LWIP 2.0 you need to call dhcp_supplied_address(const struct netif *netif) instead

If you would need to handle some drastic physical network changes like, for example, a mobile system that can be unplugged and plugged to a different network, you need to inform the DHCP functions of such a situation. This is normally done by the dhcp_network_changed() function. However, the stack takes care of informing not just DHCP but also AUTOIP and IGMP of link changes, so the right calls are:



You should tie these to your link state change detection for your interface.

If you want to get more involved, here you have more (and probably outdated) information:

To use DHCP on an interface, simply use the following commands:

  • dhcp_start() - start DHCP configuration for an interface.
  • dhcp_renew() - enforce early lease renewal (not needed normally)
  • dhcp_release() - release the DHCP lease, usually called before dhcp_stop()
  • dhcp_stop() - stop DHCP configuration for an interface
  • dhcp_inform() - inform server of our manual IP address

Note: These functions are lwIP core functions. They are not protected against concurrent access. In multithreaded environments, they may be called from the core thread only (aka. the tcpip-thread). When calling from other threads, use the netifapi_dhcp_*() functions defined in the api-module netifapi.c.

One option is to take advantage of the phy auto-negotiation. Most phys will generate an interrupt when the link status changes (a valid auto-negotiation has completed, or the cable has disconnected). Processing of the "phy link status changed" interrupt is passed to the tcpip thread (using, for example, tcpip_callback_with_block( HandlePhyInterrupt, NULL, 0) ). Then in HandlePhyInterrupt, if the link is up, make any necessary hardware register adjustments for the auto-negotiated speed, then call dhcp_start. If the link is down, first call netif_set_down( .. ). The other dhcp functions above may not be needed.

DHCP support history in lwIP[]

HEAD Unspecified.
1.2 Unspecified.

External references[]

  • RFC 1531 "Dynamic Host Configuration Protocol" October 1993, obsoleted by RFC 1541
  • RFC 1541 "Dynamic Host Configuration Protocol" October 1993, obsoleted by RFC 2131
  • RFC 2131 "Dynamic Host Configuration Protocol" March 1997, updated by RFC 3396
  • RFC 3396 "Encoding Long Options in the Dynamic Host Configuration Protocol (DHCPv4)" November 2002

See also[]