diff --git a/docs/source/onu-state-machine.rst b/docs/source/onu-state-machine.rst
new file mode 100644
index 0000000..9df3ca6
--- /dev/null
+++ b/docs/source/onu-state-machine.rst
@@ -0,0 +1,113 @@
+.. _ONU State Machine:
+
+ONU State Machine
+=================
+
+In ``BBSim`` the device state is createdtained using a state machine
+library: `fsm <https://github.com/looplab/fsm>`__.
+
+Here is a list of possible state transitions in BBSim:
+
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| Transition                     | Starting States                                                                        | End State                      | Notes                                                                                         |
++================================+========================================================================================+================================+===============================================================================================+
+|                                |                                                                                        | created                        |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| discover                       | created                                                                                | discovered                     |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| enable                         | discovered, disabled                                                                   | enabled                        |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| receive_eapol_flow             | enabled, gem_port_added                                                                | eapol_flow_received            |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| add_gem_port                   | enabled, eapol_flow_received                                                           | gem_port_added                 | We need to wait for both the flow and the gem port to come before moving to ``auth_started``  |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| start_auth                     | eapol_flow_received, gem_port_added                                                    | auth_started                   |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| 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                     | eap_response_success_received                                                          | dhcp_started                   |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+| 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                    |                                                                                               |
++--------------------------------+----------------------------------------------------------------------------------------+--------------------------------+-----------------------------------------------------------------------------------------------+
+
+In addition some transition can be forced via the API:
+
++---------------------+----------------------------------------------------------------------------+-----------+---------------------------------------------------------------------------------------------------------+
+| End StateTransition | Starting States                                                            | End State | Notes                                                                                                   |
++=====================+============================================================================+===========+=========================================================================================================+
+| disable             | eap_response_success_received, auth_failed, dhcp_ack_received, dhcp_failed | disabled  | Emulates a devide mulfunction. Sends a ``DyingGaspInd`` and then an ``OnuIndication{OperState: 'down'}``|
++---------------------+----------------------------------------------------------------------------+-----------+---------------------------------------------------------------------------------------------------------+
+
+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 {
+        graph [pad="1,1" bgcolor="#cccccc"]
+        node [style=filled]
+
+        created [fillcolor="#bee7fa"]
+        discovered [fillcolor="#bee7fa"]
+        enabled [fillcolor="#bee7fa"]
+        disabled [fillcolor="#f9d6ff"]
+        gem_port_added [fillcolor="#bee7fa"]
+
+        eapol_flow_received [fillcolor="#e6ffc2"]
+        auth_started [fillcolor="#e6ffc2"]
+        eap_start_sent [fillcolor="#e6ffc2"]
+        eap_response_identity_sent [fillcolor="#e6ffc2"]
+        eap_response_challenge_sent [fillcolor="#e6ffc2"]
+        eap_response_success_received [fillcolor="#e6ffc2"]
+        auth_failed [fillcolor="#e6ffc2"]
+
+        dhcp_started [fillcolor="#fffacc"]
+        dhcp_discovery_sent [fillcolor="#fffacc"]
+        dhcp_request_sent [fillcolor="#fffacc"]
+        dhcp_ack_received [fillcolor="#fffacc"]
+        dhcp_failed [fillcolor="#fffacc"]
+
+        created -> discovered -> enabled
+        enabled -> gem_port_added -> eapol_flow_received -> auth_started
+        enabled -> eapol_flow_received -> gem_port_added -> auth_started
+
+        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_response_success_received -> dhcp_started
+        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
+
+        eap_response_success_received -> disabled
+        auth_failed -> disabled
+        dhcp_ack_received -> disabled
+        dhcp_failed -> disabled
+        disabled -> enabled
+    }
\ No newline at end of file