Declarative RPC

This document describes the usage of the Declarative RPC functions used to generate TR-069 or USP-compatible RPC structures based on Search Paths. It includes supported syntax, expressions and examples. It also includes examples of using this syntax to activate services and classify CPE.

Scenario overview

Declarative RPCs provide four main scenarios for working with CPE parameters and objects:

SetPath

Executes SetParameterValues on the device using declarative search paths instead of exact parameter paths.

Input data: path → value dictionary, similar to regular SetParameterValues, but with paths that may contain extended Search Path expressions

GetPath

Executes GetParameterValues on the device using declarative search paths for flexible selection of required parameters.

Input data: list of paths, similar to regular GetParameterValues (partial paths allowed), but with paths that may contain extended Search Path expressions

DelPath

Executes DeleteObject on the device using declarative search paths. Supports both deletion of individual objects and bulk deletion of all objects matching the criteria.

Input data: list of paths ending with a dot (partial paths allowed), but with paths that may contain extended Search Path expressions

ApplyPath

Universal entry point for executing SetParameterValues/GetParameterValues/DeleteObject operations. Automatically determines the operation type based on input data format. To delete objects, add the del: prefix to all paths.

Input data: any possible SetPath/GetPath/DelPath input data, the scenario will be selected according to the input data format

Syntax overview

1. Search Path

Search Paths allow addressing parameters and objects in a declarative and expressive way.

Expression Matching

Expressions are enclosed in square brackets [ ] and allow filtering object instances.

Supported comparison operators:

Operator	Meaning	Example
`==`	Equals	`[Name=="SSID1"]`
`!=`	Not equals	`[Enable!=true]`
`>`	Greater than (numeric)	`[Uptime>1000]`
`>=`	Greater or equal (numeric)	`[Uptime>=60]`
`<`	Less than (numeric)	`[SignalStrength<0]`
`<=`	Less or equal (numeric)	`[SignalStrength<=-50]`
`~=`	Contains (substring for strings)	`[SSID~="Guest"]`

Notes:

String literals can use 'single' or "double" quotes.
Only == and != are allowed for boolean types.
Only ==, !=, and ~= are allowed for strings.
Date values must follow ISO format: 2021-08-01T10:00:00Z.
Multiple conditions could be combined with logical AND operator: VLANID==123&&BridgeName=="br0".

2. Wildcards

Use * to match any single node or index.

Example:

Device.IP.Interface.*.Stats.Packets
Device.*.Interface.1.Stats.Packets

3. Regex Matching

Use /.../ to match node via regular expression.

Example:

/.*evice/.DeviceInfo.ModelName

Matches both Device.DeviceInfo.ModelName and InternetGatewayDevice.DeviceInfo.ModelName.

4. Reference Following

Use +. to resolve references in expressions or path resolution.

Notes:

Appliable only for TR-181 datamodel.

Example:

Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=="2.4GHz"].SSID -> Device.WiFi.SSID.1.SSID and all other SSIDs with Device.WiFi.Radio. object underneath with OperatingFrequencyBand==2.4GHz

Follows the LowerLayers reference and evaluates the condition on the referenced object.

5. Indexing and Slicing

Use indexing after expression blocks to select specific items from results:

Syntax	Description
#1	First item (1-based index)
#-1	Last item (Python-style negative index)
#2:4	Slice (2nd to 3rd items)
#:	All items (default)

Syntax Examples

1. Search Path

Example 1: Simple condition

Example with TR-98:

InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.[Name=="INTERNET"].Enable

This expression:

Navigates to the WANIPConnection objects
Locates the one with Name parameter equal to "INTERNET"
Retrieves its Enable parameter

Real-world application:

In a router with multiple WAN connections:

InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.Name = "INTERNET"
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.Enable = true
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.2.Name = "IPTV"
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.2.Enable = false

The search expression would return true, allowing you to check if the main Internet connection is enabled without needing to know its instance number.

This approach is valuable when configuration systems automatically assign instance numbers that may change after reboots or reconfiguration.

Example 2: Regex condition

Example with TR-98:

InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.[Name~="INTER.*"].Enable

This expression:

Searches WANIPConnection objects
Finds any whose Name starts with "INTER" followed by any characters
Returns their Enable parameter

Real-world application: In a network with various connection types:

InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1.Name = "INTERNET_PRIMARY"
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.2.Name = "INTERNET_BACKUP"
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.3.Name = "IPTV_SERVICE"

The regular expression query would return the Enable status of both "INTERNET_PRIMARY" and "INTERNET_BACKUP" connections, but not "IPTV_SERVICE". This is particularly useful for working with naming conventions where exact matches aren't feasible but patterns are consistent.

Example 3: Multiple conditions

Example with TR-98:

InternetGatewayDevice.Layer2Bridging.Bridge.[VLANID==123&&BridgeName=="br0"].BridgeEnable

This expression:

Searches through Bridge objects
Finds those where both VLANID equals 123 AND BridgeName equals "br0"
Returns their BridgeEnable parameter

Real-world application: In a complex network with multiple bridges:

InternetGatewayDevice.Layer2Bridging.Bridge.1.VLANID = 123
InternetGatewayDevice.Layer2Bridging.Bridge.1.BridgeName = "br0"
InternetGatewayDevice.Layer2Bridging.Bridge.1.BridgeEnable = true

InternetGatewayDevice.Layer2Bridging.Bridge.2.VLANID = 123
InternetGatewayDevice.Layer2Bridging.Bridge.2.BridgeName = "iptv"
InternetGatewayDevice.Layer2Bridging.Bridge.2.BridgeEnable = false

The multiple condition query would return only true from the first bridge, as the second bridge doesn't meet all conditions. This capability is essential for precise configuration in complex systems with multiple similar objects that need to be differentiated by multiple properties.

2. Wildcards (*)

Example with TR-98:

InternetGatewayDevice.LANDevice.1.WLANConfiguration.*.SSID

This expression:

Starts at the InternetGatewayDevice
Navigates to the first LANDevice (instance 1)
Finds all WLANConfiguration objects (regardless of instance number)
Retrieves the SSID parameter from each one

Real-world application: In a home router with multiple Wi-Fi networks:

InternetGatewayDevice.LANDevice.1.WLANConfiguration.1.SSID = "HomeNetwork"
InternetGatewayDevice.LANDevice.1.WLANConfiguration.2.SSID = "GuestNetwork"
InternetGatewayDevice.LANDevice.1.WLANConfiguration.3.SSID = "IoTNetwork"

Using the wildcard expression would return:

["HomeNetwork", "GuestNetwork", "IoTNetwork"]

This is particularly useful for listing all networks or applying changes across all WLANs without having to know exactly how many exist in the device.

3. Regex Matching

Example with TR-98:

InternetGatewayDevice.LANDevice.1.LANEthernetInterfaceConfig.*.Stats./Packets.*/

This expression::

Navigates to all LAN Ethernet interface Stats objects
Returns all parameters containing "Packets" in their name

Real-world application: In a router with Ethernet statistics:

{
  "PacketsReceived": 12345,
  "PacketsSent": 67890,
  "BytesReceived": 1234567,
  "BytesSent": 7654321
}

The parameter pattern matching would return:

{
  "PacketsReceived": 12345,
  "PacketsSent": 67890
}

4. Reference Following (+.)

Example 1: Simple following

Real-world application: Looking at our Wi-Fi configuration:

{
  "Device.WiFi.Radio.1.LowerLayers": "",
  "Device.WiFi.Radio.1.OperatingFrequencyBand": "2.4GHz",
  "Device.WiFi.SSID.1.LowerLayers": "Device.WiFi.Radio.1.",
  "Device.WiFi.SSID.1.SSID": "HomeNetwork"
}

When we use:

Device.WiFi.SSID.1.LowerLayers+.OperatingFrequencyBand

The system:

Looks at the value of Device.WiFi.SSID.1.LowerLayers, which is "Device.WiFi.Radio.1."
Follows this reference to find the Radio.1 object
Accesses the "OperatingFrequencyBand" parameter of Radio.1
Returns "2.4GHz"

This operator allows us to determine which frequency band an SSID operates on by following the reference from the SSID to its associated radio.

Example 2: Combined with Search Path

You can combine Search Path expressions with Reference Following for powerful queries:

Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=="2.4GHz"].SSID

This finds all SSID objects whose LowerLayers reference points to a Radio with OperatingFrequencyBand of "2.4GHz".

Result:

["HomeNetwork", "GuestNetwork"]

5. Indexing and slicing

Example 1: Combined with Reference Following

Source data:

{
  "Device.WiFi.SSID.100.LowerLayers": "Device.WiFi.Radio.1.,Device.WiFi.Radio.2.",
  "Device.WiFi.Radio.1.OperatingFrequencyBand": "2.4GHz",
  "Device.WiFi.Radio.2.OperatingFrequencyBand": "5GHz"
}

Expressions:

Device.WiFi.SSID.100.LowerLayers#1+.OperatingFrequencyBand  // → 2.4GHz
Device.WiFi.SSID.100.LowerLayers#2+.OperatingFrequencyBand  // → 5GHz

Example 2: Combined with Search Path

Expression:

Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=="5GHz"]#1.SSID

This expression:

Finds all SSIDs that operate on the 5GHz band
Selects only the first one (#1) from those results
Returns just that single SSID name

Detailed scenario examples

GetPath

The GetPath method extracts parameter values based on provided path expressions.

Example 1: Basic Extraction

[
  "InternetGatewayDevice.Layer2Bridging.AvailableInterface.[InterfaceReference=='InternetGatewayDevice.WANDevice.1.WANConnectionDevice.1.WANIPConnection.1'].InterfaceType",
  "InternetGatewayDevice.Layer2Bridging.AvailableInterface.*.InterfaceType"
]

Example 2: Getting Network Statistics

[
  "InternetGatewayDevice.LANDevice.1.LANEthernetInterfaceConfig.*.Stats./Packets.*/"
]

Example 3: Following References

[
  "Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz'].SSID"
]

Extracts all SSIDs associated with 2.4 GHz radio interfaces.

Example 4: Complex Reference Following

[
  "Device.WiFi.AccessPoint.[SSIDReference+.SSID=='PVK072318'].AssociatedDevice.[OperatingStandard=='ac'].SignalStrength"
]

Extracts signal strength of all AC clients connected to access points with SSID "PVK072318".

Example 5: Getting Information About All Bridges

[
  "InternetGatewayDevice.Layer2Bridging.Bridge.*.BridgeEnable",
  "InternetGatewayDevice.Layer2Bridging.Bridge.*.BridgeName",
  "InternetGatewayDevice.Layer2Bridging.Bridge.*.VLANID"
]

Example 6: Getting Information About Connected Clients

[
  "Device.WiFi.AccessPoint.[SSIDReference+.SSID=='MyHomeNetwork'].AssociatedDevice.*.MACAddress",
  "Device.WiFi.AccessPoint.[SSIDReference+.SSID=='MyHomeNetwork'].AssociatedDevice.*.SignalStrength"
]

Example 7: Getting Only the First SSID on 2.4 GHz Radio Interfaces

[
  "Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz']#1.SSID"
]

Example 8: Getting the First 3 SSIDs on 2.4 GHz Radio Interfaces

[
  "Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz']#1:4.SSID"
]

Example 9: Getting the Last SSID on 2.4 GHz Radio Interfaces

[
  "Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz']#-1.SSID"
]

SetPath

The SetPath method sets parameter values based on provided path expressions and values.

Example 1: Setting DNS Servers

{
  "InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANIPConnection.[Name=='INTERNET'].DNSEnabled": true,
  "InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANIPConnection.[Name=='INTERNET'].DNSServers": "8.8.8.8,1.1.1.1"
}

Example 2: Configuring VLAN Bridge

{
  "InternetGatewayDevice.Layer2Bridging.Bridge.[VLANID==1234&&BridgeName=='br0'].BridgeEnable": true,
  "InternetGatewayDevice.Layer2Bridging.Bridge.[VLANID==1234&&BridgeName=='br0'].BridgeStandard": "802.1Q"
}

Example 3: Configuring Port Forwarding, Creating New if Not Exists

{
  "~InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANPPPConnection.[ConnectionStatus=='Connected'].PortMapping.[ExternalPort==8080].ExternalPort": 8080,
  "~InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANPPPConnection.[ConnectionStatus=='Connected'].PortMapping.[ExternalPort==8080].InternalPort": 80,
  "~InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANPPPConnection.[ConnectionStatus=='Connected'].PortMapping.[ExternalPort==8080].Protocol": "TCP"
}

Example 4: Wi-Fi Configuration Using Reference Following

{
  "Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz'].Enable": true,
  "Device.WiFi.SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz'].SSID": "MyHomeNetwork_2.4G"
}

Example 5: Enabling Wi-Fi on Specific Frequency

{
  "Device.WiFi.Radio.[OperatingFrequencyBand=='5GHz'].Enable": true
}

Example 6: Finding and Configuring Ethernet Ports by MAC Address

{
  "InternetGatewayDevice.LANDevice.1.LANEthernetInterfaceConfig.[MACAddress=='8a:aa:14:6b:de'].Enable": true,
  "InternetGatewayDevice.LANDevice.1.LANEthernetInterfaceConfig.[MACAddress=='8a:aa:14:6b:de'].MaxBitRate": "1000"
}

Example 7: Configuring SSID Based on Module Name and Frequency

{
  "Device.WiFi.[Name=='foo'].SSID.[LowerLayers+.OperatingFrequencyBand=='2.4GHz'].Enable": true,
  "Device.WiFi.[Name=='foo'].SSID.[LowerLayers+.OperatingFrequencyBand=='5GHz'].Enable": true
}

CPE classification

In everyday operations, many scenarios are aimed at identifying specific groups of CPE based on device characteristics, such as software version, hardware version, or specific issues like incorrect configurations. While most of these classification actions are conceptually simple, their effective implementation can be complex.

Based on these classifications or groupings, administrators can define specific logic, such as corrective actions or notification mechanisms. To make this process simpler and more convenient, declarative scenarios provide an elegant solution.

Filtering rules syntax

Filtering rules are expressed as an array of condition groups. Each condition group contains one or more parameters to check. A device matches a CPE class if it satisfies at least one of these condition groups (logical OR between groups).

Within each condition group, all parameters must match for the group to be considered satisfied (logical AND between parameters).

Parameter matching options

For each parameter, you can define matching rules using:

Exact value match - parameter must exactly match the specified value
Regular expression matching - parameter must match the specified regex pattern

Filtering rules examples

Example 1: All AVM devices

This CPE class identifies all CPE manufactured by AVM (FRITZ!Box devices) by checking if the hardware version starts with "FRITZ":

[
  {
    "params": {
        "InternetGatewayDevice.DeviceInfo.HardwareVersion": "^FRITZ.*$"
    }
  }
]

Example 2: Devices with incorrect DNS configuration

This CPE class identifies devices that either have no configured DNS servers or are not using Google DNS servers (8.8.8.8, 8.8.4.4):

[
  {
    "params": {
      "~InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANPPPConnection.[Name==\"internet\"&&ConnectionStatus==\"Connected\"].DNSServers": ""
    }
  },
  {
    "params": {
      "~InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANPPPConnection.[Name==\"internet\"&&ConnectionStatus==\"Connected\"].DNSServers": "^(?!8\\.8\\.8\\.8, 8\\.8\\.4\\.4$).+$"
    }
  }
]

In this example:

The first condition group checks for absence of DNS servers
The second condition group uses negative lookahead in regex to find devices whose DNS servers don't match Google DNS configuration

Example 3: Classification by firmware version

Identifying devices with a specific range of firmware versions:

[
  {
    "params": {
      "InternetGatewayDevice.DeviceInfo.SoftwareVersion": "^1\\.2\\.[0-9]+$"
    }
  }
]

Declarative RPC

Scenario overview​

SetPath​

GetPath​

DelPath​

ApplyPath​

Syntax overview​

1. Search Path​

2. Wildcards​

3. Regex Matching​

4. Reference Following​

5. Indexing and Slicing​

Syntax Examples​

1. Search Path​

2. Wildcards (*)​

3. Regex Matching​

4. Reference Following (+.)​

5. Indexing and slicing​

Detailed scenario examples​

GetPath​

SetPath​

CPE classification​

Scenario overview

SetPath

GetPath

DelPath

ApplyPath

Syntax overview

1. Search Path

2. Wildcards

3. Regex Matching

4. Reference Following

5. Indexing and Slicing

Syntax Examples

1. Search Path

2. Wildcards (*)

3. Regex Matching

4. Reference Following (+.)

5. Indexing and slicing

Detailed scenario examples

GetPath

SetPath

CPE classification