onumock

README

PON & ONU Hardware Mock

The PON & ONU hardware mock provides a simulation of an entire PON containing multiple ONUs in order to test scalability of the VOLTHA OpenOMCI protocol library, ONU device adapters, as well as any associated OLT device adapters. In addition to being able to test out OpenOMCI, the ONU Mock could also be used to test other implementations such as improvements to an existing VOLTHA OLT device adapter or even a traditional fixed-OLT implementations.

This mock is not for testing the dataplane (passing user data), but primarily for provisioning and scalability issues with existing software with initial focus on MIB upload/download, high-speed Internet service establishment, and 15-minute/historical PM simulation. Some work is expected to be performed in the near future to allow Rx & Tx of subscriber traffic to allow for integration of the mock into authentication workflows.

The initial release will probably not support a NBI to allow for create/delete/enable/disable of additional ONUs on a PON, due to time constraints. Instead, the initial release will allow for a configuration input file & CLI options to allow for a variety of patterns of ONU creation and startup times.

See Future Requirements for a list of a few future requirements/enhancements to the ONU Mock.

NOTE: This application is currently in development. A usable version is expected to be released in late Fall of 2019. Most likely this may be on or after late December 2019.

Current Feature Set

Below is a list of currently supported High-Level Requirements and Features

• Support OMCI Rx/Tx from a single OLT Device Adapter

• Support OMCI PLOAM Discovery/Activation

• Simulate up to 64 ONUs on a PON

• Simulate multiple PONs (initial goal is 16 PONs per OLT)

• Simulate multiple vendors ONU hardware devices (initial goal is a single ANI and a multiple UNI ports per ONU device based on the vendor ONU capabilities)

  • Currently support mock of Alpha, and T&W XGS ONUs
  • A 'Default' onu (vender code DFLT) will be created with several 'models' that support different numbers of UNI ports and various traffic models and optional OMCI support.

• Support the following OMCI features & state-machines/operations:

  • OMCI Communications Channel support
  • MIB Reset handling (canned MIB defaults on a per ONU basis)
  • MIB Synchronization
  • OMCI Capabilities (OMCI ME)
  • Time Synchronization and 15-minute interval support (minimal stats update)

Design

The ONU Mock is written in Go and consists of a primary MOCK service that provides an interface to a single OLT as a pair of gRPC channels for PLOAM and OMCI messaging.

The ONU Mock service controls the lifetime of the MOCK and based on configuration/startup options, it will enter into either a disabled state or enabled state after a user specified period of time. This delay allows for background creation of any PONs so that upon initial connection from the virtualized OLT (via gRPC) it is ready to begin simulation.

The service will run for a user specified period of time and will add ONU(s) to the PON(s) as specified in the startup configuration. When the ONUs are added, and the PON is enabled, the ONUs can be discovered by the OLT via a Discovery Request. After discovery, the OLT can activate the ONU and begin OMCI operations. In the case of VOLTHA, OMCI is carried out by the appropriate ONU device adapter.

Internally, the PON and ONU objects are controlled by a state machine and each PON or ONU object runs in its own go-routine context. Additionally within the ONU, there are additional state machines for various OMCI functionality and these state machines run in the context of the ONU go-routine.

When provisioning an ONU with OMCI, the ONU may create specific structs with timers associated with them to provide appropriate functionality (status updates, PM increments, ...).

Operational Information

TODO: Brief intro on section

Mock YAML Configuration Files

Operation of the initial ONU-Mock PON/ONU startup can be automated with a YAML configuration file. In addition, Vendor ONU data models are also supported through model (and software version) specific YAML files.

Configuration order of precedence

The configuration of a test run is performed by first applying the default configuration, then updating it with any changes/additions from the configuration YAML file, and then finally applying any command line options.

One exception to this order is that a command line option specifying the location and name of the configuration YAML file is applied if present before opening the configuration file.

ONU Mock YAML Configuration

The ONU Mock YAML Configuration file specifies the test settings for a specific run of of the ONU MOCK application. The Default Configuration is a default configuration file for the application that provides the default settings the application runs with should no configuration file or command line options be provided.

Another Configuration is a configuration file that demonstrates a more complex configuration.

ONU Vendor Model YAML Configuration

ONU Vendor Model configuration files, located in the vendor_info subdirectory provide initial vendor and model information for ONUs that can be mocked by this program. Initially only a single model and firmware version per vendor is supported.

Command Line Options

When an ONU-Mock is launched, a limited number of application configuration options can be overwritten via CLI options.

Option	Parameter	Notes
-config	string	Configuration file. Default: './default.yaml' (default "./default.yaml")
-cpus	uint	Maximum CPUs to use (0..max), Default: system max of 8
-delay	uint	AutoStart delay (0..3600), Default: 0
-grpc	string	gRPC port, '' to disable, Default: 50051 (default "50051")
-no-autostart		Disable AutoStart (true/false), Default: false
-onus	uint	Maximum ONUs allowed on a single PON (1..256), default: 128 (default 128)
-pons	uint	Number of PONs (1..48), Default: 1 (default 1)
-rest	int	RESTConf port, 0 to disable, Default: 55055 (default 55055)

Northbound Interfaces

The ONU-MOCK Northbound Interfaces (NBIs) provide for integrating the ONU-Mock into existing OLT hardware (or virtualized hardware) as well as for runtime control of the application.

NOTE: This is currently under development. Only the OLT NBI interface is expected to be supported in the initial release.

OLT NBI Interface

TODO: Brief description (ploam/omci-msgs)

Protobuf / gRPC OLT SBI Interface

The communications between the ONU Mock and the OLT is implemented as a pair of gRPC stream interfaces defined in the omci.proto protobuf definition.

The OMCI Channel

The OmciChannel is used to send/receive OMCI Requests/Responses. The ONU Mock will also use this channel for autonomous ONU notifications.

rpc OmciChannel(stream OmciRequest) returns (stream OmciResponse) {}

The OmciRequest is defined by the following message:

message OmciRequest {
    // TODO: Move timestamps into metadata if possible (and wise)
    int64 utc_timestamp = 1;            // UTC seconds since epoch, set by OLT
    int64 utc_arrival_timestamp = 2;    // Filled out by ONU mock on arrival
    uint32 pon_id = 3;
    uint32 onu_id = 4;
    bytes payload = 5;
}

The OmciResponse is defined by the following message

message OmciResponse {
     // TODO: Move timestamps into metadata if possible (and wise)
     int64 utc_request_timestamp = 1;    // Copied from Request
     int64 utc_arrival_timestamp = 2;    // Copied from Request
     int64 utc_response_timestamp = 3;   // Earliest time response should be returned
 
     uint32 pon_id = 4;
     uint32 onu_id = 5;
     bytes payload = 6;
 }

The PLOAM Channel

The PloamChannel is used to send PLOAM messages from the OLT to the ONU Mock. Only the Discovery request returns a response.

rpc PloamChannel(stream PloamRequest) returns (stream PloamDiscoveryResponse) {}

message PloamRequest {
    uint32 pon_id = 1;
    uint32 onu_id = 2;
    enum OperationType {
        DISCOVERY = 0;      // Send serial number if in Discovery state
        ACTIVATE = 1;       // Transition ONU to operational if in Discovery state
        TX_STATUS = 2;      // Inform ONU that OLT PON Tx is on or off
    }
    OperationType operation = 3;
    string serial_number = 4;   // ASCII (Not base64 encoded) used if ACTIVATE
    bool tx_los = 5;            // No PON Tx if true, used if TX_STATUS
}

message OnuDiscoveryInfo {
    string serial_number = 1;   // ASCII (Not base64 encoded)
    uint32 distance = 2;        // ONU Distance in meters
}

// Response to a Discovery request on a PON. No response is returned if there
// are not ONUs in a discoverable state
message PloamDiscoveryResponse {
    uint32                    pon_id = 1;
    repeated OnuDiscoveryInfo onus = 2;
}

Application NBI Interface

TODO: Brief description (PON/ONU manipulation) NOTE: This is not an initial release requirement.

Protobuf / gRPC Interface

TODO: more concrete information here (or point to protobuf files) NOTE: This is not an initial release requirement.

REST Interface

TODO: Intro. If swagger supported, point the reader to where to browse NOTE: This is not an initial release requirement.

How to integrate ONU Mock into your environment

The primary target for the ONU Mock application is for integration into a virtualized version of an OLT firmware implementation. This allows any application that typically controls the firmware, whether it is ONF VOLTHA, BBWF OB_BBA, or a custom vendor PON controller to benefit the PON abstraction. However a virtualized (x86) OLT firmware implementation may not always be available. As work on non-virtualized firmware is first accomplished, more information will be provided.

Integrating ONU-Mock into an existing OLT hardware (or virtualized hardware)

TODO: Describe how to tie into an existing device adapter if they have virtualized support for their OLT.

Integrating ONU-Mock into an existing OLT VOLTHA device Adapter

As work on non-virtualized firmware is first accomplished, more information will be provided.

TODO: Can this be tied into BBSim as well? VOLTHA BBSim if it is possible.

Adding New ONU Vendor Configs

TODO: Add helpful tips on how to get some of the information needed to create an ONU Vendor model.

Original High Level Requirements

Testing

To initially test the ONU MOCK, an onumock-olt-test.go application is available in the utilities subdirectory that will perform several of the sequences expected to be requested from a VOLTHA ONU device adapter (OpenOMCI) or from an actual OLT that has its own OMCI stack. This OLT test is for demonstration and internal testing purposes only at this time as it allows for quick incremental additions of functionality.

Running the test

Start an implementation of the onu_mock application such as:

  onumock -config config/config.yaml -pons 1 -onus 1

This will start the MOCK and it will wait for a connection from an OLT. Then start the onumock-olt-test:

  onumock-olt-test

The OLT test should then run and perform some basic exercising of the ONU Mock application. See the README.md file in the utilities information for current support and pending tasks that remain for both the OLT test and portions of the ONU Mock that need to be written or exercised.

Documentation

Overview

* Copyright 2018 - present. Boling Consulting Solutions (bcsw.net) * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License.