README.md

GatewayInfo

This repository provides Device.GatewayInfo. functionality

Below is the sequence diagram for the Device-Gateway association with DHCP Discover.

sequenceDiagram
    participant ACS
    participant Gateway
    participant Lan-Device
    Lan-Device->>Gateway: DHCP Discover (Device Identity)
    Gateway->>Lan-Device: DHCP Offer (Gateway Identity)
    Lan-Device->>Gateway: DHCP Request (Device Identity)
    Gateway->>Lan-Device: DHCP ACK (Gateway Identity)
    Note right of Lan-Device: Lan-Device Populate GatewayInfo. table
    Note right of Gateway: Gateway Populate ManageableDevice.{i}. table
    Lan-Device->>ACS:  TR069 Inform (with Gateway Identity)
    ACS->>Lan-Device:  TR069 Inform response
    ACS->>Gateway:  TR069 Get (ManageableDevice)
    Gateway->>ACS:  TR069 GetResp (ManageableDevice) table

Gateway UCI

config global 'global'
	option wan_interface 'wan'
	option lan_interface 'lan'

Note: For extender devices both wan_interface and lan_interface are set to "lan"

Gateway Procedures

The Gateway Identity tuple (OUI, ProductClass, SerialNumber) is present in 'db' (Same source used for Device.DeviceInfo. object).

The 86-set-gateway-device-info uci-default script reads the lan interface from UCI option gateway.global.lan_interface and configures the gateway identity in dhcp UCI for the corresponding LAN interface section to publish gateway information to its LAN clients.

Lan-Device procedures

The Lan-Device Identity tuple (OUI, ProductClass, SerialNumber) is present in 'db' (Same source used for Device.DeviceInfo. object).

The 86-set-gateway-device-info uci-default script reads the wan interface from UCI option gateway.global.wan_interface and configures the device identity in network UCI to publish its own identity to upstream network (DHCP server) using DHCP option 125 for the corresponding wan interface.

How GatewayInfo works

• When CPE comes up after reboot, gateway-info package first identifies the upstream(wan_interface) and downstream(lan_interface) interfaces from its UCI file /etc/config/gateway

• After that it checks if DHCP opt125 is configured in upstream(for DeviceInfo) and downstream(for GatewayInfo) interfaces. If find not configured already then it identifies the manufacturer oui, serial number and product class of the device and configures DHCP opt125 as follows.

  To send gateway info to Lan devices in dhcp UCI:

Encapsulated option	DHCPv4 opt125 sub-opt	DM param
ManufacturerOUI	4	Device.DeviceInfo.ManufacturerOUI
SerialNumber	5	Device.DeviceInfo.SerialNumber
ProductClass	6	Device.DeviceInfo.ProductClass

To send manageable devices info to upstream in network UCI:

Encapsulated option	DHCPv4 opt125 sub-opt	DM param
ManufacturerOUI	1	Device.DeviceInfo.ManufacturerOUI
SerialNumber	2	Device.DeviceInfo.SerialNumber
ProductClass	3	Device.DeviceInfo.ProductClass

This options are encapsulated in DHCP option125 with Broadband Forum's IANA enterprise ID which is 3561.

Note: For extender devices it only configures manageable device sub-options (1,2 & 3).

• If the device is a Gateway and it has obuspa package installed then at boot-up it creates an MDNS advertisement file to announce the service with its EndpoitID in TXT record. Which further helps the connected devices to identify the management protocol of the gateway device.

{
	"usp_mdns": {
		"service": "_usp-agt-mqtt._tcp.local",
		"port": 0,
		"txt": [ "ID=os::XXXX-XXXXXXXX" ]
	}
}

Note: In the current implementation umdns is used (for simplicity reasons) for mDNS advertisement and Discovery, but due to the limitation of umdns, the mDNS advertisement is not compliant with TR-369 mDNS advertisement requirements.

• Once these configurations are done, devices starts sending DHCP option125 in DHCP packets.

Identification of GatewayInfo

• gateway-info package installs a DHCP hook script etc/udhcpc.user.d/udhcpc_gateway_info.user, which gets invoked at every DHCP events(release, renew, bind) and parses DHCP option 125 to extract gateway identity based on Enterprise ID 3561 as follows
  • At DHCP release event it deletes the gateway information from /var/state/gwinfo
  • At DHCP renew and bind:
    • If opt125 is not present in DHCP offer or sub-opt 4,5 & 6 are not present in DHCP opt125 then it sends UnknownGatewayDiscovered! event and deletes all information like oui, serial number, product class e.t.c from /var/state/gwinfo. In this case Device.GatewayInfo.ManagementProtocol would be Unknown and the below parameters would have "" (Empty) value.
      1. Device.GatewayInfo.ManufacturerOUI
      2. Device.GatewayInfo.ProductClass
      3. Device.GatewayInfo.SerialNumber
      4. Device.GatewayInfo.EndpointID
    • If sub-opt 4,5 or 6 found in DHCP offer then it sets the oui, serial and class in /var/state/gwinfo and protocol is set to 'CWMP'.
    • Then it performs MDNS discovery and if finds a USP Agent service from the same IP address as the DHCP Server then does the followings:
      1. Identifies the Endpoint-ID from the TXT record and sets it in /var/state/gwinfo
      2. Sets the protocol to 'USP' in /var/state/gwinfo.
      3. Sends the USPGatewayDiscovered! event.
    • Otherwise sends CWMPGatewayDiscovered! event.

Identification of Manageable Device in LAN network

Device.ManagementServer.ManageableDevice.{i}. object table is populated by cwmp and gateway device relies on DHCP options (/tmp/dhcp.client.options) file for getting the Manageable Device identities, which is exposed in the TR181 datamodel using (libbbf) API's.

The Device.ManagementServer.ManageableDevice.{i}. object table is populated for the active devices available in Device.Hosts. table and their device identity is collected from /tmp/dhcp.client.options file.