DOCUMENTACION DE PROTOCOLO MAM TCP V2
Descripción
Protocolo de comunicación para extraer los datos de los dispositivos remotos
orientado a la conexión, basado en el protocolo TCP. Este protocolo permitirá la
implementación de una serie de frames apara el intercambios de datos, teniendo en
cuenta tres aspectos fundamentales; seguridad, consumo de datos, y trasmisión de
datos en tiempo real.
Para conseguirlo el protocolo utilizara pequeños fragmentos de datos los cuales
denominamos frame que encapsularan todos los datos a intercambiar, un sistema de
login basado en la combinación de el unix y la clave de seguridad, con la cual solo
después de este haberse realizado exitosa mente se procede con el intercambio de
información, y un modelo de intercambio de datos dinámico que permite variar los
intervalos de conexión permitiendo así un flujo de datos en tiempo real para los
casos en que sea necesario.
Objetivos principales
1. El protocolo debe ser seguro: se debe tener en
consideración
una
implementación que asegure la integridad de los datos y que solo los dispositivos
capas de pasar el login puedan realizar un intercambio de datos.
2. Se debe de considerar que el consumo de datos sea el mínimo para que el
protocolo sea rentable a grandes escalas.
3. Debe tener la capacidad de crear conexiones que permitan el flujo de datos en
tiempo real, reduciendo al mínimo el tiempo para el intercambio de información.
4. Se debe de implementar un flujo de intercambio de datos que tome en
consideración los ack y los re-intentos de ambas partes cuando algunos de las dos
partes no logro interpretar el dato recibido, con el fin de no tener que esperar una
nueva conexión para realizar la solicitud nuevamente.
5. Se debe de incluir uno o mas bytes que permitan dinamizar tanto las solicitudes
como las repuestas, para poder enviar mas datos de ser necesario en la misma
respuesta.
6. Crear una cola de peticiones y respuestas de tal modo que se puedan recibir
varias peticiones continuas y poder responderlas según la prioridad de las mismas.
7. Crear un formato de envío de datos que se puedan paginar dependiendo de la
cantidad de dispositivos que este monitoreando el el módem.
8. Crear un sistema de notificaciones para poder alertar los eventos generados en
tiempo real, sin necesidad de esperar que se cumpla en intervalo de conexión
configurado.
9. Debe existir la posibilidad de hablar directamente con el dispositivo remoto en su
protocolo nativo, con el fin de que se pueden extraer datos que no están
incorporados nativa mente en el protocolo de comunicación.
10. Los tiempos en los que se envían los datos al servidor y las tareas para la
recolección de los mismos debe poder ser configura-bles desde el servidor.
Diagrama de flujo de peticiones del protocolo
1. El cliente (dispositivo remoto) sean quien inicie la comunicación con el servidor.
2. Una ves recibida la respuesta de la solicitud de conexión por el servidor, este
validara el dispositivo y procederá a realizar un login.
3. El login es recibido por el cliente y este validad el login y calcula un key para la
sesión.
4. Una vez calculado el key el cliente enviara los datos que tiene preparados al
servidor.
5. Por cada frame de datos recibidos por el server este responderá con un ack que
valide los datos recibidos.
6. Si existen mas datos por enviar del lado del cliente la secuencia anterior se repite.
7. Cunado finalicen los datos a a enviar por el cliente este le indicara al servidor el
cierre de sesión.
8. En el caso de que llegue una petición del lado del servidor para solicitar datos en
tiempo real la sesión quedara abierta con el fin de poder enviar y recibir datos con la
menor latencia posible.
En esta condición se plantea un modo donde el cliente envíe sus datos con un
intervalo de transmisión mínimo, en el caso de que lleguen peticiones para el cliente
mientras se esta en este modo estas peticiones serán respondidas con mayor
prioridad a las de envío de datos recurrentes.
En el momento que el usuario no necesite tal flujo de datos se regresa al modo
anterior.
Descripción de la cabecera
La cabecera esta compuesta por los bytes de: Inicio de nuevo
frame(STX),longitud(LEN), comando (CMD), dinámico(DYN), tipo de modulo(MT), la
llave que se genera luego de hacer un login (KEY), y el checksum(CSK) . Estos valores
están el formato big-endian.

STX[0]: este byte esta ubicado en la posición 0 del frame indica el inicio de un
nuevo frame de datos, el valor es 0x68 hex.

LEN[1,2]: estos bytes componen la longitud del frame a partir del STX hasta el
CSK.

CMD[3]: indica la acción o tempo de dato que contiene el frame.

DYN[4]: este byte puede contener un valor para especificar un contenido
adicional en el mismo frame de datos es decir, hacer el frame dinámico, cada
cmd puede tener uno o varios valores dinámicos para indicar datos adicionales
el la estructura original de frame.

KEY[5,6]: estos valores corresponde a la llave generada por el login que realiza el
dispositivo cuando inicia el proceso de intercambio de datos, todos los
intercambio de datos deben de tener una llave valida para esa sesión, en caso de
que el dispositivo o el servido reciban una llave invalida dentro de una sesión
cualquiera de los dos puede terminar la sesión inmediatamente.

CSK[valor del len]: es el residuo del modulo de la sumatoria de todos los bytes
(desde la posición 0 hasta el ultimo byte de datos) con 256. Este tiene posición
variable ya que su posición depende la longitud del frame
Otros bytes de datos que se pueden incluir en la cabecera, pero que dependen del
tipo de dato que se este enviado o del cmd en particular son:

MT: tipo de modulo(module type), este sirve para indicarle al servidor el tipo de
información que este le va a servir y el formato de los datos.

DT: tipo de dispositivo, este byte identifica el dispositivo por marca y modelo
dentro de una lista ya definida, esto permite saber los parámetros y datos que
se pueden obtener el dispositivo.

ID: este byte corresponde al id que posee el dispositivo dentro de la lista del
gateway.

QTY: este valor indica la cantidad de dispositivos que se va a recibir en un solo
frame de datos.
Inicio de comunicación desde el gateway
MAM_KEEPALIVE(0x00):
En este cmd el dispositivo se comunica para verificar si el servidor tiene alguna
petición en cola, si existe alguna petición en la cola el servidor responderá con un
mam_login, de no tener nada el servidor enviara un cierre de sesión.
Estructura del frame:
1 byte
2 byte
1 byte
1 byte
1 byte
XX byte
1 byte
STX
LEN
CMD DYN
MT
MAC ADDRESS o IMEI
CKS
type
serial of master
sum
start
high
low
comand
0x68
X
0x0E
0
X
X
x
x
x
x
x
x
x
x
X
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Este frame contiene la macaddress o el imei del gateway y su longitud sera obtenida
dinamicamente por el servidor.
MAM_EVENT_DATA(0x03):
En este cmd el dispositivo se comunica para notificar al servidor que tiene datos
nuevos para enviar, el servidor responderá con un mam_login.
1 byte
2 byte
1 byte
1 byte
1 byte
XX byte
1 byte
STX
LEN
CMD DYN
MT
MAC ADDRESS o IMEI
CKS
type
serial of master
sum
start
high
low
comand
0x68
X
0x0E
0x03
X
X
x
x
x
x
x
x
x
x
X
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
Este frame contiene la macaddress o el imei del gateway y su longitud sera obtenida
dinamicamente por el servidor.
Respuesta de inicio de comunicación desde el server
MAM_CLOSE(0x01): este comando es enviado como respuesta a un gateway luego
hacer haber recibido un un keepalive y que el mismo no tuviera ninguna petición en
la cola.
Estructura del frame:
1 byte
2 byte
STX
LEN
1 byte
1 byte
1 byte
CMD
DYN
CKS
start
high
low
comand
0x68
0x00
0x05
0x01
0x00
XX
0
1
2
3
4
5
sum
MAM_LOGIN(0x02): este comando tiene varias funciones, actualizar la hora y fecha
del dispositivo en cada conexión, inicial la validación del dispositivo para el proceso
de intercambio de datos. El login envía como parámetro el unix-time del servidor en
el momento en que se pone en cola, y este sirve para generar un hash de 16bytes
que se utiliza como llave de la sesión para todos los comandos que se envíen o se
reciban luego de que este se haya validado del lado del servidor. Por motivos de
seguridad y espacio cada dispositivo comparte un fragmento del hash que se genero,
pero la validación se realiza con el hash completo.
Estructura del frame de login
1 byte
2 byte
STX
LEN
1 byte
1 byte
CMD
DYN
start
high
low
comand
0x68
0x00
0x09
0x02
0
1
2
3
4 byte
1 byte
CKS
UNIXTIME
0x00 0x5C
4
5
sum
0x6B
0xD9
0x5E
0x81
6
7
8
9
El orden del unix recibido esta en litte-endian.
Si el login no se completa por parte del server o del gateway la sesión se cierra por
cualquiera de los dispositivo.
Solicitud desde el servidor hacia el gateway
Una ves que se haya validado el login el servidor procederá enviar las peticiones que
estén el la cola para el dispositivo en particular.
MAM_DATA_REQUEST (0x04): Este comando solicita todos los datos que el gateway
tiene en su cola para ser enviados el servidor. Este comando no tiene una respuesta
única, es decir cualquier tipo de evento generado por el dispositivo puede sera
recibido con este comando (lecturas, alarmas, eventos, contadores, etc).
Estructura del frame:
1 byte
2 byte
1 byte
1 byte
STX
LEN
CMD
DYN
start
0x68
high
0x0
0
low
0x08
1
X
3
X
4
1 byte
CKS
KEY
comand
0x04
2
2 byte
sum
X
5
X
6
8
MAM_REALTIME_REQ(0xA9): Este comando sirve para activar y desactivar el flujo
de dato tiempo real entre el gateway y el servidor. Los datos intercambiado en este
modo son configurados en el dispositivo. En este modo tanto el gateway como el
servidor pueden recibir y enviar datos simultanea mente ya que las solicitudes se van
al almacenando en una cola esto permite recibir varias peticiones al simultanea y
luego responderlas por separado.
El modo tiempo real solamente se desactiva cuando se recibe el el mismo comando
con el parámetro de desactivar, si la sesión se interrumpe, una vez que el dispositivo
se conecte, seguirá enviando datos den tiempo real. En caso de que el dispositivo se
apague en este modo el servidor deberá de enviar nuevamente la solicitud de datos
de ser requerido.
Descripción del frame:
1 byte
2 byte
1 byte
1 byte
STX
LEN
CMD
DYN
start
high
low
2 byte
KEY
comand
0x68
0x0
0x08
0xA9
0
1
2
3
X
X
4
1 byte
X
5
6
1 byte
ID
SUB CMD
CKS
Device ID
act/dead
sum
X
X
7
X
8
9
El SUB CMD es el parámetro que indica si el modo real time sera activado o
desactivado, para esto solo hay que indicar el valor de 0 o 1.
Descripción de los frames de datos
Cabecera del frame de datos
Los frame de la cabecera de datos contienen dos byte adicionales que son el tipo de
dispositivo y el id que tiene este en la lista del gateway.
Los frame de datos están separados en tres grupos: los que tiene lecturas de
entradas digitales y lo que tiene lecturas de entradas análogas y los eventos,
contadores y alarmas.
Los frame de dato pueden variar el contenido y la cantidad de datos dependido del
tipo de dispositivo que genere la información. Ademas un mismo dispositivo puede
enviar el dato con mas o con menos información indicando esto, en el byte del
dinámico.
Todos la información contenida en la sección de datos dentro del frame deberá estar
en el formato litte-endian.
Los comando que agrupan este tipo de datos son:
MAM_MEASUREMENTS(0xA1): este comando contiene los valores de lecturas
análogas de un dispositivo o varios dispositivos. Los datos de este frame están
estructurados según el tipo de dispositivo. En este tipo de frame puede cambiar si el
dinámico lo indica, conteniendo mas o menos información según el parámetro del
DYN.
Descripción del frame de datos análogos.
1 byte 2 byte
1 byte
1
byte
STX LEN CMD DYN
0
1
2
3
KEY
1 byte
TYPE
ID
high low Device Type Device ID
start high low comand
0x68 x x 0xA1
2 byte
X
X
X
4
5
6
X
7
1
XX byte
byte
CKS
DATA
sum
XX X X X X X X X X X X X X
8
9 10 11 12 13 14 15 16 17 18 19 20 21
X
22
X
23
29
MAM_INPUTS(0xA2): Este comando contiene la información de las entradas
digitales del dispositivo. Los datos de este frame están estructurados según el tipo
de dispositivo .En este tipo de frame puede cambiar si el dinámico lo indica,
conteniendo mas o menos información según el parámetro del DYN.
1 byte 2 byte
1 byte
1
2 byte
1 byte
1
XX byte
byte
STX LEN CMD DYN
0
1
2
3
KEY
TYPE
ID
high low Device Type Device ID
start high low comand
0x68 x x 0xA2
byte
X
X
X
4
5
6
X
7
CKS
DATA
sum
XX X X X X X X X X X X X X
8
9 10 11 12 13 14 15 16 17 18 19 20 21
X
22
X
23
29
Descripción de los frames de control del servidor
Los frame de control permiten realizar alguna acción en el dispositivo. Estas acciones
se realizaran on request, es decir que se esperara una respuesta o confirmación del
dispositivo para ser enviada al servidor.
MAM_CONTROL(0xA3): este frame contiene los parámetros para realizar las
acciones de control de un dispositivo especifico.
El frame de control contiene dos parámetros, el ID: id del dispositivo en la lista del
gateway el SUB CMD: el tipo de acción que se va a realizar.
1 byte
2 byte
1 byte
1 byte
STX
LEN
CMD
DYN
start
high
low
2 byte
KEY
comand
0x68
0x0
0x08
0xA3
0
1
2
3
X
X
4
1 byte
X
5
1 byte
ID
SUB CMD
CKS
Device ID
act/dead
sum
X
X
6
7
X
8
9
Descripción de los frames de control del gateway
MAM_CONTROL(0xA3): Este frame contiene la respuesta a una solicitud de control
desde el servidor. Este frame puede variar dependiendo el tipo de dispositivo y la
respuesta del mismo.
1 byte
2 byte
1 byte
1 byte
2 byte
STX
LEN
CMD DYN
KEY
start
high
low
comand
0x68
x
x
0xA3
0
1
2
3
1 byte
TYPE
high
low
X
X
X
4
5
6
ID
DATA UNIX TIME
X
X
8
CKS
of Data
Device Type Device ID
7
1
byte
4 byte
9
sum
X
10
11
Descripción de los frames de agregar dispositivos al
gateway desde el server
X
X
12
X
13
14
MAM_ADD_DEVICE 0(xAB):
1 byte
2 byte
1 byte
1 byte
1 byte
STX
LEN
CMD
DYN
QTY
start
high
low
comand
device amount
0x68
X
0x0E
0
0
X
0
1
2
3
4
5
1 byte
2 byte
2 byte
1 byte
Gateway GSM
1 byte
1 byte
1 byte
1 byte
COM TYPE
ID
device id
device id
device type
X
X
X
X
6
7
8
1 byte
DEVICE TYPE STATUS FROM BYTE FRAME BAUDRATE COM ADDRRES SERIAL LEN
act/inactive serial/server
N byte
1 byte
SERIAL
NUMBER
CKS
device id
device id
rs 485 port
bytes of serial
n bytes
sum
X
X
X
X
X
X
X
9
10
11
12
13
14
15
16
Raspberry Pi
1 byte
1 byte
1 byte
1 byte
1 byte
2 byte
1 byte
N byte
2 byte
4 byte
1 byte
COM
TYPE
ID
DEVICE
TYPE
STATUS
FROM
COM
ADDRRES
SERIAL
LEN
SERIAL
NUMBER
PORT
IP HOST
CKS
device id
device id
device id
device id
device id
device id
device id
device id
device id
device id
sum
X
X
X
X
X
X
X
X
X
X
X
6
7
8
9
10
13
14
15
11
12
16
Descripción de los frames de listar los dispositivos del
gateway al server
MAM_DEVICES_LIST(0xAE):
1 byte
2 byte
1 byte
1 byte
STX
LEN
CMD
DYN
1 byte
1 byte
1 byte
QTY
ID
STATUS
1 byte
low
device amount device id act/inactive device type bytes of serial
0x68
X
0x0E
0
X
X
X
X
X
0
1
2
3
4
5
6
7
8
comand
n bytes
TYPE SERIAL LEN SERIAL NUM
high
start
1 byte
1 byte
CKS
n bytes
sum
X
X
X
9
10
11