Assembleur pour Arduino - Mac OSX

Lorsque l'on cherche à programmer sur "Arduino" en assembleur sur Mac, on se retrouve assez rapidement perdu dans tout un tas d'installations, plus compliquées les unes que les autres. Pourtant il ne faut pas plus de 10 min pour tout installer et réaliser son premier programme. Etes-vous OK? Alors allons-y les Lapinots!

Note: l'installation décrite ici tourne sur un Mac Mini avec  macOS High Sierra 10.13.2 et TextWrangler 5.5.1

Les outils

Pour développer en assembleur et réaliser des programmes pour l'Arduino, il nous faut 4 choses:

• Un Arduino ("Là Tonton Lapin, tu nous étonnes!") qui va recevoir le programme que nous allons réaliser et qui va l'exécuter. Nous utiliserons ici un Arduino UNO, mais peu importe le modèle.
• Un programmeur, c'est-à-dire un logiciel qui va envoyer notre progamme à l'Arduino. En fait un outil qui va faire la fonction "Téléverser" de l'Ide Arduino. Nous utiliserons AVRDUDE.
• Un assembleur pour assembler le code c'est-à-dire transformer ce que nous allons taper dans notre éditeur de texte, en fichier exécutable. Nous utiliserons AVRA.
• Un éditeur de texte pour taper notre code. Nous utiliserons TextWrangler. Ce choix s'explique par le fait que c'est un éditeur de texte simple, très popularie sur Mac, gratuit et qui posséde la capacité de gérer des modules externes en AppleScript, ce qui nous sera bien utile ici! Si vous préférez utiliser BBEdit, le grand frère de TextWrangler, cela ne pose aucun problème, ce qui est décrit ici fonctionne aussi bien sur ces deux logiciels.

Installation

Installons notre assembleur, notre programmeur et l'éditeur de texte. C'est l'affaire de quelques minutes.

Installer AVRA et AVRDUDE

Ouvrez le Terminal de votre Mac (Applications/Utilitaires/Terminal.app) et tapez la commande suivante:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null

Cette commande va installer Homebrew. Hombrew c'est un gestionnaire de paquets pour Mac OSX. Grosso modo c'est un outil qui va se charger d'installer des logiciels. L'installation de Homebrew va prendre à peine quelques minutes. Une fois l'installation de Homebrew terminée, nous pouvons nous en servir pour installer AVRA et AVRDUDE.

Pour cela, tapez la ligne suivante dans le Terminal, ce qui va installer AVRA, en quelques dizaines de secondes.
brew install avra

Recommencer la même chose pour installer AVRDUDE en tapant la commande suivante:
 brew install avrdude

Impeccable: vous avez terminé l'installation de l'assembleur qui va créer l'exécutable et le programmeur qui va envoyer les données à l'Arduino.

Installer l'éditeur de texte

Si vous n'avez pas TextWrangler d'installé, aller le chercher sur la page de Barbones, en cliquant ici. 

Paramétrages

Nous allons paramétrer TextWrangler afin d'activer la coloration de syntaxe pour notre code assembleur puis nous allons le paramétrer pour qu'il lance AVRA et AVRDUDE. Car ce que nous voulons c'est taper le code sous TextWrangler et avec un seul clic dans le menu, assembler ce code et le transmettre à l'Arduino.

Activer la coloration de syntaxe

Cela se fait en plaçant un fichier .plist dans le dossier "Application Support" de TextWrangler.
Pour cela, commençez par ouvrir TextWrangler puis copier-y le code ci-dessous:

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>BBEditDocumentType</key> <string>CodelessLanguageModule</string> <key>BBLMColorsSyntax</key> <true/> <key>BBLMIsCaseSensitive</key> <false/> <key>BBLMKeywordList</key> <array> <string>add</string> <string>adc</string> <string>adiw</string> <string>sub</string> <string>subi</string> <string>sbc</string> <string>sbci</string> <string>and</string> <string>andi</string> <string>or</string> <string>ori</string> <string>eor</string> <string>com</string> <string>neg</string> <string>sbr</string> <string>cbr</string> <string>inc</string> <string>dec</string> <string>tst</string> <string>clr</string> <string>ser</string> <string>mul</string> <string>muls</string> <string>mulsu</string> <string>fmul</string> <string>fmuls</string> <string>fmulsu</string> <string>rjmp</string> <string>ijmp</string> <string>jmp</string> <string>rcall</string> <string>icall</string> <string>call</string> <string>ret</string> <string>reti</string> <string>cpse</string> <string>cp</string> <string>cpc</string> <string>cpi</string> <string>sbrc</string> <string>sbrs</string> <string>sbic</string> <string>sbis</string> <string>brbs</string> <string>brbc</string> <string>breq</string> <string>brne</string> <string>brcs</string> <string>brcc</string> <string>brsh</string> <string>brlo</string> <string>brmi</string> <string>brpl</string> <string>brge</string> <string>brlt</string> <string>brhs</string> <string>brhc</string> <string>brts</string> <string>brtc</string> <string>brvs</string> <string>brvc</string> <string>mov</string> <string>movw</string> <string>ldi</string> <string>ld</string> <string>ldd</string> <string>lds</string> <string>st</string> <string>std</string> <string>sts</string> <string>lpm</string> <string>spm</string> <string>in</string> <string>out</string> <string>push</string> <string>pop</string> <string>sbi</string> <string>cbi</string> <string>lsl</string> <string>lsr</string> <string>rol</string> <string>ror</string> <string>asr</string> <string>swap</string> <string>bset</string> <string>bclr</string> <string>bst</string> <string>bld</string> <string>sec</string> <string>clc</string> <string>sen</string> <string>cln</string> <string>sez</string> <string>clz</string> <string>sei</string> <string>cli</string> <string>ses</string> <string>cls</string> <string>sev</string> <string>clv</string> <string>set</string> <string>clt</string> <string>seh</string> <string>clh</string> <string>nop</string> <string>sleep</string> <string>wdt</string> <string>break</string> </array> <key>BBLMLanguageCode</key> <string>AVR</string> <key>BBLMLanguageDisplayName</key> <string>AVR</string> <key>BBLMScansFunctions</key> <true/> <key>BBLMSuffixMap</key> <array> <dict> <key>BBLMLanguageSuffix</key> <string>.asm</string> </dict> </array> <key>Language Features</key> <dict> <key>Comment Pattern</key> <string><![CDATA[(?x: (?> (?<!\\) ; .* $ ) )]]></string> <key>Close Parameter Lists</key> <string></string> <key>Close Statement Blocks</key> <string></string> <key>Close Strings 1</key> <string></string> <key>Close Strings 2</key> <string></string> <key>End-of-line Ends Strings 1</key> <true/> <key>End-of-line Ends Strings 2</key> <true/> <key>Escape Char in Strings 1</key> <string></string> <key>Escape Char in Strings 2</key> <string></string> <key>Identifier and Keyword Characters</key> <string>0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz#</string> <key>Open Parameter Lists</key> <string></string> <key>Open Statement Blocks</key> <string></string> <key>Prefix for Functions</key> <string></string> <key>Prefix for Procedures</key> <string></string> <key>Terminator for Prototypes 1</key> <string></string> <key>Terminator for Prototypes 2</key> <string></string> </dict> </dict> </plist>

Sauvez ce fichier sous le nom AVR.plist puis fermer son édition dans TextWrangler (cliquez sur le petit rond avec une croix en face du nom de ce fichier dans la colonne de gauche de l'éditeur). Ce détail est important: quand le fichier plist est ouvert dans TextWrangler celui-ci ne le prend pas en compte et il n'y a donc pas de coloration de la syntaxe.
Ce fihcier AVR.plist doit être recopié dans "Bibliothéque/Application Support/TextWrangler/Language Module".
Attention, ce n'est pas le dossier Bibliothéque principal, visible quand vous ouvrez le disque de votre Mac, mais le dossier Biblothéque de votre compte Utilisateur.

Note: par défaut, ce dossier est caché. Si vous n'avez pas activé sa visualisation, ici cliquez ici pour savoir comment faire.

Lancer AVRA et AVRDUDE depuis TextWrangler

Une fois que nous aurons tapé notre code, nous allons devoir l'envoyer à AVRA puis à AVRDUDE. Pour cela nous allons créer un petit Script "AppleScript" que nous fournirrons à TextWrangler et auquel il nous donnera accés via son menu.

Dans textWrangler, allez dans le menu juste avant le menu Help donc le menu avec une icône en forme de petit parchemin. Deux cas possibles:

1. vous avez déjà créé au moins un script pour piloter TextWrangler
2. vous n'avez jamais utilisé ce menu, donc sous les trois premières entrées, il n'y a rien.

Vous avez déjà au moins un script

Si vous en êtes l'auteur, je suppose que vous savez comment créer un script, donc à vous de jouer. Le script est un peu plus bas dans cet article.
Si vous n'êtes pas l'auteur du ou des scripts actuellement disponibles, la solution la plus simple est la suivante:

1. Cliquez dans le menu sur "Open Scripts Folder". Dans la fenêtre qui s'ouvre et qui liste tous les scripts, cliquez avec le bouton droit sur un des scripts (.scpt) et choisissez "Dupliquez". Donnez à ce fichier le nom que vous voulez voir apparaître dans le menu (moi je l'ai nommé "Arduino assemble and run.scpt").
2. Double cliquez sur ce fichier ce qui ouvrira l'éditeur de script de votre Mac. Effacez le contenu du script qui s'affiche collez à la place le script qui est un peu plus bas dans cet article. Une fois que c'est fait, cliquez sur le petit marteau en haut de la fenêtre pour validez le script, puis cliquez sur "Enregistrer" dans le menu "Fichier".

Vous n'avez aucun script

Dans ce cas dans le menu de TextWrangler, cliquez sur "Open Scripting Editor". Dans la fenêtre d'édition, recopiez le code ci-dessous. Cliquez ensuite sur le petit marteau pour valider le script. Ensuite, cliquez dans le menu sur "Enregistrer" pour sauvez le fichier en lui donnant le nom que vous voulez voir apparaître dans le menu (moi je l'ai nommé "Arduino compile and run.scpt"). Le script doit être sauvé dans le dossier Bibliothéque/Application Support/TextWrangler/Scripts donc dans un dossier voisin de celui dans lequel nous avons déposé AVR.plist
Si vous n'arrivez pas à accéder à ce dossier depuis le sélecteur de fichier, sauvez AVR.plist sur votre bureau et ensuite, recopier le manuellement dans le dossier.

tell application "TextWrangler" save text document 1 set the_file to file of text document 1 end tell set AppleScript's text item delimiters to ":" set source_file to the last text item of (the_file as string) set exec_file to text 1 thru (offset of "." in source_file) of source_file & "hex" tell application "Finder" set the_folder to container of file the_file end tell tell application "Terminal" activate set p to POSIX path of (the_folder as string) set shell_script to "cd " & (quoted form of p) & "; avra '" & source_file & "'; avrdude -patmega328p -carduino -P/dev/cu.usbmodemFD121 -b115200 -Uflash:w:'" & exec_file & "':i" if (count windows) is 0 then do script shell_script else do script shell_script in the front window end if end tell

Ci-dessous le script coloré aprés avoir cliqué sur le petit marteau.

Analyse et éventuelle modification du Script

Jetons un oeil sur ce script afin de comprendre ce qu'il fait et éventuellement le modifier.
En premier on demande à TextWrangler de sauver le fichier. Puis nous créeons deux chaines de caractères: source_file et exec_file. La première (source_file) va contenir le nom du fichier. Donc si votre fichier se nomme "mon_test.asm", source_file contiendra donc "mon_test.asm". Quand nous enverrons ce fichier à AVRA, celui-ci l'assemblera et produira un fichier exécutable, portant le même nom mais avec ".hex" comme extension.
Donc le source "mon_test.asm" donnera l'exécutable "mon_test.hex" et c'est  "mon_test.hex" que AVRDUDE devra envoyer à l'Arduino. Notre chaîne exec_file va donc contenir le nom du fichier, complété par ".hex" afin d'être utilisée pour l'envoi vers l'Arduino.
Nous sauvons ensuite le chemin actuel pour accéder au fichier, dans la chaine de caractère nommée "p".
Le plus intéressant, c'est la ligne suivante. Nous y définissons la chaîne shell_script qui va contenir les commandes que nous allons envoyer au Terminal.
En fait, nous allons simuler le fait d'ouvrir le Terminal et d'y taper les commandes pour se placer sur le bon répertoire, lancer AVRA puis lancer AVRDUDE.
Deux choses pour comprendre: en AppleScript, la concaténation de chaînes de caractères se fait avec l'opérateur "&". Ensuite lorsque nous avons plusieurs commandes à envoyer au Terminal, nous pouvons toutes les mettre dans la même ligne, mais à condition de les séparer par ";".
Nous avons donc ici 3 commandes dans notre chaîne shell_script:

1. cd suivi du chemin, qui va régler le chemin d'accés à notre fichier 
2. avra suivi du nom du fichier source afin que celui-ci soit assemblé
3. avrdude qui va envoyer le résultat vers l'Arduino.

Si vous désirez ajouter des paramètres lors de l'appel à AVRA, il suffit de les ajouter dans la commande par exemple "avra --max_errors 5" si vous voulez que AVRA sorte au bout de 5 erreurs (au lieu des 10 par défaut). La liste des commandes AVRA est disponible en bas de cette page.
Concernant AVRDUDE,  la liste compléte des options est disponible ici, dans le manuel d'utilisation. Ouvrez la page avec la liste des commandes et analysons celle que nous avons mis dans notre Script.

avrdude -patmega328p -carduino -P/dev/cu.usbmodemFD121 -b115200 -Uflash:w:'" & exec_file & "':i

Dans cette chaîne nous trouvons les éléments suivants

• Le premier paramètre c'est "-patmega328p". Cela indique le processeur employé. Note: assez bizarrement cette valeur (atmega328p) n'est pas dans la liste des options indiquées sur le site de Avrdude...).
• Le second paramètre (-c) indique le programmeur que AVRDUDE utilisera en interne. Ici nous utiliserons celui de l'Arduino.
• Le troisième paramètre (-P) indique le port sur lequel est connecté le hardware destination.  Dans mon cas le port est "/dev/cu.usbmodemFD121". Mais ce n'est pas forcément le cas chez vous... Pour connaître le port utilisé, lancez l'Ide Arduino et ouvrez le menu "Outil". Notez la valeur indiquée dans l'option "Port" et recopiez là dans le script en la faisant précéder de "-P" (sans espace entre le -P et le premier / de la chaîne).

• La commande -b donne la vitesse de transmission. Ici nous avons 115200 Bauds
• Ensuite -U va indiquer le type de mémoire destination, comment va être traité cette mémoire, le nom du fichier et son type (-U memtype:op:filename[:format]) . "flash" indique que nous déposons dans la mémoire flash de l'Arduino, "w" que nous allons lire le fichier et l'écrire dans la mémoire. Nous avons ensuite le nom du fichier (donc celui qui est dans exec_file) puis son type. Ici nous mettons "i" qui signifie "Intel Hex" puisque c'est ce format qui a été généré par AVRA.

Nous exécutons ensuite le Script avec la commande "do shell" , ce qui ouvrira le Terminal pour lui envoyer les commandes que préparées dans la chaîne shell_script.

Notre premier programme en Assembleur!

Quittez et relancez TextWrangler pour activer la plist. Ouvrez un nouveau document et copiez-y le code suivant:

;---------------------------------------------------------- ; Blink ; V 2.00 avec un peu de nettoyage... ;---------------------------------------------------------- .device atmega328p .equ RAMEND = 0x8ff ;Fin de la RAM utilisateur .equ SREG = 0x3f ;Status Register .equ SPL = 0x3d ;Stack Pointer Bas (Low) .equ SPH = 0x3e ;Stack Pointer Haut (High) .equ PORTB = 0x05 ;Port B .equ DDRB = 0x04 ;Data Direction Register Port B ; Reset Vector .org 0x0000 ; Début du code .org 0x003a main: ; Init le Stack Pointer ldi r16,low(RAMEND) ;0xff out SPL,r16 ldi r16,high(RAMEND) ;0x08 out SPH,r16 ldi r16,0b00100000 out DDRB,r16 clr r17 mainloop: eor r17,r16 ;Inverse le bit OUTPUT out PORTB,r17 ;Ecrit sur le port call wait ;Attend un peu... rjmp mainloop ;boucle sans fin ; Fonction d'attente. Elle réalise un grand nombre de boucle wait: ldi r18,0x40 ;boucle 0x400000 fois ldi r19,0x00 ;~12 million cycles ldi r20,0x00 ;~0.7s à 16Mhz w0: dec r20 brne w0 dec r19 brne w0 dec r18 brne w0 ret

Ce code ASM c'est l'équivalent du code "blink" donné en exemple avec l'Ide Arduino. Sauvez ce fichier sous le nom que vous voulez mais avec l'extension ".asm" car c'est avec cette extension que TextWrangler fait le lien avec le fichier plist pour la coloration.

Vérifiez que votre Ardino UNO et bien branché, ouvrez le menu des outils de TextWrangler (avec l'icône en forme de parchemin) et cliquez sur le script que vous avez créé (dans mon cas "Arduino assemble and run"). Cela va ouvrir le Terminal, lancer AVRA donc assembler le code, puis lancer AVRDUDE qui va transmettre le fichier à l'Arduino et, oh miracle, la Led 13 (interne) de votre Arduino va clignoter. AVRA et AVRDUDE indiquerons les opérations réalisées dans la fenêtre du Terminal (erreurs, taille mémoire occupée etc...)

"Houlala, Tonton Lapin, autant de lignes pour faire un blink??" Oui Jeune Lapinot. Il est vrai qu'en utilisant l'exemple Blink, disponible via le menu Fichier>Exemples>01-Basic>Blink, de l'Ide Arduino, nous aurions obtenu le même résultat. Ou du moins, à peu prés. Car si on observe les valeurs affichées lors du transfert des données vers la carte Arduino, on constate une différence: l'exemple Blink de l'Ide Arduino occupe 928 octets dans la mémoire Flash, tandis que notre exemple Blink en assembleur n'en occupe que 160. La différence est assez énorme. Evidement lorsque l'on a un ordinateur avec 8Go de mémoire, gratter quelques octets n'est pas franchement utile. Mais avec la faible mémoire des Micro-Contrôleurs, il devient clair que ce gain est intéressant.

Conclusion

En à peine une dizaine de minutes, nous avons installé nos outils pour développer en assembleur sur Arduino, sachant qu'un coup d'oeil à la documentation d'AVRDUDE nous a montré que nous pouvions envoyer notre code vers d'autres cartes. La facilité de création des Scripts pour TextWrangler a facilité notre travail et rien ne nous empêche d'en créer d'autres, pour d'autres cartes.
A noter que les Script peuvent aussi présenter un interface, par exemple avec un menu déroulant: si vous avez plusieurs cartes, au lieu de créer un Script par carte, vous pouvez créer un Script unique qui présentera un formulaire dans lequel vous choisirez la carte de votre choix. Pour cela, chercher des informations sur AppleScript et vous trouverez votre bonheur (voir ici un article sur ce sujet).