Deployment Guide - USBLAN Version 2.3

Belcarra USBLAN Class Drivers

Evaluation and Deployment Guide

CDC-ECM, CDC-EEM, and CDC-NCM

[UPDATE:  Version 2.4.4 Released December 2013.  Download OEM Manual]

 1.  OVERVIEW

Belcarra offers a Windows USB Class driver to implement Networking over USB. This allows for a network connection to be used to connect to various hardware devices including handheld devices, network infrastructure devices, etc.

The driver is licensed to hardware OEM’s and is generally then made available to end users either through Windows Update or through pre-installation of the drivers by integration of the signed drivers in the OEM installation kit.

An evaluation version of the Belcarra USBLAN driver is available in Windows Update. By configuring your target device with the correct Belcarra USB Vendor ID and Product ID the evaluation version of the driver will be downloaded and installed allowing you to verify that your target device correctly inter-operates with the Belcarra USBLAN driver.

Please note that the evaluation version of the driver will only operate for 60 minutes at a time. It is not intended for general distribution or use.

The rest of this document will outline some of the technical details of testing with the Belcarra USBLAN driver.

 2. DESCRIPTION

Belcarra USBLAN is a USB network class driver for Microsoft Windows. Features include the following:

 -  Support for 32 bit and 64 bit Windows 7, Vista, Window XP

• NDIS 5 
• NDIS 6 ((scheduled Q2/2011)

 -  Fully WDM (Windows Driver Model) compliant

 -  WHQL Certified

 -  Silent installation – no user warnings from Microsoft during installation.

 -  Installation via Windows Update

 -  Support for a variety of network protocols

• CDC-ECM (Ethernet Control Model)
• CDC-EEM (Ethernet Emulation Model)
• CDC-NCM (Network Control Model) 
• MDLM BLAN 
• ECM-Basic, Gadget SIMPLE

 -  Seamless customization for vendors includes information (INF), catalogue (CAT) files and Microsoft WHQL submission.

 -  Internal DHCP server available to assist in zero-configuration network setup

 -  Multicast support (allowing device/host discovery using mDNS)

 -  Extensive compliance and stress testing

• USB Compliance Tool – USB Command Verifier
• Extensive stress testing against many devices
• Wide field deployment with many actual devices

 -  Tested with Windows Driver Test Manager (DTM)

 -  Windows Logo Kit testing available

2.1 USBLAN Networking Protocol Support

The USBLAN class driver seamlessly recognizes and supports the following standard USB network protocols, and also some widely used de facto variants (see Section 5.1 for more detail)

• CDC-ECM Ethernet Control Model - the most widely implemented USB Networking protocol Designed for network infrastructure devices. Linux Gadget users see Section 6.
• SIMPLE –a widely-deployed subset of CDC-ECM. See Section 5.1.
• CDC-NCM Network Control Model - update of CDC-ECM for high-performance networks. See Section 5.1.1. Belcarra offers a device-side implementation of CDC-NCM.
• CDC-EEM Ethernet Emulation Model - A revision of CDC-ECM adapted for simple 2-node Ethernet-like networks..
• MDLM-BLAN – A Belcarra proprietary variant of ECM with extensions suitable to manage a personal area network. See Section 5.1.2

2.2 Platform Selection

USBLAN is available for Windows versions, as follows:

• Windows 7 (32 bit and 64 bit)
• Windows Visa (32 bit and 64 bit)
• Windows XP (32 bit)
• Windows CE and Windows Mobile 

2.3 Architecture

Figure 2‑1 USBLAN Architecture

Windows USBLAN architecture within Microsoft Windows operating systems is illustrated in the Figure 2. 1 on the left. Applications access NDIS, the Windows network subsystem. USBLAN implements an NDIS Intermediate Miniport Driver.

On the lower edge, USBLAN implements a Windows Driver Model (WDM) USB Class Driver.

Windows USBLAN consists of a single INF, and builds for NDIS 5 and 6, 32 bit and 64 bit architectures. The correct version is automatically selected when the driver is installed. A signed limited capability version is available for immediate testing from Windows Update.

2.4 Zero-configuration

Belcarra USBLAN supports zero-configuration with a built-in DHCP server, offering service to both the Windows side and the device side. The Windows side is assigned a fixed IP address using a registry value (built-in fixed value for the evaluation driver), from the special link-local IP address block (see [RFC 3927] and [RFC 5735] in Section 7.2)

3.0 USBLAN EVALUATION

Evaluating USBLAN is easy, using a special time limited version available from Windows Update. To deploy:

• Select a protocol (Section 3.1)
• Configure your device (Section 3.2)
• Set up a Windows test system
• Run tests (Section 3.5 has some suggested tests)

3.1 Protocol selection

The evaluation version of USBLAN supports CDC-ECM, CDC-EEM, SIMPLE, and MDLM-BLAN.

3.2 Prepare the device

Set the following choices in the device firmware, either by editing the source code or by an appropriate configuration file:

Parameter	Value
Vendor ID	0x15ec (Belcarra Technologies)
Product ID	0xd042 (Built in DHCP server enabled)
	0xd041 (Built-in DHCP server disabled)
Networking protocol	The evaluation driver supports CDC-ECM, ECM-Basic/SIMPLE, and CDC-EEM

3.3 Prepare a Windows test system

You may select Windows XP, Windows Vista, or Windows 7 for testing. Systems should be prepared as follows:

• A fresh install
• Apply all available service packs and updates

Before any testing is done, set a Restore Point. There is no other way to completely reverse the effect of a driver installation. In the case of Windows 7, restore points are set automatically. You will need to note the time that testing began.

3.4 Connecting the device for the first time

After setting up the Windows machine and the device as described above, boot the device (if necessary), but do not connect the USB cable yet.

On the Windows machine, open the Control Panel, run the System function, and within that the Device Manager. These names are from Windows Vista. Details vary slightly on Windows XP and Windows 7. This application will instantly update the display when a USB device is inserted or removed.

Now connect a USB cable between the devices.

At this point, a Windows dialog similar to the following may appear

Figure 3.4 Found New Hardware Wizard

NOTE:  If the option “Yes, now and every time I connect a device” was previously selected, then the wizard operates silently, and displays progress messages in the system tray. In Windows 7, this is the default behaviour.

If the first option is selected, then Windows will, for this purpose only, try to find a driver from Windows update.  If the preparations described above were completed correctly, then Windows will soon announce that the device is ready to be used.

Two problems may arise:

• Driver not found – if the vendor and product ID are not correct, Windows will be unable to find a driver. If this happens, fix the device configuration, return the system to the restore point established in Section 3.3 above and try again.  
• The device’s CDC-ECM or CDC-EEM implementation may malfunction in other ways . In this case, Belcarra USBLAN will be installed, but Windows will show a message in the System Tray that the device was unable to start.

When all the steps have been completed successfully, the Hardware Manager (or Device Manager, depending on Windows version) will show a new network interface. In addition, the Control Panel will also show a new Network Connection.

3.4.1 DHCP enabled

If the built-in DHCP server is enabled, the new Network Connection will be configured with an address and network mask. For the evaluation driver, the internal DHCP server, when enabled, uses the following configuration

Windows Machine IP: 169.254.1.1

Device IP: 169.254.1.2 (1^st device), 169.254.1.2 (2^nd device), …

Network mask: 169.254.255.255.

3.4.2 Device-resident DHCP Server

If the built-in DHCP server is not enabled, then the next possibility is a DHCP service offered by the device.

3.4.3 Manual configuration

If no DHCP service is available, then zero-configuration procedures will be applied if available. Otherwise manual configuration is required . After zero configuration, dynamic discovery is needed. See Section 5.4.

3.5 Test procedures

Assuming that by DHCP or manual configuration both the device and the new Windows Network Connection have an IP address on the same network segment, then normal network operations can begin. For simple network stress testing, Belcarra recommends command-line web servers and clients on both ends of the link:

•  Device side web server: thttpd
•  Windows side web client: wget
•  Windows side web server: Apache
•  Device side web client: urlget or wget.

 Other simple test procedures include:

•  Flood ping

3.6 Connecting the device to a second USB port

When the device is connected to a second USB port on the Windows machine, two things can happen

• If the device offers the identical properly-constructed USB serial number, Windows will activate the same Network Connection
• Otherwise, Windows will create a new Network Connection. Some portions of the “New Hardware Found” procedure are repeated (shown primarily as bubbles from the system tray).

4. USBLAN SOFTWARE LICENSING AND DISTRIBUTION AGREEMENT

The evaluation driver may not be used for field deployment or with customer devices. To secure a fully functional, signed solution, customers will need to execute a Software License and Distribution Agreement. For more information on this contact Belcarra at info@belcarra.com.

This following section describes how the final deployment kit is constructed.

4.1 Customer-settable parameters

4.1.1 Hardware ID’s

Windows matches USB drivers based on the following

• Vendor ID
• Product ID
• Matching Interface (MI) – composite functions only

Belcarra builds an INF based on matching rules provided by the customer.

The third part of a matching rule, MI, applies if you want to deploy CDC-ECM or another protocol as part of a composite function. For instance MI_0 would mean that you want to match the first interface (interface 0) of a composite bundle (and also interface 1 for the case of CDC ECM). In addition, you may want to include IAD descriptors, especially if you want to deploy CDC-ECM as other than MI_0.

4.1.2 Registry settings
The USBLAN driver uses a number of registry settings, mostly related to the internal DHCP server. These registry settings are initialized via the INF file. Therefore, Belcarra uses the following information to build a suitable INF file

• DHCP status: enabled, disabled, or enabled selectively (see below)
• DHCP Server Configuration (when enabled)., consisting of
 -  allocation block, an address block [NetworkLIP,NetworkMIP] from which allocations are made (the allocation block), 
 - NetworkSIP the DHCP server’s own IP address (which must be outside the allocation block),
 - NetworkMask,

The DHCP server always assigns the Windows side the address NetworkLIP.. Devices are assigned addresses consecutively beginning at NetworkLIP+1.

4.2 Examples

Example #1

          Hardware ID: 15ec/d042; DHCP disabled

Example #2

          Hardware ID1: 15ec/d041/MI_02; DHCP Disabled

          Hardware ID2: 15ec/d040; DHCP Disabled

This example matches the Vendor ID 15ec (Belcarra) Product ID xxxx Interface 2

Hardware ID1 is part of a composite function. Hardware ID2 is a second ID for the same device with a different configuration (network only, not composite). Belcarra USBLAN is not involved in supporting the other parts of the composite function. The device should use Interface Association Descriptors for the first configuration for this example to work properly (see Section 4.1.1 above).

Example #3

          Hardware ID: 15ec/d041 DHCP enabled for all protocols

          DHCP Address block: 169.254.1.1 to 169.254.1.15 (assigned addresses)

          DHCP Server address: 169.254.0.1

          DHCP Netmask 255.255.0.0

Example #4

          Hardware ID: 15ec/d041 DHCP enabled for ECM, disabled for EEM and SIMPLE

          DHCP Address block: 169.254.1.1 to 169.254.1.15 (assigned addresses)

          DHCP Server address: 169.254.0.1

          DHCP Netmask 255.255.0.0

5. NETWORK ADDRESS MANAGEMENT

In Section 2.4 and Section 4.1.2 above, we described USBLAN’s internal DHCP server, part of Belcarra’s comprehensive model of managing a USB network, especially a personal area network.

5.1 Networking models

The CDC networking documents describe 3 different USB networking “models” as follows:

• Ethernet Control Model (ECM) – technically a way to access an Ethernet adapter across a USB link, but adapted to other uses
• Ethernet Emulation Model (EEM) – a model of a simple 2-node “network” using Ethernet framing. Since there is no physical Ethernet hardware, various hardware-related parts of ECM are not needed, resulting in a simplified protocol. In addition, EEM offers better streaming of data than ECM. However EEM is not widely implemented.
• Network Control Model (NCM) – see Section 5.1.1

In addition we have another unofficial but widely deployed model (protocol):

• SIMPLE – a subset of ECM designed to conform to limitations of certain USB subsystems. 

Finally, there is MDLM-BLAN, Belcarra’s own variant of ECM (see Section 5.1.2 below)

5.1.1 Network Control Model

Of the protocols described so far, CDC-ECM is the best choice for tethering, but certain details of the CDC-ECM standard are not optimal for low-latency high-throughput transport. The Network Control Model (CDC-NCM) was designed to address these concerns. Belcarra was part of the USB-IF standards design process and offers NCM solutions for ultrahigh-performance networking.

5.1.2 MDLM-BLAN

Belcarra extends the concept of 2-node model of EEM and CDC-Basic to more than one attached device. USBLAN can provide not only device-to-host communication but device-to-device communication. We call such a simulated Ethernet a personal area network (PAN) and takes USB networking to a new level. Belcarra’s MDLM-BLAN supports personal area networks with additional features:

• IP direct assignment – IP Address and Network Mask from the DHCP service can be directly assigned by a device request, eliminating the need for a DHCP client on the device side
• Time service – the host can set the device time

5.2 Management role assignment

A closely related question is: which node in the virtual network will assume the management role. The possible answers are

• none – addresses on each end are statically assigned. Simple but inflexible
• device – the device offers a DHCP server to the host
• host – the host offers a DHCP server to the device
• zero conf – a fall-back from other schemes

A cell phone offering tethering (3G or LTE access) service is a good example of an infrastructure device. Note: the same cell phone may revert to a personal area network to synchronize data (contact info music files, etc) with a host PC.

5.3 Personal area network management strategies

There are two issues when setting up a PAN address scheme

• Setting up the low-level addresses
• Discovery by application software on both ends of the link

5.3.1 Fixed addresses at both ends

The simplest strategy, and the most frequently adopted, is to assign a fixed address to both ends of the link.

PRO: After initial setup, extremely simple.

CON: Possibility of address conflict, requiring configuration of both the device and management software.

CON: Manual intervention in Control Panel required even in the simplest case

CON: No provision for managing multiple devices simultaneously

5.3.2 Device-resident DHCP server

This strategy is a variant of the previous one.

PRO: No intervention needed on Windows to set up the address.

CON: Address conflicts still possible

PRO: Multiple devices possible if the device chooses its address block randomly

CON: Potential conflict if there is a collision

5.3.3 Host-resident DHCP server

PRO: Can resolve all address conflicts

CON: Standard Windows DHCP server not available for all versions of Windows, complex to set up, and not suitable for this purpose

5.3.4 Belcarra USBLAN internal DHCP server

PRO: USBLAN can allocate IP address into the special 169.254.*.* address block. This block is never used by permanent parts of an office network (routers, etc)

PRO: USBLAN can allocate distinct IP addresses for all connected devices.

CON: The connected devices will have dynamic addresses, and therefore a discovery process will be needed (see following section).

5.4 Dynamic discovery
Whenever dynamic addressing is used, the participants in the personal area network need to discover each other.
If the participants have knowledge of the setup of the DHCP server (see Section 3.4.1 and Section 4.1.2), they can easily try a limited number of fixed addresses.
Another, more general approach to this problem is Multicast DNS (mDNS), which is a joint effort of the IET Zero Configuration Networking (zeroconf) and DNS Extensions (dnsext) working groups.
In essence, mDNS is an extension of ordinary DNS to include ad hoc mDNS servers built into devices on the local network.
If a device from vendor Q offers a special service, then it can bind to the special multicast address of 224.0.0.251:5353. Then if a query is received for the string “QSpecial.local” it can respond. On the client side, mDNS is added to the ways that the client can resolve a symbolic address. Support libraries for this are freely available for Windows and major embedded platforms.

These libraries patch the name resolving system to allow nodes to advertise “local” services (such as QService.local) and for other nodes to discover them with a conventional DNS discovery. With this setup in place, a conventional web query for http://QService.local/ would bind to the first node binding to the QService.local service string. Slightly more effort, not using any special multicast primitives, would discover a complete list of responding nodes.

Some reference material on ZeroConf and mDNS is shown in Section 7.2

6. CONFIGURING EMBEDDED LINUX FOR CDC-ECM

The test procedure calls for setting up a test system for CDC-ECM or similar protocol. For Embedded Linux using Gadget, proceed as follows:

• Ensure that CDC-ECM is enabled and that RNDIS is disabled (kernel configuration options)
• Enable EEM protocol (optional)
• Select correct module parameters

6.1 Module parameters

The following table summarizes the important module parameters for g_ether.

Table 6‑1 g_ether module parameters

Parameter Name	Description	USBLAN Evaluation value
idVendor	USB Vendor ID	0x15ec – This Vendor ID belongs to Belcarra
idProduct	USB Product ID	0xd042 for DHCP service, 0xd001 for no DHCP service
use_eem[1]	Enables EEM protocol (instead of ECM)	USBLAN transparently recognizes EEM and ECM
iSerial	USB Serial No	Any sixteen byte hex string such as 0x00112233445566778899AABBCCDDEEFF
host_addr	MAC address assigned to host	optional. If this parameter is provided, it should be from a locally-administered MAC address block[2] The value is a six-byte hex string
dev_addr	MAC address used by the device	This value can also be set from ifconfig: ifconfig usb0 hw ether yy:xx:xx:xx:xx:xx:xx This value yy should conform to IEEE policy for locally administered MAC addresses.

[1] This parameter is only available if EEM is enabled in the kernel configuration.[2] The IEEE specifies that a MAC address is locally administered if the 2^nd least significant bit of its most significant (first) octet is 1. See the :”MAC Address” article on Wikipedia for details.

7. REFERENCES

7.1 USB Standards

Note: current USB standards documents, including those below, are available for download from http://www.usb.org/.

[USB] Universal Serial Bus Specification Revision 2.0

CDC1.1]  Universal Serial Bus Class Definitions for Communications Devices Version 1.1. This document contains specifications for a wide variety of real and anticipated communications devices, including ACM (serial) and Ethernet Control Model. Now obsolete.

[CDC1.2] Universal Serial Bus Class Definitions for Communications Devices Version 1.2. This document bundle supersedes [CDC1.1], and contains the following documents, among others

 [CDC-CORE] Universal Serial Bus Class Definitions for Communications Devices – Revision 1.2

[ECM] Universal Serial Bus Communications Class Subclass Specification for Ethernet Control Model Devices – Revision 1.2 February 9, 2007. This document, part of the [CDC1.2] document series, documents the specification known informally as “CDC Ethernet”, or sometimes “CDC”

[WMC] Universal Serial Bus CDC Subclass Specification for Wireless Mobile Communications Devices This document contains specifications for MDLM (Mobile Direct Line Model). Belcarra’s proprietary BLAN protocol closely resembles this protocol.

[EEM] Universal Serial Bus Communications Class Subclass Specification for Ethernet Emulation Model Devices – Revision 1.0 – February 2, 2005.

7.2 Zero configuration

[RFC 3927] Dynamic Configuration of IPv4 Link-Local addresses

[RFC 5735] Special-Use IPv4 Addresses

www.zeroconf.org – Zero Configuration Networking (Zeroconf)

www.dns-sd.org – DNS Service Discovery

draft-cheshire-dnsext-nbp.txt – Requirements for replacing AppleTalk  AppleTalk is the most successful zeroconf system known to date.

www.multicastdns.org – Multicast DNS resource page.

Zero Configuration Networking: The Definitive Guide, Daniel Steinberg and Stuart Cheshire, O’Reilly

7.3 Miscellaneous

Mac Address – an article on Wikipedia – http://en.wikipedia.org/MAC_address