Software Design Document: Dual-Protocol Devices via USP Serial Postfix

This document describes how a physical device managed over both TR-069 (CWMP) and TR-369 (USP) is kept as two independent device records: the TR-069 record keeps the device serial number, while the USP record is stored under <serial>_USP. The behavior is controlled by a global flag that is disabled by default.

Requirements: PROD-501 (FRD "Dual protocol logic — USP serial postfix"). Implementation: DEV-3143.

1. Description

The platform identifies a device by its serial number. Without this feature, when a device that speaks both protocols connects over the second protocol, its existing record is deleted and re-created under the new protocol, so only one management channel is available at a time.

With the feature enabled, a device registering over USP gets the platform identifier <serial>_USP, while a device registering over TR-069 keeps its serial number. The two records never collide, and each has its own data model, tasks, profiles, monitoring and license.

The postfix applies to the platform identifier only:

  • The postfix is the fixed literal _USP and is never added twice.

  • The serial number reported by the device is stored unchanged in Device.DeviceInfo.SerialNumber, and the postfix is never sent to the device.

  • No API signature changes. The base serial addresses the TR-069 record and <serial>_USP addresses the USP record.

2. Configuration

The behavior is controlled by two settings that drive the same flag.

Setting Scope Description

dualProtocolDeviceHandling
(ACS configuration parameter)

Cluster-wide, applied without restart

0 (default) — disabled.
1 — USP devices registering from now on are created as <serial>_USP. Existing USP records are not renamed.
Managed in FT Configs (see ACS Configuration).

FTACS_DUAL_PROTOCOL
(environment variable)

Per instance, applied at startup

true — enables the flag on this instance and renames existing USP records (see Renaming Existing USP Records).
false — disables the flag on this instance.
Unset — the ACS configuration parameter applies.
See Environment Variables.
Existing USP records are renamed only when FTACS_DUAL_PROTOCOL=true.

2.1. Effective Behavior

FTACS_DUAL_PROTOCOL dualProtocolDeviceHandling New USP device Existing USP record <serial>

unset

0

Created as <serial> (legacy behavior).

Unchanged.

unset

1

Created as <serial>_USP.

Keeps its serial. Suitable when the device has no TR-069 counterpart (see TR-069 Side).

true

(forced to 1)

Created as <serial>_USP.

Renamed to <serial>_USP the next time the device registers.

false

(forced to 0)

Created as <serial>, unless a USP record <serial>_USP already exists (see Disabling the Feature).

Unchanged.

2.2. Enabling the Feature

  1. Set FTACS_DUAL_PROTOCOL=true in app.env (or .env for Docker) on every cluster node.

  2. Do not set dualProtocolDeviceHandling in FT Configs at the same time (see Precedence Between the Two Settings).

  3. Restart the nodes. USP devices re-register when they reconnect, and their existing records are renamed at that point.

If the existing USP devices have no TR-069 counterparts, setting dualProtocolDeviceHandling=1 in FT Configs is enough and needs no restart. Existing USP records then keep their serials, and only new USP devices get the postfix.

2.3. Disabling the Feature

Set FTACS_DUAL_PROTOCOL=false (or remove it and set dualProtocolDeviceHandling=0) and restart the nodes.

  • Postfixed records are not renamed back. A device whose USP record is <serial>_USP keeps using it, so it never collides with its TR-069 record.

  • To return a USP device to its original serial, delete its <serial>_USP record manually. The device then re-registers as <serial>, and if a TR-069 record <serial> exists, the legacy behavior applies: the TR-069 record is replaced by the USP one.

  • USP devices that never had a postfixed record behave exactly as before the feature.

2.4. Precedence Between the Two Settings

FTACS_DUAL_PROTOCOL is applied once, at startup. Once dualProtocolDeviceHandling has been saved in FT Configs, its value is pushed to every node on each configuration change and can override the environment variable. Use one mechanism per deployment, preferably the environment variable.

3. Processing

3.1. USP Registration

When a USP device registers, its reported serial is converted to the platform identifier. An existing USP record of the device is always kept:

Condition Platform identifier

A USP record <serial>_USP exists (whatever the flag)

<serial>_USP

The flag is disabled

<serial>

The flag is enabled and a USP record <serial> exists

<serial>

The flag is enabled and there is no USP record yet

<serial>_USP

  • Whitelist: the reported serial is checked first, then the platform identifier, so whitelist entries can use the serial printed on the device.

  • License: every record consumes one license, so a device managed over both protocols consumes two.

3.2. Renaming Existing USP Records

With FTACS_DUAL_PROTOCOL=true, a USP record that still holds the original serial is renamed to <serial>_USP when its device registers. There is no batch migration. A TR-069 record is never renamed.

  • The record keeps its id, so its parameters, tasks, profiles and monitoring stay attached.

  • History stored by serial (activity log, monitoring history, traces, QoE data, license tracking) stays under the original serial.

  • If a record <serial>_USP already exists, the rename is skipped and the device uses that record.

  • If the database rejects the new serial (for example, it exceeds the column length), the record keeps its original serial and the rename is retried on the next registration. The application performs no length check of its own.

3.3. Bulk Data

Devices that push bulk data with their own serial are matched to their USP record, whether or not it has the postfix. Bulk data is never stored on the TR-069 record.

3.4. TR-069 Side

While the flag is enabled, a TR-069 Inform never deletes a USP record.

A USP record that still holds the original serial (not yet renamed, or kept with FTACS_DUAL_PROTOCOL unset) is matched by a TR-069 Inform with the same serial and turned into a TR-069 record. When devices have TR-069 counterparts, enable the feature with FTACS_DUAL_PROTOCOL=true and a restart, so the USP records are renamed as early as possible.

4. Logging

Log entries related to the feature carry the [DUAL-PROTOCOL] prefix and include the base serial number:

  • INFO — a USP record has been renamed.

  • ERROR — a rename was skipped or rejected by the database.

  • DEBUG — a USP record keeps its original serial while the flag is enabled.

5. Limitations

  • Pairing of the TR-069 and USP records, and the UI part of the FRD (protocol labels, a companion-device link, search by base serial), are not part of this change.

  • Northbound integrations, bulk imports and reports that address a USP device by serial must use its platform identifier, which can be <serial>_USP.