Tibit YANG Examples

Copyright (c) 2020-2024, Ciena Corporation                              #
  All rights reserved.

This document provides information for running the Tibit YANG Examples
with the Tibit Netconf Server.

See the following additional documents for more information on the Tibit Netconf Server:
 * Tibit Tech Note TN037 Tibit NETCONF/YANG User Guide & Release Notes.


Overview
--------
The Tibit YANG Examples are a collection of Python scripts for select use cases
to demonstrate managing OLTs and ONUs using the Tibit YANG models. The ncclient
Python library is used to send and receive Netconf requests in these examples.

Examples for the following use cases are provided with the Tibit YANG Examples:
 * add_ctag_service/
     edit_config_add_ctag_svc.py      - Configure an Add CTag Service for an ONU.
     edit_config_disable_svc.py       - Disable Service for an ONU.
 * firmware_upgrade/
     get_onu_firmware.py              - Get ONU Firmware Information.
     edit_config_onu_firmware.py      - Configure Firmware Upgrade for an ONU.
     edit_config_activate_firmware.py - Configure Activate Firmware for an ONU.
     edit_config_disable_firmware_upgrade.py - Disable Firmware Upgrade for an ONU.
 * get_onu_optical_levels.py          - Get optical levels for an ONU.
 * get_onu_registration_status.py     - Get the registration status for ONUs.
 * get_onu_stats.py                   - Get statistics for an ONU.

Details on the the examples are provided in the sections below.


Prerequisites
-------------
Install the ncclient and other Python dependencies using pip3. A Python virtual
environment is recommended for running the examples. Alternatively, the
requirements.txt dependencies can be installed directly into local user or
system libraries using: pip3 install -r requirements.txt.

Use the following steps to run the examples from a Python virtual environment.

1. Create and activate the virtual environment.

    $ python3 -m venv ./venv
    $ source ./venv/bin/activate

2. Upgrade pip and install Python dependencies.

    $ pip3 install --upgrade pip
    $ pip3 install -r ./requirements.txt

3. Run Tibit YANG examples.

4. Exit out of the Python virtual environment after running the examples

    $ deactivate


edit_config_add_ctag_svc.py
---------------------------

NAME
    edit_config_add_ctag_svc - Configure an Add CTag Service for an ONU.

DESCRIPTION
    This Tibit YANG Example script configures an "Add CTag Service" for an ONU,
    where the OLT adds an outer CTag and the ONU adds an inner CTag. This example
    also configures SLA and DHCP Relay Option 82 for the ONU.

    Example - Configure ONU ALPHe30cadcf with outer tag 200 and inner tag 25:

    ./add_ctag_service/edit_config_add_ctag_svc.py \
        --olt 70:b3:d5:52:37:24 \
        --onu ALPHe30cadcf \
        --olt_tag 200 \
        --onu_tag 25 \
        --sla Max \
        --opt82-circuit-id "tibit pon 1/0/1:vlan200.25" \
        --opt82-remote-id "ALPHe30cadcf"


    usage: edit_config_add_ctag_svc.py [--help] [-h HOST] --olt OLT
                                       [--olt_tag OLT_TAG] --onu ONU --onu_tag
                                       ONU_TAG [--option_82 OPTION_82]
                                       [--opt82-circuit-id CIRCUIT_ID]
                                       [--opt82-remote-id REMOTE_ID] [-w PASSWD]
                                       [-p PORT] --sla SLA [-u USER] [-v]

    optional arguments:
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --olt OLT             OLT MAC Address (e.g., 70:b3:d5:52:37:24) (default:
                            None)
      --olt_tag OLT_TAG     Tag to be added by the OLT (default: 0)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      --onu_tag ONU_TAG     Tag to be added by the ONU (default: None)
      --option_82 OPTION_82
                            Option 82 Value (hex string) (default: None)
      --opt82-circuit-id CIRCUIT_ID
                            DHCP Relay Option 82, Circuit ID (default: )
      --opt82-remote-id REMOTE_ID
                            DHCP Relay Option 82, Remote ID (default: )
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      --sla SLA             SLA (default: None)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FUNCTIONS
    get_alloc_id_from_serial_number(nc, serial_number, options)
        Get the configured Alloc ID value for an ONU by serial number.

        Note, this routine assumes only one Alloc ID is configured for each ONU. As a result,
        only the first Alloc ID value is returned.

        Args:
            nc: Netconf driver object.
            serial_number: ONU Vendor-specific serial number
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            alloc_id: The Alloc ID configured for this ONU or 'None'.

    get_alloc_ids(nc, options)
        Get a dictionary of Alloc ID values per ONU configured in ONU Inventory for an OLT.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            alloc_ids: A dictionary of a list Alloc IDs for each ONU configured in ONU inventory

    get_next_alloc_id(nc, options)
        Get the next free Alloc ID that has _not_ been configured in the ONU Inventory.

        If the list of empty, return the first valid Alloc ID value '1154'. Otherwise find the first
        unused value starting from from 1154 to 1534.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            next_alloc_id: The next available Alloc ID value or 'None'.

    get_next_nni_network_id(nc, options)
        Get the next free NNI Network index (id) that has _not_ been configured in the NNI Inventory.

        If the list of empty, return the first valid index value = '0'. Otherwise, find the first
        unused value starting from from '0'.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            next_nni_network_id: The next available NNI Network index (id) value or 'None'.

    get_next_onu_id(nc, options)
        Get the next free ONU ID that has _not_ been configured in the ONU Inventory.

        If the list of empty, return the first valid ONU ID value '1'. Otherwise find the first
        unused value starting from from 1 to 128.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            next_onu_id: The next available ONU ID value or 'None'.

    get_nni_network_id_from_tags(nc, tags, options)
        Get the next free NNI Network index (id) value for the specified VLAN tags.

        Args:
            nc: Netconf driver object.
            tags: VLAN tags with the format 'sX.cY.cZ'
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            nni_network_id: The NNI Network index (id) value for the specified VLAN tags or 'None'.

    get_nni_networks(nc, options)
        Get a list of NNI Networks configured in NNI Inventory for an OLT.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            nni_networks: A dictionary of a list Alloc IDs for each ONU configured in ONU inventory

    get_onu_id_from_serial_number(nc, serial_number, options)
        Get the configured ONU ID value for an ONU by serial number.

        Args:
            nc: Netconf driver object.
            serial_number: ONU Vendor-specific serial number
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            onu_id: The ONU ID configured for this ONU or 'None'.

    get_onu_ids(nc, options)
        Get a dictionary of ONU ID values configured in ONU Inventory for an OLT.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            onu_ids: A dictionary mapping ONU serial number to ONU ID configured in ONU inventory

FILE
    add_ctag_service/edit_config_add_ctag_svc.py


edit_config_disable_svc.py
---------------------------

NAME
    edit_config_disable_svc - Disable Service for an ONU.

DESCRIPTION
    This Tibit YANG Example script disables service for an ONU. The script also
    provides an option to delete the ONU configuration from the database.

    Example:

        ./add_ctag_service/edit_config_disable_svc.py \
          --olt 70:b3:d5:52:37:24 \
          --onu ALPHe30cadcf \
          --olt_tag 200 \
          --onu_tag 25


    usage: edit_config_disable_svc.py [--delete] [--help] [-h HOST] --olt OLT
                                      [--olt_tag OLT_TAG] --onu ONU --onu_tag
                                      ONU_TAG [--option_82 OPTION_82] [-w PASSWD]
                                      [-p PORT] [-u USER] [-v]

    optional arguments:
      --delete              Deletes the ONU configuration from the database.
                            (default: False)
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --olt OLT             OLT MAC Address (e.g., 70:b3:d5:52:37:24) (default:
                            None)
      --olt_tag OLT_TAG     Tag to be added by the OLT (default: 0)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      --onu_tag ONU_TAG     Tag to be added by the ONU (default: None)
      --option_82 OPTION_82
                            Option 82 Value (hex string) (default: None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FILE
    add_ctag_service/edit_config_disable_svc.py


edit_config_onu_firmware.py
---------------------------

NAME
    edit_config_onu_firmware - Configure Firmware Upgrade for an ONU.

DESCRIPTION
    This Tibit YANG Example script configures firmware upgrade for an ONU. The script
    provides examples for configuring firmware images for an ONU.

    Example - Configure the firmware image (filename + version string) in bank 1:

    ./firmware_upgrade/edit_config_onu_firmware.py \
        --onu ALPHe30cadcf \
        --upgrade-bank 1 \
        --upgrade-file FW-GPON-ALPH-34000-5025_007_SFU24.bin \
        --upgrade-version 5025_007_SFU24

    usage: edit_config_onu_firmware.py [--help]
                                       [-h HOST] --onu ONU [-w PASSWD] [-p PORT]
                                       [--upgrade-bank UPGRADE_BANK]
                                       [--upgrade-file UPGRADE_FILE]
                                       [--upgrade-version UPGRADE_VERSION]
                                       [-u USER] [-v]

    optional arguments:
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      --upgrade-bank UPGRADE_BANK
                            Specify the bank for that the --upgrade-version and
                            --upgrade-file options apply to. (default: None)
      --upgrade-file UPGRADE_FILE
                            Firmware filename to set for the specified bank.
                            (default: None)
      --upgrade-version UPGRADE_VERSION
                            Firmware version to set for the specified bank.
                            (default: None)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FUNCTIONS
    get_fw_upgrade_config(nc, options)
        Get the firmware upgrade configuration for an ONU.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            firmware_upgrade_config: Dictionary containing the firmware upgrade information for the ONU.

    get_fw_upgrade_state(nc, options)
        Get the firmware upgrade state for an ONU.

        Args:
            nc: Netconf driver object.
            options: Netconf request options ({{VAR}}=value) dictionary.

        Returns:
            firmware_upgrade_state: Dictionary containing the firmware upgrade information for the ONU.

FILE
    firmware_upgrade/edit_config_onu_firmware.py


edit_config_activate_firmware.py
--------------------------------

NAME
    edit_config_activate_firmware - Configure Firmware Upgrade for an ONU.

DESCRIPTION
    This Tibit YANG Example script configures firmware upgrade for an ONU. The script
    provides examples for activating a specific version of firmware.

    Example - Activate the firmware in bank 1:

      ./firmware_upgrade/edit_config_onu_firmware.py --onu ALPHe30cadcf --activate-bank 1


    usage: edit_config_onu_firmware.py [--activate-bank ACTIVATE_BANK] [--help]
                                       [-h HOST] --onu ONU [-w PASSWD] [-p PORT]
                                       [-u USER] [-v]

    optional arguments:
      --activate-bank ACTIVATE_BANK
                            Activate the firmware in the specified bank. (default:
                            None)
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FILE
    firmware_upgrade/edit_config_activate_firmware.py


edit_config_disable_firmware_upgrade.py
---------------------------------------

NAME
    edit_config_disable_firmware_upgrade - Configure Firmware Upgrade for an ONU.

DESCRIPTION
    This Tibit YANG Example script configures firmware upgrade for an ONU. The script
    provides an example for disabling firmware upgrade for an ONU.

    Example - Disable firmware upgrade for the ONU:

      ./firmware_upgrade/edit_config_disable_firmware_upgrade.py --onu ALPHe30cadcf


    usage: edit_config_onu_firmware.py [--activate-bank ACTIVATE_BANK] [--help]
                                       [-h HOST] --onu ONU [-w PASSWD] [-p PORT]
                                       [-u USER] [-v]

    optional arguments:
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FILE
    firmware_upgrade/edit_config_disable_firmware_upgrade.py


get_onu_optical_levels.py
-------------------------

NAME
    get_onu_optical_levels - Get optical levels for an ONU.

DESCRIPTION
    This Tibit YANG Example script retrieves optical levels for an ONU.

    Example:

      ./get_onu_optical_levels.py --onu ALPHe30cadcf


    usage: get_onu_optical_levels.py [--help] [-h HOST] --onu ONU [-w PASSWD]
                                     [-p PORT] [-u USER] [-v]

    optional arguments:
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FILE
    get_onu_optical_levels.py


get_onu_registration_status.py
------------------------------

NAME
    get_onu_registration_status - Get the registration status for ONUs.

DESCRIPTION
    This Tibit YANG Example script retrieves ONU registration status for an OLT.

    Example - Get the ONU registration status for an OLT:

      ./get_onu_registration_status.py --olt 70:b3:d5:52:37:24

    Example - Get ONUs with registration state 'disallowed-admin' for an OLT:

      ./get_onu_registration_status.py --olt 70:b3:d5:52:37:24 --filter disallowed-admin


    usage: get_onu_registration_status.py [-f FILTER] [--help] [-h HOST] --olt OLT
                                          [-w PASSWD] [-p PORT] [-u USER] [-v]

    optional arguments:
      -f FILTER, --filter FILTER
                            Filter by ONU state (e.g., deregistered, disabled,
                            disallowed-admin, disallowed-error, dying-gasp,
                            registered, unprovisioned, unspecified) (default:
                            None)
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --olt OLT             OLT MAC Address (e.g., 70:b3:d5:52:37:24) (default:
                            None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FILE
    get_onu_registration_status.py


get_onu_stats.py
----------------

NAME
    get_onu_stats - Get statistics for an ONU.

DESCRIPTION
    This Tibit YANG Example script retrieves statistics for an ONU. This example provides the option
    of retrieving historic ONU statistics for the last 15-minute time slot or
    retrieving the current ONU statistics being accumulated for the next 15-minute
    slot.

    Example:

      ./get_onu_stats.py --onu ALPHe30cadcf


    usage: get_onu_stats.py [--help] [-h HOST] --onu ONU [-w PASSWD] [-p PORT]
                            [-u USER] [-v]

    optional arguments:
      --help                Show this help message and exit.
      -h HOST, --host HOST  NETCONF Server IP address or hostname. (default:
                            127.0.0.1)
      --onu ONU             ONU Serial Number (e.g., TBITc84c00df) (default: None)
      -w PASSWD, --passwd PASSWD
                            Password. If no password is provided, the user will be
                            prompted to enter. (default: None)
      -p PORT, --port PORT  NETCONF Server port number. (default: 830)
      -u USER, --user USER  Username. (default: None)
      -v, --verbose         Verbose output. (default: False)

FUNCTIONS
    print_olt_service_port_stats(stats)
        Print statistics for an OLT Service Port or an ONU Managemnet Channel (OMCC).

        Args:
            stats: OLT Service Port or OMCC statistics objects

FILE
    get_onu_stats.py
