module bbf-xpon-onu-state {

    yang-version 1.1;

    namespace
      "urn:bbf:yang:bbf-xpon-onu-state";

    prefix bbf-xpon-onu-s;

    import ietf-interfaces {
      prefix if;
    }
    import ietf-yang-types {
      prefix yang;
    }
    import bbf-xpon-types {
      prefix bbf-xpon-types;
    }
    import bbf-xpon-onu-types {
      prefix bbf-xpon-onu-types;
    }
    import bbf-xpon {
      prefix bbf-xpon;
    }

    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 state data and notifications
     related to each 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>";

    }


    feature notify-previous-onu-presence-state {
      description
        "Indicates support for providing the previous
       Optical Network Unit (ONU) presence state in
       in the 'onu-presence-state-change' notification.";
    }

    grouping onu-state-data {
      description
        "Information about an Optical Network Unit (ONU).";
      leaf onu-presence-state {
        type identityref {
          base bbf-xpon-onu-types:onu-presence-state-base;
        }
        mandatory true;
        description
          "State information related to the presence of the Optical
         Network Unit (ONU). The most specific applicable identity
         should be reported.";
      }

      leaf onu-id {
        type bbf-xpon-types:onu-id;
        description
          "This is the ITU-T TC layer ONU-ID identifier which the
         Optical Network Unit (ONU) is currently using on the channel
         group.";
        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 detected-registration-id {
        type bbf-xpon-types:onu-registration-id;
        description
          "The registration ID value which the Optical Line Termination
         (OLT) has received from the Optical Network Unit (ONU). This
         leaf is not present if the ONU has not provided any
         registration ID to the OLT. Registration ID may be useful in
         identifying a particular ONU installed at a particular
         location. Each octet is represented as 2 hexadecimal
         characters, therefore the leaf must contain an even number of
         characters. For ITU-T G.984.3, the leaf can only be up to
         20 octets long (refer to 'password'), for ITU-T G.987.3,
         ITU-T G.9807.1, ITU-T G.989.3 and ITU-G G.9804.2,
         the leaf can be up to 72 octets long.";
        reference
          "ITU-T G.984.3 Clause 9.2.4.2;
          ITU-T G.987.3 Clause 11.3.4.2;
          ITU-T G.9807.1 Clause C.11.3.4.2;
          ITU-T G.989.3 Clause 11.3.4.2;
          ITU-T G.9804.2 Clause 11.3.4.2";

      }

      leaf v-ani-ref {
        type if:interface-ref;
        description
          "The virtual Access Network Interface (vANI) corresponding to
         this Optical Network Unit (ONU) when configured on this
         Optical Line Termination (OLT). This leaf is not present if
         no vANI is corresponding to the ONU in the OLT.";
      }
    }  // grouping onu-state-data

    grouping onus-present-on-local-channel-termination {
      description
        "State data of all Optical Network Units (ONU) present on a
       given channel termination local to this Optical Line
       Termination (OLT).";
      container onus-present-on-local-channel-termination {
        description
          "State data of all Optical Network Units (ONU) present on a
         given channel termination local to this Optical Line
         Termination (OLT) (Refer to 'inside-olt'). Even the ONUs for
         which no corresponding virtual Access Network Interface
         (vANI) is configured in the OLT are accounted.

         An ONU is considered present on a channel termination when it
         is using the optical signal of this channel termination i.e.
         as early as the channel termination receives from the ONU a
         Physical Layer Operations, Administrations and Maintenance
         (PLOAM) Serial_Number_ONU message or as early as it receives
         a PLOAM Tuning_Resp(Complete_u) message and as long as the
         channel termination is not in LOBi state for this ONU (i.e in
         practice the ONU keeps responding to downstream OLT bandwidth
         map messages).";
        list onu {
          key "detected-serial-number";
          description
            "The list of all Optical Network Units (ONU) present on the
           channel termination.";
          leaf detected-serial-number {
            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";

          }

          uses onu-state-data;

          leaf onu-detected-datetime {
            type yang:date-and-time;
            mandatory true;
            description
              "The Optical Line Termination (OLT) system date and time
             when the Optical Network Unit (ONU) was detected present
             on the channel termination.";
          }

          leaf onu-state-last-change {
            type yang:date-and-time;
            mandatory true;
            description
              "The Optical Line Termination (OLT) system date and time
             when the 'onu-state' YANG leaf got its current value.";
          }
        }  // list onu
      }  // container onus-present-on-local-channel-termination
    }  // grouping onus-present-on-local-channel-termination

    augment /if:interfaces/if:interface/bbf-xpon:channel-termination {
      description
        "Augment the channel termination configuration with
       configuration associated with the presence of Optical Network
       Units (ONU).";
      leaf-list notifiable-onu-presence-states {
        type identityref {
          base bbf-xpon-onu-types:onu-presence-state-base;
        }
        description
          "The Optical Line Termination (OLT) is expected to generate a
         'onu-presence-state-change' notification each time any
         Optical Network Unit (ONU) transitions in any of the presence
         states listed in the leaf-list. If
         'notifiable-onu-presence-states' includes an identity which
         is the base value for other presence state(s) identity(ies),
         the OLT will generate a single notification if it detects
         that an ONU undergoes a transition into the configured
         presence state, directly or indirectly via one of its derived
         presence states.

         For example, if 'notifiable-onu-presence-states' list
         includes the identity
         'onu-present-and-v-ani-known-and-o5-failed' and the OLT
         detects that an ONU undergoes a transition into
         'onu-present-and-v-ani-known-and-o5-failed-no-onu-id',
         the OLT will generate a single notification reporting
         the ONU transition into
         'onu-present-and-v-ani-known-and-o5-failed-no-onu-id'.

         In case the leaf-list is empty (as by default) the OLT
         should not generate any 'onu-presence-state-change'
         notification.";
      }
    }

    augment /if:interfaces-state/if:interface/bbf-xpon:channel-termination {
      when
        "derived-from-or-self"
          + "(/if:interfaces/if:interface[if:name=current()/../if:name]"
          + "/bbf-xpon:channel-termination/bbf-xpon:location, "
          + "'bbf-xpon-types:inside-olt')";
      description
        "State data associated with the presence of all Optical Network
       Units (ONU) on a given channel termination local to this
       Optical Line Termination (OLT) (Refer to 'inside-olt'). Even
       the ONUs for which no corresponding virtual Access Network
       Interface (vANI) is configured in the OLT are reported.

       An ONU is considered present on a channel termination when it
       is using the optical signal of this channel termination i.e.,
       as early as the channel termination receives from the ONU a
       Physical Layer Operations, Administrations and Maintenance
       (PLOAM) Serial_Number_ONU message or as early as it receives a
       PLOAM Tuning_Resp(Complete_u) message and as long as the
       channel termination is not in LOBi state for this ONU (i.e in
       practice the ONU keeps responding to downstream OLT bandwidth
       map messages).";
      uses onus-present-on-local-channel-termination;

      notification onu-presence-state-change {
        description
          "A notification traceable to a channel termination which
         signifies that an Optical Network Unit (ONU) has transitioned
         into the indicated presence state. This notification
         considers not only Optical Network Units (ONUs) for which a
         corresponding virtual Access Network Interface (vANI) is
         configured in the Optical Line Termination (OLT) but also
         ONUs for which no corresponding vANI is configured in the
         OLT. Such notifications are to be generated only when an ONU
         enters one of the presence states listed in
         'notifiable-onu-presence-states' leaf-list.";
        leaf detected-serial-number {
          type bbf-xpon-types:onu-serial-number;
          mandatory true;
          description
            "The serial number of the Optical Network Unit (ONU)
           entering the new state.";
          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 C.11.2.6.2;
            ITU-T G.9807.1 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 last-change {
          type yang:date-and-time;
          mandatory true;
          description
            "The Optical Line Termination (OLT) system date and time
           when the Optical Network Unit (ONU) has transitioned into
           the indicated presence state.";
        }

        uses onu-state-data;

        leaf previous-onu-presence-state {
          if-feature bbf-xpon-onu-s:notify-previous-onu-presence-state;
          type identityref {
            base bbf-xpon-onu-types:onu-presence-state-base;
          }
          mandatory true;
          description
            "The previous presence state of the Optical Network Unit
           (ONU) after a presence state change. The most specific
           applicable identity should be reported.";
        }
      }  // notification onu-presence-state-change
    }
  }  // module bbf-xpon-onu-state