Summary: Added some docs

git-svn-id: https://redmine.imt-atlantique.fr/svn/xaal/code/Python/trunk@1886 b32b6428-25c9-4566-ad07-03861ab6144f

libs/lib/README.rst

@@ -4,7 +4,6 @@ xaal.lib
 xaal.lib is the official python stack to developp home-automation devices
 and gateways with the xAAL protocol.
 
-
 For a full description of the protocol check out
 http://recherche.imt-atlantique.fr/xaal/
 
@@ -20,3 +19,86 @@ But ujson compiled by hand (with pip install ie), will lead in a slow startup.
 I'm unable to know exactly why. Using package distribution is really recommended.
 If you can't, simply use json in place.
 
+
+Install
+~~~~~~~
+Please refer to the official full documentation to install the lib in a virtualenv.
+https://redmine.telecom-bretagne.eu/projects/xaal/repository/entry/code/Python/trunk/README.rst
+
+
+Usage
+~~~~~
+The main goal of xaal.lib is to provide an API to easily develop devices & gateways.
+xaal.lib.Engine send / receive / parse to|from xAAL Bus.
+
+
+To receive / parse / display incoming xAAL messages, you can simply try something like
+this.
+
+.. code::
+   from xaal.lib import Engine
+
+   def display(msg):
+       print(msg)
+
+   eng = Engine()
+   eng.add_rx_handler(display)
+   eng.run()
+   
+The Engine will call the display function every time it receive a xAAL message.
+
+Let's take a look at a simple lamp device : 
+
+.. code:: 
+   from xaal.lib import Device,Engine,tools
+   
+   # create and configure the lamp device, with a random address
+   dev = Device("lamp.basic", tools.get_random_uuid()) 
+   dev.product_id = 'Dummy Lamp'
+   dev.url  = 'http://www.acme.org'
+   dev.info = 'My fake lamp'
+
+   # add an xAAL attribute 'light'
+   light = dev.new_attribute('light')
+   
+   # declare two device methods ON & OFF
+   def on():
+       light.value = True
+
+   def off():
+       light.value = False
+       
+   dev.add_method('on',on)
+   dev.add_method('off',off)
+
+   # last step, create an engine and register the lamp
+   eng = Engine()
+   eng.add_device(dev)
+   eng.run()
+   
+   
+FAQ
+~~~
+The core engine run forever so how can I use it in webserver, GUI or to develop device
+with IO. The whole API is absolutely not thread safe, so don't use thread unless you
+exactly know what's going on. Anyways, you have several options for fix this issue:
+
+* You can use you own loop and periodically call *eng.loop()*
+  for example, you can do something like this:
+  
+  .. code::
+     while 1:
+         do_some_stuff()
+         eng.loop()
+
+* You can use a engine timer, to perform some stuff.
+  
+  .. code::
+     def read_io():
+         pass
+
+     # call the read_io function every 10 sec
+     eng.add_timer(read_io,10)
+
+* Use an async lib, you can use asyncio or greenlet for example. Look at apps/rest for
+  a simple greenlet example.