Tutorat système IMA4 (USB et ATMega32u4)

Julien Forget, Xavier Redon et Thomas Vantroys

2021 - 2022

1 Objectif

Le but de ce tutorat est de comprendre le fonctionnement du bus USB par la pratique. Pour cela, vous allez utiliser une carte spécifiquement conçue pour ce tutorat à base de microcontrôleur ATMega32u4. Vous trouverez de précieuses informations sur cette carte à l’URL https://wiki-ima.plil.fr/mediawiki/index.php/IMA4_2018/2019_SEC4.

Vous aurez à programmer la carte comme périphérique USB de type joystick. Vous aurez aussi à programmer utilitaire sur PC avec la libusb-1.0 pour gérer les LED et les vibreurs de la carte.

2 Matériel

Pour le tutorat vous disposerez d’une carte manette Polytech’Lille et de son câble USB. Si vous manipulez correctement, vous n’aurez besoin d’aucun autre matériel. En cas de microcontrôleur non initialisé ou briqué, il est toujours possible de flasher l’ATMega32u4 au travers de son connecteur ICSP. Un connecteur ICSP dispose de toutes les lignes permettant de flasher un ATMega, à savoir l’alimentation, le reset et les lignes du bus SPI. Si vous en arrivez là, il vous faudra un Arduino à utiliser comme programmateur et quelques câbles pour connecter l’Arduino à la manette. Référez-vous au site de la manette pour le détail de la procédure.

La carte comporte un accéléromètre que vous allez utiliser durant ce tutorat. Le PCB de la carte comporte une erreur concernant l’accéléromètre, laquelle ? Comment ce bogue de conception de la carte a-t-il été corrigé ?

3 Programmation

Vous allez devoir écrire deux programmes.

Vous devez programmer l’ATMega32u4 pour gérer le bus USB et implanter un périphérique USB. Vous utiliserez avr-gcc comme compilateur C. Le téléchargement du programme sur le microcontrôleur se fera en utilisant l’utilitaire dfu-programmer capable de programmer l’ATMega32u4 via le bus USB. Vous n’aurez pas à programmer directement les registres de l’ATMega32u4 pour gérer l’USB, vous utiliserez une bibliothèque nommée LUFA.
Il faut aussi écrire un programme C conventionnel sur le PC pour utiliser les LED et les vibreurs de votre manette. Ce programme est compilé par gcc et utilise la bibliothèque USB libusb-1.0. Votre programme pourra être intégré à un jeu pour afficher des informations sur les LED comme le nombre de vies restantes. Une intégration plus poussée consiste à faire vibrer la manette sur certains événements comme la perte d’une vie.

4 Périphérique USB

Il s’agit du point le plus délicat du tutorat, la programmation du comportement USB de la manette. Cela va se faire sur le microcontrôleur ATMega32u4. Comme le u de son nom l’indique, ce microcontrôleur possède une gestion matérielle du bus USB (USB2.0).

Sur le principe vous devez implanter un périphérique USB HID (périphérique d’interface homme-machine, Human Interface Device en patoi). Un tel périphérique comporte une interface de classe HID avec au minimum un point d’accès entrant (IN). Plutôt que d’utiliser le joystick de la carte pour votre HID, vous utiliserez l’accéléromètre.

Vous allez ajouter à ce périphérique USB une interface supplémentaire pour gérer les LED et les vibreurs. L’interface supplémentaire doit présenter un point d’accès de type interruption en écriture (endpoint OUT). Les données envoyéies sur ce point d’accès doivent avoir une taille de deux octets. Organisez les bits correspondant aux LED et aux vibreurs comme vous l’entendez.

4.1 Téléversement du programme

Pour téléverser votre programme sur l’ATMega32u4, le paquetage Debian dfu-programmer est nécessaire. Installez le au besoin. La procédure à suivre pour charger votre programme sur l’ATMega32u4 est la suivante :

appuyez sur le bouton de réinitialisation de la carte Polytech’Lille ;
la carte doit être listée comme en mode DFU dans un lsusb, vous pouvez alors exécuter les commandes suivantes :
```
dfu-programmer atmega32u4 erase
dfu-programmer atmega32u4 flash Manette.hex
dfu-programmer atmega32u4 reset
```
débranchez et rebranchez votre carte, votre programme doit être actif sur l’ATMega32u4.

4.2 Prise en main

Commencez par un test basique de la clef : faites clignoter des LED, activez un vibreur. Testez aussi les boutons et l’accéléromètre. Pour le programme de test, vous pouvez partir du programme disponible sur la page de description de la carte.

4.3 Code LUFA d’exemple

Sur le site http://www.fourwalledcubicle.com/LUFA.php, téléchargez la dernière version de la bibliothèque USB LUFA. Créez un répertoire PolytechLille au même niveau que les répertoires Demos et Projects. Dans ce répertoire, copiez la démonstration du sous-chemin Device/ClassDriver/Joystick sous le nom, par exemple, Manette. Renommez aussi les fichiers dans le répertoire et modifiez le makefile. Au niveau du makefile indiquez atmega32u4 comme microcontrôleur, NONE comme platine, ajustez le chemin d’accès LUFA_PATH et passez à 16Mhz.

4.4 Adaptation du code à la manette

Importez les fonctions de gestion de la carte Polytech’Lille dans le répertoire PolytechLille/Manette. Modifiez le fichier makefile pour compiler ces sources. Modifiez ensuite le fichier Manette.c, en particulier la fonction CALLBACK_HID_Device_CreateHIDReport pour créer des rapports HID en fonction des valeurs retournées par l’accéléromètre.

4.5 Gestion des actionneurs

En toute théorie, il serait possible d’intégrer la gestion des LED et des vibreurs sous la classe USB HID. Le moins que l’on puisse dire c’est que cela complexifie considérablement le descripteur HID et encore il faut faire de l’ingéniérie inverse pour le constituer. Nous allons donc procéder autrement. Vous allez ajouter, à l’interface standard HID, une autre interface de classe spécifique au vendeur (USB_CSCP_VendorSpecificClass, pas de descripteur supplémentaire nécessaire) peuplée d’un point d’accès de type interruption en écriture (endpoint OUT). La communication sur ce point d’accès se fera sur deux octets. Le premier octet peut commander les 8 premières LED, le second octet peut commander les LED restantes et les deux vibreurs.

Pour la gestion des points d’accès interruption, vous pouvez vous aider de la démonstration Keyboard dans le répertoire Device/LowLevel. La déclaration des interfaces et des points d’accès est clairement montrée dans les fichiers Descriptors.c et Descriptors.h de cette démonstration. La gestion de points d’accès de type interruption est montrée dans l’autre source C de la démonstration, cherchez les fonctions Endpoint_ConfigureEndpoint, Endpoint_SelectEndpoint, etc.

N’hésitez pas à consulter la documentation de la bibliothèque sur Internet.

5 Utilitaire PC

Utilisez la bibliothèque USB libusb-1.0 pour écrire un programme C permettant de contrôler les LED et les vibreurs de la manette USB. Vous avez le manuel complet de la bibliothèque à l’URL http://libusb.sourceforge.net/api-1.0/modules.html. Vous trouverez un résumé de la bibliothèque à l’URL http://rex.plil.fr/Enseignement/Systeme/Systeme.IMA4/. Pour cette utilisation assez basique nous utiliserons les fonctions de communication bloquantes.

5.1 Enumération des périphériques USB

Ecrivez une fonction pour examiner tous les périphériques USB disponibles sur les bus USB de votre machine de TP. Dès qu’un périphérique s’avère être un périphérique USB du type cherché, sauvez la "poignée" (obtenue avec libusb_open) vers ce périphérique dans un tableau statique global de type libusb_device_handle[].

Vous pouvez utiliser la commande lsusb pour trouver les identifiants USB de votre type de périphérique. Pour chaque périphérique sélectionné, faites afficher le numéro du bus sur lequel se trouve le périphérique ainsi que son adresse sur ce bus.

5.2 Appropriation des interfaces spécifiques

Une fois un périphérique détecté, il faut récupérer sa configuration. La fonction libusb_get_active_config_descriptor qui permet cela nécessite un pointeur sur périphérique de type libusb_device *. Vous pouvez retrouver ce pointeur en fonction de la "poignée" par la fonction libusb_get_device. Faites afficher la valeur de cette configuration.

Il vous reste ensuite, à réclamer les interfaces nécessaires pour votre usage. Attention, la fonction libusb_claim_interface nécessite le numéro de l’interface et pas son indice. Vous allez donc parcourir la structure arborescente de description de configuration du périphérique de la façon suivante :

itérer sur le nombre d’interfaces ;
explorer chaque sous-structure d’interface de classe LIBUSB_CLASS_VENDOR_SPEC ;
pour chaque interface, prendre la première alternative d’interface ;
trouver le numéro d’interface pour utilisation avec libusb_claim_interface ;
récupérer le point d’accès présent, sauver le numéro du point d’accès dans une variable globale (pas la peine de déclarer un tableau, tous les périphériques de même identifiant sont réputés avoir les mêmes numéros de point d’accès).

Affichez l’indice et le numéro de chaque interface détectée et réclamée. Affichez aussi le numéro du point d’accès trouvé.

5.3 Fermeture du périphérique USB

Ecrivez une fonction qui libère les périphériques détectés. Pour cela, relachez toutes les interfaces réclamées puis fermez la "poignée". Vous allez devoir, à nouveau, explorer la structure arborescente de description de configuration du périphérique ou sauver les numéros des interfaces dans le tableau global. Affichez l’indice et le numéro de chaque interface libérée.

5.4 Gestion des actionneurs

Dans un premier temps, testez les manettes en allumant des LED et en actionnant les vibreurs. Par exemple, réalisez un chenillard avec vibrations en fin de chaque balayage. Sur arrêt du programme par CTRL-C, éteignez les LED et désactivez les vibreurs et fermez le périphérique USB. La gestion des LED et des vibreurs des manettes doit être effectuée via le point d’accès OUT de l’interface spécifique. Pour communiquer avec les manettes vous utiliserez la fonction libusb_interrupt_transfer. Les LED et les vibreurs doivent être activés sur toutes les manettes connectées.

6 Pour finaliser

Pour mettre les dernières touches à votre tutorat :

Installez un jeu prévu pour utiliser une manette USB (e.g. wordwarvi), vérifiez que vos manettes sont reconnues et fonctionnelles ;
Récupérez les sources de votre jeu par la commande apt-get source. Intégrez votre programme C utilisant la libusb-1.0 dans le jeu, utilisez les LED et les vibreurs de la manette en adéquation avec le scénario du jeu.

Ce document a été traduit de L^AT_EX par H^EV^EA