Table des matières

1 Informations générales

1.1 Notation

1.1.1 Conventions typographiques

Les lignes de commandes sont représentées en police bold typewriter. Les réponses de l'ordinateur sont en police typewriter. Depuis début 2006, plus aucune commande ne nécessite les privilèges du root, de sorte que tous les exemples seront précédés par le prompt utilisateur normal, $. Le texte entre crochets est un texte optionnel [comme-cela]. Le texte entre crochets <comme-cela> représente un champ qui peut prendre différentes valeurs, le paragraphe suivant explique les valeurs appropriées. Les items de texte séparés par une barre verticale signifie que l'un ou l'autre, mais pas plus, doit être présent. Toutes les lignes de commandes des exemples supposent que vous êtes dans le répertoire d'emc2/ ou vous avez configuré ou compilé emc2 avec l'option --run-in-place. Les chemins seront par conséquent, affichés en accord avec cet emplacement.

1.1.2 Noms

Toutes les entités de HAL sont accessibles et manipulées par leurs noms, donc, documenter les noms des pins, signaux, paramètres, etc, est très important. Les noms dans HAL ont un maximum de 41 caractères de long (comme défini par HAL_NAME_LEN dans hal.h). De nombreux noms seront présentés dans la forme générale, avec un texte entre crochets <comme-cela> représentant les champs de valeurs diverses.

Quand les pins, signaux, ou paramètres sont décrits pour la première fois, leur nom sera précédé par leur type en (PETITES CAPITALES) et suivi par une brève description. Les définitions typiques de pins ressemblent à ces exemples:

De temps en temps, une version abrégée du nom peut être utilisée, par exemple la deuxième pin ci-dessus pourrait être appelée simplement avec .output quand cela peut être fait sans prêter à confusion.

1.2 Conventions générales de nommage

Le but des conventions de nommage est de rendre l'utilisation de HAL plus facile. Par exemple, si plusieurs interfaces de codeur fournissent le même jeu de pins et qu'elles sont nommées de la même façon, il serait facile de changer l'interface d'un codeur à un autre. Malheureusement, comme tout projet open-source, HAL est la combinaison de choses diversement conçues et comme les choses simples évoluent. Il en résulte de nombreuses incohérences. Cette section vise à remédier à ce problème en définissant certaines conventions, mais il faudra certainement un certain temps avant que tous les modules soient convertis pour les suivre.

Halcmd et d'autres utilitaires HAL de bas niveau, traitent les noms HAL comme de simples entités, sans structure. Toutefois, la plupart des modules ont une certaine structure implicite. Par exemple, une carte fournit plusieurs blocs fonctionnels, chaque bloc peut avoir plusieurs canaux et chaque canal, une ou plusieurs broches. La structure qui en résulte ressemble à une arborescence de répertoires. Même si halcmd ne reconnait pas la structure arborescente, la convention de nommage est un bon choix, elles lui permettra de regrouper ensemble, les items du même groupe, car il trie les noms. En outre, les outils de haut niveau peuvent être conçus pour reconnaitre de telles structures si les noms fournissent les informations nécessaires. Pour cela, tous les modules de HAL devraient suivrent les règles suivantes:

1.3 Conventions de nommage des pilotes de matériels2

1.3.1 Noms de pin/paramètre

Les pilotes matériels devraient utiliser cinq champs (sur trois niveaux) pour obtenir un nom de pin ou de paramètre, comme le suivant:

<device-name>.<device-num>.<io-type>.<chan-num>.<specific-name>

Les champs individuels sont:

<device-name>
Le matériel avec lequel le pilote est sensé travailler. Il s'agit le plus souvent d'une carte d'interface d'un certain type, mais il existe d'autres possibilités.
<device-num>
Il est possible d'installer plusieurs cartes servo, ports parallèles ou autre périphérique matériel dans un ordinateur. Le numéro du périphérique identifie un périphérique spécifique. Les numéros de périphériques commencent à 0 et s'incrémentent.3
<io-type>
La plupart des périphériques fournissent plus d'un type d'I/O. Même le simple port parallèle a, à la fois plusieurs entrées et plusieurs sorties numériques. Les cartes commerciales plus complexes peuvent avoir des entrées et des sorties numériques, des compteurs de codeurs, des générateurs d'impulsions de pas ou de PWM, des convertisseurs numérique/analogique, analogique/numérique et d'autres possibilités plus spécifiques. Le “I/O type” est utilisé pour identifier le type d'I/O avec lequel la pin ou le paramètre est associé. Idéalement, les pilotes qui implémentent les mêmes type d'I/O, même sur des dispositifs très différents, devraient fournir un jeu de pins et de paramètres cohérents et de comportements identiques. Par exemple, toutes les entrées numériques doivent se comporter de la même manière quand elles sont vues de l'intérieur de HAL, indépendamment du périphérique.
<chan-num>
Quasiment tous les périphériques d'I/O ont plusieurs canaux, le numéro de canal “chan-num” identifie un de ceux ci. Comme les numéros de périphériques “device-num”, les numéros de canaux, “chan-num”, commencent à zéro et s'incrémentent.4 Si plusieurs périphériques sont installés, les numéro de canaux des périphériques supplémentaires recommencent à zéro. Comme il est possible d'avoir un numéro de canal supérieur à 9, les numéros de canaux doivent avoir deux chiffres, avec un zéro en tête pour les nombres inférieur à 10 pour préserver l'ordre des tris. Certains modules ont des pins et/ou des paramètres qui affectent plusieurs canaux. Par exemple un générateur de PWM peut avoir quatre canaux avec quatre entrées “duty-cycle” indépendantes, mais un seul paramètre “frequency” qui contrôle les quatres canaux (à cause de limitations matérielles). Le paramètre “frequency” doit utiliser les numéros de canaux de “00-03”.
<specific-name>
Un canal individuel d'I/O peut avoir une seule HAL pin associée avec lui, mais la plupart en ont plus. Par exemple, une entrée numérique a deux pins, une qui est l'état de la broche physique, l'autre qui est la même chose mais inversée. Cela permet au configurateur de choisir entre les deux états de l'entrée, active haute ou active basse. Pour la plupart des types d' entrée/sortie, il existe un jeu standard de broches et de paramètres, (appelé l'“interface canonique”) que le pilote doit implémenter. Les interfaces canoniques sont décrites au chapitre [.].

1.3.1.1 Exemples

motenc.0.encoder.2.position
-- la sortie position du troisième canal codeur sur la première carte Motenc.
stg.0.din.03.in
-- l'état de la quatrième entrée numérique sur la première carte Servo-to-Go.
ppmc.0.pwm.00-03.frequency
-- la fréquence porteuse utilisée sur les canaux PWM de 0 à 3.

1.3.2 Noms des fonctions

Les pilotes matériels ont généralement seulement deux types de fonctions HAL, une qui lit l'état du matériel et met à jour les pins HAL, l'autre qui écrit sur le matériel en utilisant les données fournies sur les pins HAL. Ce qui devrait être nommé de la façon suivante:

<device-name>-<device-num>[.<io-type>[-<chan-num-range>]].read|write
<device-name>
Le même que celui utilisé pour les pins et les paramètres.
<device-num>
Le périphérique spécifique auquel la fonction aura accès.
<io-type>
Optionnel. Une fonction peut accéder à toutes les d'entrées/sorties d'une carte ou, elle peut accéder seulement à un certain type. Par exemple, il peut y avoir des fonctions indépendantes pour lire les compteurs de codeurs et lire les entrées/sorties numériques. Si de telles fonctions indépendantes existent, le champ <io-type> identifie le type d'I/O auquelles elles auront accès. Si une simple fonction lit toutes les entrés/sorties fournies par la carte, <io-type> n'est pas utilisé.5
<chan-num-range>
Optionnel. Utilisé seulement si l'entrée/sortie <io-type> est cassée dans des groupes et est accédée par différentes fonctions.
read|write
Indique si la fonction lit le matériel ou lui écrit.

1.3.2.1 Exemples

motenc.0.encoder.read
-- lit tous les codeurs sur la première carte motenc.
generic8255.0.din.09-15.read
-- lit le deuxième port 8 bits sur la première carte d'entrées/sorties à base de 8255.
ppmc.0.write
-- écrit toutes les sorties (générateur de pas, pwm, DAC et ADC) sur la première carte ppmc.

2 Périphériques d'interfaces canoniques

Les sections qui suivent expliquent les pins, paramètres et functions qui sont fournies par les “périphériques canoniques”. Tous les pilotes de périphériques HAL devraient fournir les mêmes pins et paramètres et implémenter les mêmes comportements.

Noter que seuls les champs <io-type> et <specific-name> sont définis pour un périphérique canonique. Les champs <device-name>, <device-num> et <chan-num> sont définis en fonction des caractéristiques du périphérique réel.

2.1 Entrée numérique (Digital Input)

L'entrée numérique canonique (I/O type: digin) est assez simple.

2.1.1 Pins

2.1.2 Paramètres

2.1.3 Fonctions

2.2 Sortie numérique (Digital Output)

La sortie numérique canonique est également très simple (I/O type: digout).

2.2.1 Pins

2.2.2 Paramètres

2.2.3 Fonctions

2.3 Entrée analogique (Analog Input)

L'entrée analogique canonique (I/O type: adcin). Devrait être utilisée pour les convertisseurs analogiques/numériques, qui convertissent par exemple, les tensions en une échelle continue de valeurs.

2.3.1 Pins

2.3.2 Paramètres

2.3.3 Fonctions

2.4 Sortie analogique (Analog Output)

La sortie analogique canonique (I/O Type: adcout). Elle est destinée à tout type de matériel capable de sortir une échelle plus ou moins étendue de valeurs. Comme par exemple les convertisseurs numérique/analogique ou les générateurs de PWM.

2.4.1 Pins

2.4.2 Paramètres

2.4.3 Fonctions

(funct) write -- Ecrit la valeur calculée sur la sortie matérielle. Si enable est fausse, la sortie passera à 0, indépendamment des valeurs de value, scale et offset. La signification de “0” dépend du matériel. Par exemple, un convertisseur A/D 12 bits peut vouloir écrire 0x1FF (milieu d'échelle) alors que le convertisseur D/A reçoit 0 Volt de la broche matérielle. Si enable est vraie, l'échelle, l'offset et la valeur sont traités et (scale * value) + offset sont envoyés en sortie de l'adc . Si enable est faux, la sortie passe à 0.

2.5 Codeur

L'interface de codeur canonique(I/O type: encoder ) fournit les fonctionnalités nécessaires pour une prise d'origine sur une impulsion d'index et pour la synchronisation avec la vitesse de broche, ainsi que de base pour le positionnement et/ou le contrôle de vitesse. Cette interface devrait être implémentable quel que soit le matériel sous-jacent, même si certains matériels donnent de “meilleurs” résultats que d'autres. (Par exemple, pour capturer un index de position à +/- 1 impulsion lors d'un mouvement rapide, ou avoir moins de fluctuation sur la pin de vitesse).

2.5.1 Pins

La pin “index-enable” est bi-directionnelle, elle exige un peu plus d'explications. Si “index-enable” est faux, le canal d'index du codeur sera ignoré et le compteur comptera normalement. Le pilote du codeur ne passera jamais “index-enable” sur vrai. Cependant, un autre composant peut le faire. Si “index-enable” est vrai, alors quand la prochaine impulsion d'index arrivera, le compteur du codeur sera remis à zéro et le pilote passera “index-enable” sur faux. Ce qui permettra à l'autre composant de savoir qu'une impulsion d'index est arrivée. C'est une forme de poignée de main, l'autre composant passe “index-enable” sur vrai pour requérir une remise à zéro du comptage d'impulsion d'index et le pilote le repasse sur faux quand la requête à été satisfaite.

2.5.2 Paramètres

2.5.3 Fonctions

Il n'y a qu'une fonction pour lire les codeurs.

Pieds de page

1   Les caractères souslignés ont été enlevés, mais il reste quelques cas de mélange de casses, par exemple “pid.0.Pgain” au lieux de “pid.0.p-gain”. Retour

2   La plupart des pilotes ne suivent pas ces conventions dans la version 2.0. Ce chapitre est réellement un guide pour les développements futurs. Retour

3   Certains matériels utilisent des cavaliers ou d'autres dispositifs pour définir une identification spécifique à chacun. Idéalement, le pilote fournit une manière à l'utilisateur de dire, le “device-num 0 est spécifique au périphérique qui a l'ID XXX”, ses sous-ensembles porterons tous un numéro commençant par 0. Mais à l'heure actuelle, certains pilotes utilisent l'ID directement comme numéro de périphérique. Ce qui signifie qu'il est possible d'avoir un périphérique Numéro 2, sans en avoir en Numéro 0. C'est un bug qui devrait disparaître en version 2.1. Retour

4   Une exception à la règle du “numéro de canal commençant à zéro” est le port parallèle. Ses “HAL pins” sont numérotées avec le numéro de la broche correspondante du connecteur DB-25. C'est plus pratique pour le câblage, mais non cohérent avec les autres pilotes. Il y a débat pour savoir si c'est un bogue ou une fonctionnalité. Retour

5   Note aux programmeurs de pilotes: ne PAS implémenter des fonctions séparées pour différents types d'I/O à moins qu'elles ne soient interruptibles et puissent marcher dans des threads indépendants. Si l'interruption de la lecture d'un codeur pour lire des entrées numériques, puis reprendre la lecture du codeur peut poser problème, alors implémentez une fonction unique qui fera tout. Retour