summaryrefslogtreecommitdiff
path: root/digital/avr
diff options
context:
space:
mode:
authorNicolas Schodet2008-06-17 22:57:39 +0200
committerNicolas Schodet2008-06-17 22:57:39 +0200
commitc908ba7058ae9bc8f7a9446e17e3482d125234de (patch)
treedf6895d8c196437e39f75e74f70cfd34ffba55fc /digital/avr
parentb56dcf06e561729f87670d32f3b75c4aeddfee29 (diff)
* digital/avr/modules/proto:
- updated doc.
Diffstat (limited to 'digital/avr')
-rw-r--r--digital/avr/modules/proto/Makefile2
-rw-r--r--digital/avr/modules/proto/proto.txt163
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