Add events & porting guide docs. Still missing detailed desc

docs/user-manual/events-cb-fn.rst

@@ -3,6 +3,91 @@
 Events and callback functions
 =============================
 
+Library uses events to notify application layer for (possible, but not limited to) unexpected events.
+This concept is used aswell for commands with longer executing time, such as *scanning access points* or when application starts new connection as client mode.
+
+There are ``3`` types of events/callbacks available:
+
+* *Global event* callback function, assigned when initializing library
+* *Connection specific event* callback function, to process only events related to connection, such as *connection error*, *data send*, *data receive*, *connection closed*
+* *API function* call based event callback function
+
+Every callback is always called from protected area of middleware (when exclusing access is granted to single thread only),
+and it can be called from one of these ``3`` threads:
+
+- *Producing thread*
+- *Processing thread*
+- *Input thread*, when ``ESP_CFG_INPUT_USE_PROCESS`` is enabled and ``esp_input_process`` function is called 
+
+.. tip::
+    Check :ref:`um_inter_thread_comm` for more details about *Producing* and *Processing* thread.
+
+Global event callback
+^^^^^^^^^^^^^^^^^^^^^
+
+Global event callback function is assigned at library initialization.
+It is used by the application to receive any kind of event, except the one related to connection:
+
+* ESP station successfully connected to access point
+* ESP physical device reset has been detected
+* Restore operation finished
+* New station has connected to access point
+* and many more..
+
+.. tip::
+    Check :ref:`api_esp_evt` section for different kind of events
+
+By default, global event function is single function.
+If the application tries to split different events with different callback functions,
+it is possible to do so by using ``esp_evt_register`` function to register a new,
+custom, event function.
+
+.. tip::
+    Implementation of :ref:`api_app_netconn` leverages ``esp_evt_register`` to 
+    receive event when station disconnected from wifi access point.
+    Check its source file for actual implementation.
+
+.. literalinclude:: ../../esp_at_lib/src/api/esp_netconn.c
+    :language: c
+
+Connection specific event
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This events are subset of global event callback. 
+They work exactly the same way as global, but only receive events related to connections.
+
+.. tip::
+    Connection related events start with ``ESP_EVT_CONN_*``. 
+    Check :ref:`api_esp_evt` for list of all connection events.
+
+Connection events callback function is set for ``2`` cases:
+
+* Each client (when application starts connection) sets event callback function when trying to connect with ``esp_conn_start`` function
+* Application sets global event callback function when enabling server mode with ``esp_set_server`` function
+
+.. literalinclude:: ../../snippets/client.c
+    :language: c
+
+API call event
+^^^^^^^^^^^^^^
+
+API function call event function is special type of event and is linked to command execution.
+It is especially useful when dealing with non-blocking commands to understand when specific
+command execution finished and when next operation could start.
+
+Every API function, which directly operates with AT command on physical device layer,
+has optional ``2`` parameters for API call event:
+
+* Callback function, called when command finished
+* Custom user parameter for callback function
+
+Below is an example code for DNS resolver.
+It uses custom API callback function with custom argument, 
+used to distinguis domain name (when multiple domains are to be resolved).
+
+.. literalinclude:: ../../snippets/dns.c
+    :language: c
+
 .. toctree::
     :maxdepth: 2
     :glob:

docs/user-manual/index.rst

@@ -8,8 +8,8 @@ User manual
 
     overview
     architecture
-    porting-guide
     inter-thread-comm
-    blocking-nonblocking
     events-cb-fn
+    blocking-nonblocking
+    porting-guide
 

docs/user-manual/porting-guide.rst

@@ -5,7 +5,13 @@ Porting guide
 
 High level of *ESP-AT* library is platform independent, written in ANSI C99,
 however there is an important part where middleware needs to communicate with target *ESP* device
-and it must work under different optional operating systems chosed by final customer.
+and it must work under different optional operating systems selected by final customer.
+
+Porting consists of:
+
+* Implementation of *low-level* part, for actual communication between host device and *ESP* device
+* Implementation of system functions, link between target operating system and middleware functions
+* Assignment of memory for allocation manager
 
 Implement low-level part
 ^^^^^^^^^^^^^^^^^^^^^^^^