IMA4 2019/2020 EC1
Objectif
Vous allez travailler sur une carte de développement ATXMEGAC3-XPLD. L'idée est de refaire le tutorat système sur cette carte.
Vous aurez donc à écrire un programme C sur PC avec la libusb-1.0 et à écrire un programme pour le micro-contrôleur ATXmega384C3 avec la LUFA.
Coté périphérique USB vous devez implanter une configuration avec une interface IN pour les deux boutons mécanique de la carte, une interface OUT pour les deux LED orange et une interface OUT pour les LED verte et rouge.
Coté PC vous devez écrire un programme qui attend une pression sur un bouton mécanique et qui déclenche un chenillard sur les 4 LED. Le chenillard s'arrête sur pression du second bouton mécanique.
Environnement de travail
Le matériel a été reçu le 09/04/2020 : il s'agit bien d'une carte de développement ATXMEGAC3-XPLD ainsi qu'une carte micro-SD de 8GB et le câble USB qui va avec.
Tout le travail sera effectué sous Linux, plus précisément avec la distribution Ubuntu. Ci-dessous, vous pourrez retrouver un aperçu des fonctionnalités de la carte :
Cahier des charges
Durant cette épreuve, je vais me servir de la board XMEGA-C3 Xplained comme un périphérique USB spécifique. Je vais devoir gérer les Endpoints pour que ma carte communique avec mon PC. Afin de réaliser toutes les tâches attendues, il va falloir procéder en plusieurs étapes :
- Lire l'état de mes I/O et sauver les points d'accès : Pour se faire, il va falloir implanter une configuration avec la librairie libusb-1.0 :
Interface IN : un seul point d'accès (sens Hôte vers Périphérique)
Elle me permettra d'écrire une donnée sur l'Endpoint et la recevoir sur mon PC pour connaître l'état de ma carte.
Interface OUT : deux points d'accès (sens inverse)
Cette interface servira à lire les données sur les Endpoints depuis l'Atxmega384c3. Ces données seront envoyées depuis le PC.
- Gestion des LEDs et du chenillard en C : Pour programmer le microcontrôleur, la LUFA me permettra de gérer l'USB et les Endpoints sans passer par les registres. Pour téléverser mon programme, je me servirai de l'utilitaire dfu-programmer.
Je pourrai alors créer une communication bi-directionnelle via deux applications : HOST vers DEVICE ainsi que DEVICE vers HOST.
Travail réalisé
Programme de l'ATXMEGA384C3
Implantation USB
Pour commencer, il faut implanter un périphérique USB. Tout le projet sera inspiré de la démonstration KeyBoard dans le répertoire Device/LowLevel/Keyboard de la LUFA.
Pour que le programme fonctionne avec la carte, je peux adapter le fichier makefile de la façon suivante :
Les fréquences choisies sont propres à la board.
Je peux maintenant adapter Descriptors.h à mon application. Je déclare, comme ci-dessous, mes trois interfaces dans une structure :
USB_Descriptor_Interface_t Binterface; USB_Descriptor_Endpoint_t EPIN; USB_Descriptor_Interface_t L1interface; USB_Descriptor_Endpoint_t EPOUT1; USB_Descriptor_Interface_t L2interface; USB_Descriptor_Endpoint_t EPOUT2;
Puis l'ID de chaque interface :
enum InterfaceDescriptors_t{
BOUTONS_ID = 0,
LEDS1_ID = 1,
LEDS2_ID = 2,
}
Enfin, il faut définir l'adresse et la direction de chacun de mes endpoints ainsi que leur taille (en bits):
#define BOUTONS_EPADDR (ENDPOINT_DIR_IN | 1) #define LEDS1_EPADDR (ENDPOINT_DIR_OUT | 1) #define LEDS2_EPADDR (ENDPOINT_DIR_OUT | 2) #define EPSIZE 8
Comme vous pouvez le voir, nous allons utiliser 1 Endpoint IN pour les boutons et 2 Endpoints OUT pour les LEDs.
Dans mon fichier Descriptors.c , j'inclus Descriptors.h. Je peux alors renseigner les VendorID et ProductID de ma board ainsi que déclarer mes interfaces et points d'accès. La XMEGAC3 XPLAINED sera finalement reconnue comme un périphérique USB avec les interfaces définies grâce à la fonction USB_USBTask() de la boucle principale de mon programme chenillard.c.
Gestion des Endpoints
Dans mon fichier chenillard.h, je définis tous les mask correspondant aux LEDs qui m'intéressent. Dans le chemin suivant, je retrouve la déclaration de chacune des LEDs :
LUFA/Drivers/USB/XMEGA/C3_XPLAINED/LEDS.h
Puis je déclare mes fonctions prototypes qui me serviront pendant ce projet. Voici mon chenillard.h final :
Dans mon chenillard.c, ma fonction principale main() configure ma XMEGAC3 XPLAINED et appelle mes fonctions dans une boucle infini pour gérer continuellement les Endpoints.
Dans SetupHardware(), je prends uniquement en compte la condition suivante pour que le programme soit adapté à ma carte :
#if (ARCH == ARCH_XMEGA) ... #endif
Puis j'initialise toutes mes I/O avec les fonctions LEDs_Init(), USB_Init() et Buttons_Init(). Je peux maintenant créer mes applications et gérer mes Endpoints :
- Mes fonctions LEDS_RV() et LEDS_OR() me permettent de gérer les Endpoints OUT de mes LEDs. Ces fonctions sélectionnent le point d'accès avec la fonction Endpoint_SelectEndpoint(). Lorsqu'il est prêt, nous pouvons lire la donnée data qui lui est attribuée. Selon sa valeur, les LEDs peuvent s'allumer ou s'éteindre. Il ne faut pas oublier la fonction Endpoint_ClearOUT() en fin d'action pour libérer le point d'accès et le rendre prêt lors les futurs échanges de données.
- Ma fonction BOUT_IN() sélectionne l'Endpoint correspondant et attend la pression d'un bouton lorsqu'il est prêt; avec la fonction Buttons_GetStatus(). Les boutons correspondants à ma XMEGAC3 XPLAINED peuvent être retrouvés dans le répertoire suivant :
LUFA/Drivers/Board/XMEGA/C3_XPLAINED/Buttons.h
Je crée une donnée data qui prend la valeur 1 lorsque le bouton 1 (SW0) est appuyé. Grâce à la fonction Endpoint_Write_8() je peux finalement écrire la donnée dans le point d'accès, qui va être lue par le PC. Après avoir libéré le point d'accès avec Endpoint_ClearIN(), le chenillard se lance.
- Ma fonction chenillard() lance un chenillard dans une boucle infini, avec les LEDs de la XMEGAC3 XPLAINED. Lors de l'appui du bouton 2 (SW1) de la board, l'endpoint des boutons est sélectionné. Le programme attend que le point d'accès soit libre et prêt puis crée une donnée data qui prend la valeur 2. Je peux également l'écrire sur l'endpoint avec la même fonction Endpoint_Write_8(), sans oublier de le libérer avec Endpoint_ClearIN() juste après.
Programme du PC
Reconnaissance USB
Pour utiliser la XMEGAC3 XPLAINED comme un périphérique USB, il faut le reconnaître parmi tous les périphériques de la machine. Grâce à la commande suivante, je peux facilement reconnaître les caractéristiques (VendorID et ProductID) de la carte :
lsusb
Je crée alors une fonction enum_usb() qui reconnaîtra le périphérique pour la suite des opérations et qui ne se soucis pas des autres :
Je peux ensuite sauver la "poingée" dans une variable globale de type libusb_device_handle *, et sauver le périphérique dans un variable globale my_device grâce à la fonction libusb_get_device().
Il faut ensuite configurer notre périphérique USB. Je crée une fonction configuration() qui permettra, dans un premier temps, de récupérer la première configuration de la carte via un pointeur sur périphérique libusb_device *. Dans un second temps, je peux afficher cette configuration et la déclarer comme courante.
Pour éviter que le méchant noyau passe avant moi, il faut détacher le "driver". Je crée alors une fonction detach qui inclura libusb_detach_kernel_driver. Je peux maintenant récupérer et sauver les endpoints.
Gestion des Endpoints
Grâce à la commande suivante, je peux retrouver le parcours de l'arbre arborescent et les paramètres qui m'intéressent :
lsusb -D /dev/bus/usb/001/00x
Avec x le numéro correspondant à l'adresse du périphérique (retrouvé avec lsusb).
Ainsi je peux retrouver les 3 interfaces du périphérique avec les endpoints correspondants, que j'ai déclaré dans le programe de l'Atxmega384c3. Toujours dans ma fonction configuration(), je peux réclamer les interfaces et parcourrir tous les Descriptors. Connaissant les addresses de mes Endpoints, je peux facilement les sélectionner pour les enregistrer dans des tableaux ep_in et ep_out. Voici le résultat final de ma configuration :
Maintenant que tout est en place, nous pouvons créer nos 2 applications qui correspondent à deux types de communication :
- HOST vers DEVICE : L'utilisateur peut gérer les LEDs de la XMEGAC3 XPLAINED grâce à son clavier.
- DEVICE vers HOST : L'utilisateur peut activer ou désactiver un chenillard via les boutons SW1 et SW0 et vérifier son état directement sur son PC.
Le programme demande alors quelle communication l'utilisateur souhaite appliquer. Lorsque l'utilisation de ces applications est terminée, je peux libérer les interfaces, re-attacher le driver, fermer le périphérique et désinitialiser la librairie avec les fonctions :
libere(); attach(); libusb_close(handle); libusb_exit(context);
Communication HOST vers DEVICE
Pour ce premier choix, le programme renvoi à la fonction keyboard(). Ici, je vais m'intéresser aux Endpoints OUT des LEDs. La fonction libusb_interrupt_transfer() me permettra alors d'écrire une donnée data sur le point d'accès. Pour cela, j'utilise la fonction getchar() qui attend l'entrée de caractères sur le terminal et qui sera lue par le programme de l'Atxmega384c3 lorsqu'il correspond.
Le modèle d'écriture sur point d'accès avec la librairie libusb-1.0 est la suivante :
if((data[0] == 'x')){
int status_interrupt = libusb_interrupt_transfer(handle,endpoint,data,length,transferred,timeout);
if(status_interrupt!=0){perror("libusb_interrupt_transfer");}
}
Communication DEVICE vers HOST
Ici, le programme renvoi à la fonction lecture(). En effet, je m'intéresse à l'Endpoint IN des boutons qui écrivent des données sur les points d'accès. L'objectif sera alors de récupérer ces données pour les transmettre à la machine. J'utilise toujours la fonction libusb_interrupt_transfer(), mais cette fois pour lire la donnée data reçu par l'Atxmega384c3. Cette fonction est capable de lire ou d'écrire grâce à la direction déterminée du point d'accès endpoint en paramètre. Voici le modèle de lecture d'Endpoint avec la librairie libusb-1.0 :
int status_interrupt = libusb_interrupt_transfer(handle,endpoint,data,length,transferred,timeout);
if(status_interrupt!=0){perror("libusb_interrupt_transfer");}
if((data[0] == 'x')){printf("donnée reçu");}
}
Je vais donc m'en servir pour connaître l'état du chenillard directement sur le PC. Nous avons vu précédemment que data prend la valeur 1 lors de l'appui de SW0 et 2 pour SW1. Donc lorsque data vaut 1, le chenillard est actif mais désactivé si elle vaut 2.
Optimisation et limites
Pour améliorer mes programmes, certaines modifications ont été effectuées :
- Tous les codes en commentaires ont été supprimés
- Dans le programme du PC, je me passe de libusb_open_device_with_vid_pid() et libusb_get_device(). Je peux donc optimiser le code dans enum_usb avec :
int status_open = libusb_open(device,&handle);
if(status_open!=0){
perror("libusb_open");
exit(-1);
}
my_device = device;
- Dans le programme de l'Atxmega384c3, l'implantation de mon chenillard via la fonction chenillard() bloquait la gestion USB de la carte. En effet, l'utilisation de _delay_ms() rend le micro-contrôleur indisponible pendant un temps donné. J'ai donc décidé d'appeler des variables globales pour la gestion d'état de mes LEDs et de mes boutons, dans la boucle principale du programme.
En ce qui concerne le chenillard, je crée un compteur de type long int pour éviter un "overflow". Tant que la valeur finale du compteur n'est pas atteinte, la LED reste allumée. Sinon elle s'éteint et la LED suivante s'allume. Lorsque le bouton 2 est appuyé, le chenillard s'arrête.
Limites :
- Le mouvement du chenillard semble plus saccadé (on dirait que pour allumer une LED, elle attend que la précédente s'éteigne). Sans en être sûr, je pense que c'est dû à la valeur finale de mon compteur que j'ai choisi par tâtonnement. Il y a sûrement un lien avec la fréquence du CPU. Lorsque je change mon compteur, le chenillard devient invisible à l'oeil nu ou "constant" (toutes les LEDs allumées) selon sa valeur. Comment trouver une valeur optimale ?
- L'état -1 de ma variable globale etat indique aux LEDs de s'éteindre. Cette valeur est appelée lorsque le deuxième bouton est appuyé. Cependant, il semblerait qu'à certains moments, une LED reste allumée avec l'appui de ce bouton. En revanche, lorsque j'utilise directement la fonction LEDs_TurnOffLEDs() pour éteindre toutes les LEDs, cela fonctionne très bien. Je n'ai pas réussit à expliquer cette différence.
Résultat Final
- Communication HOST vers DEVICE
Ci-dessous vous pouvez retrouver un exemple d'utilisation de la gestion des LEDs via le clavier d'une machine :
Comme vous pouvez remarquer, il est possible d'entrer plusieurs commande à la fois. L'état des LEDs sera toujours indiqué.
- Communication DEVICE vers HOST
Ci-dessous vous pouvez retrouver l'enregistrement des états du chenillard directement sur la machine :
Vous pourrez remarquer que son état est donné de manière périodique, pour permettre de le récupérer à n'importe quel moment.
