CXMAN-153: Started adding fw_upgrade tutorial. Made it consistent with

the fabric_basics tutorial.

3 files changed, 95 insertions, 5 deletions

diff --git a/cxmanage_api/docs/source/fab_basics.rst b/cxmanage_api/docs/source/fab_basics.rst
index d4badd8..5a17ce2 100644
--- a/cxmanage_api/docs/source/fab_basics.rst
+++ b/cxmanage_api/docs/source/fab_basics.rst
@@ -4,8 +4,6 @@ Fabric Basics
 Overview
 ========
 
-This tutorial assumes basic Object Oriented Programming knowledge.
-
 Constructing a Fabric object in Python is **VERY** easy. You simply need to
 know the ip address of *ANY* Node in your configuration ...
 Thats it. The API will do the rest!
@@ -17,13 +15,18 @@ What purpose do Fabric objects in Python do for me as a user?
     * Gathering real time information from the Fabric (statistics, topology,
       software versions, etc.)
 
+.. note::
+    * This tutorial assumes:
+        * Basic Object Oriented Programming knowledge
+        * Basic Python language syntax and data structures
+    
 Example
 =======
 
 **Lets start by stating what the end goals of this example will be:**
-    1. Construct a Fabric object using the Cxmanage API in Python.
-    2. Query the Fabric object for **basic** information from each node.
-    3. Print out the information.
+    1. Construct a Fabric object using the Cxmanage API.
+    #. Query the Fabric object for **basic** information from each node.
+    #. Print out the information.
 
 .. seealso:: `Fabric Info Basic <fabric.html#cxmanage_api.fabric.Fabric.info_basic>`_ & `Node Info Basic <node.html#cxmanage_api.node.Node.info_basic>`_ for more details on the function(s) we'll be using.
 
diff --git a/cxmanage_api/docs/source/fw_install.rst b/cxmanage_api/docs/source/fw_install.rst
new file mode 100644
index 0000000..561b34d
--- /dev/null
+++ b/cxmanage_api/docs/source/fw_install.rst
@@ -0,0 +1,86 @@
+Firmware Installation Basics
+----------------------------
+
+Overview
+========
+
+Now that we can construct a Fabric object using the Cxmanage API, we can use the
+Fabric functionality to load firmware onto each node.
+
+.. note::
+    * This tutorial assumes:
+        * Basic Object Oriented Programming knowledge
+        * Basic Python language syntax and data structures
+
+Example
+=======
+
+**Lets start by stating what the end goals of this example will be:**
+    1. Construct a FirmwarePackage object using the Cxmanage API.
+    #. Construct a Fabric object using the Cxmanage API.
+    #. Print out each Nodes' current firmware version.
+    #. If the Fabric is *updatable*, update the firmware.
+    #. If the Fabric is not, print out which Node(s) cannot be updated.
+
+.. seealso::
+    Fabric `is_updatabale() <fabric.html#cxmanage_api.fabric.Fabric.is_updatable>`_ for more details on the functions we'll be using.
+
+**Now lets dive right in with code ...**
+
+You can either write a script in your favorite text editor of choice or use
+Python's Interactive Interpreter. The interactive interpreter is used for these
+code examples, however ANY of this code can be copied/pasted into a script.
+
+To start the Interactive Interpreter, at a terminal command-line prompt::
+
+   python
+    Python 2.7.3 (default, Aug  1 2012, 05:14:39)
+    [GCC 4.6.3] on linux2
+    Type "help", "copyright", "credits" or "license" for more information.
+   >>>
+
+.. note::
+    * If you're using a Virtual Environment ... BEFORE you start the interpreter, be sure to:
+        workon <VirtualEnvironment Name>
+
+.. seealso:: `Using the Python Interpreter <http://docs.python.org/2/tutorial/interpreter.html>`_
+
+
+The Code
+########
+
+.. code-block:: python
+    :linenos:
+
+    from cxmanage_api.firmware_package import FirmwarePackage
+    fw_pkg = FirmwarePackage('ECX-1000_update-v1.6.1-2-g279e340.tar.gz')
+
+    from cxmanage_api.fabric import Fabric
+    my_fabric = Fabric('10.20.1.9')
+
+    basic_info = my_fabric.info_basic()
+    for node_num, info in basic_info.items():
+        print 'Node %d Firmware Version: %s' % (node_num, info.version)
+
+    results = my_fabric.is_updatable(package=fw_pkg)
+    if (False in results.values()):
+        print 'The following nodes CANNOT be updated:'
+        print '%s' % [node for node, value in results.items() if value is False]
+    else:
+        print 'Fabric Firmware Update -> %s' % fw_pkg.version
+        my_fabric.update_firmware(package=fw_pkg)
+
+    new_basic_info = my_fabric.info_basic()
+    for node_num, info in new_basic_info.items():
+        print 'Node %d Firmware Version: %s' % (node_num, info.version)
+
+
+The Output
+##########
+
+::
+    Foo Bar Baz
+
+Line by Line Explaination
+#########################
+
diff --git a/cxmanage_api/docs/source/index.rst b/cxmanage_api/docs/source/index.rst
index 8d3a064..a2f56d2 100644
--- a/cxmanage_api/docs/source/index.rst
+++ b/cxmanage_api/docs/source/index.rst
@@ -172,4 +172,5 @@ API Docs & Code Examples
 .. toctree::
 
     Fabric Basics <fab_basics>
+    Firmware Installation Basics <fw_install.rst>