doc/protocolo.txt

   1 petherled - Protocolo de comunicación del dispositivo etherled
   2 ==============================================================
   3
   4
   5 Objetivo
   6 --------
   7
   8 El objetivo del protocolo de comunicación con el dispositivo etherled es que sea
   9 de lo más simple para el dispositivo, dejando la mayor responsabilidad posible
  10 en el cliente (PC que se conecta al dispositivo). Además tiene como objetivo la
  11 simplicidad y la minimización de los datos a enviar (requerimientos de buffer).
  12
  13
  14 Introducción
  15 ------------
  16
  17 Este protocolo está pensado para funcionar sobre UDP, es por esto que posee
  18 algunos mecanismos básicos para control de errores y confirmación de entrega.
  19 Para esto utiliza un identificador de paquete pequeño por cada tipo de
  20 operación que se utiliza para saber a que paquete pertenece una respuesta (ACK).
  21 Para control de errores se utiliza por un lado un bit de paridad en la cabecera
  22 y por otro un CRC para los datos (de haber).
  23
  24 El protocolo, como se dijo anteriormente diferencia bien entre el dispositivo
  25 etherled (servidor) y la PC u otro dispositivo que le envía comandos (cliente).
  26 Es por esto que un mismo comando puede tener distinta semántica según su
  27 dirección (cliente->servidor o servidor->cliente). Incluso cambia la
  28 conformación del paquete según su dirección.
  29
  30 El protocolo se trata básicamente de un mecanismo para establecer u obtener el
  31 valor de ciertas variables del dispositivo (servidor). Por tanto define esas
  32 variables e indica que tipo de operación se está llevando a cabo sobre ellas:
  33 GET o SET. GET indica que el cliente va a obtener el valor de la variable y SET
  34 que va a establecerlo. Las operaciones de GET no tienen parámetros extra (Datos)
  35 cuando van en dirección cliente->servidor pero sí cuando van en dirección
  36 inversa (servidor->cliente). Las operaciones SET se comportan exactamente de
  37 modo inverso.
  38
  39 Toda operación tiene una respuesta idéntica (excepto por los datos). Es decir,
  40 si el cliente envía un SET de una variable VAR al servidor, con los datos DATA
  41 y con identificador ID, el servidor responderá con otro paquete SET con la
  42 variable VAR, con identificador ID pero sin datos. Es decir, se utiliza como
  43 ACK al mismo paquete recibido (sólo que sin los datos).
  44
  45
  46 Paquete petherled
  47 -----------------
  48
  49 +----------------+--------------------------------+
  50 |    CABECERA    |        DATOS (opcional)        |
  51 +----------------+--------------------------------+
  52 /---- 1 byte ----/---------- 0-64 bytes ----------/
  53
  54
  55 CABECERA
  56 --------
  57 La cabecera está compuesta por los siguientes campos:
  58
  59 +-----+---------------+---------------+-----+
  60 | GS  |      VAR      |      ID       | PAR |
  61 +-----+---------------+---------------+-----+
  62 /- 1 -/--- 3 bits ----/--- 3 bits ----/- 1 -/
  63
  64 GS:
  65         Este bit indica si la operación es GET (0) o SET (1).
  66
  67 VAR:
  68         Es un número de 0 a 7 que indica la variable sobre la cual se está
  69         operando. Ver sección Variables Definidas.
  70
  71 ID:
  72         Es un número de 0 a 7 que indentifica al paquete. Para extender la
  73         cantidad de identificadores efectivos disponibles, se utiliza un
  74         contador por cada tupla (GS,Variable), por lo tanto, en el caso ideal de
  75         que las operaciones estén perfectamente distribuidas entre todas las
  76         variables y GET y SET, se tendría una cantidad de indentificadores
  77         efectivos de 8 bits completo (256 posibilidades).
  78
  79 PAR:
  80         Es un bit que indica la paridad (par) de la cabecera, utilizado para
  81         control de errores.
  82
  83 DATOS
  84 -----
  85 Los datos se envían para cada operación SET en sentido cliente->servidor y para
  86 cada operación GET en sentido contrario (servidor->cliente). Pueden haber
  87 variables que no posean datos en absoluto (una variable booleana tipo switch,
  88 que active algo si estaba desactivado o a la inversa).
  89 Los datos no son codificados de ninguna manera en particular ni requiere (en
  90 términos generales) un campo de longitud, ya que la cantidad de datos enviados
  91 está predefinido para cada VARiable (ver sección Variables Definidas).
  92 Para control de errores los datos finalizan con un CRC.
  93
  94 +--------------------------------+----------------+
  95 |             DATOS              |      CRC       |
  96 +--------------------------------+----------------+
  97 /---------- 0-63 bytes ----------/---- 1 byte ----/
  98
  99 El CRC es de un byte y se utiliza el mismo CRC que utiliza IP y UDP (complemento
 100 a 1 de la suma). Se aplica sólo en los datos (no en las cabeceras, que utilizan
 101 el bit de paridad). A efectos de calcular el CRC, se toma el CRC como todo en 0.
 102
 103
 104 Variables Definidas
 105 -------------------
 106
 107  Id | Nombre      | Descripción      | Datos
 108 ----+-------------+------------------+------------------------------------------
 109   0 | Matriz      | Matriz a dibujar | 1 byte para la cantidad de columnas
 110     |             |                  | (ancho) más 2*ancho bytes con el
 111     |             |                  | contenido de la matriz organizado
 112     |             |                  | como se indica en la sección Matriz
 113 ----+-------------+------------------+------------------------------------------
 114   1 | Funcionando | Prendido/apagado | 1 byte con conteniendo 0xFF para prender
 115     |             | del dispositivo  | o con 0x00 para apagar
 116 ----+-------------+------------------+------------------------------------------
 117
 118 El resto de las variables quedan para futuras extensiones.
 119
 120
 121 Matriz
 122 ------
 123
 124 Para convertir la matriz a un array de bits se utiliza el siguiente esquema:
 125
 126 Suponemos una matriz chica, de 4x4 para simplificar el ejemplo. Para organizar
 127 dicha matriz como un array de bits, simplemente hay que rotarla en sentido
 128 antihorario y recorrer por filas de arriba hacia abajo (agrupando por bytes).
 129
 130   7   6   5   4   3   2   1   0 cols       7   6   5   4   3   2   1   0 filas
 131 7 o---o---o---o---o---o---o---o          0 o---o---o---o---o---o---o---o
 132   |   |   |   |   |   |   |   |            |   |   |   |   |   |   |   |
 133 6 o---o---o---o---o---o---o---o          1 o---o---o---o---o---o---o---o
 134   |   |   |   |   |   |   |   |            |   |   |   |   |   |   |   |
 135 5 o---o---o---o---o---o---o---o          2 o---o---o---o---o---o---o---o
 136   |   |   |   |   |   |   |   |            |   |   |   |   |   |   |   |
 137 4 o---o---o---o---o---o---o---o          3 o---o---o---o---o---o---o---o
 138   |   |   |   |   |   |   |   |  =====>    |   |   |   |   |   |   |   |
 139 3 o---o---o---o---o---o---o---o          4 o---o---o---o---o---o---o---o
 140   |   |   |   |   |   |   |   |            |   |   |   |   |   |   |   |
 141 2 o---o---o---o---o---o---o---o          5 o---o---o---o---o---o---o---o
 142   |   |   |   |   |   |   |   |            |   |   |   |   |   |   |   |
 143 1 o---o---o---o---o---o---o---o          6 o---o---o---o---o---o---o---o
 144   |   |   |   |   |   |   |   |            |   |   |   |   |   |   |   |
 145 0 o---o---o---o---o---o---o---o          7 o---o---o---o---o---o---o---o
 146 filas                                    cols
 147
 148 Quedando por resultado las columnas desde la 0 a la 7 en cada byte del stream de
 149 bits:
 150
 151 +-----+-----+-----+-----+-----+-----+-----+-----+
 152 | 7,0 | 6,0 | 5,0 | 4,0 | 3,0 | 2,0 | 1,0 | 0,0 | byte 0 == col 0
 153 +-----+-----+-----+-----+-----+-----+-----+-----+
 154
 155 +-----+-----+-----+-----+-----+-----+-----+-----+
 156 | 7,1 | 6,1 | 5,1 | 4,1 | 3,1 | 2,1 | 1,1 | 0,1 | byte 1 == col 1
 157 +-----+-----+-----+-----+-----+-----+-----+-----+
 158
 159 etc., etc., etc.
 160
 161 En el protocolo la cantidad de filas es _SIEMPRE_ 16, ya que está limitada
 162 físicamente por la cantidad de leds del dispositivo. Por lo tanto, siempre
 163 tendremos agrupada cada columna en 2 bytes.
 164
 165 Es decir, el stream de bits será:
 166
 167 HIGH(col0), LOW(col0), HIGH(col1), LOW(col1), ... , HIGH(colN), LOW(colN)
 168
 169 Siendo HIGH(colI) la parte alta de la columan I y LOW(colI) su parte baja.
 170
 171 Finalmente, los DATOS de una matriz tienen la siguiente estructura:
 172 +----------------+--------------------------------+----------------+
 173 |      LEN       | H(col0)L(col0)..H(colN)L(colN) |      CRC       |
 174 +----------------+--------------------------------+----------------+
 175 /---- 1 byte ----/---------- 0-62 bytes ----------/---- 1 byte ----/
 176
 177 Siendo LEN la cantidad columnas de la matriz.