Projet

Général

Profil

Actions
Historique

Projet interface Python Usb à partir d'un module FT245

Statut du wiki : Terminé

Edit du 02/07/2013 : Loi de Murphy oblige, quelques jours après la fin de notre projet, les développeurs de Pyjnius ont corrigé ce jour le bug des paramètres de sortie (mais un peu hâtivement selon nous, nous doutons que tous les cas soient bien pris en compte). Le fichier DriverAdaptor.java pourrait donc probablement être retiré, en modifiant le code Python en conséquence.

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'exploitation 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és à le réaliser.

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.

Structure externe et documentation des fonctions de la bibliothèque

Du point de vue d'un développeur l'utilisant, 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 peut ainsi être résumée par le schéma suivant :

Diagramme pseudo-uml vue externe

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 (docstrings), ainsi qu'à la documentation des fonctions du pilote FTDI.

  • 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îne 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îne 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.

Structure interne de la bibliothèque

La structure décrite 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 quel que 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) :

Diagramme pseudo-uml vue interne et arborescence de la bibliothèque

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 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 classe 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.

Utilisation de la bibliothèque

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 :

# 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()

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.

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'exploitation 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

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.

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 charge 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.

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. 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 :

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

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.

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

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.

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/

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 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.

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.

Icône FTDI Speed Test

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 :

./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

Capture d'écran FTDI Speed Test

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 donnent un débit variant de 60 à 90 KB/s.

Problèmes connus

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

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 :

blacklist ftdi_sio

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

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

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.

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 :

libusb couldn't open USB device /dev/bus/usb/001/015: Permission denied.
libusb requires write access to USB device nodes.

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 insuffisants, 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 : 

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

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.

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.

Annexe : astuces diverses

"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 booléenne Vrai.

Par exemple :

class TestApp(App):

   def on_pause(self):
      return True

Pour plus d'informations, rendez-vous sur la documentation de Kivy à ce sujet

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.

       // go to fullscreen mode
        requestWindowFeature(Window.FEATURE_NO_TITLE);
        //getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
        //                     WindowManager.LayoutParams.FLAG_FULLSCREEN);

Ressources et liens utiles

Mis à jour par Anonyme il y a presque 12 ans · 27 révisions verrouillé