module bbf-xponani {

    yang-version 1.1;

    namespace "urn:bbf:yang:bbf-xponani";

    prefix bbf-xponani;

    include bbf-xponani-base;
    include bbf-xponani-ani-body;
    include bbf-xponani-v-enet-body;

    organization
      "Broadband Forum <https://www.broadband-forum.org>
Fiber Access Networks Work Area";

    contact
      "Comments or questions about this Broadband Forum YANG module
should be directed to <mailto:info@broadband-forum.org>.

Editor:      Robert Peschi, Nokia

PS Leader:   Joey Boyd, Adtran

WA Director: Marta Seda, Calix";

    description
      "This module contains a collection of YANG definitions for
supporting the Broadband Forum requirements on management of
ITU-T Passive Optical Network (PON) interfaces as defined in
ITU-T G.984.x, G.987.x, ITU-T G.989.x and ITU-T G.9807.x. As
such, this module is specific to access network equipment (e.g.,
BBF-specified Access Nodes and FTTdp DPUs).

Specifically, this module defines management of Access Network
Interfaces (ANI) which represent the physical Optical Network
Unit (ONU).

Copyright (c) 2018-2024, Broadband Forum

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The above license is used as a license under copyright only.
Please reference the Forum IPR Policy for patent licensing terms
<https://www.broadband-forum.org/ipr-policy>.

Any moral rights which are necessary to exercise under the above
license grant are also deemed granted under this license.

This version of this YANG module is part of TR-385i3; see
the TR itself for full legal notices.";

    revision "2024-04-23" {
      description
        "Issue 3.
* Approval Date:    2024-04-23.
* Publication Date: 2024-04-23.";
      reference
        "TR-385i3: YANG Modules for PON Management
        	<https://www.broadband-forum.org/technical/download/
        		 TR-385_Issue-3.pdf>";

    }

    revision "2023-06-21" {
      description
        "Issue 2 Amendment 1.
* Approval Date:    2023-06-21.
* Publication Date: 2023-06-21.";
      reference
        "TR-385i2a1: ITU-T PON YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-385_Issue-2_Amendment-1.pdf>";

    }

    revision "2020-10-13" {
      description
        "Issue 2.
* Approval Date:    2020-10-13.
* Publication Date: 2020-10-13.";
      reference
        "TR-385i2: ITU-T PON YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-385_Issue-2.pdf>";

    }

    revision "2019-02-25" {
      description
        "Initial revision.
* Approval Date:    2019-02-25.
* Publication Date: 2019-02-25.";
      reference
        "TR-385: ITU-T PON YANG Modules
        	<https://www.broadband-forum.org/technical/download/
        		 TR-385.pdf>";

    }


    // features

    feature configurable-ani-onu-id {
      description
        "Indicates support for configuration of the Optical Network Unit
(ONU) ID associated with the Access Network Interface (ANI).";
    }

    feature configurable-ani-management-gem-port-id {
      description
        "Indicates support for configuration of the management
G-PON Encapsulation Method (GEM) port.";
    }

    feature ani-onu-serial-number-reporting {
      description
        "Indicates that the Access Network Interface (ANI) holds the
Optical Network Unit (ONU) serial number in its state data.";
    }

    feature ani-defects {
      description
        "Indicates support for reporting defects observed at the Access
Network Interface (ANI).";
    }

    feature ani-defect-notifications {
      description
        "Indicates support for reporting state change of the defects
observed at the Access Network Interface (ANI).";
    }

    // groupings
    grouping ani-config-data {
      description
        "Configuration data intended for the Optical Network Unit (ONU)
physical device. This data is brought to the ONU, when present,
for instance via the Physical Layer Operations, Administrations
and Maintenance (PLOAM) channel or using ONU Management and
Control Interface (OMCI) on the Management G-PON Encapsulation
Method (GEM) port.";
      leaf upstream-fec {
        type boolean;
        default "false";
        description
          "If 'true', enable Forward Error Correction (FEC) in the
upstream direction for this specific Optical Network Unit
(ONU). If 'false', disable FEC in the upstream direction
for this specific ONU.";
        reference
          "ITU-T G.984.3 Clause 13.3.1.1;
          ITU-T G.987.3 Clause 10.2;
          ITU-T G.9807.1 Clause C.10.1.3.2.4;
          ITU-T G.989.3 Clause 10.1.3.2.4;
          ITU-T G.9804.2 Clause 10.3.2.4";

      }

      leaf management-gemport-aes-indicator {
        type boolean;
        default "false";
        description
          "If 'true', enable Advanced Encryption Standard (AES)
for the management G-PON Encapsulation Method (GEM) port
of this Optical Network Unit (ONU). If 'false', disable
AES for the management GEM port of this ONU.

For G-PON, this applies in the downstream direction. For
XG-PON, XGS-PON, NG-PON2 and 50G-PON, this applies to both
the upstream and downstream directions.";
        reference
          "ITU-T G.984.3 Clause 12.1;
          ITU-T G.987.3 Clause 15.5.1;
          ITU-T G.9807.1 Clause C.15.5.1;
          ITU-T G.989.3 Clause 15.5.1;
          ITU-T G.9804.2 Clause 15.5.1";

      }

      leaf onu-id {
        if-feature bbf-xponani:configurable-ani-onu-id;
        type bbf-xpon-types:onu-id;
        description
          "The TC layer ONU Identifier (ONU-ID). When configured this
is the value which the Optical Line Termination (OLT) must
assign to the Optical Network Unit (ONU) during the ONU's
activation using the Assign_ONU-ID Physical Layer Operations,
Administrations and Maintenance (PLOAM) message.
For G-PON, range is 0..253.
For XG-PON, range is 0..1022.
For XGS-PON, range is 0..1020.
For NG-PON2, range is 0..1020.
For 25GS-PON, range is 0..1018.
For 50G-PON, range is 0..1019.";
        reference
          "ITU-T G.984.3 Clause 5.5.2;
          ITU-T G.987.3 Clause 6.4.2;
          ITU-T G.9807.1 Clause C.6.1.5.6;
          ITU-T G.989.3 Clause 6.1.5.6;
          ITU-T G.9804.2 Clause 6.5.2.5;
          MSA 25GS-PON Section C.6.1.5.7";

      }

      leaf management-gemport-id {
        if-feature bbf-xponani:configurable-ani-management-gem-port-id;
        type uint32;
        description
          "This leaf is only relevant to G-PON ONUs; it is ignored for
non-G-PON ONUs. In contrast with other xPON technologies, in
the case of G-PON, there is no requirement that the ITU-T TC
ID of the management G-PON Encapsulation Method (GEM) port
for the Optical Network Unit (ONU) is numerically equal to
the ONU-ID. This leaf provides the capability to specify
value for the management GEM port ID.

If this leaf is not configured the management GEM port
ID must be numerically equal to the ONU-ID.";
        reference
          "ITU-T G.984.3 Clause 5.5.5 - OMCC Port-ID;
          ITU-T G.987.3 Clause 6.4.4 - OMCC Port-ID;
          ITU-T G.989.3 Clause 6.1.5.8 - OMCC Port-ID;
          ITU-T G.9807.1 Clause C.6.1.5.8 - OMCC Port-ID;
          ITU-T G.9804.2 Clause 6.5.2.7 - OMCC Port-ID";

      }

      leaf-list notifiable-defect {
        if-feature bbf-xponani:ani-defect-notifications;
        type identityref {
          base bbf-xpon-def:items-detected-at-onu;
        }
        description
          "Optical Network Unit (ONU) is expected to generate a
'defect-state-change' notification each time defect(s)
listed in this leaf-list are raised or cleared.
If 'notifiable-defect' includes an identity which
is the base value for other defect(s) identity(ies),
the OLT will generate a single notification when status of
any defect derived from this base value changes.

In case the leaf-list is empty (as by default) the OLT
should not generate any 'defect-state-change'
notification.";
      }
    }  // grouping ani-config-data

    grouping ani-state-data {
      description
        "State data from the Optical Network Unit (ONU) physical device.
This data is fetched from the ONU physical device, when
present, for instance via the Physical Layer Operations,
Administrations and Maintenance (PLOAM) channel or using ONU
Management and Control Interface (OMCI) on the Management
G-PON Encapsulation Method (GEM) port.";
      leaf onu-id {
        type bbf-xpon-types:onu-id;
        description
          "The TC layer ONU Identifier (ONU-ID) which the Optical Line
Termination (OLT) has assigned to the Optical Network Unit
(ONU) during the ONU's activation using the Assign_ONU-ID
Physical Layer Operations, Administrations and Maintenance
(PLOAM) message.";
        reference
          "ITU-T G.984.3 Clause 5.5.2;
          ITU-T G.987.3 Clause 6.4.2;
          ITU-T G.9807.1 Clause C.6.1.5.6;
          ITU-T G.989.3 Clause 6.1.5.6;
          ITU-T G.9804.2 Clause 6.5.2.5";

      }

      leaf onu-serial-number {
        if-feature bbf-xponani:ani-onu-serial-number-reporting;
        type bbf-xpon-types:onu-serial-number;
        mandatory true;
        description
          "The serial number of the Optical Network Unit (ONU).";
        reference
          "ITU-T G.984.3 Clause 9.2.4.1;
          ITU-T G.987.3 Clause 11.3.3.2;
          ITU-T G.9807.1 Clause C.11.2.6.1;
          ITU-T G.9807.1 Clause C.11.2.6.2;
          ITU-T G.9807.1 Clause C.11.3.4.1;
          ITU-T G.989.3 Clause 11.2.6.1;
          ITU-T G.989.3 Clause 11.2.6.2;
          ITU-T G.989.3 Clause 11.3.4.1;
          ITU-T G.9804.2 Clause 11.2.6.1;
          ITU-T G.9804.2 Clause 11.2.6.2;
          ITU-T G.9804.2 Clause 11.3.4.1";

      }

      leaf channel-partition-id {
        type uint8;
        description
          "An index of the operator-specified channel subset in a
NG-PON2 system. During operation, the Optical Network Units
(ONUs) can be re-tuned between the channels within a channel
partition, but not across the boundaries of the channel
partition.";
      }

      leaf management-tcont-alloc-id {
        type uint32;
        description
          "The ITU-T Transmission Convergence (TC) Allocation Identifier
(Alloc-ID) of the management Transmission Container (T-CONT)
for the Optical Network Unit (ONU). It has the same numerical
value as the ITU-T TC ONU-ID.";
        reference
          "ITU-T G.987.3 Clause 6.1.5.7 - Default Alloc-ID;
          ITU-T G.9807.1 Clause C.6.1.5.7 - Default Alloc-ID;
          ITU-T G.987.3 Clause 6.4.3 - Default Alloc-ID;
          ITU-T G.984.3 Clause 5.5.3 - Default Alloc-ID;
          ITU-T G.9804.2 Clause 6.5.2.6 - Default Alloc-ID";

      }

      leaf management-gemport-id {
        type uint32;
        description
          "The ITU-T Transmission Convergence (TC) ID of the management
G-PON Encapsulation Method (GEM) port for the Optical Network
Unit (ONU). For NG-PON2, XGS-PON, XG-PON and 50G-PON,
it has the same numerical value as the ITU-T TC ONU-ID.
For G-PON, its value is not necessarily numerically equal
to the ONU-ID.";
        reference
          "ITU-T G.987.3 Clause 6.1.5.8 - OMCC Port-ID;
          ITU-T G.9807.1 Clause C.6.1.5.8 - OMCC Port-ID;
          ITU-T G.987.3 Clause 6.4.4 - OMCC Port-ID;
          ITU-T G.984.3 Clause 5.5.5 - OMCC Port-ID;
          ITU-T G.9804.2 Clause 6.5.2.7 - OMCC Port-ID";

      }

      leaf-list active-defects {
        if-feature bbf-xponani:ani-defects;
        type identityref {
          base bbf-xpon-def:items-detected-at-onu;
        }
        description
          "Defects detected by Optical Network Unit (ONU) for which
Access Network Interface (ANI) is configured. All applicable
identities should be reported.";
        reference
          "ITU-T G.984.3 Clause 11.1.2;
          ITU-T G.987.3 Clause 14.2.2;
          ITU-T G.989.3 Amd.2 Table 14-3;
          ITU-T G.9807.1 Amd.1 Table C.14.3;
          ITU-T G.9804.2 Table 14-4";

      }

      notification defect-state-change {
        if-feature bbf-xponani:ani-defect-notifications;
        description
          "A notification traceable to an ani which signifies that
defect(s) detected by an Optical Network Unit (ONU) have
been raised and/or cleared. Such notification is only
generated for defects listed in the 'notifiable-defect'
leaf list.";
        list defect {
          key "type";
          description
            "A notifiable defect that has changed state since
the previous 'defect-state-change' notification.";
          leaf type {
            type identityref {
              base bbf-xpon-def:items-detected-at-onu;
            }
            description "Defect type.";
          }

          leaf state {
            type bbf-xpon-def:defect-state;
            mandatory true;
            description
              "The current defect state.";
          }

          leaf last-change {
            type yang:date-and-time;
            mandatory true;
            description
              "The Optical Network Unit (ONU) system date and
time when the ONU has declared that the defect
state has changed.";
          }
        }  // list defect
      }  // notification defect-state-change
    }  // grouping ani-state-data

    grouping onu-v-enet-config-data {
      description
        "Config data intended for the ONU-vENET interface.
This data is brought to the Optical Network Unit (ONU) physical
device, when present, for instance using ONU Management and
Control Interface (OMCI) on the Management G-PON Encapsulation
Method (GEM) port.";
      leaf ani {
        type if:interface-ref;
        must
          "derived-from-or-self(/if:interfaces/if:interface[if:name = current()]/if:type,'bbf-xponift:ani')" {
          error-message
            "The referenced interface is not of type or derived from type 'bbf-xponift:ani'.";
          description
            "The referenced interface must be of or derived from type
'bbf-xponift:ani'.";
        }
        mandatory true;
        description
          "References the Access Network Interface (ANI) which is the
lower-layer interface under the ONU-vENET.";
      }
    }  // grouping onu-v-enet-config-data

    grouping onu-v-vrefpoint-config-data {
      description
        "Config data intended for the ONU-vVREFPOINT interface,
(sometimes also called 'virtual User Network Interface (UNI)').
This data is brought to the Optical Network Unit (ONU) physical
device, when present, for instance using ONU Management and
Control Interface (OMCI) on the Management G-PON Encapsulation
Method (GEM) port.";
      leaf related-onu {
        type if:interface-ref;
        must
          "derived-from-or-self(/if:interfaces/if:interface[if:name = current()]/if:type,'bbf-xponift:ani')" {
          error-message
            "The referenced interface is not of type or derived from type 'bbf-xponift:ani'.";
          description
            "The referenced interface must be of or derived from type
'bbf-xponift:ani'.";
        }
        mandatory true;
        description
          "References the Optical Network Unit (ONU) to which the
virtual User Network Interface (UNI) relates.";
      }
    }  // grouping onu-v-vrefpoint-config-data

    // objects
    augment /if:interfaces/if:interface {
      when
        "derived-from-or-self(if:type, 'bbf-xponift:ani')";
      description
        "Augment interface configuration with xPON Access Newtork
Interface (ANI) configuration.
The ANI represents the Optical Network Unit (ONU) device.";
      container ani {
        description "ANI configuration.";
      }  // container ani
    }

    augment /if:interfaces/if:interface {
      when
        "derived-from-or-self(if:type, 'bbf-xponift:onu-v-enet')";
      description
        "Augment interface configuration with xPON Optical Network Unit
(ONU) virtual ENET interface configuration.";
      container onu-v-enet {
        description
          "ONU virtual ENET configuration.";
      }  // container onu-v-enet
    }

    augment /if:interfaces/if:interface {
      when
        "derived-from-or-self(if:type,'bbf-xponift:onu-v-vrefpoint')";
      description
        "Augment interface configuration with xPON virtual V reference
point interface per TR-167 (sometimes also called 'virtual User
Network Interface (UNI)').";
      container onu-v-vrefpoint {
        description
          "Virtual User Network Interface (UNI) configuration.";
      }  // container onu-v-vrefpoint
    }

    augment /if:interfaces-state/if:interface {
      when
        "derived-from-or-self(if:type, 'bbf-xponift:ani')";
      description
        "Augment interface state data with xPON Access Network Interface
(ANI) state data.
The ANI represents the Optical Network Unit (ONU) device.";
      container ani {
        config false;
        description
          "State data for ANI interface.";
      }  // container ani
    }

    augment /if:interfaces/if:interface/bbf-xponani:ani {
      description
        "Configuration of an xPON Access Network Interface (ANI),
i.e., an Optical Network Unit (ONU) device.";
      uses ani-config-data;
    }

    augment /if:interfaces-state/if:interface/bbf-xponani:ani {
      description
        "State data of an xPON Access Network Interface (ANI),
i.e., an Optical Network Unit (ONU) device.";
      uses ani-state-data;
    }

    augment /if:interfaces/if:interface/bbf-xponani:onu-v-enet {
      description
        "Configuration of an xPON Optical Network Unit (ONU) virtual
Ethernet (ENET) interface.";
      uses onu-v-enet-config-data;
    }

    augment /if:interfaces/if:interface/bbf-xponani:onu-v-vrefpoint {
      description
        "Configuration of an xPON Optical Network Unit (ONU) virtual V
reference point interface per TR-167 (sometimes also called
'virtual User Network Interface (UNI)').";
      reference
        "TR-167";

      uses onu-v-vrefpoint-config-data;
    }
  }  // module bbf-xponani