Projets_Etudiants

h1. Projet interface Python Usb à partir d'un module FT245

_Statut du wiki : *En cours de rédaction... 97% fait*_

{{>toc}}

h2. Introduction

L'objectif de ce projet est de réaliser une bibliothèque de fonctions multiplateforme en Python permettant de communiquer avec un périphérique en USB via la puce FTDI 245RL. Cette bibliothèque doit pouvoir être utilisée avec le même code Python sur les principaux systèmes d'exploitations du marché (Windows, Linux, Mac OS X et Android), en fournissant une couche d'abstraction des accès aux différents pilotes correspondants.

Ce projet a été réalisé durant le premier semestre 2013, dans le cadre de notre première année d'étude à l'ISIMA. Il a été suivi par M. Jacques Laffont et M. Clément Jacob, que nous souhaitons tous deux remercier de nous avoir proposé ce projet et de nous avoir aidé à le réaliser.

h2. Systèmes supportés

La bibliothèque que nous avons réalisée est conçue pour fonctionner sur les systèmes suivants :

* Windows XP, Vista, 7 et 8 (32 et 64 bits)

* Android (version 3.1 et ultérieures), sur les terminaux compatibles avec le mode USB Host (également appelé USB On The Go : permet l'utilisation de périphériques USB externes)

* Linux (32 et 64 bits)

* Mac OX X (version 10.5 et ultérieures)

Toutefois, en raison du matériel à notre disposition, nous n'avons pu tester la bibliothèque que sur Windows 7 (32 et 64 bits), Linux (32 bits), Android 4.1.2 et Mac OS X 10.8.

Les contraintes de support de cette bibliothèque sont directement liées à celles des pilotes FTDI sous-jacents. 

Ainsi, pour Android par exemple, l'"API USB Host":http://developer.android.com/guide/topics/connectivity/usb/host.html, permettant de gérer et d’accéder à des périphériques sur une tablette ou un smartphone Android sans privilèges adminitrateur, n'est présente qu'à partir de la version 3.1 de ce système. FTDI fournit un pilote utilisant cette API, ainsi qu'un autre pilote pour les versions précédentes. Toutefois, ce second pilote nécessite des privilèges administrateur (root), ce qui n'est pas possible par défaut sur les terminaux du marché. Nous avons donc choisi d'utiliser le pilote "moderne", utilisant l'API, ce qui restreint quelques peu la compatibilité de la bibliothèque.

De même, les versions de Mac OS supportées sont celles compatibles par le pilote FTDI associé.

h2. Structure externe et documentation des fonctions de la bibliothèque

Du point de vue de son utilisateur, la bibliothèque possède une structure très simple : toutes les méthodes utiles sont regroupées dans une seule et unique classe, portant le même nom que la bibliothèque elle-même (_Xftdi_). Une seconde classe existe toutefois : la classe _XftdiError_. Il s'agit d'une classe d'exception qui peut être levée par toutes les méthodes de la bibliothèque lorsque le code de retour d'une des fonctions du pilote FTDI indique une erreur. Cette exception possède un attribut _errorcode_ qui contient le code de retour de la fonction du pilote ayant échoué, ainsi qu'un attribut _message_ qui peut contenir une description textuelle de l'erreur.

La structure de la bibliothèque, du point de vue d'un développeur l'utilisant, peut ainsi être résumé par le schéma suivant :

p=. !xftdi-uml-externe.png!

p=. _Aspect extérieur de la bibliothèque_

La liste ci-dessous documente succinctement les méthodes publiques de la bibliothèque. Ces méthodes portent souvent le même nom que les fonctions du pilote qu'elles utilisent. Pour une documentation plus détaillée sur une de ces méthodes, nous vous recommandons de vous reporter à son code source (docstring), ainsi qu'à la "documentation des fonctions du pilote FTDI":http://www.ftdichip.com/Support/Documents/ProgramGuides/D2XX_Programmer%27s_Guide%28FT_000071%29.pdf.

* *deviceCount()* : Retourne le nombre de périphériques FTDI connectés

* *listDevices()* : Retourne la liste des numéros de série des périphériques FTDI connectés

* *isAvailable()* : Retourne Vrai si au moins un périphérique FTDI est connecté.

* *isOpen()* : Retourne Vrai si un périphérique FTDI est ouvert.

* *openByIndex(_index_)* : Ouvre un périphérique FTDI identifié par son index. Il est recommandé de vérifier que l'ouverture a fonctionné en appelant la méthode _isOpen()_ après un _open[...]()_

* *openBySerialNumber(_serialNumber_)* : Ouvre un périphérique FTDI identifié par son numéro de série.

* *write(_data_)* : Envoi de données vers le périphérique ouvert. Les données sont une chaînes de caractères non signés. La méthode retourne le nombre d'octets effectivement envoyés.

* *read(_size_)* : Reçoit un paquet de données de taille maximale indiquée en paramètre (_size_) depuis le périphérique précédemment ouvert. Les données sont retournées sous la forme d'une chaînes de caractères non signés. 

* *getQueueStatus()* : Retourne le nombre d'octets disponibles en lecture. Un appel à la méthode _read()_ demandant au plus ce nombre d'octets permet de retourner les données immédiatement (sans blocage).

* *flush(_input=True_, _output=True_)* : Efface les données en attente dans les buffers de lecture (si input est Vrai) et/ou d'écriture (si output est Vrai). Retourne Vrai si l'opération a réussi, Faux sinon.

* *resetDevice()* : Envoi un ordre de réinitialisation du périphérique. Retourne Vrai si l'opération a réussi, Faux sinon.

* *closeDevice()* : Ferme la communication avec un périphérique.

h2. Structure interne de la bibliothèque

La structure présentée précédemment n'est pas réellement la structure complète de la bibliothèque, mais plutôt une "façade" présentée à son utilisateur, grâce à un jeu d'importation. Cela permet d'avoir une interface unique quelque soit la plateforme utilisée.

La structure réelle de la bibliothèque est plus proche du diagramme ci-dessous, qui présente les trois principales classes de la bibliothèque et la classe d'exception, ainsi que l'arborescence des fichiers sources de la bibliothèque et la correspondance entre chaque classe et le fichier dans lequel elle est implémentée (association par rectangle de couleur identique) :

p=. !xftdi-uml-interne-arbo.png!

p=. _Structure interne du code et arborescence des fichiers de la bibliothèque_

En réalité, la bibliothèque est donc composée d'une classe de base, abstraite, nommée _XftdiBase_, qui décrit sans les implémenter l'ensemble des méthodes fournies par la bibliothèque.

Ces méthodes sont ensuite implémentées par deux classes filles : _XftdiPC_ et _XftdiAndroid_. La seconde est conçue pour les terminaux Android, et utilise le pilote Java D2XX fourni par FTDI sous la forme d'un Jar, via Pyjnius qui permet l'appel de ces méthodes Java depuis Python. Ce pilote est lui-même basé sur l'"API USB Host":http://developer.android.com/guide/topics/connectivity/usb/host.html fourni par Google au sein de son système d'exploitation à partir de sa version 3.1. Un second pilote existe pour les versions antérieures de ce système, mais il requiert le plus souvent des privilèges administrateurs sur le terminal (droits root), ce qui est souvent interdit par les constructeurs sous peine d'annulation de la garantie. Pour cette raison, nous avons choisi de ne pas utiliser ce pilote.

La première fonctionne indifféremment sur Windows, Linux ou Mac OS X. En effet, celle-ci est basée sur les pilotes natifs fournis par FTDI (_.dll_, _.so_ ou _.dylib_) qui fournissent tous la même API, et qui peuvent tous être utilisés avec ctypes et un code Python identique. Seul le chargement du pilote correspondant à la plateforme utilisée doit être traité de manière différente selon cette plateforme, ce qui est fait dans le fichier _ftdidrv.py_.

Le choix de l'une de ces deux classes est automatiquement effectué lors de l'importation de la bibliothèque grâce au code écrit dans le fichier spécial ___init__.py_. Ainsi, ce même fichier permet également de masquer cette structure plus complexe en la réduisant à celle présentée dans la section précédente. La classe de base permet quant à elle de garantir une interface commune quelle que soit la plateforme cible.

h2. Utilisation de la bibliothèque

h3. Utilisation basique

Cette abstraction de la structure interne de la bibliothèque permet de simplifier grandement son utilisation. Ainsi, le script suivant montre un exemple d'utilisation basique mais fonctionnel de la bibliothèque Xftdi :

<pre><code class="python">

# Importation de la bibliothèque

from xftdi import Xftdi

# Instanciation de la classe

xftdi = Xftdi()

# Obtention de la liste des numéros de série

# des périphériques compatibles connectés

serials = xftdi.listDevices()

# Si il y a au moins un périphérique disponible

if len(serials) > 0:

    # Ouvre le premier périphérique trouvé

    # à partir de son numéro de série

    xftdi.openBySerialNumber(serials[0])

    # Vérifie que l'ouverture a fonctionné

    if xftdi.isOpen():

        # Envoi d'un message à ce périphérique

        xftdi.write("Hello World")

        # Lecture de sa réponse

        reponse = xftdi.read(50)

        # Fermeture du périphérique

        xftdi.closeDevice()

</code></pre>

Pour que ce script fonctionne, il est bien évidemment nécessaire de placer le dossier de la bibliothèque (xftdi) dans le même dossier que le script lui-même, ou de modifier le path (_sys.path_) de sorte à ce que la librairie soit contenue dans un des dossiers énumérés dans cette variable d'environnement.

h4. Suppression des éléments inutiles en fonction de la plateforme ciblée

Comme nous l'avons montré dans la section précédente, la bibliothèque est divisée en deux blocs principaux : un premier destiné à fonctionner sur PC, un second pour les terminaux Android. Lors de la réalisation d'une application utilisant Xftdi ciblant l'une ou l'autre de ces familles de plateformes, il est possible de supprimer la partie complémentaire de la bibliothèque dans un but d'optimisation de l'espace disque occupé.

Pour cela, il suffit de supprimer le sous-dossier _pc_ du dossier _xftdi_ si votre application est destinée à des terminaux Android, ou le sous-dossier _android_ si votre application est destinée à Windows, Linux ou Mac. Cette manipulation est surtout utile dans le premier cas, où vous pouvez économiser près de 3 Mo pour une application destinée à des terminaux encore souvent limités en capacité de stockage.

Concernant la partie PC, il est également possible d'agir plus finement en supprimant les pilotes natifs non utilisés selon les systèmes d'exploitations PC ciblés. Par exemple, lorsque vous créer le package pour Windows, vous pouvez supprimer sans problème les pilotes pour Linux et Mac OS X présents dans les sous dossiers du dossier _xftdi/pc/native_fdti_drivers_

h3. Modification de l’emplacement des drivers natifs

Les drivers FTDI natifs concernant la partie PC sont disposés par défaut dans des sous-dossiers précis de la bibliothèque. Les chemins de ces pilotes sont incrits "en dur" dans le code de la bibliothèque, relativement à l'emplacement de cette dernière.

Si, pour une raison quelconque, vous souhaitez modifier l'emplacement de ces pilotes, vous devez mettre à jour le code en indiquant le nouvel emplacement de chacun de ces pilotes *dans le fichier _constants.py_*, ainsi que le chemin du pilote Linux dans le fichier _build-ftdidrv.sh_ du dossier _ressources_.

h3. Particularité du fichier ftdidrv.py

Le fichier _ftdidrv.py_ (partie PC) a la particularité d'être généré automatiquement à l'aide du script bash _build-ftdidrv.sh_ (dossier _ressources_). *Il est donc important de ne pas le modifier manuellement*, car ces modifications seront écrasées lors de la prochaine exécution du script.

Ce fichier fournit une première couche d’abstraction des pilotes natifs fournis par FTDI. Il contient une classe FtdiDriver qui est chargée de charger le pilote PC adapté au système d'exploitation, et qui encapsule l'appel à chacune des fonctions de ce dernier en vérifiant le code de retour à l'aide d'un décorateur, et en levant une exception _FtdiError_ si nécessaire.

Toutes les fonctions exportées par le pilote sont présentes grâce à la génération automatique à partir d'une commande Bash : strings. Cette commande permet de lister les chaines de caractères présentes dans un binaire. Grâce à un filtre simple, il est possible d'obtenir la liste des fonctions disponibles (elles commencent toutes par FT_ ). A partir de cette liste, le script génère le code Python correspondant pour chacune des fonctions.

Si vous souhaitez modifier la première partie de ce fichier source (importations, déclaration de la classe, constructeur et méthode _loadDriver()_), vous devez le faire non pas dans le fichier lui même, mais dans le script bash que vous devez ensuite exécuter à nouveau pour mettre à jour le code Python.

h3. Création d'une application Kivy pour Android

En raison des dépendances de la bibliothèque Xftdi, la création d'une application Kivy pour Android utilisant la bibliothèque Xftdi requiert quelques étapes supplémentaires par rapport à la procédure habituelle décrite dans la "documentation de Kivy":http://kivy.org/docs/guide/packaging-android.html. Avant de lire cette section, nous vous recommandons de vous reporter sur cette documentation.

Tout d'abord, il faut commencer par créer une distribution Kivy, comme indiqué dans la documentation. Xftdi utilise le module Pyjnius, ce dernier doit donc impérativement apparaitre dans l'option -m :

<pre>./distribute.sh -m "pyjnius kivy" -d <Chemin de la distribution à créer></pre>

Xftdi a également besoin du pilote Java D2XX de FTDI pour fonctionner sur Android. Ce pilote doit être inclus dans l'APK final. Pour cela, copiez le fichier _ftdi_d2xx_android_driver.jar_, que vous trouverez dans le dossier ressources de la bibliothèque Xftdi, vers le dossier libs de la distribution.

<pre>cp <Chemin de Xftdi>/ressources/ftdi_d2xx_android_driver.jar <Chemin de la distribution>/libs/</pre>

Vous devez ensuite copier le fichier _DriverAdaptor.java_ du dossier ressources dans le sous-dossier src/fr/isima/xftdi/android de la distribution, en ayant préalablement créer les éventuels dossiers manquants.

<pre>

mkdir -p <Chemin de la distribution>/src/fr/isima/xftdi/android

cp <Chemin de Xftdi>/ressources/DriverAdaptor.java <Chemin de la distribution>/src/fr/isima/xftdi/android/

</pre>

En ayant pris soin de disposer le module Xftdi dans le même dossier que votre application (ou dans un dossier déclaré dans le _PYTHONPATH_), vous pouvez maintenant lancer le script _build.py_ comme indiqué dans la documentation de Kivy, puis utiliser ADB pour installer votre application sur votre terminal.

Le fichier _DriverAdaptor.java_ est un adaptateur permettant de contourner un bug de Pyjnius. Les méthodes Java utilisant des paramètres de sortie ne fonctionnent pas correctement avec Pyjnius : les valeurs assignées à ces paramètres lors de l’exécution du code Java ne sont pas reportées par Pyjnius dans les variables Python après l'appel aux méthodes en question. Pour plus d'informations et des exemples sur ce bug, vous pouvez consulter le "rapport de bug":http://github.com/kivy/pyjnius/issues/58 que nous avons soumis au développeur de Pyjnius à sa demande suite à une conversation IRC.

Pour contourner ce bug, nous utilisons un bout de code Java permettant d'encapsuler l'appel à des méthodes Java utilisant des paramètres de sortie en redirigeant chacun de ces paramètres vers un attribut de classe Java. Nous pouvons ainsi ensuite appeler depuis Python via Pyjnius la méthode encapsulante en lieu et place de la méthode encapsulée, et récupérer ensuite les valeurs de sortie dans les attributs de classe.

h2. Application de démonstration : FTDI Speed Test

Afin de montrer un exemple d'utilisation de la bibliothèque Xftdi sur Android, nous avons réalisé une application de démonstration permettant de mesurer approximativement le débit de la communication USB. Nous avons nommé cette application _FTDI Speed Test_.

p=. !icon_128px.png!

p=. Icône de l'application

Le code source de cette application est stocké dans le dossier _demo_ du dépôt SVN. La création de l'APK se déroule comme cela a été décrit dans la section précédente, avec une commande build.py semblable à celle-ci :

<pre>./build.py --dir <Chemin de Xftdi>/demo/ 

           --name "FTDI Speed Test"  

           --package "fr.isima.xftdi.speedtest"  

           --orientation portrait  

           --icon <Chemin de Xftdi>/demo/icon.png  

           --version 1.0.0 

           clean debug installd

</pre>

p=. !Screenshot1.png!

p=. Capture d'écran de FTDI Speed Test

L'application se présente sous la forme d'un simple écran offrant le choix du nombre de paquets à envoyer et de la taille de chacun de ces paquets. L'envoi de plusieurs paquets permet d'effectuer une mesure moyennée qui sera donc plus précise.

Les mesures effectuées sur le téléphone de développement et à partir de la VM Kivy donne un débit variant de 60 à 90 KB/s.

h2. Problèmes connus

h3. Conflit avec le module ftdi_sio sur Linux

Lorsque le module ftdi_sio est chargé, le périphérique USB ne peut plus être ouvert avec l'application utilisant Xftdi : une exception DEVICE_NOT_OPENED est lancée. Il s'agit en fait d'un problème déjà répertorié dans le "README du pilote FTDI":http://www.ftdichip.com/Drivers/D2XX/Linux/ReadMe-linux.txt

Une solution simple consiste à blacklister ce module en ajoutant dans /etc/modprobe.d/blacklist (créer le fichier s'il n'existe pas) la ligne suivante :

<pre>blacklist ftdi_sio</pre>

Pour cela, vous pouvez par exemple lancer cette commande dans un terminal administrateur :

<pre>echo "blacklist ftdi_sio" >> /etc/modprobe.d/blacklist </pre>

Il est également possible de retirer temporairement le module à l'aide de la commande _rmmod ftdi_sio_, mais cette manipulation devra être renouvelée très régulièrement.

h3. Permissions d'accès au périphérique sur Linux

Si vous ne parvenez pas à ouvrir le périphérique à cause d'une exception DEVICE_NOT_FOUND, éventuellement accompagné d'un message similaire à celui-ci :

<pre>libusb couldn't open USB device /dev/bus/usb/001/015: Permission denied.

libusb requires write access to USB device nodes.

</pre>

Vérifiez que vous possédez les droits de lecture et d'écriture sur le fichier spécial pointé par le message précédent (ici _/dev/bus/usb/001/015_). Si vous ne voyez pas ce message, tentez d'identifier le fichier en examinant les logs du noyau (commande dmesg), ou en comparant les fichiers existants avant et après avoir branché le périphérique.

Si les droits sont insuffisant, vous pouvez dans un premier temps les modifier simplement à l'aide de _chmod_, puis relancer l'application pour vérifier si le problème est résolu. Toutefois, cette procédure devra être renouvelée à chaque branchement du périphérique, car le fichier spécial est recréé à chaque fois.

Pour éviter cela, une solution définitive consiste à modifier les règles de _udev_ afin que le périphérique soit accessible à tous les utilisateurs Unix de l'application. Pour cela, lancer la commande suivante dans un terminal administrateur : 

<pre>

echo 'ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"' >> /etc/udev/rules.d/80-ftdiusb.rules

</pre>

Ici, la ligne permet de donner les droits de lecture/écriture à tout le monde. D'autres options permettent de créer un groupe associé au périphérique par exemple. Pour plus d'informations, veuillez vous reporter sur le manuel de _udev_.

h2. Conclusion

Ce projet nous a permis de fonder une bibliothèque de fonctions évolutive, fournissant les procédures de base permettant la communication avec un périphérique USB utilisant un module FT245RL. Toutefois, toutes les fonctions fournies par les pilotes FTDI n'ont pas été reflétées dans notre bibliothèque Python, nous avons sélectionné celles qui nous semblaient être les plus indispensables. Cependant, nous avons pris le soin de concevoir la structure de cette bibliothèque de manière à ce qu'elle puisse aisément être étendue au gré des besoins.

Plusieurs améliorations peuvent être envisagées. Tout d'abord, il ne semble pas difficile d'ajouter la compatibilité avec Windows Mobile (5 à 6.5), car FTDI fournit également un pilote pour ce système. Les chemins des pilotes natifs pour PC pourrait également être soit déplacé dans un fichier de configuration, soit passé par argument pour plus de souplesse.

Enfin, ce projet nous a également permis d'apporter notre modeste contribution à deux projets Open Source via GitHub (Pyjnius et Kivy Remote Shell), par le dépôt d'un ticket de bug et la proposition de quelques lignes de codes pour en corriger un second.

h2. Annexe : astuces diverses

h3. "Plantage" d'une application Kivy lors de la demande de permissions d'Android

Lorsque vous connectez le périphérique USB FT245RL à votre terminal Android avec une application Kivy utilisant la bibliothèque Xftdi, une demande de permission apparait sous la forme d'un popup dès que cette application tente de communiquer avec le périphérique en question. Il peut alors arriver que l'application Kivy semble "planter".

En réalité, et plus généralement, une application Android est mise en pause dès qu'elle n'est plus affichée en premier plan, ce qui est le cas lorsque le popup s'affiche. Le comportement par défaut d'une application Kivy lors de cette mise en pause est de s’arrêter purement et simplement. Pour modifier ce comportement, vous devez redéfinir la méthode _on_pause_ dans la classe dérivant de _App_ de sorte à ce qu'elle retourne la valeur binaire Vrai.

Par exemple :

<pre><code class="python">

class TestApp(App):

   def on_pause(self):

      return True

</code></pre>

Pour plus d'informations, rendez-vous sur la "documentation de Kivy à ce sujet":http://kivy.org/docs/api-kivy.app.html#pause-mode 

h3. Désactiver le plein écran d'une application Kivy

Par défaut, une application Kivy s’exécute en plein écran sur le terminal de l'utilisateur (la barre de notifications n'est pas visible). Pour désactiver ce comportement, il faut supprimer (ou commenter) les lignes 108, 109 et 110 du fichier src/org/renpy/android/PythonActivity.java, que vous trouverez à partir du dossier de la distribution généré par Kivy (après le distribute.sh). Vous pouvez tout de même laisser la ligne 108 active si vous ne souhaitez pas voir apparaître la barre de titre de l'application.

<pre><code class="java">

       // go to fullscreen mode

        requestWindowFeature(Window.FEATURE_NO_TITLE);

        //getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,

        //                     WindowManager.LayoutParams.FLAG_FULLSCREEN);

</code></pre>

h2. Ressources et liens utiles

* "Page de téléchargement des pilotes FTDI":http://www.ftdichip.com/Drivers/D2XX.htm

* "Documentation des pilotes FTDI pour les programmeurs":http://www.ftdichip.com/Support/Documents/ProgramGuides/D2XX_Programmer%27s_Guide%28FT_000071%29.pdf

* "Documentation de l'API USB Host d'Android":http://developer.android.com/guide/topics/connectivity/usb/host.html

* "Ticket de bug déposé sur le GitHub de Pyjnius concernant les paramètres de sortie":http://github.com/kivy/pyjnius/issues/58

* "Application Kivy Remote Shell":https://github.com/kivy/kivy-remote-shell, très utile pour le développement Python sur Android.