Configuration and Detection

Starting with v2.00, the ETH32 API includes functionality that allows your applications to detect the presence of ETH32 devices on the local network, retrieve their current network configuration settings, and store new configuration settings into devices. One of the main reasons for including this functionality is the ability for ETH32 devices with firmware v3.000 and greater to use DHCP to automatically acquire an IP address. If the device is using DHCP, your application needs some way of finding out which IP address has been assigned to the device so your application can connect to it. If you control the configuration of the DHCP server, in most cases it is possible to configure the DHCP server to assign a specific, fixed IP address to a specific device based on its MAC address. In that case, your application could always connect to that fixed IP address and know that the ETH32 had that address. And of course, as before, the ETH32 device can still be configured with a static IP address, yielding a similar result. However, when DHCP is used and not configured to provide a fixed IP address, you will most likely want to utilize this functionality of the API to determine the IP address that has been assigned.

This functionality of the API is only able to detect and configure devices that are on the same local network segment as your PC. The functionality works by sending out UDP broadcast packets onto the network. This is the only practical way to detect the devices, since the specific address of each is unknown. However, network routers do not forward broadcast packets on to other network segments, so the API will not be able to detect any ETH32 devices that are past routers. Devices that are behind normal switches and hubs will be detected. Note that these restrictions only apply to the configuration and detection functionality. The normal ETH32 communications are implemented with standard (unicast) TCP/IP communications, and will work between any PC and device regardless of any routers in between, including over the Internet, as long as there is a valid route between them.

The API includes two different ways to detect devices. The Query function detects every ETH32 device on the local network, and returns all of the available settings and device information about each device. On the other hand, the Discover IP function allows you to discover just the active IP address and settings for a particular device that you specify by its MAC address or serial number. The Discover IP function is intended to be the standard method for your application to determine the IP to connect to when working with a device using DHCP. Your application should know the MAC address or the serial number of the device, and when provided to Discover IP, only information about that device will be returned. When a filter is provided to Discover IP, it is able to return immediately with that information as soon as the requested device replies. On the other hand, the Query functionality does not know how many replies will come in, so it delays a short period to allow replies to arrive, and also sends out the broadcast requests multiple times in case any network congestion causes interference. Query also sends two different types of packets out and potentially receives two different types of replies from each device, which is necessary to determine every available detail about the device, whereas Discover IP only sends and receives one type of packet, which provides the active IP settings and the DHCP status of the device. So to summarize, since Query is attempting to find every bit of information about every device on the network, it will necessarily take longer than Discover IP, which is able to return as soon as the requested device replies. Note that if a filter is not provided to Discover IP, then it attempts to find all devices, and will take as long as Query. In that case, there is little difference except that Query sends out two different types of queries and Discover IP sends only one type. The packet type that Discover IP uses is supported on devices with firmware v3.000 and greater (those that support DHCP).

Depending on if and how you decide to detect devices, it may help to know how device serial numbers are constructed. An example of a serial number as it would be printed on the product label is 105-AB291. Each serial number is made up of three components: Product ID, Batch number, and Unit number. The Product ID is constant for all ETH32 devices, which is defined to be 105. As the example shows, this is printed first and followed by a dash. Batch and Unit numbers taken together are unique to each ETH32 device. The batch number is represented by letters in the serial number, such as the AB in the example. Internally and in the API code, the batch number is represented numerically, but when the serial number is printed, it is shown with letters. The letters are NOT hexadecimal, but rather in the style of Microsoft Excel column identifiers, although starting with AA. So, AA means 0, AB means 1, ..., AZ means 25, BA means 26, and so on. Lastly, the unit number is simply shown numerically and zero-padded out to three digits if necessary. The API includes a function to take the individual components and format a serial number string in the same way it is printed on the device.

The broadcast address to which packets are sent out may depend on your particular network configuration or PC, so it can therefore be specified to the API by your application. In most cases, a broadcast address of 255.255.255.255 is suitable.

The API also includes functions to convert between a string representation of an IP address, and the binary representation that is used by the Configuration / Detection functionality of the API.

Applicable Functions and Information

TaskC / C++.NET LanguagesVisual Basic 6
Queryeth32cfg_queryQuery MethodQuery Method
Discover IPeth32cfg_discover_ipDiscoverIp MethodDiscoverIp Method
Get resultseth32cfg_get_configResult PropertyResult Property
Free memory for resultseth32cfg_freeFree MethodFree Method
Store new configuration to deviceeth32cfg_set_configSetConfig MethodSetConfig Method
Broadcast addressParameters to above functions
IP Address Conversion
Format a serial number stringeth32cfg_serialnum_stringSerialNumString MethodSerialNumString Method
MAC Address ConversionNone