Physical Address
304 North Cardinal St.
Dorchester Center, MA 02124
ISO/IEC 29341-26-16: UPnP WANDevice v2 — Root WAN Device Architecture
Architectural Analysis of the WANDevice v2 Root Device in the UPnP Internet Gateway Device Framework
Introduction to WANDevice v2
ISO/IEC 29341-26-16 defines the WANDevice v2 root device, the top-level UPnP device template for the WAN side of an Internet Gateway Device (IGD). While the individual WAN services (WANIPConnection, WANPPPConnection, WANCommonInterfaceConfig, etc.) handle specific control functions, WANDevice v2 provides the compositional framework that binds them together. It defines the device hierarchy, mandatory and optional embedded devices, and the service discovery surface presented to UPnP control points on the local network.
The WANDevice v2 standard is ISO/IEC 29341-26-16, but it is architecturally the keystone of the entire 29341-26 UPnP WAN series. Every other part (26-11 through 26-15) defines services that are embedded within the WANDevice or its child WANConnectionDevice.
The WANDevice v2 is updated from v1 with several architectural improvements: support for multiple WANConnectionDevice instances (enabling multi-WAN configurations like load balancing and failover), enhanced device description metadata including manufacturer URL and model description, and the integration of the IPv6-capable service variants. The device template explicitly defines which services are mandatory versus optional, providing implementers with clear guidance on minimum compliance requirements.
Device Hierarchy and Composition
The WANDevice v2 template specifies a two-level device hierarchy. At the root level, the WANDevice itself contains the WANCommonInterfaceConfig service (mandatory) and any number of vendor-specific services. Below the root, one or more WANConnectionDevice sub-devices are embedded, each containing connection-specific services. Each WANConnectionDevice typically hosts one instance of either WANIPConnection or WANPPPConnection, and optionally WANEthernetLinkConfig or WANDSLLinkConfig depending on the physical medium.
Multiple WANConnectionDevice instances within a single WANDevice enable physical redundancy and load balancing. However, each WANConnectionDevice represents an independent connection context — port mappings and connection states are NOT shared between instances. A port mapping created on WANConnectionDevice 1 cannot forward traffic arriving on WANConnectionDevice 2’s external interface.
The device description document (in XML format, served via UPnP’s device discovery mechanism) declares the full hierarchy. The WANDevice v2 template includes several key device properties in the description: friendlyName (user-visible device name), manufacturer, manufacturerURL, modelDescription, modelName, modelNumber, serialNumber, UDN (Unique Device Name), and UPC (Universal Product Code). These properties are crucial for control points implementing device inventories and firmware management.
| Component | Type | Mandatory | Service/Function |
|---|---|---|---|
| WANDevice | Root device | Yes | Hosts WANCommonInterfaceConfig |
| WANConnectionDevice | Embedded device | Yes (1+) | Hosts connection-specific services |
| WANCommonInterfaceConfig | Service | Yes | Physical interface monitoring |
| WANIPConnection | Service | At least one per WANConnectionDevice | IP connection management |
| WANPPPConnection | Service | Optional | PPP connection management |
| WANEthernetLinkConfig | Service | If Ethernet WAN | Ethernet link configuration |
| WANDSLLinkConfig | Service | If DSL WAN | DSL link configuration |
Engineering Integration Patterns
When engineering a UPnP control point that interacts with WANDevice v2, the first step is device discovery via UPnP’s SSDP (Simple Service Discovery Protocol). The WANDevice v2 must respond to M-SEARCH requests with a device description URL. Control points should parse the device description to discover the WANCommonInterfaceConfig service URL (for monitoring) and the available WANConnectionDevice instances (for connection management).
Implement robust device discovery with a timeout and retry mechanism. The WANDevice v2 description document is critical — without it, control points cannot discover the embedded services. Use a 3-second SSDP search interval with at least 3 retries. Cache the device description URLs to minimize multicast traffic on subsequent interactions with the same gateway.
For multi-WAN gateway implementations (e.g., LTE failover + DSL primary), the WANDevice v2 contains multiple WANConnectionDevice entries. Control points should iterate through all WANConnectionDevice instances to build a complete view of the gateway’s WAN connectivity. Each instance’s WANIPConnection or WANPPPConnection service exposes the connection state, allowing the control point to identify which WAN link is currently active or preferred.
The WANDevice v2 template does not prescribe a standard mechanism for determining the active WANConnectionDevice when multiple are present. Control points should not assume that WANConnectionDevice 1 is always the primary. Instead, compare the ConnectionStatus of each WANIPConnection/WANPPPConnection — the one in “Connected” state with the highest UpTime value is typically the active primary link.
The v2 specification also improves eventing support. When connection state changes occur (e.g., a WAN link drops), the WANDevice v2 service can emit UPnP event notifications to subscribed control points via the GENA (General Event Notification Architecture) protocol. This enables real-time monitoring without polling. Control points should subscribe to the ConnectionStatus variable of all available WAN connection services to receive immediate notifications of link state transitions.
Frequently Asked Questions
Q: How does WANDevice v2 differ from the IGD (Internet Gateway Device) root device?
A: The IGD root device (ISO/IEC 29341-24) contains both the WANDevice and LANDevice as embedded sub-devices. WANDevice v2 is specifically the WAN-side sub-device within the IGD. The IGD root provides the overall gateway abstraction, while WANDevice v2 focuses on WAN connectivity.
A: The IGD root device (ISO/IEC 29341-24) contains both the WANDevice and LANDevice as embedded sub-devices. WANDevice v2 is specifically the WAN-side sub-device within the IGD. The IGD root provides the overall gateway abstraction, while WANDevice v2 focuses on WAN connectivity.
Q: Can there be multiple WANDevice instances in a single gateway?
A: The standard models a single WANDevice per IGD. However, for gateways with multiple physical WAN interfaces (e.g., separate DSL and LTE modules), each physical WAN may have its own WANConnectionDevice within the single WANDevice, or the implementation may use multiple IGD instances — a scenario not fully addressed by the standard.
A: The standard models a single WANDevice per IGD. However, for gateways with multiple physical WAN interfaces (e.g., separate DSL and LTE modules), each physical WAN may have its own WANConnectionDevice within the single WANDevice, or the implementation may use multiple IGD instances — a scenario not fully addressed by the standard.
Q: What happens to port mappings when a WANConnectionDevice fails over?
A: Port mappings are per-connection-device. If the active WAN link fails over from WANConnectionDevice 1 to WANConnectionDevice 2, the port mappings on Device 1 remain intact but inactive. Mappings on Device 2 must be created separately. Some gateway implementations offer a “copy port mappings” feature, but this is vendor-specific and not standardized in WANDevice v2.
A: Port mappings are per-connection-device. If the active WAN link fails over from WANConnectionDevice 1 to WANConnectionDevice 2, the port mappings on Device 1 remain intact but inactive. Mappings on Device 2 must be created separately. Some gateway implementations offer a “copy port mappings” feature, but this is vendor-specific and not standardized in WANDevice v2.
Q: Is WANDevice v2 backward compatible with WANDevice v1 control points?
A: Generally yes. The v2 specification maintains backward compatibility with v1 by retaining all v1 services and state variables. Control points designed for v1 will discover and interact with v2 devices, but they will not be able to access v2-specific features such as multiple WANConnectionDevice instances or IPv6 address variables.
A: Generally yes. The v2 specification maintains backward compatibility with v1 by retaining all v1 services and state variables. Control points designed for v1 will discover and interact with v2 devices, but they will not be able to access v2-specific features such as multiple WANConnectionDevice instances or IPv6 address variables.
