From c908ba7058ae9bc8f7a9446e17e3482d125234de Mon Sep 17 00:00:00 2001 From: Nicolas Schodet Date: Tue, 17 Jun 2008 22:57:39 +0200 Subject: * digital/avr/modules/proto: - updated doc. --- digital/avr/modules/proto/Makefile | 2 +- digital/avr/modules/proto/proto.txt | 163 ++++++++++++++++++++++-------------- 2 files changed, 103 insertions(+), 62 deletions(-) diff --git a/digital/avr/modules/proto/Makefile b/digital/avr/modules/proto/Makefile index 1c9f69b6..91058741 100644 --- a/digital/avr/modules/proto/Makefile +++ b/digital/avr/modules/proto/Makefile @@ -1,5 +1,5 @@ BASE = ../.. DOC = proto.html -EXTRACTDOC = proto.h avrconfig.h proto_inline.c +EXTRACTDOC = proto.h +proto_inline.c avrconfig.h include $(BASE)/make/Makefile.gen diff --git a/digital/avr/modules/proto/proto.txt b/digital/avr/modules/proto/proto.txt index 2a20d268..fbf1322f 100644 --- a/digital/avr/modules/proto/proto.txt +++ b/digital/avr/modules/proto/proto.txt @@ -1,89 +1,130 @@ -*Title: Module AVR Protocole série -*Author: Ni +===================== + Protocol AVR module +===================== +:Author: Nicolas Schodet -* Principe +Introduction +============ -Ce module s'occupe de gérer le protocole de communication sur une ligne de type -port série. Il propose un service de décodage et un service d'encodage. +This module handles a communication protocol suitable to be used with a serial +line. It handles coding and decoding. -Pour utiliser le décodage, il suffit d'appeler une fonctions à chaque -caractère reçu. Si une commande a été reçu, ou en cas d'erreur, elle appelle -une fonction définie par l'utilisateur avec pour paramètres les informations -sur la commande reçue. +To use the decoding part, just call a dedicated function at each character +reception. If a complete frame has been received, the callback defined by the +user is called with the received frame as parameter. -Pour utiliser l'encodage, il suffit d'appeler une fonction émission avec -les paramètres que l'on veux envoyer. +The encoding part is a set of functions to send frames with a given format. -* Protocole +Protocol +======== -Le protocole de communication est basé sur des trames. Chaque trame commence -par un point d'exclamation et se termine par un retour chariot. Tout ce qui -n'est pas entouré de ces caractères est ignoré. +The protocol is based on frames composed of readable characters. This permits +easy debugging for human eyes. Each frame starts with an exclamation mark +(``!``) and stops with a carriage return (``\r``). Any extra character not +embedded in a frame is ignored. -Le point d'exclamation est directement suivi de la commande. La commande est -un caractère alphabétique minuscule ou majuscule. +The exclamation mark is directly followed by the command character. This is +an alphabetic character, lower or upper case. -Après la commande vient une liste de d'arguments. Les arguments sont codés en -hexadécimal. +After the command comes a list of arguments. Arguments are coded in pairs of +hexadecimal digits. Each pair corresponds to one byte. Several bytes can be +combined to form words or double words, but this is not represented in the +protocol, there are simply concatenated. -Par exemple : +For example:: -^<< -!z -!v03f5 -!c0094ffa8 -^>> + !z + !v03f5 + !c0094ffa8 -On peut aussi envoyer directement un caractère ascii en paramètre en le -précédant d'une apostrophe, ce caractère devant être imprimable. +A printable ASCII character can also be sent directly using a simple quote +(``'``), this is equivalent to send the ASCII code as a pair of hexadecimal +digits. -Par exemple : +For example, theses two frames are equivalents:: -^<< -!p'sa800 -^>> + !p's40 + !p7340 -Enfin, on peut envoyer une chaine de caractères imprimables. +Last, a string of printable characters can be sent using a double quote +(``"``):: -Par exemple : + !p"Hello World -^<< -!p"Hello World -^>> +Warning: the exclamation mark is still a special character. Theses two modes +are provided for human interaction. If a program needs to send a character +string, it should rather send them as hexadecimal arguments. -Attention, le point d'exclamation reste un caractère spécial. +Error checking +============== -* Vérification d'erreur +This module does not enforce any error checking, but here is a proposed +system: -La vérification d'erreur n'est pas forcée par l'utilisation de ce module. En -règle générale, on utilisera le fonctionnement suivant : +- For reliable messages, the slave device must sent back the received command + as acknowledgement once it has been handled. +- For unreliable messages, there is no acknowledgement. +- If the slave device does not understand a message from the master device, it + sends a frame with the ``?`` command to signal the error in order to shorten + retransmission delay. - * pour un message fiable, le périphérique doit retourner la commande - dès réception ; - * pour un message non-fiable, le périphérique ne retourne rien. +A unreliable message is a message which is sent regularly and for which a +retransmission would not be interesting as we prefer to wait for the next +newer value than retransmit the old one. -Par message non-fiable, on entend un message qui arrive en permanence, et dont -l'on a pas besoin de vérifier la bonne réception. En effet, une valeur plus à -jour est préférable à une réémission. +Only the slave device sends acknowledgement or error messages. The upper +layer protocol should take this into account during the design phase. -Seul le périphérique renvois des messages de vérification ou des messages -d'erreur. Le protocole d'échange doit être prévu en prenant cela en compte. Il -n'est par exemple pas conseillé de déclencher des messages non demandé depuis -le périphérique, en effet, il n'y a aucun moyen de vérifier s'il est arrivé -correctement. Des messages envoyés sous l'initiative du périphérique doivent -donc être des messages périodiques, pas événementiels. +Pitfalls +======== -* Utilisation +Using the error checking procedure defined above, there is some pitfalls if +the master is not a human: -On doit définir une fonction de callback afin de traiter les messages arrivant -et une fonction d'envois de caractère utilisée dans les fonctions d'envois. Le -nom de ces deux fonctions est défini dans |avrconfig.h| +Handling duplicates +------------------- -Pour chaque caractère reçu, on appelle |proto_accept|. Pour envoyer des -commandes, on utilise les fonctions |proto_send...|. +If the slave device received the message, but its acknowledgement was not +received by the master, the master can retransmit the frame. This behaviour +can leads to duplicate receptions of frames. If this causes a problem for +your application, you should add a mechanism, like a sequence number, in order +to detect duplicates. -Regarder le programme de test pour avoir un example. +For example, include an extra sequence number at the end of your frame. When +the slave receives the frame, it first checks that this sequence number is not +the last received one. If it matches, the frame is ignored, but an +acknowledgement is sent anyway. If it does not match, the frame is handled, +the sequence number is remembered and an acknowledgement is sent. -* Doc +This sequence number can also be used by the slave to signal that a long +command is finished. -*File: proto.exd +Unexpected transmission from the slave +-------------------------------------- + +There is no acknowledgement from the master and no retransmission from the +slave. Therefore, the slave is not able to know if its message has been +received. + +To handle this, here is two methods: + +- Transmit periodically a variable which must be known by the master instead + of sending only changes. +- Transmit periodically a sequence number once an event occurs. The master + must give this sequence number back to stop the transmission. + +Usage +===== + +The user must define a callback function to handle incoming frames, and a +function used to send a character. The names of theses function is defined in +``avrconfig.h``. + +For each received character, the function ``proto_accept`` should be called. + +To send frames, the ``proto_send...`` functions should be used. + +API +=== + +.. include:: proto.exd -- cgit v1.2.3