Dependencies

xaal.lib depends on :

• ujson

• pysodium

• configobj

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:

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 :

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 threads unless you exactly know what's going on. Anyways, you have several options to fix this issue:

• You can use you own loop and periodically call eng.loop() for example, you can do something like this:

  while 1:
      do_some_stuff()
      eng.loop()

• You can use a engine timer, to perform some stuff.

  def read_io():
      pass
  
  # call the read_io function every 10 sec
  eng.add_timer(read_io,10)
  eng.run()

• Use an async lib, you can use asyncio or greenlet for example. Look at apps/rest for a simple greenlet example.