blob: 8eec878f00f91509ddf762b479298334385754cb [file] [log] [blame]
Matteo Scandolo9f619492019-10-25 13:11:58 -07001.. BBSim documentation master file, created by
2 sphinx-quickstart on Fri Oct 25 12:03:42 2019.
3 You can adapt this file completely to your liking, but it should at least
4 contain the root `toctree` directive.
5
6Welcome to BBSim's documentation!
7=================================
8
9.. toctree::
10 :maxdepth: 2
11 :caption: Contents:
12
Matteo Scandoloe383d5d2019-10-25 14:47:27 -070013 operations.rst
Matteo Scandolo9f619492019-10-25 13:11:58 -070014 onu-state-machine.rst
Matteo Scandolod02b79b2019-12-05 16:42:13 -080015 olt-state-machine.rst
Matteo Scandolo9f619492019-10-25 13:11:58 -070016 development-dependencies.rst
17 bbr.rst
18 bbsimctl.rst
Zdravko Bozakov2da76342019-10-21 09:47:35 +020019 api.rst
Matteo Scandolo9f619492019-10-25 13:11:58 -070020
21
22Quickstart
23----------
24
Zack Williams4b0ef4d2019-12-18 14:25:20 -070025BBSim (a.k.a. BroadBand Simulator) is a tool designed to emulate an `Openolt
26<https://github.com/opencord/openolt>`_ compatible device.
Matteo Scandolo9f619492019-10-25 13:11:58 -070027
28In order to use BBSim you need to have:
29
30- a Kubernetes cluster
31- helm
32- a working installation of VOLTHA
33
Zack Williams4b0ef4d2019-12-18 14:25:20 -070034We strongly recommend the utilization of `kind-voltha
35<https://github.com/ciena/kind-voltha>`_ to setup such environment.
Matteo Scandolo9f619492019-10-25 13:11:58 -070036
37Installation
38------------
39
40Once VOLTHA is up and running, you can deploy BBSim with this command:
41
42.. code:: bash
43
44 helm install -n bbsim cord/bbsim
45
Matteo Scandoloc1147092019-10-29 09:38:33 -070046If you need to specify a custom image for BBSim you can:
47
48.. code:: bash
49
50 helm install -n bbsim cord/bbsim --set images.bbsim.repository=bbsim --set images.bbsim.tag=candidate --set images.bbsim.pullPolicy=Never
51
Zack Williams4b0ef4d2019-12-18 14:25:20 -070052The BBSim installation can be customized to emulate multiple ONUs and multiple
53PON Ports:
Matteo Scandolo9f619492019-10-25 13:11:58 -070054
55.. code:: bash
56
57 helm install -n bbsim cord/bbsim --set onu=8 --set pon=2
58
Matteo Scandoloc1147092019-10-29 09:38:33 -070059BBSim can also be configured to automatically start Authentication or DHCP:
60
61.. code:: bash
62
63 helm install -n bbsim cord/bbsim --set auth=true --set dhcp=true
64
Matteo Scandolo9f619492019-10-25 13:11:58 -070065Once BBSim is installed you can verify that it's running with:
66
67.. code:: bash
68
69 kubectl logs -n voltha -f $(kubectl get pods -n voltha | grep bbsim | awk '{print $1}')
70
71Provision a BBSim OLT in VOLTHA
72-------------------------------
73
74Create the device:
75
76.. code:: bash
77
78 voltctl device create -t openolt -H $(kubectl get -n voltha service/bbsim -o go-template='{{.spec.clusterIP}}'):50060
79
80Enable the device:
81
82.. code:: bash
83
84 voltctl device enable $(voltctl device list --filter Type~openolt -q)
Matteo Scandoloc1147092019-10-29 09:38:33 -070085
86BBSim startup options
87---------------------
88
Zack Williams4b0ef4d2019-12-18 14:25:20 -070089``BBSim`` supports a series of options that can be set at startup, you can see
90the list via ``./bbsim --help``
Matteo Scandoloc1147092019-10-29 09:38:33 -070091
92.. code:: bash
93
94 $ ./bbsim --help
95 Usage of ./bbsim:
96 -auth
97 Set this flag if you want authentication to start automatically
98 -c_tag int
99 C-Tag starting value, each ONU will get a sequential one (targeting 1024 ONUs per BBSim instance the range is big enough) (default 900)
100 -cpuprofile string
101 write cpu profile to file
Matteo Scandolocae57b52019-11-12 10:52:53 -0800102 -delay int
103 The delay between ONU DISCOVERY batches in milliseconds (1 ONU per each PON PORT at a time (default 200)
Matteo Scandoloc1147092019-10-29 09:38:33 -0700104 -dhcp
105 Set this flag if you want DHCP to start automatically
106 -logCaller
107 Whether to print the caller filename or not
108 -logLevel string
109 Set the log level (trace, debug, info, warn, error) (default "debug")
110 -nni int
111 Number of NNI ports per OLT device to be emulated (default 1)
112 -olt_id int
113 Number of OLT devices to be emulated
114 -onu int
115 Number of ONU devices per PON port to be emulated (default 1)
116 -pon int
117 Number of PON ports per OLT device to be emulated (default 1)
118 -s_tag int
119 S-Tag value (default 900)
Pragya Arya324337e2020-02-20 14:35:08 +0530120 -enableEvents
121 Set this flag for publishing BBSim events on configured kafkaAddress
122 -kafkaAddress string
123 IP:Port for kafka, used only when bbsimEvents flag is set (default ":9092")
Pragya Arya3f8fdc62020-03-16 11:12:27 +0530124 -ca string
125 Set the mode for controlled activation of PON ports and ONUs
126 -enableperf bool
127 Setting this flag will cause BBSim to not store data like traffic schedulers, flows of ONUs etc
Zdravko Bozakov3ddb2452019-11-29 14:33:41 +0100128
Zack Williams4b0ef4d2019-12-18 14:25:20 -0700129``BBSim`` also looks for a configuration file in ``configs/bbsim.yaml`` from
130which it reads a number of default settings. The command line options listed
131above override the corresponding configuration file settings. A sample
132configuration file is given below:
Zdravko Bozakov3ddb2452019-11-29 14:33:41 +0100133
134.. literalinclude:: ../../configs/bbsim.yaml
Zdravko Bozakov958d81c2019-12-13 22:09:48 +0100135
136Using the BBSim Sadis server in ONOS
137------------------------------------
138
Zack Williams4b0ef4d2019-12-18 14:25:20 -0700139BBSim provides a simple server for testing with the ONOS Sadis app. The server
140listens on port 50074 by default and provides the endpoints
141``subscribers/<id>`` and ``bandwidthprofiles/<id>``.
Zdravko Bozakov958d81c2019-12-13 22:09:48 +0100142
Zack Williams4b0ef4d2019-12-18 14:25:20 -0700143To configure ONOS to use the BBSim ``Sadis`` server endpoints, the Sadis app
144must use be configured as follows (see ``examples/sadis-in-bbsim.json``):
Zdravko Bozakov958d81c2019-12-13 22:09:48 +0100145
Matteo Scandolo9d08be52020-03-12 09:43:53 -0700146.. literalinclude:: ../../examples/sadis-in-bbsim2.json
Zdravko Bozakov958d81c2019-12-13 22:09:48 +0100147
Zack Williams4b0ef4d2019-12-18 14:25:20 -0700148This base configuration may also be obtained directly from the BBSim Sadis
149server:
Zdravko Bozakov958d81c2019-12-13 22:09:48 +0100150
151.. code:: bash
152
153 curl http://<BBSIM_IP>:50074/cfg -o examples/sadis.json
154
155It can then be pushed to the Sadis app using the following command:
156
157.. code:: bash
158
159 curl -sSL --user karaf:karaf \
160 -X POST \
161 -H Content-Type:application/json \
162 http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis \
163 --data @examples/sadis-in-bbsim.json
164
165You can verify the current Sadis configuration:
166
167.. code:: bash
168
169 curl --user karaf:karaf http://localhost:8181/onos/v1/network/configuration/apps/org.opencord.sadis
170
171In ONOS subscriber information can be queried using ``sadis <id>``.
Pragya Arya324337e2020-02-20 14:35:08 +0530172
Matteo Scandolo9d08be52020-03-12 09:43:53 -0700173*Note that BBSim supports both sadis configuration versions, here is an example of the configuration needed to return
174the old format:*
175
176.. literalinclude:: ../../examples/sadis-in-bbsim.json
177
Pragya Arya3f8fdc62020-03-16 11:12:27 +0530178Controlled PON and ONU activation
179---------------------------------
180
181BBSim provides support for controlled PON and ONU activation. By default both PON ports and ONUs are automatically activated when OLT is enabled.
182This can be controlled using ``-ca`` option.
183
184``-ca`` can be set to one of below four modes:
185
186- default: PON ports and ONUs are automatic activated (default behavior).
187
188- only-onu: PON ports automatically enabled and ONUs dynamically activated
189 On Enable OLT, IntfIndications for all PON ports are sent but ONU discovery indications are not sent.
190 When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
191- only-pon: PON ports dynamically enabled and ONUs automatically activated
192 On Enable OLT, neither IntfIndications for PON ports nor ONU discovery indications are sent.
193 When EnablePonIf request is received at OpenOLT server, then that PON port is enabled and
194 IntfIndication is sent for that PON and all ONUs under that ports are discovered automatically.
195- both: Both PON ports and ONUs are dynamically activated
196 On Enable OLT, neither IntfIndication for PON ports nor ONU discovery indications are sent.
197 When EnablePonIf request is received on OpenOLT server then IntfIndication is sent for that PON but no ONU discovery indication will be sent.
198 When PoweronONU request is received at BBSim API server then ONU discovery indication is sent for that ONU.
199
200
Pragya Arya324337e2020-02-20 14:35:08 +0530201Publishing BBSim Events on kafka
202--------------------------------
203
204BBSim provides option for publishing events on kafka. To publish events on kafka, set BBSimEvents flag and configure kafkaAddress.
205Once BBSim is started, it will publish events (as and when they happen) on topic ``BBSim-OLT-<id>-Events``.
206
207Types of Events:
208 - OLT-enable-received
209 - OLT-disable-received
210 - OLT-reboot-received
211 - OLT-reenable-received
212 - ONU-discovery-indication-sent
213 - ONU-activate-indication-received
214 - MIB-upload-received
215 - MIB-upload-done
216 - Flow-add-received
217 - Flow-remove-received
218 - ONU-authentication-done
219 - ONU-DHCP-ACK-received
220
221Sample output of kafkacat consumer for BBSim with OLT-ID 4:
222
223.. code:: bash
224
225 $ kafkacat -b localhost:9092 -t BBSim-OLT-4-Events -C
226 {"EventType":"OLT-enable-received","OnuSerial":"","OltID":4,"IntfID":-1,"OnuID":-1,"EpochTime":1583152243144,"Timestamp":"2020-03-02 12:30:43.144449453"}
227 {"EventType":"ONU-discovery-indication-sent","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":0,"EpochTime":1583152243227,"Timestamp":"2020-03-02 12:30:43.227183506"}
228 {"EventType":"ONU-activate-indication-received","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":1,"EpochTime":1583152243248,"Timestamp":"2020-03-02 12:30:43.248225467"}
229 {"EventType":"MIB-upload-received","OnuSerial":"BBSM00040001","OltID":4,"IntfID":0,"OnuID":1,"EpochTime":1583152243299,"Timestamp":"2020-03-02 12:30:43.299480183"}