FIXME **This page is not fully translated, yet. Please help completing the translation.**\\ //(remove this paragraph once the translation is finished)//

====== Universal communication library pymlab ======

It is software package wich allows creation of sensor network based on RS232, I²C, Ethernet and USB interfaces. It is the first experimental implementation of [[en:pdn|polymorphous device network]].

The function principle is based on definig of the network structure and addresses of each network node. Whole configuration is described in configuration file of the control software which is usually writen in Python.
Physical routing between I2C bus segments which contains sesnors with the same i2c addersses, is realised by [[cs:i2chub|I2Chub02A]] modules. 
Source files of the library and use examples you can found in  [[https://github.com/MLAB-project/MLAB-I2c-modules|pyMLAB repository]] at MLAB group on Github.

The result is a opportunity  to test and demonstrate every new sensor and device without need of maintain specific sourcefiles for every used MCU. It brings code independence on mictrocontroler architecture even in case if firmware generation will be possible from Python source code. 

===== Installation =====

If you use Python package version of pymplam you should execute this command.

  sudo easy_install pymlab
  
or 
  sudo pip install pymlab

Both commands are equivalent and uses the  [[https://pypi.python.org/pypi/pymlab/|python packaging system]]. Intallation procedury automatically installs dependencies. But it cannot install libusb which needs to be installed manually.

  sudo apt-get install libudev-dev libusb-1.0-0-dev libhidapi-dev python-setuptools python-smbus cython 

If you need to use USB as connetion interface for the device you should use the [[en:usbi2c|USBI2C01A]] module. The module needs hidapi software interface and other dependencies.


==== Development version ====

Up to date version of pymlab library is on gitbub. We should install it in the system in order of the library development. 

  git clone https://github.com/MLAB-project/MLAB-I2c-modules.git
  git checkout dev
  sudo python setup.py develop

User usualy needs permissions to access the I²C and USB bus. Therefore user must be added to i2c group by:
  sudo adduser kaklik i2c
 
The change will take effect on a next user login.
===== TODO =====

==== Graphical interface ====
Graphical interface to the pymlab library will be usefull for defining of network topology and ploting of graphs from sensors connected to network. One possible software which could be used is [[http://www.pyqtgraph.org/|PyQtGraph]].

{{ :cs:sw:flowchart.png?direct&500 |}}

===== ARM STM32 Python interpreter ====

The latest version of Pymlab is compatible with the [[https://micropython.org/|MicroPython]] interpretation of Python. Testing has been performed on the [[http://docs.micropython.org/en/latest/pyboard/pyboard/quickref.html|Pyboard v1.0]] ([[http://www.st.com/en/microcontrollers/stm32f405rg.html|STM32F405RG]] processor) and [[https://github.com/micropython/micropython/tree/v1.9.3|version 1.9.3 of MicroPython]].

=== Example ===

<file python main.py>
import pymlab.config

cfg = pymlab.config.Config(i2c={"device": "machine", "port": 1, "freq": 100000},
                           bus=[{"name": "altimet", "type": "altimet01"},
                                {"name": "light", "type": "isl03"},
                                {"name": "sht", "type": "sht31"}])
cfg.initialize()

altimet = cfg.get_device("altimet")
altimet.route()
light = cfg.get_device("light")
light.config(0x0000)
sht = cfg.get_device("sht")
sht.soft_reset()

t1, p = altimet.get_tp()
l = light.get_lux()
t2, h = sht.get_TempHum()
</file>

=== Tips & Tricks ===

Resources (Flash and RAM) embedded systems are typically quite limited, the whole pymlab module does not fit to the flash memory available on the [[http://docs.micropython.org/en/latest/pyboard/pyboard/quickref.html|Pyboard]] for example.

Fortunately MicroPython provides cross compiler that allows us to compile the source code to bytecode and therefore reduce the RAM and flash usage.

Version of the cross compiler must match the version of MicroPython running on your board. If in doubt just compile and flash your board with firmware compiled from the same branch of the [[https://github.com/micropython/micropython#the-stm32-version|MicroPython repository]] as the cross compiler, instruction can be found at [[https://github.com/micropython/micropython#the-stm32-version|https://github.com/micropython/micropython#the-stm32-version]].

<code sh>
$ git clone https://github.com/micropython/micropython
$ cd micropython
$ git checkout UPY_VERSION # This is very important!
$ # Optional compiling and flashing of the firmware
$ cd mpy-cross
$ make
</code>

In  Makefile at [[https://github.com/MLAB-project/pymlab/blob/master/src/pymlab/Makefile|pymlab/src/pymlab/Makefile]] edit the path to the cross compiler, mountpoint of the flash memory and devices you wish to use as all drivers are still to much for the limited space on the Pyboard. The just type

  make deploy

and you are good to go.