A library to obtain network configuration for your Arduino Ethernet shield via DHCP (Wikipedia), so that you can easily have your board be auto-configured in networks that have a DHCP server without needing to worry about address clashes or the like.
As an example, if you connect your Arduino board to your home network or your company network, you will most likely have a DHCP server ready that you can use with this library. This takes the guesswork/experimentation out of the configuration process and makes sure that no other peer gets assigned the same address that you have given to your board manually.
Credit: This library is based on previous work by Jordan Terrell, and I augmented the library to work both in a blocking and a polling mode, as well as adding functionality to automatically renew leases and rebind (if necessary) and some reliability improvements.
The library ships with 2 extensively commented examples, but here's an additional run-down of the public methods. Nevertheless, I suggest to have a look at the examples for a short introduction to the library.
int begin(byte* macAddr); int begin(byte* macAddr, int pollingMode);
begin() sets up the DHCP library and initiates the negotiation of a DHCP lease. The first argument is a pointer to an array of 6 bytes, specifying the desired MAC hardware address of your Arduino ethernet shield. This is similar to the first argument of the Ethernet library's begin() method.
The second argument (default: false) specifies whether you want polling mode enabled (if non-zero) or disabled (zero): In polling mode, begin() will return immediately, so that you can then poll the DHCP library within your loop() to find out when a lease has been obtained. If polling is disabled (the default), the call to begin will block until a lease has been obtained. However, if you fail to obtain a lease in non-polling mode, your sketch will effectively be blocked forever. Thus, use polling mode if you want to avoid this.
Packets will automatically be resent once every second until a lease has been obtained, as to make sure that the DHCP negotiation is not hindered by packet drop.
begin() will return a non-zero value on success, 0 otherwise.
NOTE: The EthernetDHCP library's begin() statement replaces the Ethernet library's begin()! Do not use both within the same sketch!
DhcpState poll(); void maintain();
poll() and maintain() actually run the DHCP module. If you use polling mode, you need to call poll() at least once within your loop. It will return the current state of the DHCP library. If you do not use polling mode, you should call maintain() at least once per loop() iteration: It will make sure that your lease is automatically renewed before it expires, or that a new lease is obtained if the current one cannot be renewed.
Failing to call either method within your loop() will cause the DHCP library not to work at all (in polling mode) or create a risk of losing your DHCP lease when it expires (in non-polling mode). Thus, be sure to call either method at least once within the loop!
In case of poll(), the return value is one of DhcpStateDiscovering, DhcpStateRequesting, DhcpStateRenewing or DhcpStateLeased, depending on the current state of the DHCP library. If the state is either "Leased" or "Renewing", it means that you currently have a valid DHCP lease.
const byte* ipAddress(); const byte* gatewayIpAddress(); const byte* dnsIpAddress();
Once you have obtained a valid lease, these methods can be used to read your DHCP configuration: Your IP address, your gateway IP address and your DNS server IP address (each as a pointer to a byte).
Note that you only need to know your IP address and gateway IP address for informational purposes, but you do not need to set them manually — This is done automatically by the library. However, you can use the DNS IP address value to initialize the EthernetDNS library, as an example.
If a lease has not been obtained yet, the return value of these methods is undefined.
const char* hostName(); int setHostName(const char* newHostName);
Use hostName() to find out your current host name, and setHostName() to set it. You can call either method even before a call to begin(), so that you can specify the host name that you want to use during the DHCP negotiation.
Some DHCP servers assign specific host names to their clients. If this is the case, calling hostName() after a lease has been obtained will reflect the new host name.
setHostName() will return a non-zero value on success, zero otherwise. Note that some DHCP servers allow you to reserve certain IP addresses by host name, so this might be a useful setting if you have such a DHCP server and want the same address assigned to your Ethernet shield every time.
void useHostNameAsClientIdentifier(int yesOrNo);
By using useHostNameAsClientIdentifier(), you can specify if you want to use the currently set host name as client identifier during the DHCP negotiation: If set to YES (a non-zero value), the host name will be used as client identifier. If set to NO (zero), the Ethernet shield's MAC hardware address is used as client identifier.
You can call this method even before your call to begin().
Some DHCP servers allow you to reserve a specific IP address for a client depending on its client identifier. If you have such a DHCP server and want the same address assigned to your Arduino every time, you will find this method useful.