Operation Details

Top  Previous  Next

The DHCP client, once started on a particular interface with the dhcp_start(), will run continuously until stopped through the dhcp_stop(). The operation of the library may be observed in the debug mode by adding #define DHCP_DEBUG_PRINT 1 to the defines section of the global.tbh file of your project. A wealth of status information will then be printed in the console pane as the DHCP library operates.

Once dhcp_start() is called successfully (and it can fail — observe returned code!), the library attempts to obtain the IP address, netmask, and the gateway IP address from the DHCP server. If the process fails, the library will retry. A total of DHCP_MAX_RETRIES attempts are performed (with randomized waiting times between retries, but not exceeding DHCP_MAX_RETRY_DELAY seconds), after which callback_dhcp_failure() is called and the library goes into the waiting period of DHCP_POST_FAIL_DELAY seconds. When the period is over, another batch of  DHCP_MAX_RETRIES attempts is performed, and so on ad infinitum, until the dhcp_stop() is called or DHCP configuration succeeds.

DHCP configuration requires that the initial IP address of the client device be 0.0.0.0. If the IP address of the specified interface is different, the library will set it to 0.0.0.0. Changing the IP address on a particular interface requires all socket connections operating on this interface to be closed first. The DHCP library will take care of that by calling sock.discard for each involved socket. Before doing that, the DHCP library will invoke callback_dhcp_pre_clear_ip(). This way, your application may "prepare" for what is coming. For example, you can add code for gracefully closing TCP connections (instead of letting the DHCP library to do a rude discard).

A buffer space of 6 pages is required while a batch of DHCP_MAX_RETRIES attempts is performed on either network interface. The library will check if the required buffer space is available and call callback_dhcp_pre_buffrq() if more space is needed. Once the batch of retry attempts finishes (either successfully or unsuccessfully), the buffer space is no longer needed and is released by the library. The callback_dhcp_buff_released() is called to notify your system of the fact. Your system can then check the total number of free pages available (now that the DHCP library released some pages) through the sys.freebuffpages R/O property. 

The library can run DHCP configuration on both the Ethernet (net.) and Wi-Fi (wln.) interfaces concurrently. This does not increase buffer space requirements. The library will appropriate buffer pages when needed by either of the interfaces and release buffer pages when neither network interface requires them any longer.

Once the DHCP configuration completes successfully on a particular network interface, the callback_dhcp_ok() is invoked. You can then program the new IP (and the netmask, and the gateway IP) into the net. or wln. object. Doing so is only possible when no sockets are active on the network interface whose properties you are about to change.

After the successful DHCP configuration, the library goes into counting lease time. Once 90% of the lease time passes, the library will attempt to renew the lease. Buffer pages will be needed for this again. The IP address does not have to be reset to 0.0.0.0 for the lease renewal, so callback_dhcp_pre_clear_ip() will not be called, either.

Note that even in case of the lease renewal the IP address offered by the DHCP server may change. Don't forget to take care of this! Actually, it may be easier to just reboot the device than deal with all the implications of the changed IP. Code Examples topic shows how to deal with this.

The library also monitors the link state of network interfaces. If the Ethernet cable is unplugged and then re-plugged (this is monitored through the net.linstate R/O property), the DHCP process (if enabled) will restart automatically for the Ethernet interface. Similarly, if the access point association is lost and then reestablished (wln.associationstate), the DHCP process (if enabled) will restart automatically for the Wi-Fi interface.