add more API sample

2 files changed, 164 insertions, 5 deletions

diff --git a/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst b/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst
index ef7feb61..29d524e1 100644
--- a/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst
+++ b/scripts/automation/trex_control_plane/doc_stl/api/client_code.rst
@@ -2,16 +2,168 @@
 Module documentation
 ================================
 
+TRex Client is an object to access TRex server. It is per user. Each user can own number of interfaces. 
+Multi user can interact with one TRex server each user should own a different set of interfaces.
+The protocol is JSON-RPC2 over ZMQ transport.
+
+The API has two type of API 
+
+1. Normal API 
+2. xx_line:  this api get a line like the Console and parse it and call the low level api 
+
+
 STLClient class
------------------
+---------------
 
 .. autoclass:: trex_stl_lib.trex_stl_client.STLClient
     :members: 
+    :member-order: bysource
+    
 
-Stream  class
+STLClient snippet
 -----------------
 
-.. automodule:: trex_stl_lib.trex_stl_streams
-    :members:
 
+Example1::
+
+    c = STLClient()
+
+    try:
+        # connect to server
+        c.connect()
+
+        # prepare our ports (my machine has 0 <--> 1 with static route)
+        c.reset(ports = [0, 1])
+
+        # add both streams to ports
+        c.add_streams(s1, ports = [0])
+
+        # clear the stats before injecting
+        c.clear_stats()
+
+        c.start(ports = [0, 1], mult = "5mpps", duration = 10)
+
+        # block until done
+        c.wait_on_traffic(ports = [0, 1])
+
+    finally:
+        c.disconnect()
+
+
+
+Example2: wait while doing somthing::
+
+    c = STLClient()
+    try:
+        #connect to server
+        c.connect()
+
+        #..
+
+        c.start(ports = [0, 1], mult = "5mpps", duration = 10)
+
+        # block until done
+        while True  :
+                # do somthing else
+                os.sleep(1) # sleep for 1 sec 
+                # check if the port is still active 
+                if c.is_traffic_active(ports = [0, 1])==False
+                        break;
+                
+    finally:
+        c.disconnect()
+
+
+Example3: Console like::
+
+        def simple ():
+        
+            # create client
+            #verbose_level = LoggerApi.VERBOSE_HIGH  # set to see JSON-RPC commands
+            c = STLClient(verbose_level = LoggerApi.VERBOSE_REGULAR)
+            passed = True
+            
+            try:
+                # connect to server
+                c.connect()
+        
+                my_ports=[0,1]
+        
+                # prepare our ports
+                c.reset(ports = my_ports)
+        
+                print (" is connected {0}".format(c.is_connected()))
+        
+                print (" number of ports {0}".format(c.get_port_count()))
+                print (" acquired_ports {0}".format(c.get_acquired_ports()))
+                # port stats
+                print c.get_stats(my_ports)  
+        
+                # port info, mac-addr info, speed 
+                print c.get_port_info(my_ports)
+        
+                c.ping()
+        
+                print("start") 
+                # start traffic on port 0,1 each 10mpps 
+                c.start_line (" -f ../../../../stl/udp_1pkt_simple.py -m 10mpps --port 0 1 ")
+                time.sleep(2);
+                c.pause_line("--port 0 1");
+                time.sleep(2);
+                c.resume_line("--port 0 1");
+                time.sleep(2);
+                c.update_line("--port 0 1 -m 5mpps");   # reduce to 5 mpps
+                time.sleep(2);
+                c.stop_line("--port 0 1");  # stop both ports
+        
+            except STLError as e:
+                passed = False
+                print e
+        
+            finally:
+                c.disconnect()
+
+Example4: Load profile from a file::
+
+def simple ():
+
+    # create client
+    #verbose_level = LoggerApi.VERBOSE_HIGH
+    c = STLClient(verbose_level = LoggerApi.VERBOSE_REGULAR)
+    passed = True
+    
+    try:
+        # connect to server
+        c.connect()
+
+        my_ports=[0,1]
+
+        # prepare our ports
+        c.reset(ports = my_ports)
+
+        profile_file =   "../../../../stl/udp_1pkt_simple.py"   # a traffic profile file 
+
+        try:                                                    # load a profile
+            profile = STLProfile.load(profile_file)
+        except STLError as e:
+            print format_text("\nError while loading profile '{0}'\n".format(profile_file), 'bold')
+            print e.brief() + "\n"
+            return
+
+        print profile.dump_to_yaml()                            # print it as YAML
+
+        c.remove_all_streams(my_ports)                          # remove all streams
+
+
+        c.add_streams(profile.get_streams(), ports = my_ports)  # add them 
+
+        c.start(ports = [0, 1], mult = "5mpps", duration = 10)  # start for 10 sec
+
+        # block until done
+        c.wait_on_traffic(ports = [0, 1])                       # wait 
+
+
+    finally:
+        c.disconnect()
+        
 
diff --git a/scripts/automation/trex_control_plane/doc_stl/index.rst b/scripts/automation/trex_control_plane/doc_stl/index.rst
index fe58db25..5437f1f9 100644
--- a/scripts/automation/trex_control_plane/doc_stl/index.rst
+++ b/scripts/automation/trex_control_plane/doc_stl/index.rst
@@ -1,5 +1,4 @@
 .. TRex Stateless Python API documentation 
-   sphinx-quickstart on Tue Jun  2 07:48:10 2015.
    contain the root `toctree` directive.
 
 TRex Stateless Python API
@@ -12,6 +11,14 @@ To understand the entirely how the API works and how to set up the server side,
    
 **Use the table of contents below or the menu to your left to navigate through the site**
 
+How to Install 
+=============
+.. toctree::
+    :maxdepth: 2
+
+* TODO[]
+        
+
 API Reference
 =============
 .. toctree::