Updating docs and releasing 1.0.0
Change-Id: Ife63de3f51be9f24f16e174a2319bd6d914abe13
diff --git a/docs/source/index.rst b/docs/source/index.rst
index cd0149b..1284fcd 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -7,16 +7,15 @@
============================
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
+ :hidden:
:caption: Contents:
+ bbsim_config.rst
+ sadis_config.rst
operations.rst
- onu-state-machine.rst
- olt-state-machine.rst
- development-dependencies.rst
- bbr.rst
- bbsimctl.rst
- api.rst
+ development/internals.rst
+ Performances <bbr.rst>
Quickstart
@@ -25,6 +24,9 @@
BBSim (a.k.a. BroadBand Simulator) is a tool designed to emulate an `Openolt
<https://github.com/opencord/openolt>`_ compatible device.
+BBSim emulates the OLT, PON Ports, ONUs, UNIs and RG.
+For more informations on how configure different Services on the RG refer to :ref:`ConfiguringServices`
+
In order to use BBSim you need to have:
- a Kubernetes cluster
@@ -58,10 +60,6 @@
BBSim can also be configured to automatically start Authentication or DHCP:
-.. code:: bash
-
- helm install -n bbsim cord/bbsim --set auth=true --set dhcp=true
-
Once BBSim is installed you can verify that it's running with:
.. code:: bash
@@ -82,276 +80,3 @@
.. code:: bash
voltctl device enable $(voltctl device list --filter Type~openolt -q)
-
-BBSim startup options
----------------------
-
-``BBSim`` supports a series of options that can be set at startup, you can see
-the list via ``./bbsim --help``
-
-.. code:: bash
-
- $ ./bbsim --help
- Usage of ./bbsim:
- -api_address string
- IP address:port (default ":50070")
- -auth
- Set this flag if you want authentication to start automatically
- -c_tag int
- C-Tag starting value, each ONU will get a sequential one (targeting 1024 ONUs per BBSim instance the range is big enough) (default 900)
- -c_tag_allocation string
- Use 'unique' for incremental values, 'shared' to use the same value in all the ONUs (default "unique")
- -ca string
- Set the mode for controlled activation of PON ports and ONUs (default "default")
- -cpuprofile string
- write cpu profile to file
- -delay int
- The delay between ONU DISCOVERY batches in milliseconds (1 ONU per each PON PORT at a time (default 200)
- -dhcp
- Set this flag if you want DHCP to start automatically
- -enableEvents
- Enable sending BBSim events on configured kafka server
- -enableperf
- Setting this flag will cause BBSim to not store data like traffic schedulers, flows of ONUs etc..
- -kafkaAddress string
- IP:Port for kafka (default ":9092")
- -logCaller
- Whether to print the caller filename or not
- -logLevel string
- Set the log level (trace, debug, info, warn, error) (default "debug")
- -nni int
- Number of NNI ports per OLT device to be emulated (default 1)
- -olt_id int
- OLT device ID
- -onu int
- Number of ONU devices per PON port to be emulated (default 1)
- -openolt_address string
- IP address:port (default ":50060")
- -pon int
- Number of PON ports per OLT device to be emulated (default 1)
- -rest_api_address string
- IP address:port (default ":50071")
- -s_tag int
- S-Tag initial value (default 900)
- -s_tag_allocation string
- Use 'unique' for incremental values, 'shared' to use the same value in all the ONUs (default "shared")
- -sadisFormat string
- Which format should sadis expose? [att|dt|tt] (default "att")
- -enableEvents
- Set this flag for publishing BBSim events on configured kafkaAddress
- -kafkaAddress string
- IP:Port for kafka, used only when bbsimEvents flag is set (default ":9092")
- -ca string
- Set the mode for controlled activation of PON ports and ONUs
- -enableperf bool
- Setting this flag will cause BBSim to not store data like traffic schedulers, flows of ONUs etc
- -kafkaEventTopic string
- Set the topic on which BBSim publishes events on kafka
- -igmp
- Set this flag to start IGMP automatically
- -dhcpRetry bool
- Set this flag if BBSim should retry DHCP upon failure until success
- -authRetry bool
- Set this flag if BBSim should retry EAPOL (Authentication) upon failure until success
-
-``BBSim`` also looks for a configuration file in ``configs/bbsim.yaml`` from
-which it reads a number of default settings. The command line options listed
-above override the corresponding configuration file settings. A sample
-configuration file is given below:
-
-.. literalinclude:: ../../configs/bbsim.yaml
-
-Specifying different tagging schemes
-------------------------------------
-
-BBSim supports two different tagging schemes:
-- ``-s_tag_allocation shared -c_tag_allocation unique``
-- ``-s_tag_allocation unique -c_tag_allocation shared``
-
-Where the former will use the same ``S-Tag`` for all the ONUs and a unique ``C-Tag`` for each of them
-and the latter will use a unique ``S-Tag`` for each ONU and the same ``C-Tag`` for all of them.
-
-For example:
-
-.. code:: bash
-
- # -s_tag_allocation shared -c_tag_allocation unique
- PONPORTID ID PORTNO SERIALNUMBER HWADDRESS STAG CTAG OPERSTATE INTERNALSTATE
- 0 0 0 BBSM00000001 2e:60:70:00:00:01 900 900 down created
- 1 0 0 BBSM00000101 2e:60:70:00:01:01 900 901 down created
- 2 0 0 BBSM00000201 2e:60:70:00:02:01 900 902 down created
- 3 0 0 BBSM00000301 2e:60:70:00:03:01 900 903 down created
-
-
- # -s_tag_allocation unique -c_tag_allocation shared
- PONPORTID ID PORTNO SERIALNUMBER HWADDRESS STAG CTAG OPERSTATE INTERNALSTATE
- 0 0 0 BBSM00000001 2e:60:70:00:00:01 900 7 down created
- 1 0 0 BBSM00000101 2e:60:70:00:01:01 901 7 down created
- 2 0 0 BBSM00000201 2e:60:70:00:02:01 902 7 down created
- 3 0 0 BBSM00000301 2e:60:70:00:03:01 903 7 down created
-
-
-
-Using the BBSim Sadis server in ONOS
-------------------------------------
-
-BBSim provides a simple server for testing with the ONOS Sadis app. The server
-listens on port 50074 by default and provides the endpoints
-``subscribers/<id>`` and ``bandwidthprofiles/<id>``.
-
-To configure ONOS to use the BBSim ``Sadis`` server endpoints, the Sadis app
-must use be configured as follows (see ``examples/sadis-in-bbsim.json``):
-
-.. literalinclude:: ../../examples/sadis-in-bbsim.json
-
-This base configuration may also be obtained directly from the BBSim Sadis
-server:
-
-.. code:: bash
-
- curl http://<BBSIM_IP>:50074/v2/cfg -o examples/sadis.json
-
-It can then be pushed to the Sadis app using the following command:
-
-.. code:: bash
-
- curl -sSL --user karaf:karaf \
- -X POST \
- -H Content-Type:application/json \
- http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis \
- --data @examples/sadis-in-bbsim.json
-
-You can verify the current Sadis configuration:
-
-.. code:: bash
-
- curl --user karaf:karaf http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis
-
-In ONOS subscriber information can be queried using ``sadis <id>``.
-
-*Note that BBSim supports both sadis configuration versions,
-if you need to support the configuration for release older than VOLTHA-2.3
-you can use the following command:*
-
-.. code:: bash
-
- curl http://<BBSIM_IP>:50074/v1/cfg -o examples/sadis.json
-
-Configure the Sadis format for different workflows
-**************************************************
-
-BBSim support different sadis formats, required for different workflows.
-The desired sadis format can be specified via the ``-sadisFormat`` flag.
-
-The difference in the format is restricted to the ``uniTagList`` property,
-for example:
-
-**ATT**
-
-.. code:: json
-
- {
- "id": "BBSM00000003-1",
- "nasPortId": "BBSM00000003-1",
- "circuitId": "BBSM00000003-1",
- "remoteId": "BBSM00000003-1",
- "uniTagList": [
- {
- "DownstreamBandwidthProfile": "User_Bandwidth1",
- "IsDhcpRequired": true,
- "IsIgmpRequired": true,
- "PonCTag": 903,
- "PonSTag": 900,
- "TechnologyProfileID": 64,
- "UpstreamBandwidthProfile": "Default"
- }
- ]
- }
-
-
-**DT**
-
-.. code:: json
-
- {
- "id": "BBSM00000003-1",
- "nasPortId": "BBSM00000003-1",
- "circuitId": "BBSM00000003-1",
- "remoteId": "BBSM00000003-1",
- "uniTagList": [
- {
- "DownstreamBandwidthProfile": "User_Bandwidth1",
- "PonCTag": 4096,
- "PonSTag": 903,
- "TechnologyProfileID": 64,
- "UniTagMatch": 4096,
- "UpstreamBandwidthProfile": "Default"
- }
- ]
- }
-
-
-**TT**
-
-*Coming soon...*
-
-Controlled PON and ONU activation
----------------------------------
-
-BBSim provides support for controlled PON and ONU activation. By default both
-PON ports and ONUs are automatically activated when OLT is enabled. This can
-be controlled using ``-ca`` option.
-
-``-ca`` can be set to one of below four modes:
-
-- default: PON ports and ONUs are automatic activated (default behavior).
-
-- only-onu: PON ports automatically enabled and ONUs dynamically activated
- On Enable OLT, IntfIndications for all PON ports are sent but ONU discovery indications are not sent.
- When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
-
-- only-pon: PON ports dynamically enabled and ONUs automatically activated
- On Enable OLT, neither IntfIndications for PON ports nor ONU discovery indications are sent.
- When EnablePonIf request is received at OpenOLT server, then that PON port is enabled and
- IntfIndication is sent for that PON and all ONUs under that ports are discovered automatically.
-
-- both: Both PON ports and ONUs are dynamically activated
- On Enable OLT, neither IntfIndication for PON ports nor ONU discovery indications are sent.
- When EnablePonIf request is received on OpenOLT server then
- IntfIndication is sent for that PON but no ONU discovery indication
- will be sent.
- When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
-
-
-Publishing BBSim Events on kafka
---------------------------------
-
-BBSim provides option for publishing events on kafka. To publish events on
-kafka, set BBSimEvents flag and configure kafkaAddress.
-
-Once BBSim is started, it will publish events (as and when they happen) on
-topic ``BBSim-OLT-<id>-Events``.
-
-Types of Events:
- - OLT-enable-received
- - OLT-disable-received
- - OLT-reboot-received
- - OLT-reenable-received
- - ONU-discovery-indication-sent
- - ONU-activate-indication-received
- - MIB-upload-received
- - MIB-upload-done
- - Flow-add-received
- - Flow-remove-received
- - ONU-authentication-done
- - ONU-DHCP-ACK-received
-
-Sample output of kafkacat consumer for BBSim with OLT-ID 4:
-
-.. code:: bash
-
- $ kafkacat -b localhost:9092 -t BBSim-OLT-4-Events -C
- {"EventType":"OLT-enable-received","OnuSerial":"","OltID":4,"IntfID":-1,"OnuID":-1,"EpochTime":1583152243144,"Timestamp":"2020-03-02 12:30:43.144449453"}
- {"EventType":"ONU-discovery-indication-sent","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":0,"EpochTime":1583152243227,"Timestamp":"2020-03-02 12:30:43.227183506"}
- {"EventType":"ONU-activate-indication-received","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":1,"EpochTime":1583152243248,"Timestamp":"2020-03-02 12:30:43.248225467"}
- {"EventType":"MIB-upload-received","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":1,"EpochTime":1583152243299,"Timestamp":"2020-03-02 12:30:43.299480183"}