<< Previous | Index | Next >>

2. TCP/IP Initialization

This chapter describes the configuration macros, data structures and functions used to configure and initialize the Dynamic C TCP/IP stack. Starting with Dynamic C version 7.30, the stack supports multiple interfaces. Interface configuration is described in Section 2.2.

The Dynamic C TCP/IP stack supports IP version 4. Although multiple interfaces are supported, the TCP/IP stack does not support packet routing at the IP level.

2.1 TCP/IP Stack Configuration

You need to know certain things to configure the stack. You need to know which interfaces will be used and how many. You also need to determine the necessary software functionality. For example, will there be DNS lookups? Are TCP and UDP protocols both necessary? Will DHCP be used? The ability to remove unneeded features via conditional compilation has been enhanced starting with Dynamic C 7.30. This is accomplished with the configuration macros described in Section 2.6.1 and Section 2.6.2.

2.1.1 Multiple Interface Support

The supported interfaces are:

• Ethernet
• PPP (Point-to-Point Protocol) over a serial link
• PPP over Ethernet
• Wi-Fi (802.11b, 802.11g)

The interfaces must be on distinct, non-overlapping subnets. In particular, each interface must be assigned a unique IP address, known as the "home IP address" for that interface.

The interfaces available to your application will depend on the hardware configuration of the target board. All Rabbit-based boards have at least four asynchronous serial ports, so PPP over serial is always available. Many boards have an Ethernet port. If an Ethernet port is available, then it may be used for normal Ethernet or PPP over Ethernet (PPPoE). No Rabbit-based board has more than one Ethernet port, however Dynamic C 7.30 contains support for a second Ethernet interface if and when such a board becomes available.

Your application uses configuration macros to select the interface(s) to use for TCP/IP. Each hardware interface will have an interface number assigned. The interface number is not used directly; instead, your application should use the macros defined for this purpose. If you are writing general-purpose routines, then you should include #ifdef tests for the interface macro if you need to refer to it. This is because the macros are not necessarily defined for non-existent interfaces. The macros are:

IF_ETH0, IF_ETH1

These macros represent Ethernet ports that are not using PPP. IF_ETH0 refers to the first Ethernet port and IF_ETH1 to the second.

IF_PPPOE0, IF_PPPOE1

These macros represent Ethernet ports used for PPP over Ethernet. IF_PPPOE0 refers to the first (and currently only) Ethernet port.

PPPoE and regular Ethernet can co-exist on the same Ethernet hardware. PPPoE effectively sets up a virtual point-to-point link between two devices on the same Ethernet LAN segment.

IF_PPP0, IF_PPP1, IF_PPP2, IF_PPP3, IF_PPP4, IF_PPP5

These macros represent asynchronous serial ports used for PPP. IF_PPP0 always refers to serial port A, IF_PPP1 refers to serial port B, etc. Most boards will avoid using serial port A, since it is most often used for Dynamic C debugging and program download.

IF_PPPX

This is an alias for the "first" PPP interface. The first PPP interface is selected as the first valid interface in the following order: IF_PPPOE0, IF_PPPOE1, IF_PPP0, IF_PPP1, etc. through to IF_PPP5.

IF_WIFI0, IF_WIFI1

These macros represent Wi-Fi interfaces. Only IF_WIFI0 is supported at this time.

IF_DEFAULT

This is an alias for the "default" interface. You can explicitly define this macro prior to including dcrtcp.lib to select a default interface. The Dynamic C TCP/IP libraries do not make use of IF_DEFAULT with the important exception of DHCP. DHCP only works on the default interface.

If you do not explicitly define IF_DEFAULT, it is chosen as the first valid interface in the following order: IF_PPPX (see above), IF_WIFI0, IF_ETH0.

If you explicitly define IF_DEFAULT, then you must define it to a hard-coded integer value, not one of the IF_* macros, since the IF_* macros are not defined until dcrtcp.lib is included. Since the actual numbers assigned to each interface depend on the values of the USE_* macros, you must be careful when doing this. The only time you may want to explicitly define IF_DEFAULT is when you are using both PPP and non-PPPoE Ethernet, and you want to use DHCP on the Ethernet interface.

IF_ANY

This is not an interface as such. It is a special value used to denote "any" or "all" interfaces, where applicable. This macro should be used only where a function documents that its use is acceptable. For example, the tcp_extlisten() function accepts IF_ANY as an interface parameter, which tells it to listen for incoming connections on any available interface.

2.1.2 Interface Selection Macros

As each physical interface has its own macro, each type of interface has a corresponding macro. The macro value determines which physical interfaces of the same type will be supported by the stack. Setting the macro to zero disables support for that type of interface, i.e., no physical interfaces of that type will be supported. If the macros are not defined in the application program, they will be set to zero internally.

USE_ETHERNET

This macro allows support of non-PPPoE Ethernet. It can be set to 0x01, 0x02 or 0x03. Most boards only support 0x01, meaning the first non-PPPoE Ethernet device. Boards with two Ethernet devices can set this macro to 0x02, referring to the second Ethernet device, or 0x03 to allow use of both devices.

USE_PPP_SERIAL

This macro allows support of PPP over asynchronous serial. It can be set to:

• 0x01 (serial port A)
• 0x02 (serial port B)
• 0x04 (serial port C)
• 0x08 (serial port D)
• 0x10 (serial port E, available on Rabbit 3000 and above)
• 0x20 (serial port F, available on Rabbit 3000 and above)

Or any bitwise combination of these values.

Serial port C is the default, but you may use any of the others. Please note that if you use serial port A (the programming port) Dynamic C will not be able to communicate with the target. You may also need to define other macros to allow correct functioning of the serial port hardware, e.g., hardware flow control.

USE_PPPOE

This macro allows support of PPP over Ethernet. It is set in the same way as USE_ETHERNET. The bitmask indicates which Ethernet devices are to be used for PPP over Ethernet.

USE_WIFI

This macro allows support of Wi-Fi. It can be set to 0x01 or 0x02.

2.1.2.1 Link Layer Drivers

The USE_* configuration macros described in Section 2.1.2 cause the appropriate link layer drivers to be included. If none of the USE_* macros are defined and the macro PKTDRV is also not defined, realtek.lib will be used. Some board types cause a driver other than realtek.lib to be used, e.g., if the board is the RCM3200 or the RCM3210, the packet driver library asix.lib will replace realtek.lib.

The following table tells which link layer drivers will be used when a USE_* macro is defined to a value greater than zero.

Table 2.1 Libraries Included When USE_* Macro Value > Zero

Configuration Macro	Realtek.lib1	Ppp.lib	Ppplink.lib	Pppoe.lib	WiFiG.lib
USE_ETHERNET	yes	no	no	no	no
USE_PPP_SERIAL	no	yes	yes	no	no
USE_PPPOE	yes	yes	no	yes	no
USE_WIFI	no	no	no	no	yes

1 or a substitute packet driver library based on board type

As the table reveals, using PPP over Ethernet causes realtek.lib, ppp.lib and pppoe.lib to be included. Multiple drivers may also be included by defining multiple interfaces.

The following macros are defined for applications to perform conditional compilation that depends on the drivers actually included:

• USING_ETHERNET
• USING_PPP_SERIAL
• USING_PPPOE
• USING_WIFI
• USING_WIFIG

These macros are always defined, but will have a zero value if the driver was not included. Thus, the conditional compilation should use the #if operator, not #ifdef. For example,

#if USING_PPP_SERIAL
   // Do something special for PPP over serial
#endif

The value assigned to the USING_* macro is the number of hardware interfaces of that type that are available. On a Rabbit 2000 board, USING_PPP_SERIAL will be defined to 4 or 0. On a Rabbit 3000 board, the value will be 6 or 0.

An additional macro, USING_PPP, is also defined if any of the PPP-type interfaces are in use. Unlike the above macros, this macro is either defined or not defined, so the correct test is #ifdef.

2.1.3 Single Interface Support

Backwards compatibility exists for applications compiled with earlier versions of Dynamic C. If none of the USE_* macros are defined, then the old behavior (pre-Dynamic C 7.30) is used, which is to include one, and only one, link layer driver.

2.1.3.1 Configuration Macros for Link Layer Driver - Single Interface

Do not define either of these macros if any of the USE_* macros are defined.

PKTDRV

This macro specifies the packet driver to use. Include one of the following statements in your application.

#define PKTDRV "realtek.lib"     // To use Ethernet
#define PKTDRV "ppp.lib"         // To use PPP (serial or Ethernet)

PPPOE

This macro is defined to use PPP over Ethernet when PKTDRV is set to ppp.lib. For other packet drivers, this define has no effect (but should not be defined in order to avoid problems with future Dynamic C releases).

#define PPPOE

2.1.4 TCP/IP Stack Initialization

The function sock_init() must be called near the start of your main() function in order to initialize the TCP/IP stack. The return value from sock_init() must indicate success before calling any other TCP/IP functions, with the possible exception of ifconfig().

IMPORTANT:

If you are using µC/OS-II, then you must ensure that OSInit() is called before calling sock_init().

The function sock_init() performs the following actions, and does not return until complete (or an error was encountered):

• Calls subsystem initialization for ARP, TCP, UDP and DNS (if applicable).
• Tests to see whether sock_init() was run previously. If so, then it returns OK. Otherwise, the following steps are executed.
• Initialize the packet driver; basically this resets the hardware and clears out the packet receive buffer pool.
• Clears the router and other server tables.
• Interfaces are initialized using the settings specified in the IFCONFIG_* macros or predefined configurations.

WiFi takes longer to initialize than the other supported interfaces, and potentially much longer if there is no AP within range (which is analogous to not plugging in the Ethernet cable). If all of the above completed successfully, the return code is set to 0. Otherwise, the return code will be non-zero, however you can still proceed if the return code is 2 since this indicates that DHCP failed but fallbacks were used. Other return codes indicate that the network is not usable.

After sock_init() returns OK, the non-PPPoE Ethernet interface should be ready for traffic if it is intended to be up initially. PPP interfaces may not be fully started even if requested to be up initially. PPP interfaces can take a substantial amount of time to come up, especially if modem dial-out is in use. You can wait for a particular interface to come up by polling the interface status using ifstatus() or, preferably, ifpending().

2.2 Interface Configuration

Prior to Dynamic C version 7.30, only a single network interface was supported. Configuration of the interface was performed by defining a set of macros, such as MY_IP_ADDRESS1, as well as by calling various configuration functions such as sethostid().

With Dynamic C 7.30's support of multiple interfaces, the macro-style configuration becomes impractical, and the configuration functions generally would require an additional parameter, the interface number. Version 7.30 implements a slightly different method of configuration, but maintains compatibility with the old style of configuration for simple applications that require only a single interface.

It is recommended that new applications use the new style of configuration, even if multiple interface support is not required. This will ease the integration of future Dynamic C upgrades.

2.2.1 Configuration Overview

To run the TCP/IP stack, a host (i.e., the controller board) needs to know its unique home IP address for each interface. Interfaces that connect to broadcast networks (e.g., Ethernet or Wi-Fi) must also have a netmask assigned. The combination of IP address and netmask describes the so-called subnet which is addressable on that interface. The subnet basically describes the community of host addresses that can talk directly to this host, without requiring data to pass through a packet router. Point-to-point links only need an IP address, since there is only one other host by definition.

IP address and netmask are the most important configuration items; however, many other items are needed for successful networking. For anything but strictly local communication, a router or gateway host must be known. The router has the important task of forwarding messages between the local host and the outside world (i.e., hosts that are not on the local subnet). Routers are associated with particular interfaces. Each interface will generally require a different router; however, in the majority of cases only one interface will actually be used to talk to non-local hosts so only one router will be required to service all requests for non-local host addresses.

Some of the configuration items are not specific to any particular interface. For example, DNS (Domain Name System) servers are known by their IP address. DNS servers are used to translate human-readable domain names (e.g., www.rabbit.com) into machine-readable IP addresses.

2.2.2 Sources of Configuration Information

The Dynamic C TCP/IP stack obtains configuration information from one or more of the following sources:

• Use one of the predefined configurations in tcp_config.lib; static or dynamic.
• Macro definitions before #use "dcrtcp.lib"; static configuration.
• Bootstrap network protocols such as BOOTP and DHCP; dynamic configuration.
• Runtime function calls such as ifconfig() (version 7.30) and sethostid() (previous versions).
• "Directed ping" IP address assignment (new in version 7.30).
• Console-based configuration, e.g., zconsole.lib.

As application designer, you have to decide which of these configuration techniques is right for your project. Entirely static configuration is typically used for initial application development and testing. Most of the TCP/IP sample programs use static configuration for simplicity in getting started. Applications which are intended for real-world use should allow at least one form of dynamic configuration. The particular form of configuration that is supported will depend on the complexity of the application, as well as the expected network or operational environment in which the application will run.

2.2.2.1 Predefined Configurations

Since networking configuration can be fairly complicated, Dynamic C version 7.30 has the concept of "canned" or predefined configurations. This has the advantage of reducing the number of macro definitions at the top of each TCP/IP program, as well as eliminating the need for copy/paste of a lot of settings from one program to the next.

Using the predefined configurations is very easy: simply #define a single macro (called TCPCONFIG) at the top of each program. The macro is defined to an integer, which selects one of the predefined configurations in tcp_config.lib. For example:

#define TCPCONFIG 1
#use "dcrtcp.lib"

causes the first predefined configuration to be used.

Most of the sample TCP/IP programs refer to one of the predefined configurations. It is fairly likely (unfortunately) that none of the configurations will work with your network. For example, the default IP address of "10.10.6.100" may not be allowed on your LAN. If this is the case, you can define the default IP address in your application or in the "Defines" tab of the Project Options dialog box.

To configure within your program, copy and paste the following into your code and modify as necessary:

#define TCPCONFIG           1
#define _PRIMARY_STATIC_IP  "10.10.6.100"
#define _PRIMARY_NETMASK    "255.255.255.0"
#define MY_GATEWAY          "10.10.6.1"
#define MY_NAMESERVER       "10.10.6.1"

To configure within the Project Options dialog box, copy and paste the following into the Defines window and modify as necessary:

TCPCONFIG          = 1;
_PRIMARY_STATIC_IP = "10.10.6.100";
_PRIMARY_NETMASK   = "255.255.255.0";
MY_GATEWAY         = "10.10.6.1";
MY_NAMESERVER      = "10.10.6.1";

Another way to change the default configuration is to create a library called custom_config.lib. In this library, you can place your own custom configurations which will not be overwritten by Dynamic C (since this is not a released library).

To create custom_config.lib, you can use tcp_config.lib as a template. Modify the definitions to suit your network environment. You must change the configuration numbers (i.e., the value of TCPCONFIG) to be greater than or equal to 100. Numbers less than 100 are expected to be in tcp_config.lib; numbers over 99 cause custom_config.lib to be included.

If you are using a Dynamic C version prior to 9.30, then the other thing you must do before using your own custom configurations is to add the library name (custom_config.lib) to the lib.dir file in the base Dynamic C installation directory. This is just a text file, which you can edit with the Dynamic C text editor. Locate the line that contains "tcp_config.lib." Repeat this line, and modify one of the line copies to point to your custom_config.lib file. You will not have to restart Dynamic C for this change to take effect. A new release of Dynamic C will overwrite the lib.dir file, so you will need to perform this edit for each release.

Starting with Dynamic C 9.30, lib.dir references entire directories automatically, so it is not necessary to edit it for the addition of the custom library.

To use custom configurations that you define, the only thing necessary in each sample program is to change the definition of the TCPCONFIG macro to indicate the appropriate configuration e.g.,

#define TCPCONFIG 100
#use "dcrtcp.lib"

2.2.2.2 Static Configuration

This is conceptually the easiest means of configuration; however it is primarily suitable for testing purposes (or possibly as a fallback in case other configuration techniques do not yield a result in a reasonable amount of time).

Prior to version 7.30, the (only) interface was configured by defining a fixed set of macros before including dcrtcp.lib. The most common definitions were limited to:

MY_IP_ADDRESS, MY_NETMASK, MY_GATEWAY and MY_NAMESERVER.

At runtime, the functions, tcp_config(), sethostid() and sethostname() override the configuration macros.

Version 7.30 still allows use of these macros for backwards compatibility; however, it is recommended that the new style of static configuration be used for new applications. The new configuration style uses macros called IFCONFIG_*, where `*' is replaced by the interface name e.g., IFCONFIG_ETH0 for the first Ethernet port. IFCONFIG_ALL contains configuration items that are not specific to any particular interface.

The value of the IFCONFIG_* macro is actually a list of items in the syntactic form of a C parameter list. For example, if the old style configuration (for Ethernet) was

#define MY_IP_ADDRESS "10.10.6.100"
#define MY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"

then the new replacement would be

#define IFCONFIG_ETH0 \
    IFS_IPADDR, aton("10.10.6.100"), \
    IFS_NETMASK, aton("255.255.255.0"), \
    IFS_ROUTER_SET, aton("10.10.6.1"), \
    IFS_UP

The replacement looks more complex, but this is because the macro value must be valid C syntax for a parameter list. The IFS_UP parameter at the end of the above example is a new feature for interfaces: they can be dynamically brought up and down. The default state for an interface is "down," which is why an explicit IFS_UP is required. The backslashes at the end of each line are used to continue the macro definition over more than one line.

The format of the static initialization macros will make more sense if you examine the documentation for the ifconfig() function. You will see that the macro definition is merely "plugged in" to the parameter list for an ifconfig() call.

2.2.2.3 Dynamic Configuration via the Network

The Dynamic C TCP/IP stack supports DHCP (Dynamic Host Configuration Protocol) or BOOTP (Bootstrap Protocol) for dynamic configuration. DHCP is a more modern replacement for BOOTP, which was originally designed to support bootstrap of diskless workstations. Use of these protocols can completely eliminate the need for static configuration.

The library BOOTP.LIB allows a target board to be a BOOTP or DHCP client. The protocol used depends on what type of server is installed on the local network. BOOTP and DHCP servers are usually centrally located on a local network and operated by the network administrator. Note that initialization may take longer when using DHCP as opposed to static configuration, but this depends on your server. Also note that if the interface goes down for any reason, the application will need to bring the interface back up and redo any changes to the default configuration, such as setting IFS_DHCP_TIMEOUT. This behavior differs from the behavior of a PC, which will automatically bring the interface back up.

Both protocols allow a number of configuration parameters to be sent to the client, including:

• client's IP address
• net mask
• list of gateways
• host and default domain names
• list of name servers

BOOTP assigns permanent IP addresses. DHCP can "lease" an IP address to a host, i.e., assign the IP address for a limited amount of time. There are two user-callable functions regarding IP address leases dhcp_release() and dhcp_acquire() (described in Chapter 8). In addition, there are a number of macros and global variables available for modifying behavior and obtaining information. Please see Section 2.6.3 and Section 2.6.4 for details.

As of Dynamic C 7.30, DHCP or BOOTP can be used only on the default interface i.e., the interface that is specified by the value of IF_DEFAULT. If you are using more than one interface then you should ensure that IF_DEFAULT is set correctly.

To successfully use DHCP configuration, ensure all of the following conditions are met. (Only the first condition applies prior to 7.30.)

• #define USE_DHCP before including dcrtcp.lib.
• Ensure IF_DEFAULT is indicating the desired interface.
• Define an IFCONFIG_* macro to include the IFS_DHCP parameter ID.

For example, if the Ethernet interface is to be used for DHCP, the following code is required for DHCP:

#define USE_DHCP
#define IF_DEFAULT 0             // not necessary unless also using PPP
#define IFCONFIG_ETH0 IFS_DHCP, 1, IFS_UP
#use "dcrtcp.lib"

You may also use the predefined configuration number 3, which is DHCP:

#define TCPCONFIG 3
#use "dcrtcp.lib"

This configuration sets all required macros for DHCP (or BOOTP) to work. Naturally, there must be a DHCP server available on the interface. The DHCP server must be set up to contain all the required configuration options, however setting up the DHCP server is outside the scope of this document, since there are many different DHCP servers in use.

The sample program Samples\tcpip\dhcp.c uses dynamic configuration in a basic TCP/IP program that will initialize the TCP/IP interface, and allow the device to be "pinged" from another computer on the network. It demonstrates DHCP features, such as releasing and re-acquiring IP addresses and downloading a configuration file.

2.2.2.4 Runtime Configuration Using ifconfig()

ifconfig() is a function introduced in version 7.30. This function does many things, and is the recommended replacement for some of the functions marked as "deprecated" (including tcp_config()). ifconfig() performs most of the work for all the other configuration techniques. For example, static configuration (via the IFCONFIG_* macros) basically calls ifconfig() with the specified parameters substituted in.

ifconfig() takes a variable number of parameters, like printf(), however the parameter list is terminated with the special IFS_END symbol. For example, to use ifconfig() to set the same parameters as described above for the static configuration:

ifconfig(IF_ETH0, IFS_IPADDR, aton("10.10.6.100"), 
         IFS_NETMASK, aton("255.255.255.0"),
         IFS_ROUTER_SET, aton("10.10.6.1"), 
         IFS_UP,
         IFS_END);

Note that this is the same as substitution of the IFCONFIG_* macro e.g.,

ifconfig(IF_ETH0, IFCONFIG_ETH0, IFS_END);

ifconfig() is also used to obtain current configuration items at runtime. For example,

longword ipaddr;
ifconfig(IF_ETH0, IFG_IPADDR, &ipaddr, IFS_END);

gets the current IP address of the first Ethernet interface into the variable ipaddr.

The first parameter of ifconfig() is the interface number. For certain settings, this can also be IF_ANY, which means apply the settings to all applicable interfaces. The parameters following the first are an arbitrary number of tuples consisting of a parameter identifier followed by the value(s) for that parameter (if any). The list of parameters must be terminated by a special identifier, IFS_END. See the documentation for ifconfig() for a complete list of parameter identifiers with their expected values.

2.2.2.5 Directed Ping

This style of configuration, also known as ICMP configuration, is limited to setting the IP address of the interface. It only works on non-PPPoE Ethernet interfaces. To specify directed ping configuration, use the IFS_ICMP_CONFIG parameter ID in a call to ifconfig() or in the definition of the IFCONFIG_* macro for the interface. For example

#define IFCONFIG_ETH0 IFS_ICMP_PING, 1

for a static configuration, or

ifconfig(IF_ETH0, IFS_ICMP_CONFIG, 1, IFS_END);

at runtime. Note that you can use both directed ping and DHCP on the same interface, but directed ping is not limited to just the default interface. If both directed ping and DHCP are allowed on a particular interface, the first one "wins."

Directed ping works as follows. The interface is brought up, but has no assigned IP address so it cannot be used for normal traffic. If the interface receives an ICMP echo request (i.e., ping) which is directed to the interface's MAC address, then the destination IP address in the ICMP packet is assigned to the interface as its home IP address. After that point, the interface is configured and is available for normal traffic.

The weakness of directed ping is that only the IP address is provided. The netmask must be pre-configured or obtained by other means. Technically, directed ping violates some tenets of the Internet standards, however, it can be useful in controlled environments.

The MAC address of the board must be known (see below) for directed ping to work. The host which initiates the ICMP echo request must have its ARP table statically configured with the target MAC address. On Unix and Windows hosts, the appropriate command sequence is

arp -s <IP address> <MAC address>

followed by

ping <IP address>

The actual format of the MAC address depends on the operating system. Most hosts will recognize a format like "00-09-A0-20-00-99". The IP address is in dotted decimal notation.

Once the interface is configured by directed ping (or DHCP), then further directed ping or DHCP configurations for that interface are not allowed. If desired, at runtime you can issue

ifconfig(IF_ETH0, IFS_ICMP_CONFIG_RESET, IFS_END);

to allow another directed ping configure.

2.2.2.6 Console Configuration Via Zconsole.lib

The zconsole.lib library contains routines for allowing an external (serial or telnet) terminal to issue configuration commands. Basically, the commands call ifconfig() to perform the actual requests or obtain information.

Using a "dumb terminal" connection over a serial port presents no special difficulties for network configuration. Using telnet over the internet obviously requires a working TCP stack to begin with. This is still useful in the case that one of the other configuration techniques can at least get to a working state. For example, directed ping can assign an IP address. You could then use the same host to telnet into the new IP address in order to set other items like the netmask and router.

2.2.2.7 Media Access Control (MAC) Address

Rarely, ISPs require that the user provide them with a MAC address for their device. Run the utility program, Samples\tcpip\display_mac.c, to display the MAC address of your controller board.

The MAC address is also required for directed PING configure, as well as some other bootstrap techniques. MAC addresses are often written as a sequence of six two-digit hexadecimal numbers, separated by colons e.g., 00:90:20:33:00:A3. This distinguishes them from IP addresses, which are written with dotted decimal numbers.

MAC addresses are completely unrelated to IP addresses. IP addresses uniquely identify each host on the global Internet. MAC addresses uniquely identify Ethernet hardware on a particular Ethernet LAN segment. Although only technically required to be unique on a LAN segment, in practice MAC addresses are globally unique and can thus be used to uniquely identify a particular Ethernet adapter.

The usual reason for an ISP requiring a MAC address is if the ISP uses DHCP to dynamically assign IP addresses. Most ISPs use PPP (Point to Point Protocol) which does not care about MAC addresses. DHCP can use the MAC address to determine that the same device is connecting, and assign it the same IP address as before.

2.3 Dynamically Starting and Stopping Interfaces

Starting with version 7.30, Dynamic C allows interfaces to be individually brought up and down by calling the ifup(), ifdown() or ifconfig() functions. The initial desired state of the interface is specified using the IFCONFIG_* macros. By default, interfaces are not brought up when sock_init() is called at boot time. Only if the IFCONFIG_* macro contains an IFS_UP directive will the interface be brought up at boot time.

Most applications should not need to dynamically change the interface status. The exception to this may be PPP over serial interfaces, where a modem is used to dial out to an ISP on demand.

2.3.1 Testing Interface Status

There are two functions for testing the current status of an interface: ifstatus() and ifpending(). The function ifstatus() merely returns a boolean value indicating whether the interface is up. If the return value is true (non-zero), then the interface is ready for normal TCP/IP communications. Otherwise, the interface is not yet available; it may either be down, or in the process of coming up.

ifpending() gives more information: its return value indicates not only the current state, but also if the state is in the process of changing. This function is very handy when using WiFi; in particular, it can be used to make sure it is okay to call the wifi_ioctl() function for most commands.

If your application needs to check the interface status, which is recommended for PPP over serial or PPPoE, then it can either poll the status using the above functions, or it can register a callback function which is automatically called whenever the interface changes status.

To register a callback function, you call ifconfig() with the IFS_IF_CALLBACK as the parameter identifier, and the address of your callback function as the parameter value.

2.3.2 Bringing an Interface Up

You can call ifup(), or ifconfig() with the IFS_UP parameter identifier. The advantage of using ifconfig() is that you can specify an interface number of IF_ANY, which brings all interfaces up together.

When the ifup() call returns, the interface may not have completed coming up. This is notably the case for PPP interfaces, which require a number of protocol negotiation packets to be sent and received. In addition, PPP over serial may require additional time to reset a modem, dial out to an ISP, and possibly respond to the ISP's login procedure. All this could take considerable time, so the ifup() function does not wait around for the process to complete, to allow the application to proceed with other work.

On return from the ifup() call, an application must test for completion using the functions described in the previous section.

For the interface to come up completely, your application must call tcp_tick() regularly while waiting for it. If you can afford to block until the interface is up, then use code similar to the following:

ifup(IF_PPP2);

// Wait for the interface to have any status other than "down coming up."
while (ifpending(IF_PPP2) == 1) tcp_tick();

if (ifstatus(IF_PPP2))
   printf("PPP2 is up now.\n");

else
   printf("PPP2 failed to come up.\n");

2.3.3 Bringing an Interface Down

You can call ifdown(), or ifconfig() with the IFS_DOWN parameter identifier. The advantage of using ifconfig() is that you can specify an interface number of IF_ANY, which brings all interfaces down together.

As for ifup(), ifdown() does not necessarily complete immediately on return. PPP requires link tear-down messages to be sent to the peer and acknowledged. Thus, similar considerations apply to bringing an interface down as they do for bringing it up.

ifdown() will always succeed eventually. Unlike ifup(), which can possibly fail to bring the interface up, ifdown() will always eventually return success i.e., it is not possible for an interface to be left "hanging up." If the PPP link tear-down does not get an acknowledgment from the peer, then the process times out and the link is forced down.

2.4 Setting Up Wi-Fi Interfaces

Wi-Fi has some specific configuration macros in addition to the basic TCP/IP macros that define the IP address, netmask, gateway and nameserver. This section will describe the setup of Wi-Fi, both at compile time and runtime. The configuration macros used in the code in this section are described in Section 2.6.11.

The Wi-Fi interface is considered "up" (ifpending() returns that the interface is up and the link LED is on) in the following conditions:

• If connecting to an AP using no encryption, then the link is "up" when 802.11 association has completed.
• If connecting to an AP with TKIP/WPA or CCMP/WPA2 encryption, the link is "up" after the 802.11i handshake has completed successfully. This means that the pre-shared key must be correct before the link is considered up.
• If connecting to an AP with WEP encryption, then the link is "up" when 802.11 association has completed, whether or not the WEP key is correct. This means that a WEP connection can show as being "up" even though the key is wrong. This is because, unlike TKIP or CCMP, WEP does not provide a way of knowing whether or not the key used is correct.

2.4.1 Wi-Fi Compile Time Configuration

The examples given here cover both Wi-Fi modes: ad-hoc and infrastructure. Note that a Wi-Fi interface can be configured for DHCP support but the examples in this section will show only static configuration.

2.4.1.1 Infrastructure, Open (No Encryption) Configuration

The simplest way to configure a Wi-Fi network interface is to use an open configuration. This means that no encryption or authentication is used. This example is configured for infrastructure mode, which means that you will also need a Wi-Fi access point or Wi-Fi router. Note that your wireless access point will need to match these settings (in particular, the SSID must be the same, and the AP must not have encryption enabled).

To configure within your program, copy and paste the following into your sample program and modify as necessary:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define IFC_WIFI_SSID  "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCT
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_NONE

Alternatively, you can configure within the Defines window. Here is an example to copy and paste into the Defines window and modify as necessary:

TCPCONFIG = 1;
_PRIMARY_STATIC_IP = "10.10.6.100";
_PRIMARY_NETMASK = "255.255.255.0";
MY_GATEWAY = "10.10.6.1";
MY_NAMESERVER = "10.10.6.1";
IFC_WIFI_SSID = "rabbitTest";
IFC_WIFI_ROAM_ENABLE = 1;
IFC_WIFI_ROAM_BEACON_MISS = 20;
IFC_WIFI_MODE = IFPARAM_WIFI_INFRASTRUCTURE;
IFC_WIFI_REGION = IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION = IFPARAM_WIFI_ENCR_NONE;

2.4.1.2 Ad-hoc, Open (No Encryption) Configuration

Another simple way to configure a Wi-Fi network interface is to use an open configuration in ad-hoc mode. An ad-hoc Wi-Fi network does not require an access point or Wi-Fi router to operate. Instead, the Wi-Fi devices communicate directly with each other. This is useful for an isolated Wi-Fi network, but it is not typically used when devices need to communicate outside of their own network. Note that all Wi-Fi devices on an ad-hoc network need to match these settings (in particular, the SSID and the channel number must be the same).

To configure within your program, copy and paste the following into your sample program and modify as necessary:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP  "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define _WIFI_SSID "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_CHANNEL 1
#define IFC_WIFI_MODE IFPARAM_WIFI_ADHOC
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_NONE

Alternatively, you can configure within the Defines window. Here is an example to copy and paste into the Defines window and modify as necessary:

TCPCONFIG = 1;
_PRIMARY_STATIC_IP = "10.10.6.100";
_PRIMARY_NETMASK = "255.255.255.0";
MY_GATEWAY = "10.10.6.1";
MY_NAMESERVER = "10.10.6.1";
IFC_WIFI_SSID = "rabbitTest";
IFC_WIFI_ROAM_ENABLE = 1;
IFC_WIFI_ROAM_BEACON_MISS = 20;
IFC_WIFI_CHANNEL = 1;
IFC_WIFI_MODE = IFPARAM_WIFI_ADHOC;
IFC_WIFI_REGION = IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION = IFPARAM_WIFI_ENCR_NONE;

2.4.1.3 Infrastructure, WEP Encryption Configuration

WEP is an encryption method for Wi-Fi networks. It is now considered insecure, but it is commonly supported by Wi-Fi devices. To use WEP, all devices including the access point or Wi-Fi router will need to be configured with the same WEP keys (as well as the same SSID). WEP allows multiple keys to be defined; all devices will need to be configured to use the same key number.

WEP keys are used for WEP shared key authentication and for WEP encryption. The Wi-Fi driver stores up to 4 different WEP keys (0 to 3) of either 5 or 13 bytes.

To configure within your program, copy and paste the following into your sample program and modify as necessary:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define IFC_WIFI_SSID "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCTURE
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_WEP
#define IFC_WIFI_WEP_KEYNUM 0
#define IFC_WIFI_WEP_KEY0_HEXSTR "0123456789abcdef0123456789"


// alternate method to define a WEP key

#define IFC_WIFI_WEP_KEY0_BIN \
0x01, 0x23, 0x45, 0x67, 0x89, 0xab,0xcd, 0xef,\
0x01, 0x23, 0x45, 0x67, 0x89

Alternatively, you can configure within the Defines window. Here is an example to copy and paste into the Defines window and modify as necessary:

TCPCONFIG = 1;
_PRIMARY_STATIC_IP = "10.10.6.100";
_PRIMARY_NETMASK = "255.255.255.0";
MY_GATEWAY = "10.10.6.1";
MY_NAMESERVER = "10.10.6.1";
IFC_WIFI_SSID = "rabbitTest";
IFC_WIFI_ROAM_ENABLE = 1;
IFC_WIFI_ROAM_BEACON_MISS = 20;
IFC_WIFI_MODE = IFPARAM_WIFI_INFRASTRUCTURE;
IFC_WIFI_REGION = IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION = IFPARAM_WIFI_ENCR_WEP;
IFC_WIFI_WEP_KEYNUM = 0;
IFC_WIFI_WEP_KEY0_HEXSTR = "0123456789abcdef0123456789";

2.4.1.4 Infrastructure, WPA/TKIP Encryption Configuration, Pre-Shared Key

Wi-Fi Protected Access (WPA) along with Temporal Key Integrity Protocol (TKIP) replaces the less secure WEP encryption method. The Rabbit Wi-Fi driver supports WPA encryption² in pre-shared key (PSK) mode. This key can be specified as a 256-bit key or as a passphrase that is expanded into a key. The code for WPA/TKIP is compiled when you define the macro WIFI_USE_WPA.

To configure within your program, copy and paste the following into your sample program and modify as necessary:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define WIFI_USE_WPA
#define IFC_WIFI_SSID "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCTURE
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_TKIP

You will also need to define WPA's pre-shared key mode. This can be done by specifying a passphrase that the driver will expand to a 256-bit key or by specifying the 256-bit key itself. Note that expanding a passphrase takes a significant amount of time at startup, up to about 20 seconds. Define WIFI_VERBOSE_PASSPHRASE to see status messages when the key is generated from the passphrase.

To specify the WPA passphrase, you will need something like the following:

#define IFC_WIFI_WPA_PSK_PASSPHRASE "myPassphrase"

To specify the WPA Pre-Shared Key itself, use the following:

#define IFC_WIFI_WPA_PSK_HEXSTR \ "1122334455667788990011223344556677889900112233445566778899001122"

Alternatively, you can configure within the Defines window:

TCPCONFIG = 1;
_PRIMARY_STATIC_IP = "10.10.6.100";
_PRIMARY_NETMASK = "255.255.255.0";
MY_GATEWAY = "10.10.6.1";
MY_NAMESERVER = "10.10.6.1";
WIFI_USE_WPA;
IFC_WIFI_SSID = "rabbitTest";
IFC_WIFI_ROAM_ENABLE = 1;
IFC_WIFI_ROAM_BEACON_MISS = 20;
IFC_WIFI_MODE = IFPARAM_WIFI_INFRASTRUCTURE;
IFC_WIFI_REGION = IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION = IFPARAM_WIFI_ENCR_TKIP;

To specify a WPA passphrase or Pre-Shared Key:

IFC_WIFI_WPA_PSK_PASSPHRASE = "myPassphrase";

To specify the WPA Pre-Shared Key itself:

IFC_WIFI_WPA_PSK_HEXSTR =  "1122334455667788990011223344556677889900112233445566778899001122";

2.4.1.5 Infrastructure, WPA2/CCMP Encryption Configuration, Pre-Shared Key

WPA2 is a more secure replacement for WEP. This implementation uses the Advanced Encryption Standard (AES) based algorithm, also known as CCMP (Counter Mode with Cipher Block Chaining Message Authentication Code Protocol) cipher suite. The Rabbit Wi-Fi driver supports CCMP/WPA2 encryption with Pre-Shared Keys (PSK). These keys can be specified as a 256-bit key or as a passphrase that is expanded into a key. Note that the code for this encryption method is not compiled unless you define the macros WIFI_USE_WPA and WIFI_AES_ENABLED.

To configure within your program, copy and paste the following into your sample program and modify as necessary for your situation:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define WIFI_USE_WPA
#define WIFI_AES_ENABLED
#define IFC_WIFI_SSID "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCTURE
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_CCMP

You will also need to define WPA2's pre-shared key mode. This can be done by specifying a passphrase that the driver will expand to a 256-bit key or by specifying the 256-bit key itself. Note that expanding a passphrase takes a significant amount of time at startup, up to about 20 seconds. Define WIFI_VERBOSE_PASSPHRASE to see status messages when the key is generated from the passphrase.

To specify the WPA2 passphrase, you will need something like the following:

#define IFC_WIFI_WPA_PSK_PASSPHRASE "myPassphrase"

To specify the WPA2 Pre-Shared Key itself, use the following:

#define IFC_WIFI_WPA_PSK_HEXSTR \ "1122334455667788990011223344556677889900112233445566778899001122"

Alternatively, you can configure within the Defines window:

TCPCONFIG 1;
_PRIMARY_STATIC_IP "10.10.6.100";
_PRIMARY_NETMASK "255.255.255.0";
MY_GATEWAY "10.10.6.1";
MY_NAMESERVER "10.10.6.1";
WIFI_USE_WPA;
WIFI_AES_ENABLED;
IFC_WIFI_SSID "rabbitTest";
IFC_WIFI_ROAM_ENABLE 1;
IFC_WIFI_ROAM_BEACON_MISS 20;
IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCTURE;
IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_CCMP;

Again, you will need to specify a WPA2 passphrase or Pre-Shared Key. To specify the WPA2 passphrase, use the following:

IFC_WIFI_WPA_PSK_PASSPHRASE = "myPassphrase";

To specify the WPA Pre-Shared Key itself, use the following:

IFC_WIFI_WPA_PSK_HEXSTR = \ "1122334455667788990011223344556677889900112233445566778899001122";

2.4.1.6 Infrastructure, WPA Enterprise using EAP-TLS and CCMP Encryption

To configure within your program, copy and paste the following into your sample program and modify as necessary:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define WIFI_USE_WPA
#define WIFI_AES_ENABLED
#define IFC_WIFI_SSID "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCTURE
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_CCMP
// The above defines are identical to using CCMP with PSK

#define WPA_USE_EAP WPA_USE_EAP_TLS
#define IFC_WIFI_WPA_PROTOCOL IFPARAM_WIFI_WPA_PROTOCOL_WPA2
#ximport "certs/root.pem" root_ca_cert
#ximport "certs/my_client.pem" my_client_cert
#define IFC_WIFI_CLIENT_CERT_XIM my_client_cert, my_client_cert
#define IFC_WIFI_CA_CERT_XIM root_ca_cert
#define IFC_WIFI_IDENTITY "MyClientIdent"
#define SSL_USE_AES

Because it is necessary to ximport SSL certificates for use with this encryption method, it is not possible to completely configure WPA Enterprise with EAP/TLS and CCMP using the Project Defines. However, as long as you include something like these two #ximport statements in your program:

#ximport "certs/root.pem" root_ca_cert
#ximport "certs/my_client.pem" my_client_cert

you can provide the rest of the configuration in the Project Defines. Here is an example--copy and paste into the Defines window and modify as necessary:

TCPCONFIG                 = 1;
_PRIMARY_STATIC_IP        = "10.10.6.100";
_PRIMARY_NETMASK          = "255.255.255.0";
MY_GATEWAY                = "10.10.6.1";
MY_NAMESERVER             = "10.10.6.1";
WIFI_USE_WPA;
WIFI_AES_ENABLED;
IFC_WIFI_SSID             = "rabbitTest";
IFC_WIFI_ROAM_ENABLE = 1;
IFC_WIFI_ROAM_BEACON_MISS = 20;
IFC_WIFI_MODE             = IFPARAM_WIFI_INFRASTRUCTURE;
IFC_WIFI_REGION           = IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION       = IFPARAM_WIFI_ENCR_CCMP;
WPA_USE_EAP = WPA_USE_EAP_TLS;
IFC_WIFI_WPA_PROTOCOL     = IFPARAM_WIFI_WPA_PROTOCOL_WPA2;
IFC_WIFI_CLIENT_CERT_XIM  = my_client_cert, my_client_cert;
IFC_WIFI_CA_CERT_XIM      = root_ca_cert;
IFC_WIFI_IDENTITY         = "MyClientIdent";
SSL_USE_AES;

2.4.1.7 Infrastructure, WPA Enterprise using PEAP and TKIP Encryption

To configure within your program, copy and paste the following into your sample program and modify as necessary for your situation:

#define TCPCONFIG 1
#define _PRIMARY_STATIC_IP "10.10.6.100"
#define _PRIMARY_NETMASK "255.255.255.0"
#define MY_GATEWAY "10.10.6.1"
#define MY_NAMESERVER "10.10.6.1"
#define WIFI_USE_WPA
#define IFC_WIFI_SSID "rabbitTest"
#define IFC_WIFI_ROAM_ENABLE 1
#define IFC_WIFI_ROAM_BEACON_MISS 20
#define IFC_WIFI_MODE IFPARAM_WIFI_INFRASTRUCTURE
#define IFC_WIFI_REGION IFPARAM_WIFI_REGION_AMERICAS
#define IFC_WIFI_ENCRYPTION IFPARAM_WIFI_ENCR_TKIP
// The above defines are identical to using TKIP with PSK

#define WPA_USE_EAP WPA_USE_EAP_PEAP
#ximport "certs/root.pem" root_ca_cert
#define IFC_WIFI_CA_CERT_XIM root_ca_cert
#define IFC_WIFI_IDENTITY "my_user1d"
#define IFC_WIFI_PASSWORD "my_passw0rd"

Because it is necessary to ximport SSL certificates for use with this encryption method, it is not possible to completely configure WPA Enterprise with PEAP using the Project Defines. However, as long as you include something similar to this #ximport statement in your program:

#ximport "certs/root.pem" root_ca_cert

you can provide the rest of the configuration in the Project Defines. Here is an example--copy and paste into the Defines window and modify as necessary:

TCPCONFIG                 = 1;
_PRIMARY_STATIC_IP        = "10.10.6.100";
_PRIMARY_NETMASK          = "255.255.255.0";
MY_GATEWAY                = "10.10.6.1";
MY_NAMESERVER             = "10.10.6.1";
WIFI_USE_WPA;
IFC_WIFI_SSID             = "rabbitTest";
IFC_WIFI_ROAM_ENABLE      = 1;
IFC_WIFI_ROAM_BEACON_MISS = 20;
IFC_WIFI_MODE             = IFPARAM_WIFI_INFRASTRUCTURE;
IFC_WIFI_REGION           = IFPARAM_WIFI_REGION_AMERICAS;
IFC_WIFI_ENCRYPTION       = IFPARAM_WIFI_ENCR_TKIP;
WPA_USE_EAP               = WPA_USE_EAP_PEAP;
IFC_WIFI_IDENTITY         = "my_user1d";
IFC_WIFI_PASSWORD         = "my_passw0rd";
IFC_WIFI_CA_CERT_XIM      = root_ca_cert;

2.4.1.8 Specifying a Pre-Shared Key

There are two ways to specify a pre-shared key--either by specifying the 256-bit pre-shared key directly in hex format, or by entering a passphrase. A passphrase is the most common method. All Wi-Fi devices that accept a passphrase use a standard algorithm to generate the pre-shared key from the passphrase and the SSID. That is, all Wi-Fi devices (including Access Points) that are configured with the same passphrase and the same SSID will generate the same pre-shared key.

IMPORTANT:

When statically configuring a Rabbit Wi-Fi device, you should specify either the pre-shared key with _WIFI_PSK_HEX or the passphrase with _WIFI_PSK_PASSPHRASE, but NOT BOTH! If you do specify both, then _WIFI_PSK_HEX will take precedence; that is, if you have a correct passphrase but an incorrect pre-shared key, then the incorrect pre-shared key will be used.

2.4.1.9 Ad-hoc, WPA/TKIP or WPA2/CCMP Encryption Configuration

The Wi-Fi driver does not support the use of ad-hoc mode with WPA/TKIP or WPA2/CCMP encryption. Ad-hoc mode with encryption is not well supported by Wi-Fi devices in general. There are multiple standards for supporting encryption on ad-hoc mode, but none of them are widely implemented. If you desire encryption for your Wi-Fi network, then we strongly recommend using infrastructure mode with one or more access points.

2.4.2 Wi-Fi RunTime Configuration

There are two runtime functions for Wi-Fi configuration.

2.4.2.1 RunTime Configuration Starting with Dynamic C 10.40

Dynamic C 10.40 introduces an expanded ifconfig() function that includes Wi-Fi configuration parameters. All Wi-Fi programs should switch to using ifconfig() for configuring Wi-Fi at runtime.

Dynamic C 10.54 introduces ifconfig() parameter identifiers for Wi-Fi Enterprise mode authentication. The Rabbit Embedded Security Pack is needed to make use of these parameters. It is available for purchase on the Rabbit web site:

www.rabbit.com/store/index.shtml

2.4.2.2 RunTime Configuration Prior to Dynamic C 10.40

Prior to Dynamic C 10.40, runtime configuration was via the function wifi_ioctl()that is described in this section. This function has been deprecated as of 10.40.

wifi_ioctl

---

int wifi_ioctl( int iface, int cmd, char * data, int len );

Description

This function is used to configure the Wi-Fi interface, including setting the SSID, the mode, WEP keys, etc. It can also be used to get status information and to request a Wi-Fi scan.

Note that the Wi-Fi interface should be down for most of the commands which perform alterations of the driver state. Those commands are documented with the text "[requires interface to be down]". If the interface must be down before calling this function, then the following code may be used to accomplish this objective:

if (ifpending(IF_WIFI0) != IF_DOWN) {
  printf("Bringing WiFi down (disassociating)...\n");
  ifdown(IF_WIFI0);
  while (ifpending(IF_WIFI0) != IF_DOWN)
    tcp_tick(NULL);
  printf("...Done.\n");
}

printf("Setting parameters...\n");

wifi_ioctl(IF_WIFI0, WIFI_WEP_KEY0, KEY0, sizeof(KEY0));
wifi_ioctl(IF_WIFI0, WIFI_SSID, "shiva-ap", 8);

printf("Bringing interface back up (associating)...\n");

ifup(IF_WIFI0);

while (ifpending(IF_WIFI0) == IF_COMING_UP)
  tcp_tick(NULL);

printf("...Done.\n");

if (ifpending(IF_WIFI0) != IF_UP) {
  printf("Unfortunately, it failed to associate :-(\n");
  // handle error
}

Naturally, you can omit the printf statements.

Parameters

iface

Specifies the Wi-Fi device interface number (either IF_WIFI0 or IF_DEFAULT)

The cmd, data, and len parameters are described below. Each valid macro for the cmd parameter is listed, along with a description of its purpose and its data and len requirements.

WIFI_SSID

This command sets the SSID for the Wi-Fi device. For an infrastructure network (one that uses an Access Point), this is typically the name of the network. This name is typically configured on the Access Point. For an ad-hoc network, this is the name that you want to give the network you created. All devices on the ad-hoc network must use the same SSID.

Requires interface to be down.
data: char * ASCII string
len: length of string, or 0 to let driver compute it. Can be up to 32.

WIFI_OWNSSID

This command sets the SSID only for boards with an interposer card, when joining an ad-hoc (IBSS) network.

Requires interface to be down.
data: char * ASCII string.
len: length of string, or 0 to let driver compute it.Can be up to 32.

WIFI_MULTI_DOMAIN

This command enables or disable your device to be configured by an 802.11d multi-domain capable Access Point. When your device is enabled, the Access Point will provide Country Information for your device to identify the regulatory domain in which it is located and to configure its PHY for operation in that regulatory domain.

Note: The Access Point must have 802.11d option enabled with the proper country selected where your wireless device is deployed.

Requires interface to be down.
data: char *
Use "0" to disable 802.11d country information capability.
Use "1" to enable 802.11d country information capability.
len: 0

WIFI_COUNTRY_SET

This command sets the channel range and maximum power limit for the country selected.

Requires interface to be down.
data: int * (Use 0 through 9)
len: 0

The region you select will automatically determine the maximum power limit and channel range, recommend checking the regulations which your wireless devices will be deployed for any specific requirements.

The following macros have been defined for convenience.

_AMERICAS_REGION: Americas, including the US (channels 1-11)
_MEXICO_REGION_INDOORS: Mexico indoors (channels 1-11)
_MEXICO_REGION_OUTDOORS: Mexico outdoors (channels 9-11)
_CANADA_REGION 3: Canada (channels 1-11)
_EMEA_REGION: Europe, Middle East, Africa (channels 1-13), except France
_FRANCE_REGION: France (channels 10-13)
_ISRAEL_REGION: Israel (channels 3-11)
_CHINA_REGION: China (channels 1-11)
_JAPAN_REGION: Japan (channels 1-13)
_AUSTRALIA_REGION: Australia (channels 1-11)

Example

auto int country;
country = _AUSTRALIA_REGION;
wifi_ioctl (IF_WIFI0, WIFI_COUNTRY_SET, &country, 0);

WIFI_COUNTRY_GET

data: _wifi_country *
Caller must ensure there is enough space for the entire data structure. Be sure the data pointer points to a buffer that is large enough to hold sizeof(_wifi_country).
len: 0

This command returns country specific information into the user-supplied buffer (or data structure) area. The wifi_status structure has the following definition:

typedef struct {
char id;                     // Country ID
char  country[16];           // Country name
int   first_channel;         // First channel
int   last_channel;          // Last channel
unsigned int channel_mask;   // Channel mask
int   max_pwr_dBm;           // Max power, dBm
int   max_pwr_index;         // Max Power index
}_wifi_country;

WIFI_MODE

Sets whether the Wi-Fi device should attach to an infrastructure or ad-hoc network. Infrastructure networks are more common and use an Access Point (AP). The AP coordinates communication among all associated devices. An ad-hoc network does not use an AP. Instead, all communication happens between peer devices. Use WIFICONF_INFRASTRUCT for an infrastructure network, and WIFICONF_ADHOC for an ad-hoc network.

Requires interface to be down
data: char *
Use either WIFICONF_INFRASTRUCT or WIFICONF_ADHOC
len: 0

WIFI_OWNCHAN

Selects the channel that is used for this device. For an infrastructure network, this should almost always be set to "0". This allows the Wi-Fi driver to automatically pick the channel for the given SSID. For an ad-hoc network, this channel must be set to "1" through "13".

Use the wifi_ioctl command WIFI_COUNTRY_GET to get valid range of Wi-Fi channels.

Note that regional regulations may not allow some channels to be used.

Requires interface to be down.
data: char*
Can be set to "0" through "13"
len: 0

WIFI_WEP_FLAG

Use to enable or disable WEP encryption. Requires interface to be down.
data: char *
Set to one of the following values:
WIFICONF_WEP_DISABLE - Disable encryption
WIFICONF_WEP_ENABLE - Enable WEP encryption
WIFICONF_WEP_TKIP - Enable WPA/TKIP encryption
len: 0

WIFI_WEP_USEKEY

Select the WEP key to use. See how to set the WEP keys below.

data: char*
Can be set to "0" through "3"
len: 0

WIFI_WEP_KEY0
WIFI_WEP_KEY1
WIFI_WEP_KEY2
WIFI_WEP_KEY3

Set WEP keys 0, 1, 2 or 3, respectively.

Requires interface to be down.
data: char[ ]; an array of 5 or 13 hex bytes, i.e., NOT an ASCII string.
len: 5 or 13 (40-bit or 104-bit key). Set the len to 5 if this is a 40-bit key, or 13 if this is a 104-bit key. Note that in marketing literature, these are sometimes referred to as 64-bit or 128-bit keys.

WIFI_AUTH

Set the authentication method for the Wi-Fi driver.

data: char*
Use one of the following macros.
WIFICONF_AUTH_OPEN_SYS: open authentication
WIFICONF_AUTH_SHARED_KEY: shared key authentication (WEP)
WIFICONF_AUTH_ALL: both types of authentication
len: 0

WIFI_WPA_PSK_PASSPHRASE

Sets a key for the previously specified WIFI_SSID value. The key is computed as a hash of the passphrase and the target SSID. This is potentially long running. See the sample program samples\rcm4400W\tcpip\passphrase.c for alternatives.

If your program (or TCP config) defines _WIFI_PSK_PASSPHRASE to a quoted string, then that string will be used automatically as a passphrase, unless WIFI_PSK_HEX is also defined (see next command).

data: char*
An ASCII string of 1 to 63 characters, NULL terminated.
len: 0

This option is only available if using WPA, i.e., the WIFI_USE_WPA macro is defined.

WIFI_WPA_PSK_HEX

Sets a hexadecimal WPA PSK master key. The string must be exactly 64 hexadecimal digits (using the characters 0-9, a-f or A-F). This is interpreted as a byte string and parsed into the appropriate 32-byte binary key.

If your program (or TCP configuration) defines _WIFI_PSK_HEX to a quoted string of 64 hex digits, then that string will be used automatically as the PSK master key.

data: char*
An ASCII string of exactly 64 characters, NULL terminated.
len: 0

This option is only available if using WPA, i.e., the WIFI_USE_WPA macro is defined.

WIFI_TX_RATE

Set the maximum transmission rate for the Wi-Fi device.

data: char *
Use one of the following:
WIFICONF_RATE_1MBPS: 1 Mbps
WIFICONF_RATE_2MBPS: 2 Mbps
WIFICONF_RATE_5_5MBPS: 5.5 Mbps
WIFICONF_RATE_11MBPS: 11 Mbps
WIFICONF_RATE_ANY: highest data rate available
len: 0

WIFI_TX_POWER

Set the transmit power for the Wi-Fi device. Higher transmit power will result in higher dBm. Use the wifi_ioctl command WIFI_COUNTRY_GET to get the maximum power limit setting.

Note that regional regulations may not allow full range of possible power settings to be used.

data: char *
Use "0" through "15"
len: 0

WIFI_FRAG_THRESH

Set the threshold (in bytes) beyond which a frame must be fragmented when transmitted. This can be useful on a very busy or noisy network, since frame corruption will be limited to the size of a fragment rather than the whole frame. This means that only the fragment will need to be retransmitted. To be effective, the fragmentation threshold will need to be set on all wireless devices on the network as well as on the Access Point.

data: char *
Use "256" through "2346"
len: 0

WIFI_RTS_THRESH

Set the threshold (in bytes) beyond which an RTS (request-to-send) frame must be sent before the data frame can be sent. This can sometimes help performance with busy networks, although it is not frequently used.

data: char *
Use "0" through "2347"
len: 0

WIFI_SCANCB

This sets up a user callback function that will be called when a user-requested scan has completed.

data: void *
This must be a pointer to the scan callback function.
len: 0

The callback function must have the following function prototype:

root void scan_callback( far wifi_scan_data * data); 

(the name of the function can be different). The scan data will be provided in the data parameter. This structure has the following definition:

#define _WIFI_SCAN_NUM
typedef struct {
  int count;
  _wifi_wln_scan_bss   bss[_WIFI_SCAN_NUM];
} wifi_scan_data;

count will have the number of access points that were detected.

bss is an array where each element corresponds to a detected access point.

_wifi_wln_scan_bss is a structure that has the following definition:

typedef struct {
  uint8 ssid[WLN_SSID_SIZE];       // max length 32
  int ssid_len;                    // SSID length in bytes
  int channel;                     // Channel: 1-13
  mac_addr bss_addr;               // BSS ID (AP MAC address)
  uint16 bss_caps;                 // reserved
  uint8 wpa_info[WLN_WPAIE_SIZE];  // reserved
  uint8 erp_info;                  // reserved
  uint16 rates;                    // reserved
  uint16 rates_basic;              // reserved
  uint16 atim;                     // reserved
  int tx_rate;                     // Max transmit rate (in 100 kbps)
  int rx_signal;                    // Received signal strength
} _wifi_wln_scan_bss;

WIFI_SCAN

Requires interface to be down.
data: NULL (not used)
len: 0

Initiates a Wi-Fi scan. When the scan has been completed, then the configured scan callback function (see WIFI_SCANCB above) will be called The callback function must be configured before using this command. A Wi-Fi scan will briefly interrupt the network connectivity, since the scan must iterate through the channels on the wireless network.

WIFI_STATUSGET

This command returns status information into the user-supplied buffer (or data structure) area.

data: wln_status *
Caller must ensure there is enough space for the entire data structure. Be sure the data pointer points to a buffer that is large enough to hold sizeof(wifi_status).

The wln_status structure is documented with the IFG_WIFI_STATUS parameter in ifconfig().

len: 0

Return Value

0: Success
-EPERM: Operation not permitted, possibly an interface other than IF_WIFI0 was supplied.
-EINVAL: Invalid command or parameter
-EBUSY: The Wi-Fi interface is currently active. Bring it down first using ifdown(); issue required wifi_ioctl() command(s), then bring the interface up using ifup().

2.5 Setting Up PPP Interfaces

PPP interfaces are slightly more complicated to configure than non-PPPoE Ethernet. They also generally take more time to become established. The advantage of PPP is that it can be made to run over a wide variety of physical layer hardware: on Rabbit-based boards this includes the asynchronous serial ports, as well as Ethernet (using PPPoE). Use of PPP over asynchronous serial allows boards with no Ethernet hardware to communicate using TCP/IP protocols.

Starting with Dynamic C version 7.30, the process of establishing a PPP link has been more tightly integrated into the library (using the ifup/ifdown/ifconfig functions). Prior to 7.30, your application had to be hard-coded to use either Ethernet, PPP or PPPoE.

Chapter 7 explains the details of establishing PPP interfaces. The following sections provide an overview.

2.5.1 PPP over Asynchronous Serial

There are two basic scenarios for use of PPP over asynchronous serial (shortened here to just PPP). The first is a direct, hard-wired, connection to another machine. The second is a connection to an ISP (Internet Service Provider) via a modem. Modem connections introduce another layer of complexity in that the modem itself must be instructed to connect to the desired peer's modem, most often via the PSTN (Public Switched Telephone Network). Most often, ISPs also have special requirements for establishing PPP links which are often unrelated to PPP itself. For example, many ISPs require navigation of "login scripts" which are basically intended for human users.

With hard-wired connections, e.g., RS232 cables with "null modems" or "crossed-over connections," the process of establishing a PPP link is relatively simple and reliable. Bringing such a PPP link up involves opening the serial port, sending and receiving PPP link negotiation messages (known as LCP; Link Control Protocol), sending and receiving authentication messages (PAP; Password Authentication Protocol) then finally sending and receiving Internet Protocol Control Messages (IPCP). If all negotiations are successful, the link is then ready for TCP/IP traffic.

If the link is established via a modem, then an extra layer of activity must precede the initial PPP negotiation. This is outside the scope of PPP, since it is really related to the establishment of a physical layer. The TCP/IP library gives you the option of incorporating the modem connection phase into the process of bringing the interface up and down. If preferred, the modem phase can be performed entirely separately from the ifup()/ifdown() process. This may be necessary if there are special requirements for connecting to the ISP.

2.5.2 PPP over Ethernet

PPPoE is often considered a hack. It seems superfluous to define a protocol that establishes a logical "connection" between two peers on what is otherwise a broadcast (i.e., any-to-any) medium. Nevertheless, the existence of PPPoE was largely dictated by the needs of ISPs who wished to continue using their existing infrastructure, based on the earlier generation of dial-in connections. The advent of high speed (ADSL etc.) modems, that had an Ethernet connection to the user's network, made PPPoE an attractive proposition. If your application requires connection to an ISP via an ADSL modem, then you will most likely need to support PPPoE.

PPPoE also requires a physical layer negotiation to precede the normal PPP negotiations. This is known as the "access concentrator discovery" phase ("discovery" for short). PPPoE makes a distinction between PPPoE servers and PPPoE clients, however, PPP makes no distinction; you can think of PPP as also standing for Peer to Peer Protocol. The PPPoE server is known as the access concentrator. The Dynamic C TCP/IP libraries do not support acting as the access concentrator; only the PPPoE client mode is supported. This is the most common case, since the DSL modem is always configured as an access concentrator.

2.6 Configuration Macro Reference

This section arranges the configuration macros according to the function they perform.

2.6.1 Removing Unnecessary Functions

The following macros default to being undefined (i.e., the functionality is included by default). You can define one or more of these macros to free up code and data memory space.

DISABLE_DNS

This macro disables DNS lookup. This prevents a UDP socket for DNS from being allocated, thus saving memory. Users may still call resolve() with an IP address, provided that the address is in dotted decimal form i.e., does not require a real DNS lookup.

DISABLE_UDP

This macro disables all UDP functionality, including DNS, SNMP, TFTP and DHCP/BOOTP. You can define this to save a small amount of code if your application only needs to be a TCP server, or a TCP client that does not need to do name lookups. This macro is available starting with Dynamic C 7.30.

DISABLE_TCP

This macro disables all TCP functionality, including HTTP (web server), SMTP (mail) and other TCP-based protocols. You can define this to save a substantial amount of code if your application only needs UDP. This macro is available starting with Dynamic C 7.30.

2.6.2 Including Additional Functions

The following macros default to being undefined i.e., the functionality is not included by default.

USE_DHCP

This macro is required when DHCP or BOOTP functionality is desired.

USE_SNMP

Define this to be the version number of SNMP (Simple Network Management Protocol) to be supported. Currently, the only allowable value is `1'.

USE_MULTICAST

This macro will enable multicast support. In particular, the extra checks necessary for accepting multicast datagrams will be enabled and joining and leaving multicast groups (and informing the Ethernet hardware about it) will be added.

USE_IGMP

If this macro is defined, the USE_MULTICAST macro is automatically defined. This macro enables sending reports on joining multicast addresses and responding to IGMP queries by multicast routers. Unlike USE_MULTICAST, this macro must be defined to be 1 or 2. This indicates which version of IGMP will be supported. Note, however, that both version 1 and 2 IGMP clients will work with both version 1 and 2 IGMP routers. Most users should just choose version 2.

2.6.3 BOOTP/DHCP Control Macros

Various macros control the use of DHCP. Apart from setting these macros before '#use dcrtcp.lib', there is typically very little additional work that needs to be done to use DHCP/BOOTP services. Most of the work is done automatically when you call sock_init() to initialize TCP/IP. There are more control macros available than what are listed here. Please look at the beginning of the file lib\tcpip\bootp.lib for more information.

USE_DHCP

If this macro is defined, the target uses BOOTP and/or DHCP to configure the required parameters. This macro must be defined to use DHCP services.

DHCP_USE_BOOTP

If defined, the target uses the first BOOTP response it gets. If not defined, the target waits for the first DHCP offer and only if none comes in the time specified by _bootptimeout does it accept a BOOTP response (if any). Use of this macro speeds up the boot process, but at the expense of ignoring DHCP offers if there is an eager BOOTP server on the local subnet.

DHCP_CHECK

If defined, and USE_DHCP is defined, then the target will check for the existence of another host already using an offered IP address, using ARP. If the host exists, then the offer will be declined. If this happened most DHCP servers would log a message to the administrator, since it may represent a misconfiguration. If not defined, then the target will request the first offered address without checking.

DHCP_CLASS_ID "Rabbit2000-TCPIP:Rabbit:Test:1.0.0"

This macro defines a class identifier by which the OEM can identify the type of configuration parameters expected. DHCP servers can use this information to direct the target to the appropriate configuration file. The standard format: "hardware:vendor:product code:firmware version" is recommended.

DHCP_USE_TFTP

If this and USE_DHCP are defined, the library will use the BOOTP filename and server to obtain an arbitrary configuration file that will be accessible in a buffer at physical address _bootpdata, with length, _bootpsize. The global variables, _bootpdone and _bootperror indicate the status of the boot file download. DHCP_USE_TFTP should be defined to the maximum file size that may be downloaded.

DHCP_CLIENT_ID clientid_char_ptr
DHCP_CLIENT_ID_LEN clientid_length

Define a client identifier string. Since the client ID can contain binary data, the length of this string must be specified as well. This string MUST be unique amongst all clients in an administrative domain, thus in practice the client ID must be individually set for each client e.g., via front-panel configuration. It is NOT recommended to program a hard-coded string (as for class ID). Note that RFC2132 recommends that the first byte of the string should be zero if the client ID is not actually the hardware type and address of the client (see next).

DHCP_CLIENT_ID_MAC

If defined, this overrides DHCP_CLIENT_ID, and automatically sets the client ID string to be the hardware type (1 for Ethernet) and MAC address, as suggested by RFC2132.

2.6.4 BOOTP/DHCP Global Variables

The following list of global variables may be accessed by application code to obtain information about DHCP or BOOTP. These variables are only accessible if USE_DHCP is defined. The variables marked "deprecated" should be accessed using ifconfig(IF_DEFAULT,...) as noted, rather than directly accessed.

_bootpon (Deprecated)

Runtime control of whether to perform DHCP/BOOTP. This is initially set to "true." It can be set to false before calling sock_init() (the function that initializes the TCP/IP stack), causing static configuration to be used. Static configuration uses the values defined for the configuration macros, MY_IP_ADDRESS etc. If BOOTP fails during initialization, this will be reset to 0. If reset, then you can call dhcp_acquire() at some later time.

NOTE	Starting with Dynamic C 7.30, it is recommended that you do not manipulate this flag. Use ifconfig() instead to set the DHCP status for the default interface, using the IFS_DHCP/IFG_DHCP parameter.

_survivebootp (Deprecated)

Set to one of the following values:

0: If BOOTP/DHCP fails, then a runtime error occurs. This is the default.
1: If BOOTP fails, then use the values in MY_IP_ADDRESS etc. If those macros are not defined, a runtime error occurs.

NOTE	Starting with Dynamic C 7.30, it is recommended that you do not manipulate this flag. Use ifconfig() with the IFS_DHCP_FALLBACK parameter.

_dhcphost

IP address of last-used DHCP server (~0UL if none). If _survivebootp is true, then this variable should be checked to see if DHCP/BOOTP was actually used to obtain the lease. If _dhcphost is ~0UL, then the fallback parameters (MY_IP_ADDRESS etc.) were used since no DHCP server responded.

_bootphost

IP address of the last-used BOOTP/TFTP server (~0UL if none). Usually obtained from the siaddr field of the DHCP OFFER/ACK message. This is the default host used if NULL is given for the hostname in the call to tftp_exec(). This is the host that provides the boot file.

_dhcplife, _dhcpt1, _dhcpt2

These variables contain various absolute time values (referenced against SEC_TIMER) at which certain aspects of the DHCP protocol get activated. _dhcplife is when the current lease expires. If _dhcplife is ~0UL (i.e., 0xFFFFFFFF) then the lease is permanent and the other variables are not used. Otherwise, _dhcpt1 is when the current lease must be renewed by the current DHCP server. _dhcpt2 is when the lease must be re-bound to a possibly different server, if the current server does not respond. In general, _dhcpt1 < _dhcpt2 < _dhcplife. To work out the number of seconds remaining until the current lease expires, use code similar to

if (_dhcplife == ~0UL)
   printf("Lease is permanent\r\n");

else if (_dhcplife > SEC_TIMER)
   printf("Remaining lease %lu seconds\r\n",
    _dhcplife - SEC_TIMER);

else
   printf("Lease is expired\r\n");

_bootptimeout (Deprecated)

Number of seconds to wait for a BOOTP or DHCP offer. If there is no response within this time (default 30 seconds), then BOOTP is assumed to have failed, and the action specified by _survivebootp will be taken. You can set this variable to a different value before calling sock_init().

NOTE	Starting with Dynamic C 7.30, it is recommended that you do not manipulate this flag. Use ifconfig() with the IFS_DHCP_TIMEOUT parameter.

_bootpdone

Is set to a non-zero value when TFTP download of the boot file is complete. This variable only exists if DHCP_USE_TFTP is defined. It is set to one of the following values:

0: Download not complete, or boot file not yet known.
1: Boot file download completed (check _bootperror for status).
2: No boot file was specified by the server.

_bootpsize

Indicates how many bytes of the boot file have been downloaded. Only exists if DHCP_USE_TFTP is defined.

_bootpdata

Physical starting address of boot data. The length of this area will be DHCP_USE_TFTP bytes, however, the actual amount of data in the buffer is given by _bootpsize. This variable only exists if DHCP_USE_TFTP is defined and is only valid if _bootpdone is 1. You can access the data using xmem2root() and related functions.

_bootperror

Indicates any error which occurred in a TFTP process. This variable only exists if DHCP_USE_TFTP is defined and is only valid when _bootpdone is 1.

_bootperror is set to one of the following values (which are also documented with the tftp_tick() function):

	0:	No error.
	-1:	Error from boot file server, transfer terminated. This usually occurs because the server is not configured properly, and has denied access to the nominated file.
	-2:	Error, could not contact boot file server or lost contact.
	-3:	Timed out, transfer terminated.
	-4:	(not used)
	-5:	Transfer complete, but truncated because buffer too small to receive the complete file.

_smtpsrv

IP address of mail server, or 0 if not obtained.

2.6.5 Buffer and Resource Sizing

MAX_SOCKETS (deprecated)

This macro defines the number of sockets that will be allocated, not including the socket for DNS lookups. It defaults to 4. If libraries such as HTTP.LIB or FTP_SERVER.LIB are used, you must provide enough sockets in MAX_SOCKETS for them also. This macro has been replaced by MAX_TCP_SOCKET_BUFFERS and MAX_UDP_SOCKET_BUFFERS.

MAX_SOCKET_LOCKS

For µC/OS-II support. This macro defines the number of socket locks to allocate. It defaults to MAX_TCP_SOCKET_BUFFERS + MAX_UDP_SOCKET_BUFFERS.

This macro is necessary because we can no longer calculate the number of socket locks needed based on the number of socket buffers, now that the user can manage their own socket buffers.

MAX_TCP_SOCKET_BUFFERS

Starting with Dynamic C version 7.05, this macro determines the maximum number of TCP sockets with preallocated buffers. If MAX_SOCKETS is defined, then MAX_TCP_SOCKET_BUFFERS will be assigned the value of MAX_SOCKETS for backwards compatibility. If neither macro is defined, MAX_TCP_SOCKET_BUFFERS defaults to 4.

MAX_UDP_SOCKET_BUFFERS

Starting with Dynamic C version 7.05, this macro determines the maximum number of UDP sockets with preallocated buffers. It defaults to 0.

SOCK_BUF_SIZE (deprecated)

This macro determines the size of the socket buffers. A TCP socket will have two buffers of size SOCK_BUF_SIZE/2 for send and receive. A UDP socket will have a single buffer of size SOCK_BUF_SIZE. Both types of sockets take the same total amount of buffer space. This macro has been replaced by TCP_BUF_SIZE and UDP_BUF_SIZE.

TCP_BUF_SIZE

Starting with Dynamic C 7.05, TCP and UDP socket buffers are sized separately. TCP_BUF_SIZE defines the buffer sizes for TCP sockets. It defaults to 4096 bytes. Backwards compatibility exists with earlier version of Dynamic C: if SOCK_BUF_SIZE is defined, TCP_BUF_SIZE is assigned the value of SOCK_BUF_SIZE. If SOCK_BUF_SIZE is not defined, but tcp_MaxBufSize is, then TCP_BUF_SIZE will be assigned the value of tcp_MaxBufSize*2.

tcp_MaxBufSize (deprecated)

This use of this macro is deprecated in Dynamic C version 6.57 and higher; it has been replaced by SOCK_BUF_SIZE.

In Dynamic C versions 6.56 and earlier, tcp_MaxBufSize determines the size of the input and output buffers for TCP and UDP sockets. The sizeof(tcp_Socket) will be about 200 bytes more than double tcp_MaxBufSize. The optimum value for local Ethernet connections is greater than the Maximum Segment Size (MSS). The MSS is 1460 bytes. You may want to lower tcp_MaxBufSize, which defaults to 2048 bytes, to reduce RAM usage. It can be reduced to as little as 600 bytes.

tcp_MaxBufSize will work slightly differently in Dynamic C versions 6.57 and higher. In these later versions the buffer for the UDP socket will be tcp_MaxBufSize*2, which is twice as large as before.

UDP_BUF_SIZE

Starting with Dynamic C 7.05, TCP and UDP socket buffers are sized separately. UDP_BUF_SIZE defines the buffer sizes for UDP sockets. It defaults to 4096 bytes. Backwards compatibility exists with earlier version of Dynamic C: if SOCK_BUF_SIZE is defined, UDP_BUF_SIZE is assigned the value of SOCK_BUF_SIZE. If SOCK_BUF_SIZE is not defined, but tcp_MaxBufSize is, then UDP_BUF_SIZE will be assigned the value of tcp_MaxBufSize*2.

ETH_MTU

Define the Maximum Transmission Unit for Ethernet and PPPoE interfaces. The default is 600, but may be increased to a maximum of 1500 subject to root data memory limitations. PPPoE always uses a value that is 8 less than this figure. For maximum throughput on an Ethernet link, use the largest value (1500).

Note that, in DC version 7.30, a macro will be defined which is set to the larger of ETH_MTU and PPP_MTU. This macro is called MAX_MTU, and is used for sizing the receive buffer for incoming packets from all interfaces.

PPP_MTU

Define the maximum transmission/receive unit for PPP over serial links. This defaults to the same as ETH_MTU if it is defined, or 600. This macro is new for 7.30.

ETH_MAXBUFS

Define the maximum number of incoming packets that may be buffered. Defaults to 10. The buffers are shared between all interfaces (in spite of the name). The total amount of root data storage for incoming packets depends on the configured mix of interface types, but is (MAX_MTU+22)*ETH_MAXBUFS for just Ethernet without PPPoE. This will default to 6220 bytes if the defaults are selected.

ARP_TABLE_SIZE

Define to the number of ARP table entries. The default is set to the number of interfaces, plus 5 entries for every Ethernet interface (excluding PPPoE). The maximum allowable value is 200.

ARP_ROUTER_TABLE_SIZE

Define the maximum number of routers. Defaults to the number of interfaces, plus an extra entry for each Ethernet (excluding PPPoE) .

MAX_STRING

Define the maximum number of characters for a hostname or for a mail server when using the function smtp_setserver(). Defaults to 50.

MAX_NAMESERVERS

Define the maximum number of DNS servers. Defaults to 2.

MAX_COOKIES

Define the maximum number of cookies that a server can send to or receive from a client. Defaults to 1.

TCP_MAXPENDING

Define the maximum number of pending TCP connections allowed in the active list. Defaults to 20.

MAX_RESERVEPORTS

Defines the maximum number of TCP port numbers that may be reserved. Defaults to 5 if USE_RESERVEDPORTS is defined (which is defined by default). For more information about USE_RESERVEDPORTS and setting up a listen queue, please see Section 3.3.4.

DNS_MAX_RESOLVES

4 by default. This is the maximum number of concurrent DNS queries. It specifies the size of an internal table that is allocated in xmem.

DNS_MAX_NAME

64 by default. Specifies the maximum size in bytes of a host name that can be resolved. This number includes any appended default domain and the NULL-terminator. Backwards compatibility exists for the MAX_DOMAIN_LENGTH macro. Its value will be overridden with the value DNS_MAX_NAME if it is defined.

For temporary storage, a variable of this size must be placed on the stack in DNS processing. Normally, this is not a problem. However, for µC/OS-II with a small stack and a large value for DNS_MAX_NAME, this could be an issue.

DNS_MAX_DATAGRAM_SIZE

512 by default. Specifies the maximum length in bytes of a DNS datagram that can be sent or received. A root data buffer of this size is allocated for DNS support.

DNS_SOCK_BUF_SIZE

1024 by default. Specifies the size in bytes of an xmem buffer for the DNS socket. Note that this means that the DNS socket does not use a buffer from the socket buffer pool.

2.6.6 Network Configuration Prior to Dynamic C 7.30

These macros should only be used for releases of Dynamic C prior to version 7.30. They are supported in newer releases of Dynamic C for backward compatibility; however, new applications should use the new style of configuration outlined in Section 2.6.7. Use of the runtime functions mentioned in this section is deprecated in favor of ifconfig().

MY_DOMAIN

This macro is the initial value for the domain portion of the controller's address. At runtime, it can be overwritten by tcp_config() and setdomainname().

MAX_DOMAIN_LENGTH

Specify the maximum domain name length, including any concatenated host name. Defaults to 128.

MY_GATEWAY

This macro gives the default value for the controllers default gateway. At runtime, it can be overwritten by tcp_config().

MY_IP_ADDRESS

This macro is the default IP address for the controller. At runtime, it can be overwritten by tcp_config() and sethostid().

MY_NAMESERVER

This macro is the default value for the primary name server. At runtime, it can be overwritten by tcp_config().

MY_NETMASK

This macro is the default netmask for the controller. At runtime, it can be overwritten by tcp_config().

2.6.7 Network Configuration Starting with Dynamic C 7.30

These macros should only be used with Dynamic C 7.30 or later.

TCPCONFIG

Define to the number of a predefined configuration in tcp_config.lib (numbers less than 100) or custom_config.lib (numbers greater or equal to 100). Defaults to 0, which means no predefined configuration.

USE_ETHERNET

Define to 0 (or leave undefined) if Ethernet is not required. Define to 1 if the first Ethernet port is to be used. Defaults to 0. This macro does not include PPPoE interfaces.

USE_PPP_SERIAL

Define to a bitwise-OR combination of:

• 0x01 - Serial port A (IF_PPP0)
• 0x02 - Serial port B (IF_PPP1)
• 0x04 - Serial port C (IF_PPP2)
• 0x08 - Serial port D (IF_PPP3)

Defaults to 0, i.e., no PPP over serial.

USE_PPPOE

Define in the same way as USE_ETHERNET, except that PPPoE is used on the specified Ethernet port. Defaults to 0 i.e., no PPPoE interfaces.

USE_WIFI

Define to 1 if Wi-Fi is required. Defaults to 0.

IFCONFIG_ALL
IFCONFIG_DEFAULT
IFCONFIG_ETH0
IFCONFIG_PPP0..5
IFCONFIG_PPPOE0
IFCONFIG_WIFI0

All the above IFCONFIG_* macros are defined in a similar manner. IFCONFIG_ALL is reserved for configuration items that are not specific to any particular interface number. IFCONFIG_DEFAULT is applied to the default interface (IF_DEFAULT) if there is no specific IFCONFIG_* for the default interface.

These macros must be defined as a C parameter list fragment. This is because the macro value is substituted into a call to ifconfig() at initialization time (sock_init()). For example, the fragment of code that initializes the non-PPPoE Ethernet interface looks somewhat like the following:

#ifdef IF_ETH0

   #ifdef IFCONFIG_ETH0
      ifconfig(IF_ETH0, IFCONFIG_ETH0, IFS_END);
   #else
      #if IF_DEFAULT == IF_ETH0
         ifconfig(IF_DEFAULT, IFCONFIG_DEFAULT, IFS_END);
      #endif
   #endif
#endif

The entire fragment is processed only if IF_ETH0 is defined, i.e., you have specified that the non-PPPoE Ethernet interface is to be used. Inside this, if the IFCONFIG_ETH0 macro has been defined, then it is substituted into an ifconfig() call for IF_ETH0. Otherwise, if IF_ETH0 is the default (i.e., equal to IF_DEFAULT) then the IFCONFIG_DEFAULT macro is substituted into the ifconfig() call.

Note that for backwards compatibility, IFCONFIG_DEFAULT is always defined to something if it was not explicitly defined prior to inclusion of dcrtcp.lib. It is defined using the given values of the pre version 7.30 macros: MY_IP_ADDRESS, MY_GATEWAY etc.

The IFCONFIG_* macros can be defined to be an arbitrary number of ifconfig() parameters. For example,

#define IFCONFIG_ETH0\
   IFS_IPADDR,aton("10.10.6.100"), \
   IFS_NETMASK,0xFFFFFF00uL, \
   IFS_ROUTER_ADD,aton("10.10.6.1"), \
   IFS_ROUTER_ADD_STATIC,aton("10.10.6.111"), \
    aton("10.10.6.0"),0xFFFFFF00uL, \
   IFS_DEBUG, 5, \
   IFS_ICMP_CONFIG, 1, \
   IFS_UP

sets up local IP address and netmask, two routers, turns the verbose level all the way up, allows ping configure, and finally specifies that the interface be brought up at boot time.

The final IFS_UP is important: if it is omitted, then the interface will not be brought up at boot time; you will need to call ifup() explicitly after sock_init().

For a full list of the parameters that you can specify in an IFCONFIG_* macro, please see the documentation for ifconfig().

2.6.8 Time-Outs and Retry Counters

RETRAN_STRAT_TIME

This is used for several purposes. It is the minimum time granularity (in milliseconds) of the retransmit process. No time-out is set less than this value. It defaults to 10 ms.

TCP_OPENTIMEOUT

Defines the time-out value (in milliseconds) for active open processing. Defaults to 31000 ms.

TCP_CONNTIMEOUT

Defines the time-out value in milliseconds during open or close negotiation. Defaults to 13000 ms.

TCP_SYNQTIMEOUT

Defines the time-out value (in milliseconds) for pending connection. Defaults to 90000 ms.

TCP_TWTIMEOUT

Define time to linger in TIMEWAIT state (milliseconds). It should be from .5 to 4 minutes (2MSL) but it's not really practical for us. Two seconds will hopefully handle the case where ACK must be retransmitted, but can't protect future connections on the same port from old packets. Defaults to 2000 ms.

KEEPALIVE_NUMRETRYS

Number of times to retry the TCP keepalive. Defaults to 4.

KEEPALIVE_WAITTIME

Time (in seconds) to wait for the response to a TCP keepalive. Defaults to 60 seconds.

TCP_MAXRTO

Set an overall upper bound for the retransmit timeout, in milliseconds. Defaults to 50,000 ms.

TCP_MINRTO

Set a lower bound for the retransmit timeout, in units of milliseconds. Prior to Dynamic C 9.01, the default value for this macro was 250 ms (¼ second). Starting with Dynamic C 9.01, stack improvements allowed the default value to be reduced to 10 ms. In either case, beware of reducing this value, since modern hosts try to ack only every second segment. If our RTO is too small, we will unnecessarily retransmit if we don't get the ack for the first of the two segments (especially on a fast LAN, where the RTT measurement will want to make us set a small time-out).

TCP_LAZYUPD

Set a delay time for "lazy update" (ms). This is used to slightly delay window updates and empty acknowledgments to the peer, in the hope of being able to tag extra data along with otherwise empty segments. This improves performance by allowing better interleaving of application processing with TCP activity, and sending fewer empty segments. This delay interval is also used when we need to retransmit owing to a temporary shortage of Ethernet transmit buffers. Defaults to 5 ms.

DNS_RETRY_TIMEOUT

2000 by default. Specifies the number of milliseconds to wait before retrying a DNS request. If a request to a nameserver times out, then the next nameserver is tried. If that times out, then the next one is tried, in order, until it wraps around to the first nameserver again (or runs out of retries).

DNS_NUMBER_RETRIES

2 by default. Specifies the number of times a request will be retried after an error or a timeout. The first attempt does not constitute a retry. A retry only occurs when a request has timed out, or when a nameserver returns an unintelligible response. That is, if a host name is looked up and the nameserver reports that it does not exist and then the DNS resolver tries the same host name with or without the default domain, that does not constitute a retry.

DNS_MIN_KEEP_COMPLETED

10000 by default. Specifies the number of milliseconds a completed request is guaranteed to be valid for resolve_name_check(). After this time, the entry in the internal table corresponding to this request can be reused for a subsequent request.

2.6.9 Program Debugging

TCP_STATS

Enable TCP socket statistics collection. This causes some additional fields to be defined in the TCP socket structure, which are updated with various counters. This is mainly for internal debugging.

DCRTCP_DEBUG

If defined, allow Dynamic C debugging in all TCP/IP libraries. This allows you to trace into library functions in case you are finding difficulty in solving a TCP/IP problem. Remember to remove this definition when compiling for a production environment.

DCRTCP_VERBOSE

If defined, enable debugging messages to be printed by the library to the Dynamic C stdout window. This can be very informative when you are trying to see how the TCP/IP libraries work. Unfortunately, the string messages take up a lot of root code space, so you may need to increase the DATAORG value in the BIOS. Otherwise, you can be more selective about which messages are printed by defining *_VERBOSE macros for individual libraries (DCRTCP_VERBOSE merely turns on all the individual library verbose definitions). See dcrtcp.lib source for a listing of the available debug and verbose macros.

Note that the number of messages printed depends on the value of a global variable, debug_on. If this variable is 0, only a few messages are printed. If set to higher numbers (up to 5), then successively more detailed messages are printed. You can set this variable directly at the start of your main() function, or preferably use

ifconfig(IF_ANY, IFS_DEBUG, 5, IFS_END);

2.6.10 Miscellaneous Macros

TCP_FASTSOCKETS

Define to `1' if sockets connected to "reserved" ports can be closed without the usual 2MSL delay. The default is set to `1', define to `0' to override this.

NET_ADD_ENTROPY

Define this macro to allow network packet arrival times (from any interface) to be a source of random number seeds. See RAND.LIB for further information.

NET_COARSELOCK

This macro is only used when µC/OS-II is active. It affects the definition of 2 other macros: LOCK_SOCK(s) and UNLOCK_SOCK(s).

If NET_COARSELOCK is not defined, the lock/unlock macros are individual socket locks for use on socket transmit/receive buffers and the socket structure itself. If it is defined, the lock/unlock macros are global locks.

TCP_NO_CLOSE_ON_LAST_READ

If defined, then support half-close; i.e., sock_close() only closes the transmit side of the socket, but allows indefinite receives until the peer closes. This prevents the normal close timeout from being set. Also, when reading, if the socket is half-closed by the peer, then the socket will be automatically closed from this side if this define is not set.

2.6.10.1 TOS and TTL

TOS and TTL are fields in the IP header. TOS, short for "Type of Service," uses 4 bits to specify different types of service. For normal service all 4 bits are zero. Different applications will want different types of service. For example, SNMP might set the maximize reliability bit, whereas FTP would want maximize throughput.

• IPTOS_DEFAULT is normal service.
• IPTOS_CHEAP minimizes monetary cost.
• IPTOS_RELIABLE maximizes reliability.
• IPTOS_CAPACIOUS maximizes throughput
• IPTOS_FAST minimizes delay.
• IPTOS_SECURE maximizes security.

Note that you may not OR these values together. You must pick one only!

TTL (Time to Live) specifies how many routers a packet may visit before it is discarded, or how many seconds it can remain in the network, whichever comes first.

TCP_TTL

Default TTL of TCP segments. This value is from Internet STD0002. Defaults to 64.

TCP_TOS

Default type of service for TCP. Defaults to IPTOS_DEFAULT.

UDP_TTL

Default TTL of UDP datagrams. This value is from Internet STD0002. Defaults to 64.

UDP_TOS

Default type of service for UDP. Defaults to IPTOS_DEFAULT.

ICMP_TOS

Default type of service for ICMP. Defaults to IPTOS_DEFAULT.

2.6.11 Wi-Fi Configuration Macros

To configure a Rabbit device for a Wi-Fi network connection, you will need to define a number of macros. As shown in Section 2.4.1, these can be defined in either the C program or the Defines window.

An important point to remember is that the configuration of TCP/IP applies equally well to Wi-Fi devices as it does to Ethernet devices.

TCPCONFIG

This macro works the same for a Wi-Fi interface as it does for an Ethernet interface. Use the value 1 for a static TCP/IP network configuration, or 5 for a DHCP (dynamic) configuration.

IFC_WIFI_SSID (default "rabbitTest")

This is the SSID (Service Set Identifier) or name of the wireless network that you want your Rabbit device to connect to. All other devices on your wireless network (including your access point or wireless router) must have this same name.

(The macro _WIFI_SSID was deprecated in Dynamic C 10.40.)

IFC_WIFI_ROAM_ENABLE (default 1)

This turns roaming on or off.

IFC_WIFI_ROAM_BEACON_MISS (default 20)

This sets the number of beacons that are missed continuously in order for scanning for a better access point and subsequent association to take place.

IFC_WIFI_MODE (default IFPARAM_WIFI_INFRASTRUCTURE)

Specifies the network architecture mode for your wireless network. This macro has two possible values. IFPARAM_WIFI_INFR means that the device will attach to an infrastructure network. An infrastructure network includes at least one access point that coordinates communication on the wireless network. IFPARAM_WIFI_ADHOC means that the device will use an ad-hoc mode network. An ad-hoc network does not have an access point; all devices on the wireless network simply communicate directly with each other.

(The macro _WIFI_MODE was deprecated in Dynamic C 10.40.)

IFC_WIFI_CHANNEL

Sets the channel (1-14) to use for an ad-hoc network.

(The macro _WIFI_OWNCHANNEL was deprecated in Dynamic C 10.40.)

IFC_WIFI_REGION (default IFPARAM_WIFI_REGION_AMERICAS)

This macro sets the channel range and maximum power limit for the region selected. Different regions have different regulations on Wi-Fi communication. This macro can have the value:

• IFPARAM_WIFI_REGION_AMERICAS - Americas, including the US (ch. 1-11)
• IFPARAM_WIFI_REGION_AUSTRALIA - Australia (ch. 1-11)
• IFPARAM_WIFI_REGION_CANADA - Canada (ch. 1-11)
• IFPARAM_WIFI_REGION_CHINA - China (ch. 1-11)
• IFPARAM_WIFI_REGION_EMEA - Europe, Middle East, Africa (ch. 1-13)
• IFPARAM_WIFI_REGION_FRANCE - France (ch. 10-13)
• IFPARAM_WIFI_REGION_ISRAEL - Israel (ch. 3-11)
• IFPARAM_WIFI_REGION_JAPAN - Japan (ch. 1-13)
• IFPARAM_WIFI_REGION_MEXICO_INDOORS - Mexico indoors (ch. 1-11)
• IFPARAM_WIFI_REGION_MEXICO_OUTDOORS - Mexico outdoors (ch. 9-11)

(The macro _WIFI_REGION_REQ was deprecated in Dynamic C 10.40.)

IFC_WIFI_ENCRYPTION (default IFPARAM_WIFI_ENCR_NONE)

This parameter controls the type of encryption used. Select one of the following:

• IFPARAM_WIFI_ENCR_ANY - Use any type of encryption.
• IFPARAM_WIFI_ENCR_NONE - No encryption used.
• IFPARAM_WIFI_ENCR_WEP - Use WEP encryption.
• IFPARAM_WIFI_ENCR_TKIP - Use WPA encryption; the macro WIFI_USE_WPA must be defined to use this parameter.
• IFPARAM_WIFI_ENCR_CCMP - Use WPA2 encryption; both WIFI_USE_WPA and WIFI_AES_ENABLED must be defined to use this parameter.

(The macro _WIFI_WEP_FLAG was deprecated in Dynamic C 10.40.)

IFC_WIFI_WEP_KEYNUM (default 0)

Select the WEP key to use when using WEP encryption. This macro can have the value 0, 1, 2, or 3, which corresponds to the WEP key macros (IFC_WIFI_WEP_KEY#_*) described next.

(The macro _WIFI_USEKEY was deprecated in Dynamic C 10.40.)

IFC_WIFI_WEP_KEY0_BIN
IFC_WIFI_WEP_KEY1_BIN
IFC_WIFI_WEP_KEY2_BIN
IFC_WIFI_WEP_KEY3_BIN

Specifies the possible WEP keys to use for WEP encryption. They default to undefined.

These keys can be either 40-bit or 104-bit (i.e., 5 bytes or 13 bytes) and must be a comma-separated list of byte values. The IFC_WIFI_WEP_KEY#_BIN macro that is used depends on the value of IFC_WIFI_WEP_KEYNUM.

(The _WIFI_KEY# macros were deprecated in Dynamic C 10.40.)

IFC_WIFI_WEP_KEY0_HEXSTR
IFC_WIFI_WEP_KEY1_HEXSTR
IFC_WIFI_WEP_KEY2_HEXSTR
IFC_WIFI_WEP_KEY3_HEXSTR

Specifies the possible WEP keys to use for WEP encryption. They default to undefined.

These keys can be either 40-bit or 104-bit (i.e., a string of either 10 or 26 hex characters). Note that you do not necessarily need to define all four WEP keys. You can typically just define one key, make sure it matches the key used on all other devices, and set IFC_WIFI_WEP_KEYNUM to point to the correct key.

If both IFC_WIFI_WEP_KEY#_HEXSTR and IFC_WIFI_WEP_KEY#_BIN are defined for a particular key, the HEX version will be used.

IFC_WIFI_WPA_PSK_PASSPHRASE

TKIP encryption requires a passphrase or a key. This macro allows you to define a passphrase with an ASCII string. The Wi-Fi driver will expand the passphrase into a key using a standard algorithm. This process takes up to 20 seconds. The same passphrase must be configured on all devices on the same Wi-Fi network.

(The macro _WIFI_PSK_PASSPHRASE was deprecated in Dynamic C 10.40.)

IFC_WIFI_WPA_PSK_HEXSTR

Instead of a passphrase, you can specify a key directly for TKIP encryption The key must be given as a series of hex digits within an ASCII string. The key must be 256 bits, or 64 hex digits. Specifying the key directly means that a passphrase does not need to be expanded, thus speeding startup time.

IMPORTANT:

When statically configuring a Rabbit Wi-Fi device, specify either the pre-shared key with IFC_WIFI_WPA_PSK_HEXSTR or the passphrase with IFC_WIFI_WPA_PSK_PASSPHRASE, but NOT BOTH! If you do specify both, then IFC_WIFI_WPA_PSK_HEXSTR will take precedence; that is, if you have a correct passphrase but an incorrect pre-shared key, then the incorrect pre-shared key will be used.

(The macro _WIFI_PSK_HEX was deprecated in Dynamic C 10.40.)

IFC_WIFI_WPA_PROTOCOL

Set to bitwise OR of the following:

· IFPARAM_WIFI_WPA_PROTOCOL_WPA2

· IFPARAM_WIFI_WPA_PROTOCOL_WPA

to support WPA2 (RSN (Robust Security Network) with CCMP) or WPA (the original TKIP-based WiFi Protected Access).

IFC_WIFI_CLIENT_CERT_XIM

Set to two parameters: first parameter is public certificate of this (client) machine for EAP/TLS. Second parameter is for the corresponding private key. These are generally #ximported files, which are the .der or .pem certificate/private key files. Currently, the private key file must not itself be encrypted. This is only used for EAP-TLS.

Note: if certificates have been generated by the Rabbit Certificate Utility, then you should #ximport the <basename>s.pem and <basename>key.pem files, where <basename> is the file name you selected for the client certificate. For example, if the file name was "client" then

#ximport "certs/clients.pem" my_client_cert
#ximport "certs/clientkey.pem" my_client_key
IFC_WIFI_CLIENT_CERT_XIM my_client_cert, my_client_key

IFC_WIFI_CA_CERT_XIM root_ca_cert

Set to the #ximported file containing the trusted certificate authority for validating the Authentication Server's public certificate. This may be a .pem or .der format file.

This is used for EAP-TLS, and should also be used for PEAP since PEAP uses TLS "under the covers." In either case, it is important to be able to verify the authenticity of the Authentication Server itself. This is done by having the trusted CA certificate available.

Note: if you generated your own Certificate Authority (CA) using the Rabbit Certificate Utility (described in the Rabbit Embedded Security Pack Manual), then you should #ximport the <basename>.der or <basename>.pem file for the CA. For example, if the file name was "my_ca" then:

#ximport "private/my_ca.der" root_ca_cert
IFC_WIFI_CA_CERT_XIM root_ca_cert

IFC_WIFI_IDENTITY

Define an identity for PEAP. Using this macro sets both the inner and outer identity to the same value.

IFC_WIFI_IDENTITY "MyClientIdent"

If your application requires a different outer "plaintext" identity, then your application will need to use the ifconfig() function directly.

This macro is also required for EAP-TLS. The userID may be set to a dummy value, depending on the requirements of the Authentication Server.

IFC_WIFI_PASSWORD

Define a password for PEAP. This is not used for EAP-TLS.

IFC_WIFI_PASSWORD "my_passw0rd"

IFC_WIFI_AUTHENTICATION (default IFPARAM_WIFI_AUTH_ANY)

Specifies the authentication mode to use for this Wi-Fi network. It accepts a combination (with multiple values ORed together) of the following values:

• IFPARAM_WIFI_AUTH_ANY - Use any method.
• IFPARAM_WIFI_AUTH_OPEN - Use open authentication.
• IFPARAM_WIFI_AUTH_SHAREDKEY - Use WEP shared-key authentication.
• IFPARAM_WIFI_AUTH_WPA_PSK - Use WPA pre-shared key (TKIP, CCMP); the macro WIFI_USE_WPA must be defined to use this parameter. This implies the IEEE 802.11i "Personal" operating mode.
• IFPARAM_WIFI_AUTH_WPA_8021X - Use IEEE 802.1X/EAP authentication. This implies the IEEE 802.11i Enterprise operating mode. For more information on Wi-Fi Enterprise, refer to: An Introduction to Wi-Fi and the Rabbit Embedded Security Pack Manual, both documents are available online and with the Dynamic C distribution.

(The macro _WIFI_AUTH_MODE was deprecated in Dynamic C 10.40.)

IFC_WIFI_FRAG_THRESHOLD (default 0)

Set the fragmentation threshold. Frames (or packets) that are larger than this threshold are split into multiple fragments. This can be useful on busy or noisy networks. The range is 256-2346, or 0 which means no fragmentation.

(The macro _WIFI_FRAG_THRESH was deprecated in Dynamic C 10.40.)

IFC_WIFI_RTS_THRESHOLD (default 0)

Set the RTS threshold, the frame size at which the RTS/CTS mechanism is used. This is sometimes useful on busy or noisy networks. Its range is 0-2347, where 0 is the default (i.e., no RTS/CTS).

(The macro _WIFI_RTS_THRESH was deprecated in Dynamic C 10.40.)

SSL_USE_AES

This is required for EAP/TLS, since it uses SSL internally.

WIFI_USE_WPA

Define this macro to use the WPA functionality in the Wi-Fi driver. This is necessary to enable TKIP encryption. Because the WPA code has a significant size, it is not compiled by default.

WPA_USE_EAP

Set to a bitwise OR combination of the following:

· WPA_USE_EAP_TLS

· WPA_USE_EAP_PEAP

which specifies the Wi-Fi Enterprise authentication method to use, currently either EAP-TLS or PEAP. Use of this macro will bring in a lot of library code to support Enterprise level authentication and key management. This will require configuration of the access point as well as a separate machine to be used as an Authentication Server (e.g., a RADIUS server).

¹ The configuration macros MY_IP_ADDRESS and MY_NETMASK have been deprecated in favor of _PRIMARY_STATIC_IP and _PRIMARY_NETMASK, respectively.

² In general usage the term "WPA encryption" sometimes refers to WPA using TKIP.