diff --git a/docs/source/api.rst b/docs/source/api.rst
index 466e3e1..c44cec4 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -1,5 +1,8 @@
 .. _BBSimAPI:
 
+REST APIs
+=========
+
 BBSimAPI
 --------
 
@@ -23,4 +26,4 @@
 corresponding REST server is started on port 50073. The following endpoints are
 currently defined:
 
-.. openapi:: ../swagger/legacy/bbsim.swagger.json
+.. openapi:: ../swagger/legacy/bbsim.swagger.json
\ No newline at end of file
diff --git a/docs/source/bbsim_config.rst b/docs/source/bbsim_config.rst
new file mode 100644
index 0000000..0ddbe1e
--- /dev/null
+++ b/docs/source/bbsim_config.rst
@@ -0,0 +1,142 @@
+BBSim Configuration
+===================
+
+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
+     -authRetry
+           Set this flag if BBSim should retry EAPOL (Authentication) upon failure until success
+     -ca string
+           Set the mode for controlled activation of PON ports and ONUs
+     -config string
+           Configuration file path
+     -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
+     -dhcpRetry
+           Set this flag if BBSim should retry DHCP upon failure until success
+     -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
+     -kafkaEventTopic string
+           Ability to configure the topic on which BBSim publishes events on Kafka
+     -logCaller
+           Whether to print the caller filename or not
+     -logLevel string
+           Set the log level (trace, debug, info, warn, error)
+     -nni int
+           Number of NNI ports per OLT device to be emulated
+     -olt_id int
+           OLT device ID
+     -onu int
+           Number of ONU devices per PON port to be emulated
+     -openolt_address string
+           IP address:port
+     -pon int
+           Number of PON ports per OLT device to be emulated
+     -rest_api_address string
+           IP address:port
+     -services string
+           Service Configuration file path
+
+
+``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
+
+.. _ConfiguringServices:
+
+Configuring RG Services
+-----------------------
+
+BBSim supports different services in the RG.
+Those services are described through a configuration file that is specified via the ``-services`` flag.
+
+Below are examples of the tree commonly used configurations:
+
+.. literalinclude:: ../../configs/att-services.yaml
+
+.. literalinclude:: ../../configs/dt-services.yaml
+
+.. literalinclude:: ../../configs/tt-services.yaml
+
+Controlled PON and ONU activation
+---------------------------------
+
+BBSim provides support for controlled PON and ONU activation. This gives you the ability
+to manually enable PON Ports and ONUs as needed.
+
+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 activated on demand
+            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 enabled on demand 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 activated on demand
+        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.
+
+Pon Port and ONU on demand activation is managed via ``BBSimCtl``.
+You can find more information in the :ref:`Operations` page.
+
+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"}
\ No newline at end of file
diff --git a/docs/source/bbsimctl.rst b/docs/source/bbsimctl.rst
deleted file mode 100644
index ea7b344..0000000
--- a/docs/source/bbsimctl.rst
+++ /dev/null
@@ -1,87 +0,0 @@
-.. _BBSimCtl:
-
-BBSimCtl
-========
-
-BBSim comes with a gRPC interface to control the internal state. This
-interface can be queried using `bbsimctl` (the tool can be build with
-`make build` and it's available inside the `bbsim` container):
-
-.. code:: bash
-
-    $ ./bbsimctl --help
-    Usage:
-      bbsimctl [OPTIONS] <command>
-
-    Global Options:
-      -c, --config=FILE           Location of client config file [$BBSIMCTL_CONFIG]
-      -s, --server=SERVER:PORT    IP/Host and port of XOS
-      -d, --debug                 Enable debug mode
-
-    Help Options:
-      -h, --help                  Show this help message
-
-    Available commands:
-      completion  generate shell compleition
-      config      generate bbsimctl configuration
-      log         set bbsim log level
-      olt         OLT Commands
-      onu         ONU Commands
-
-``bbsimctl`` can be configured via a config file such as:
-
-.. code:: bash
-
-    $ cat ~/.bbsim/config
-    apiVersion: v1
-    server: 127.0.0.1:50070
-    grpc:
-      timeout: 10s
-
-Example commands
-----------------
-
-.. code:: bash
-
-    $ ./bbsimctl olt get
-    ID    SERIALNUMBER    OPERSTATE    INTERNALSTATE
-    0     BBSIM_OLT_0     up           enabled
-
-
-    $ ./bbsimctl olt pons
-    PON Ports for : BBSIM_OLT_0
-
-    ID    OPERSTATE
-    0     up
-    1     up
-    2     up
-    3     up
-
-
-    $ ./bbsimctl onu list
-    PONPORTID    ID    SERIALNUMBER    STAG    CTAG    OPERSTATE    INTERNALSTATE
-    0            1     BBSM00000001    900     900     up           eap_response_identity_sent
-    0            2     BBSM00000002    900     901     up           eap_start_sent
-    0            3     BBSM00000003    900     902     up           auth_failed
-    0            4     BBSM00000004    900     903     up           auth_failed
-    1            1     BBSM00000101    900     904     up           eap_response_success_received
-    1            2     BBSM00000102    900     905     up           eap_response_success_received
-    1            3     BBSM00000103    900     906     up           eap_response_challenge_sent
-    1            4     BBSM00000104    900     907     up           auth_failed
-    2            1     BBSM00000201    900     908     up           auth_failed
-    2            2     BBSM00000202    900     909     up           eap_start_sent
-    2            3     BBSM00000203    900     910     up           eap_response_identity_sent
-    2            4     BBSM00000204    900     911     up           eap_start_sent
-    3            1     BBSM00000301    900     912     up           eap_response_identity_sent
-    3            2     BBSM00000302    900     913     up           auth_failed
-    3            3     BBSM00000303    900     914     up           auth_failed
-    3            4     BBSM00000304    900     915     up           auth_failed
-
-Autocomplete
-------------
-
-``bbsimctl`` comes with autocomplete, just run:
-
-.. code:: bash
-
-    source <(bbsimctl completion bash)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 81910a3..c04bb3f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -54,7 +54,7 @@
 # ones.
 extensions = [
     'sphinxcontrib.openapi',
-    'sphinx.ext.graphviz'
+    'sphinx.ext.graphviz',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/development-dependencies.rst b/docs/source/development/development-dependencies.rst
similarity index 100%
rename from docs/source/development-dependencies.rst
rename to docs/source/development/development-dependencies.rst
diff --git a/docs/source/development/internals.rst b/docs/source/development/internals.rst
new file mode 100644
index 0000000..f936f64
--- /dev/null
+++ b/docs/source/development/internals.rst
@@ -0,0 +1,221 @@
+.. _BBSim Internals:
+
+BBSim Internals
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Other Resources:
+
+   development-dependencies.rst
+
+BBSim heavily leverages state machines to control the device lifecycle
+and channels to propagate and react to state changes.
+
+The most common pattern throughout the code is that any operations,
+for example a gRPC call to the ``ActivateOnu`` endpoint will result in:
+
+1. A state change in the ONU device, that will
+2. Send a message on the ONU Channel, that will
+3. Trigger some operation (for example send Indications to the OLT)
+
+.. _OLT State Machine:
+
+OLT State Machine
+-----------------
+
+Here is a list of possible states for an OLT:
+
+.. list-table:: OLT States
+    :header-rows: 1
+
+    * -
+      - Initialized
+      - Enabled
+      - Disabled
+      - Deleted
+    * - Data model is created for OLT, NNIs, PONs and ONUs
+      - Starts the listener on the NNI interface and the DHCP server,
+        Starts the OLT gRPC server,
+        Moves the ONUs to ``initialized`` state
+      - Sends OLT, NNIs and PONs ``UP`` indications
+        Transition the ONUs into ``discovered`` state
+      - Transition the ONUs into ``disabled`` state
+        Sends OLT, NNIs and PONs ``UP`` indications
+      - Stops the OLT gRPC Server
+
+Below is a diagram of the state machine allowed transitions:
+
+.. graphviz::
+
+    digraph {
+        rankdir=LR
+        newrank=true
+        graph [pad="1,1" bgcolor="#cccccc"]
+        node [style=filled, fillcolor="#bee7fa"]
+
+        created -> initialized -> enabled -> disabled -> deleted
+        disabled -> enabled
+        deleted -> initialized
+    }
+
+
+
+.. _ONU State Machine:
+
+ONU State Machine
+-----------------
+
+Here is a list of possible state transitions for an ONU in BBSim:
+
+.. list-table:: ONU States
+    :widths: 10 35 10 45
+    :header-rows: 1
+
+    * - Transition
+      - Starting States
+      - End State
+      - Notes
+    * -
+      -
+      - created
+      -
+    * - initialize
+      - created, disabled, pon_disabled
+      - initialized
+      -
+    * - discover
+      - initialized
+      - discovered
+      -
+    * - enable
+      - discovered, disabled, pon_disabled
+      - enabled
+      -
+    * - disable
+      - enabled
+      - disabled
+      - This state signifies that the ONU has been disabled
+    * - pon_disabled
+      - enabled
+      - pon_disabled
+      - This state signifies that the parent PON Port has been disabled, the ONU state hasn't been affected.
+
+Below is a diagram of the state machine:
+
+- In blue PON related states
+- In purple operator driven states
+
+.. graphviz::
+
+    digraph {
+        rankdir=LR
+        newrank=true
+        graph [pad="1,1" bgcolor="#cccccc"]
+        node [style=filled]
+
+        subgraph {
+            node [fillcolor="#bee7fa"]
+
+            created [peripheries=2]
+            initialized
+            discovered
+            {
+                rank=same
+                enabled
+                disabled [fillcolor="#f9d6ff"]
+                pon_disabled [fillcolor="#f9d6ff"]
+            }
+
+            {created, disabled} -> initialized -> discovered -> enabled
+        }
+
+        disabled -> enabled
+        enabled -> pon_disabled
+        pon_disabled -> {initialized, disabled, enabled}
+    }
+
+.. _Service State Machine:
+
+Service State Machine
+---------------------
+
+..
+    TODO add table
+
+.. graphviz::
+
+    digraph {
+        rankdir=TB
+        newrank=true
+        graph [pad="1,1" bgcolor="#cccccc"]
+        node [style=filled]
+
+        subgraph cluster_lifecycle {
+            node [fillcolor="#bee7fa"]
+            style=dotted
+
+            created [peripheries=2]
+            initialized
+            disabled
+
+            created -> initialized -> disabled
+            disabled -> initialized
+        }
+
+        subgraph cluster_eapol {
+            style=rounded
+            style=dotted
+            node [fillcolor="#e6ffc2"]
+
+            auth_started [peripheries=2]
+            eap_start_sent
+            eap_response_identity_sent
+            eap_response_challenge_sent
+            {
+                rank=same
+                eap_response_success_received
+                auth_failed
+            }
+
+            auth_started -> eap_start_sent -> eap_response_identity_sent -> eap_response_challenge_sent -> eap_response_success_received
+            auth_started -> auth_failed
+            eap_start_sent -> auth_failed
+            eap_response_identity_sent -> auth_failed
+            eap_response_challenge_sent -> auth_failed
+
+            auth_failed -> auth_started
+        }
+
+        subgraph cluster_dhcp {
+            node [fillcolor="#fffacc"]
+            style=rounded
+            style=dotted
+
+            dhcp_started [peripheries=2]
+            dhcp_discovery_sent
+            dhcp_request_sent
+            {
+                rank=same
+                dhcp_ack_received
+                dhcp_failed
+            }
+
+            dhcp_started -> dhcp_discovery_sent -> dhcp_request_sent -> dhcp_ack_received
+            dhcp_started -> dhcp_failed
+            dhcp_discovery_sent -> dhcp_failed
+            dhcp_request_sent -> dhcp_failed
+            dhcp_ack_received dhcp_failed
+
+        }
+
+        subgraph cluster_igmp {
+            node [fillcolor="#ffaaff"]
+            style=rounded
+            style=dotted
+
+            igmp_join_started [peripheries=2]
+            igmp_join_started -> igmp_join_error -> igmp_join_started
+            igmp_join_started -> igmp_left
+        }
+    }
\ No newline at end of file
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"}
diff --git a/docs/source/olt-state-machine.rst b/docs/source/olt-state-machine.rst
deleted file mode 100644
index e40774a..0000000
--- a/docs/source/olt-state-machine.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-.. _OLT State Machine:
-
-OLT State Machine
-=================
-
-In ``BBSim`` the device state is created using a state machine
-library: `fsm <https://github.com/looplab/fsm>`__.
-
-Here is a list of possible states for an OLT in BBSim:
-
-.. list-table:: OLT States
-    :header-rows: 1
-
-    * -
-      - Initialized
-      - Enabled
-      - Disabled
-      - Deleted
-    * - Data model is created for OLT, NNIs, PONs and ONUs
-      - Starts the listener on the NNI interface and the DHCP server,
-        Starts the OLT gRPC server,
-        Moves the ONUs to ``initialized`` state
-      - Sends OLT, NNIs and PONs ``UP`` indications
-        Transition the ONUs into ``discovered`` state
-      - Transition the ONUs into ``disabled`` state
-        Sends OLT, NNIs and PONs ``UP`` indications
-      - Stops the OLT gRPC Server
-
-Below is a diagram of the state machine allowed transitions:
-
-.. graphviz::
-
-    digraph {
-        rankdir=TB
-        newrank=true
-        graph [pad="1,1" bgcolor="#cccccc"]
-        node [style=filled]
-
-        created -> initialized -> enabled -> disabled -> deleted
-        disabled -> enabled
-        deleted -> initialized
-    }
-
diff --git a/docs/source/onu-state-machine.rst b/docs/source/onu-state-machine.rst
deleted file mode 100644
index a7adb9e..0000000
--- a/docs/source/onu-state-machine.rst
+++ /dev/null
@@ -1,234 +0,0 @@
-.. _ONU State Machine:
-
-ONU State Machine
-=================
-
-In ``BBSim`` the device state is created using a state machine
-library: `fsm <https://github.com/looplab/fsm>`__.
-
-Here is a list of possible state transitions for an ONU in BBSim:
-
-.. list-table:: ONU States
-    :widths: 10 35 10 45
-    :header-rows: 1
-
-    * - Transition
-      - Starting States
-      - End State
-      - Notes
-    * -
-      -
-      - created
-      -
-    * - initialize
-      - created, disabled, pon_disabled
-      - initialized
-      -
-    * - discover
-      - initialized
-      - discovered
-      -
-    * - enable
-      - discovered, disabled, pon_disabled
-      - enabled
-      -
-    * - start_auth
-      - enabled, eap_start_sent, eap_response_identity_sent, eap_response_challenge_sent, eap_response_success_received, auth_failed, dhcp_ack_received, dhcp_failed
-      - auth_started
-      - Requires that both the EAPOL flow has been received and the GemPort added
-    * - eap_start_sent
-      - auth_started
-      - eap_start_sent
-      -
-    * - eap_response_identity_sent
-      - eap_start_sent
-      - eap_response_identity_sent
-      -
-    * - eap_response_challenge_sent
-      - eap_response_identity_sent
-      - eap_response_challenge_sent
-      -
-    * - eap_response_success_received
-      - eap_response_challenge_sent
-      - eap_response_success_received
-      -
-    * - auth_failed
-      - auth_started, eap_start_sent, eap_response_identity_sent, eap_response_challenge_sent
-      - auth_failed
-      -
-    * - start_dhcp
-      - enabled, eap_response_success_received, dhcp_discovery_sent, dhcp_request_sent, dhcp_ack_received, dhcp_failed
-      - dhcp_started
-      - Requires that both the DHCP flow has been received and the GemPort added. In addition the transtition from the ``enabled`` state is only allowed if Auth is set to false
-    * - dhcp_discovery_sent
-      - dhcp_started
-      - dhcp_discovery_sent
-      -
-    * - dhcp_request_sent
-      - dhcp_discovery_sent
-      - dhcp_request_sent
-      -
-    * - dhcp_ack_received
-      - dhcp_request_sent
-      - dhcp_ack_received
-      -
-    * - dhcp_failed
-      - dhcp_started, dhcp_discovery_sent, dhcp_request_sent
-      - dhcp_failed
-      -
-    * - disable
-      - enabled, eap_response_success_received, auth_failed, dhcp_ack_received, dhcp_failed
-      - disabled
-      -
-    * - pon_disabled
-      - enabled, gem_port_added, eapol_flow_received, eap_response_success_received, auth_failed, dhcp_ack_received, dhcp_failed
-      - pon_disabled
-      -
-
-In addition some transition can be forced via the API,
-check the previous table to verify when you can trigger those actions and
-:ref:`BBSimCtl` for more informations about ``BBSimCtl``:
-
-.. list-table:: API State Transitions
-    :widths: 15 15 70
-    :header-rows: 1
-
-    * - BBSimCtl command
-      - Transitions To
-      - Notes
-    * - shutdown
-      - disable
-      - Emulates a device shutdown. Sends a ``DyingGaspInd`` and then an ``OnuIndication{OperState: 'down'}``
-    * - poweron
-      - discover
-      - Emulates a device power on. Sends a ``OnuDiscInd``
-    * - auth_restart
-      - start_auth
-      - Forces the ONU to send a new ``EapStart`` packet.
-    * - dhcp_restart
-      - start_dhcp
-      - Forces the ONU to send a new ``DHCPDiscovery`` packet.
-    * - softReboot
-      - disable
-      - Emulates a device soft reboot. Sends ``LosIndication{status: 'on'}`` and then after reboot delay ``LosIndication{status: 'off'}``
-    * - hardReboot
-      - disable
-      - Emulates a device hard reboot. Sends a ``DyingGaspInd`` and ``OnuIndication{OperState: 'down'}`` and raise necessary alarmIndications and after reboot delay sends ``OnuDiscInd`` and clear alarm indications.
-    * - onuAlarms
-      - TBD
-      -
-
-.. list-table::
-    :widths: 15 15 70
-    :header-rows: 1
-
-    * - OpenOlt request
-      - Transitions To
-      - Notes
-    * - ActivateOnu
-      - enable
-      - VOLTHA assigns ID to ONU and then BBSim sends a ``OnuIndication{OperState: 'up'}``
-    * - DeleteOnu
-      - initialized
-      - Reset ONU-ID to zero and move ONU to initialized state so that its ready to poweron again when required
-
-Below is a diagram of the state machine:
-
-- In blue PON related states
-- In green EAPOL related states
-- In yellow DHCP related states
-- In purple operator driven states
-
-..
-  TODO Evaluate http://blockdiag.com/en/seqdiag/examples.html
-
-.. graphviz::
-
-    digraph {
-        rankdir=TB
-        newrank=true
-        graph [pad="1,1" bgcolor="#cccccc"]
-        node [style=filled]
-
-        subgraph {
-            node [fillcolor="#bee7fa"]
-
-            created [peripheries=2]
-            initialized
-            discovered
-            {
-                rank=same
-                enabled
-                disabled [fillcolor="#f9d6ff"]
-            }
-
-            {created, disabled} -> initialized -> discovered -> enabled
-        }
-
-        subgraph cluster_eapol {
-            style=rounded
-            style=dotted
-            node [fillcolor="#e6ffc2"]
-
-            auth_started
-            eap_start_sent
-            eap_response_identity_sent
-            eap_response_challenge_sent
-            {
-                rank=same
-                eap_response_success_received
-                auth_failed
-            }
-
-            auth_started -> eap_start_sent -> eap_response_identity_sent -> eap_response_challenge_sent -> eap_response_success_received
-            auth_started -> auth_failed
-            eap_start_sent -> auth_failed
-            eap_response_identity_sent -> auth_failed
-            eap_response_challenge_sent -> auth_failed
-
-            eap_start_sent -> auth_started
-            eap_response_identity_sent -> auth_started
-            eap_response_challenge_sent -> auth_started
-
-            eap_response_success_received -> auth_started
-            auth_failed -> auth_started
-        }
-
-        subgraph cluster_dhcp {
-            node [fillcolor="#fffacc"]
-            style=rounded
-            style=dotted
-
-            dhcp_started
-            dhcp_discovery_sent
-            dhcp_request_sent
-            {
-                rank=same
-                dhcp_ack_received
-                dhcp_failed
-            }
-
-            dhcp_started -> dhcp_discovery_sent -> dhcp_request_sent -> dhcp_ack_received
-            dhcp_started -> dhcp_failed
-            dhcp_discovery_sent -> dhcp_failed
-            dhcp_request_sent -> dhcp_failed
-            dhcp_ack_received dhcp_failed
-
-            dhcp_discovery_sent -> dhcp_started
-            dhcp_request_sent -> dhcp_started
-            dhcp_ack_received -> dhcp_started
-            dhcp_failed -> dhcp_started
-        }
-        enabled -> auth_started
-        enabled -> dhcp_started
-
-        {dhcp_ack_received, dhcp_failed} -> auth_started
-
-        eap_response_success_received -> dhcp_started
-
-        eap_response_success_received -> disabled
-        auth_failed -> disabled
-        dhcp_ack_received -> disabled
-        dhcp_failed -> disabled
-        disabled -> enabled
-    }
diff --git a/docs/source/operations.rst b/docs/source/operations.rst
index cc977f3..72c636d 100644
--- a/docs/source/operations.rst
+++ b/docs/source/operations.rst
@@ -1,38 +1,91 @@
 .. _Operations:
 
-BBSim Operations
-================
+Operate BBSim
+=============
 
 If you are testing basic functionality using BBSim no operator intervention is required.
 
 When you ``enable`` the device in VOLTHA the simulator will:
 
 - activate all the configured ONUs
-- wait for the EAPOL flow for each ONU and trigger the authentication state machine as soon as it's received
-- wait for the DHCP flow for each ONU and trigger the DHCP state machine as soon as it's received
+- wait for the EAPOL flow for each Service that requires it and trigger the authentication state machine as soon as it's received
+- wait for the DHCP flow for each Service that requires it and trigger the DHCP state machine as soon as it's received
+
+BBSimCtl
+--------
+
+BBSim comes with a gRPC interface to control the internal state. This
+interface can be queried using `bbsimctl` (the tool can be build with
+`make build` and it's available inside the `bbsim` container):
+
+.. code:: bash
+
+    $ ./bbsimctl --help
+    Usage:
+      bbsimctl [OPTIONS] <command>
+
+    Global Options:
+      -c, --config=FILE           Location of client config file [$BBSIMCTL_CONFIG]
+      -s, --server=SERVER:PORT    IP/Host and port of XOS
+      -d, --debug                 Enable debug mode
+
+    Help Options:
+      -h, --help                  Show this help message
+
+    Available commands:
+      completion  generate shell compleition
+      config      generate bbsimctl configuration
+      log         set bbsim log level
+      olt         OLT Commands
+      onu         ONU Commands
+      pon         PON Commands
+      service     Service Commands
 
 Access bbsimctl
----------------
++++++++++++++++
 
-When running a test you can check the state of each ONU using :ref:`BBSimCtl`.
+When running a test you can check the state of each ONU using ``BBSimCtl``.
 
 The easiest way to use ``bbsimctl`` is to ``exec`` inside the ``bbsim`` container:
 
 .. code:: bash
 
-    kubectl exec -it -n voltha -f $(kubectl get pods -n voltha | grep bbsim | awk '{print $1}') bash
+    kubectl -n voltha exec -it $(kubectl -n voltha get pods -l app=bbsim -o name) -- /bin/bash
+
+In case you prefer to run ``bbsimctl`` on your machine,
+it can be configured via a config file such as:
+
+.. code:: bash
+
+    $ cat ~/.bbsim/config
+    apiVersion: v1
+    server: 127.0.0.1:50070
+    grpc:
+      timeout: 10s
 
 Check the ONU Status
---------------------
+++++++++++++++++++++
 
 .. code:: bash
 
     $ bbsimctl onu list
-    PONPORTID    ID    PORTNO    SERIALNUMBER    HWADDRESS            STAG    CTAG    OPERSTATE    INTERNALSTATE
-    0            1     0         BBSM00000001    2e:60:70:13:00:01    900     900     up           dhcp_ack_received
+    PONPORTID    ID    PORTNO    SERIALNUMBER    OPERSTATE    INTERNALSTATE
+    0            1     0         BBSM00000001    up           enabled
+
+Check the Service Status
+++++++++++++++++++++++++
+
+.. code:: bash
+
+    $ bbsimctl onu services BBSM00000001
+    ONUSN           INTERNALSTATE    NAME    HWADDRESS            STAG    CTAG    NEEDSEAPOL    NEEDSDHCP    NEEDSIGMP    GEMPORT    EAPOLSTATE    DHCPSTATE            IGMPSTATE
+    BBSM00000001    initialized      hsia    2e:60:00:00:01:00    900     900     false         false        false        1056       created       created              created
+    BBSM00000001    initialized      voip    2e:60:00:00:01:01    333     444     false         true         false        1104       created       dhcp_ack_received    created
+    BBSM00000001    initialized      vod     2e:60:00:00:01:02    555     55      false         true         true         1084       created       dhcp_ack_received    igmp_join_started
+    BBSM00000001    initialized      MC      2e:60:00:00:01:03    550     55      false         false        false        0          created       created              created
 
 Advanced operations
--------------------
++++++++++++++++++++
 
 In certain cases you may want to execute operations on the BBSim ONUs.
 
@@ -55,10 +108,45 @@
       -h, --help                  Show this help message
 
     Available commands:
+      alarms
       auth_restart
       dhcp_restart
+      flows
       get
+      igmp
       list
       poweron
+      services
       shutdown
+      traffic_schedulers
 
+Enable ONUs
++++++++++++
+
+``BBSimCtl`` gives you the ability to control the device lifecycle,
+for example you can turn ONUs on and off:
+
+.. code:: bash
+
+    $ bbsimctl onu shutdown BBSM00000001
+    [Status: 0] ONU BBSM00000001 successfully shut down.
+
+    $ bbsimctl onu poweron BBSM00000001
+    [Status: 0] ONU BBSM00000001 successfully powered on.
+
+Autocomplete
+++++++++++++
+
+``bbsimctl`` comes with autocomplete, just run:
+
+.. code:: bash
+
+    source <(bbsimctl completion bash)
+
+Other APIS
+----------
+
+.. toctree::
+    :maxdepth: 1
+
+    api.rst
\ No newline at end of file
diff --git a/docs/source/sadis_config.rst b/docs/source/sadis_config.rst
new file mode 100644
index 0000000..4d74631
--- /dev/null
+++ b/docs/source/sadis_config.rst
@@ -0,0 +1,62 @@
+SADIS Configuration
+===================
+
+BBSim generates a ``sadis`` configuration starting from the :ref:`Service <ConfiguringServices>`
+configuration file.
+
+For example if you consider this Service configuration:
+
+.. literalinclude:: ../../configs/att-services.yaml
+
+The corresponding ``sadis`` configuration that you'll need to use in ONOS is:
+
+.. literalinclude:: ../../examples/sadis-att.json
+
+As you can imagine this file will get pretty big pretty quickly as soon as you scale
+the number of ONUs and/or Services in your setup. For that reason (and to avoid mistakes)
+we strongly suggest to configure ONOS to fetch informations from BBSim.
+
+If you are using ``kind-voltha`` to deploy your setup, you can easily achieve that by:
+
+.. code:: bash
+
+    CONFIG_SADIS=external voltha up
+
+Or you can manually configure ONOS as explained below.
+
+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 <uni-id>``.
\ No newline at end of file