doc/protocolo.txt

   1 ELP - Etherled Protocol (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 confirmación de entrega.
  19 Para esto utiliza un identificador de paquete pequeño por cada tipo de operación
  20 que se utiliza para saber a que paquete pertenece una respuesta (ACK).
  21 No se realiza control de errores ya que la capa de transporte (UDP) nos provee
  22 de un CRC.
  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       |
  61 +-----+--------------------+---------------+
  62 /- 1 -/------ 4 bits ------/--- 3 bits ----/
  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 15 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
  80 DATOS
  81 -----
  82 Los datos se envían para cada operación SET en sentido cliente->servidor y para
  83 cada operación GET en sentido contrario (servidor->cliente). Pueden haber
  84 variables que no posean datos en absoluto (una variable booleana tipo switch,
  85 que active algo si estaba desactivado o a la inversa).
  86 Los datos no son codificados de ninguna manera en particular ni requiere (en
  87 términos generales) un campo de longitud, ya que la cantidad de datos enviados
  88 está predefinido para cada VARiable (ver sección Variables Definidas).
  89
  90 La máxima cantidad de bytes que se pueden enviar está determinada por la
  91 implementación del dispositivo.
  92
  93
  94 Variables Definidas
  95 -------------------
  96
  97  Id | Nombre      | Descripción      | Datos
  98 ----+-------------+------------------+------------------------------------------
  99   0 | OFF         | Apaga el         | Ninguno, esta operación sólo tiene
 100     |             | dispositivo      | sentido haciendo un SET
 101 ----+-------------+------------------+------------------------------------------
 102   1 | MATRIX      | Matriz a dibujar | 1 byte para la cantidad de columnas
 103     |             |                  | (ancho) más 2*ancho bytes con el
 104     |             |                  | contenido de la matriz organizado
 105     |             |                  | como se indica en la sección Matriz
 106 ----+-------------+------------------+------------------------------------------
 107   2 | DRAW        | Prendido/apagado | 1 byte con conteniendo 0xFF para prender
 108     |             | del dibujado     | o con 0x00 para apagar
 109 ----+-------------+------------------+------------------------------------------
 110
 111 El resto de las variables quedan para futuras extensiones.
 112
 113
 114 Matriz
 115 ------
 116
 117 Para convertir la matriz a un array de bits se utiliza el siguiente esquema:
 118
 119 Suponemos una matriz chica, de 4x4 para simplificar el ejemplo. Para organizar
 120 dicha matriz como un array de bits, simplemente hay que rotarla en sentido
 121 horario y recorrer por filas de arriba hacia abajo (agrupando por bytes).
 122
 123 Por ejemplo:
 124
 125
 126 0           columna          15
 127
 128 0 0 0 0 1 1 1 1 1 1 1 1 0 0 0 0   fila 0
 129 0 0 1 1 1 1 1 1 1 1 1 1 1 1 0 0   fila 1
 130 0 1 1 1 0 0 0 0 0 0 0 0 1 1 1 0   fila 2
 131 0 1 1 0 0 0 0 0 0 0 0 0 0 1 1 0   fila 3
 132 1 1 0 0 0 1 1 0 0 1 1 0 0 0 1 1   fila 4
 133 1 1 0 0 0 1 1 0 0 1 1 0 0 0 1 1   fila 5
 134 1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1   fila 6
 135 1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 1   fila 7
 136 1 1 0 0 1 0 0 0 0 0 0 1 0 0 1 1   fila 8
 137 1 1 0 0 1 1 0 0 0 0 1 1 0 0 1 1   fila 9
 138 1 1 0 0 0 1 1 1 1 1 1 0 0 0 1 1   fila 10
 139 1 1 0 0 0 0 1 1 1 1 0 0 0 0 1 1   fila 11
 140 0 1 1 0 0 0 0 0 0 0 0 0 0 1 1 0   fila 12
 141 0 1 1 1 0 0 0 0 0 0 0 0 1 1 1 0   fila 13
 142 0 0 1 1 1 1 1 1 1 1 1 1 1 1 0 0   fila 14
 143 0 0 0 0 1 1 1 1 1 1 1 1 0 0 0 0   fila 15
 144
 145                |
 146                |
 147                V
 148
 149 15           fila             0
 150 /--------------/--------------/
 151       HIGH           LOW
 152
 153 0 0 0 0 1 1 1 1 1 1 1 1 0 0 0 0   columna 0
 154 0 0 1 1 1 1 1 1 1 1 1 1 1 1 0 0   columna 1
 155 0 1 1 1 0 0 0 0 0 0 0 0 1 1 1 0   columna 2
 156 0 1 1 0 0 0 0 0 0 0 0 0 0 1 1 0   columna 3
 157 1 1 0 0 0 0 1 1 0 0 0 0 0 0 1 1   columna 4
 158 1 1 0 0 0 1 1 0 0 0 1 1 0 0 1 1   columna 5
 159 1 1 0 0 1 1 0 0 0 0 1 1 0 0 1 1   columna 6
 160 1 1 0 0 1 1 0 0 0 0 0 0 0 0 1 1   columna 7
 161 1 1 0 0 1 1 0 0 0 0 0 0 0 0 1 1   columna 8
 162 1 1 0 0 1 1 0 0 0 0 1 1 0 0 1 1   columna 9
 163 1 1 0 0 0 1 1 0 0 0 1 1 0 0 1 1   columna 10
 164 1 1 0 0 0 0 1 1 0 0 0 0 0 0 1 1   columna 11
 165 0 1 1 0 0 0 0 0 0 0 0 0 0 1 1 0   columna 12
 166 0 1 1 1 0 0 0 0 0 0 0 0 1 1 1 0   columna 13
 167 0 0 1 1 1 1 1 1 1 1 1 1 1 1 0 0   columna 14
 168 0 0 0 0 1 1 1 1 1 1 1 1 0 0 0 0   columna 15
 169
 170
 171 Para serializarlo se convierte en este stream de bytes (fila;columna):
 172
 173 /-------------------------- byte 0 -----------------------------/
 174 +-------+-------+-------+-------+-------+-------+-------+-------+
 175 | cols7 | cols6 | cols5 | cols4 | cols3 | cols2 | cols1 | cols0 | == cant. cols
 176 +-------+-------+-------+-------+-------+-------+-------+-------+
 177
 178 /-------------------------- byte 1 -----------------------------/
 179 +-------+-------+-------+-------+-------+-------+-------+-------+
 180 |  8;0  |  9;0  | 10;0  | 11;0  | 12;0  | 13;0  | 14;0  | 15;0  | == HIGH(col0)
 181 +-------+-------+-------+-------+-------+-------+-------+-------+
 182
 183 /-------------------------- byte 2 -----------------------------/
 184 +-------+-------+-------+-------+-------+-------+-------+-------+
 185 |  0;0  |  1;0  |  2;0  |  3;0  |  4;0  |  5;0  |  6;0  |  7;0  | == LOW(col0)
 186 +-------+-------+-------+-------+-------+-------+-------+-------+
 187
 188 ...
 189
 190 /-------------------------- byte 31 ----------------------------/
 191 +-------+-------+-------+-------+-------+-------+-------+-------+
 192 |  8; 5 |  9;15 | 10;15 | 11;15 | 12;15 | 13;15 | 14;15 | 15;15 | == HIGH(col15)
 193 +-------+-------+-------+-------+-------+-------+-------+-------+
 194
 195 /-------------------------- byte 32 ----------------------------/
 196 +-------+-------+-------+-------+-------+-------+-------+-------+
 197 |  0;15 |  1;15 |  2;15 |  3;15 |  4;15 |  5;15 |  6;15 |  7;15 | == LOW(col15)
 198 +-------+-------+-------+-------+-------+-------+-------+-------+
 199
 200
 201 En el protocolo la cantidad de filas es _SIEMPRE_ 16, ya que está limitada
 202 físicamente por la cantidad de leds del dispositivo. Por lo tanto, siempre
 203 tendremos agrupada cada columna en 2 bytes.
 204
 205 Es decir, el stream de bits será:
 206
 207 HIGH(col0), LOW(col0), HIGH(col1), LOW(col1), ... , HIGH(colN), LOW(colN)
 208
 209 Siendo HIGH(colI) la parte alta de la columan I y LOW(colI) su parte baja.
 210
 211 Finalmente, los DATOS de una matriz tienen la siguiente estructura:
 212 +----------------+------------------------------------------------+
 213 |      LEN       | HIGH(col0) LOW(col0) ...  HIGH(colN) LOW(colN) |
 214 +----------------+------------------------------------------------+
 215 /---- 1 byte ----/------------------- variable -------------------/
 216
 217 Siendo LEN la cantidad columnas de la matriz.
 218
 219
 220
 221
 222 vim: set encoding=iso-8859-1 :