Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                

KProductAPI ESP

Descargar como pdf o txt
Descargar como pdf o txt
Está en la página 1de 72

KProductAPI-PY

Manual del servidor API KXP vía comandos HTTP

V.1.01

Kimaldi Electronics, S.L. www.kimaldi.com


Ctra. Rubí, 292-B Pol.Ind. Can Guitard Tel: 937 361 510
08228 Terrassa (Barcelona) CIF B61802302 E-mail: kimaldi@kimaldi.com
ÍNDICE
1 INTRODUCCIÓN __________________________________________________________________________ 5
1.1 KProductAPI: API SERVER para redes KXP ________________________________________________________ 5
2 INSTALACIÓN Y CONFIGURACIÓN __________________________________________________________ 6
2.1 Instalación ____________________________________________________________________________________ 6
2.2 Fichero de configuración ________________________________________________________________________ 6
3 FUNCIONALIDADES DEL SERVER KPRODUCTAPI _____________________________________________ 8
3.1 Identificación de los equipos de las redes KXP _____________________________________________________ 8
3.2 Administración de las redes KXP _________________________________________________________________ 8
3.3 Intercambio de datos con los equipos de las redes KXP ______________________________________________ 9
3.3.1 Ejemplo: Probando las comunicaciones con un equipo ___________________________________________________________ 9
3.4 Detección de Eventos _________________________________________________________________________ 10
3.4.1 Detección de eventos mediante polling _______________________________________________________________________ 10
3.4.1.1 Lectura de eventos mediante polling ______________________________________________________________________ 10
3.4.1.2 Borrado de colas de eventos ____________________________________________________________________________ 11
3.4.2 Detección de eventos mediante socketio _____________________________________________________________________ 11
3.5 Actualización del firmware de los equipos de las redes KXP _________________________________________ 12
4 URIS Y MÉTODOS DEL SERVER KPRODUCTAPI ______________________________________________ 13
4.1 Acerca del servicio ____________________________________________________________________________ 14
4.1.1 Métodos _______________________________________________________________________________________________ 14
4.2 Instrucciones Genéricas (CPU). _________________________________________________________________ 15
4.2.1 Métodos _______________________________________________________________________________________________ 15
4.2.1.1 TestNodeLink ________________________________________________________________________________________ 15
4.2.1.2 HotReset____________________________________________________________________________________________ 15
4.2.1.3 GetFwVersion ________________________________________________________________________________________ 16
4.2.1.4 GetNodeInUseIpAddress _______________________________________________________________________________ 16
4.2.2 Eventos _______________________________________________________________________________________________ 18
4.2.2.1 OnUpdateNodeFlash __________________________________________________________________________________ 18
4.3 Instrucciones de Configuración (CFG). ___________________________________________________________ 19
4.3.1 Métodos _______________________________________________________________________________________________ 19
4.3.1.1 ReadCFG ___________________________________________________________________________________________ 19
4.3.1.2 WriteCFG ___________________________________________________________________________________________ 20
4.3.1.3 LoadFactoryCFG _____________________________________________________________________________________ 21
4.3.1.4 STORECFG _________________________________________________________________________________________ 21
4.4 Instrucciones InOut ___________________________________________________________________________ 22
4.4.1 Métodos _______________________________________________________________________________________________ 22
4.4.1.1 InOutLedOperate _____________________________________________________________________________________ 22
4.4.1.2 InOutBuzzerOperate __________________________________________________________________________________ 23
4.4.1.3 InOutRelayOperate ___________________________________________________________________________________ 23
4.4.1.4 InOutDigitalInputGet ___________________________________________________________________________________ 24
4.4.1.5 InOutLedSwitchOn ____________________________________________________________________________________ 24
4.4.1.6 InOutLedSwitchOff ____________________________________________________________________________________ 25
4.4.1.7 InOutRelaySwitchOn __________________________________________________________________________________ 25
4.4.1.8 InOutRelaySwitchOff __________________________________________________________________________________ 26
4.4.2 Eventos _______________________________________________________________________________________________ 26
4.4.2.1 OnInOutDigitalInputGetEcho ____________________________________________________________________________ 26
4.5 Instrucciones Rtc._____________________________________________________________________________ 27
4.5.1 Métodos _______________________________________________________________________________________________ 27
4.5.1.1 RtcRead ____________________________________________________________________________________________ 27
4.5.1.2 RtcWrite ____________________________________________________________________________________________ 27
4.6 Instrucciones Mifare. __________________________________________________________________________ 28
4.6.1 Métodos _______________________________________________________________________________________________ 28
4.6.1.1 Mifare ATQA-UID Get _________________________________________________________________________________ 28
4.6.1.2 MifareHalt ___________________________________________________________________________________________ 29
4.6.1.3 MifareWakeUp _______________________________________________________________________________________ 29
4.6.1.4 MifareLogin __________________________________________________________________________________________ 30

13/02/2020 2 de 72
4.6.1.5 MifareBlockRead _____________________________________________________________________________________ 31
4.6.1.6 MifareBlockWrite _____________________________________________________________________________________ 31
4.6.1.7 MifareBlockBackUp ___________________________________________________________________________________ 32
4.6.1.8 MifareSectorRead ____________________________________________________________________________________ 32
4.6.1.9 MifareSectorWrite _____________________________________________________________________________________ 33
4.6.1.10 MifareValueRead ____________________________________________________________________________________ 33
4.6.1.11 MifareValueWrite ____________________________________________________________________________________ 34
4.6.1.12 MifareValueIncrement ________________________________________________________________________________ 34
4.6.1.13 MifareValueDecrement ________________________________________________________________________________ 35
4.6.1.14 MifareValueRestore __________________________________________________________________________________ 35
4.6.1.15 MifareSecurityLevelRead ______________________________________________________________________________ 36
4.6.1.16 MifareSecurityLevelWrite ______________________________________________________________________________ 37
4.6.1.17 MifareKeyWrite ______________________________________________________________________________________ 38
4.6.2 Eventos _______________________________________________________________________________________________ 39
4.6.2.1 OnMifareTrack _______________________________________________________________________________________ 39
4.7 Instrucciones Ttl. _____________________________________________________________________________ 40
4.7.1 Eventos _______________________________________________________________________________________________ 40
4.7.1.1 OnTtlTrack __________________________________________________________________________________________ 40
4.8 Instrucciones Fim _____________________________________________________________________________ 41
4.8.1 Métodos _______________________________________________________________________________________________ 41
4.8.1.1 FimGetDeviceInfo _____________________________________________________________________________________ 41
4.8.1.2 FimGetFirmwareVersion _______________________________________________________________________________ 42
4.8.1.3 FimGetTemplate ______________________________________________________________________________________ 43
4.8.1.4 FimInstantMatching ___________________________________________________________________________________ 44
4.8.1.5 FimEnterMasterMode __________________________________________________________________________________ 45
4.8.1.6 FimLeaveMasterMode _________________________________________________________________________________ 46
4.8.1.7 FimGetNumberOfUsers ________________________________________________________________________________ 47
4.8.1.8 FimDeleteUser _______________________________________________________________________________________ 48
4.8.1.9 FimDeleteAllUsers ____________________________________________________________________________________ 49
4.8.1.10 FimAddUser ________________________________________________________________________________________ 50
4.8.1.11 FimIdentifyUser _____________________________________________________________________________________ 52
4.8.1.12 FimVerifyUser _______________________________________________________________________________________ 53
4.8.1.13 FimTransceive ______________________________________________________________________________________ 54
4.8.2 Eventos _______________________________________________________________________________________________ 56
4.8.2.1 OnFimFinger_________________________________________________________________________________________ 56
4.9 Instrucciones Rd _____________________________________________________________________________ 57
4.9.1 Métodos _______________________________________________________________________________________________ 57
4.9.1.1 RdTrackGet _________________________________________________________________________________________ 57
4.9.2 Eventos _______________________________________________________________________________________________ 58
4.9.2.1 OnRdTrack __________________________________________________________________________________________ 58
4.10 Instrucciones Uart. ___________________________________________________________________________ 59
4.10.1 Métodos ______________________________________________________________________________________________ 59
4.10.1.1 UartSend __________________________________________________________________________________________ 59
4.10.2 Eventos ______________________________________________________________________________________________ 60
4.10.2.1 OnUartReceive ______________________________________________________________________________________ 60
4.11 Instrucciones Keyboard. ______________________________________________________________________ 61
4.11.1 Eventos ______________________________________________________________________________________________ 61
4.11.1.1 OnKeyboardEcho ____________________________________________________________________________________ 61
4.12 Instrucciones Display. ________________________________________________________________________ 62
4.12.1.1 Métodos ___________________________________________________________________________________________ 62
4.12.1.2 DisplayWriteT0T1 ____________________________________________________________________________________ 62
4.12.1.3 DisplayWriteT0 ______________________________________________________________________________________ 63
4.12.1.4 DisplayWriteT1 ______________________________________________________________________________________ 63
4.12.1.5 DisplayClear ________________________________________________________________________________________ 64
4.12.1.6 DisplayBacklitSwitchOn _______________________________________________________________________________ 64
4.12.1.7 DisplayBacklitSwitchOff _______________________________________________________________________________ 64
4.13 Instrucciones Open __________________________________________________________________________ 65
4.13.1 Métodos ______________________________________________________________________________________________ 65
4.13.1.1 OpenTransceive _____________________________________________________________________________________ 65
4.13.1.2 OpenSend _________________________________________________________________________________________ 66

13/02/2020 3 de 72
4.13.2 Eventos ______________________________________________________________________________________________ 67
4.13.2.1 OnOpenEvent _______________________________________________________________________________________ 67
APENDICE A: CODIFICACIÓN KNET_ID _______________________________________________________ 68
APENDICE B: CÓDIGOS DE RETORNO _______________________________________________________ 69
APENDICE C: EJEMPLO DE FICHEROS DE CONFIGURACIÓN ____________________________________ 70
CONTROL DE REVISIONES _________________________________________________________________ 71
NOTAS __________________________________________________________________________________ 72

13/02/2020 4 de 72
1 INTRODUCCIÓN

1.1 KPRODUCTAPI: API SERVER PARA REDES KXP

Un conjunto de productos Kimaldi compatibles con el protocolo KXP e interconectados entre sí, ya sea mediante
comunicación serie RS-232, USB, bus CAN o Ethernet (UDP) constituyen una unidad lógica que denominaremos
Red KXP.

El Server KProductAPI permite acceder a la red KXP mediante el uso del protocolo HTTP y el conjunto de
métodos (GET, POST,) usados para llevar a cabo los denominados servicios CRUD (Create, Read, Update and
Delete).

En este manual se describen los métodos y recursos que ofrece el Server KProductAPI. Gracias a ellos, se
pueden desempeñar las siguientes tareas:

1. Administrar la red KXP.


2. Intercambiar datos con los equipos de la red.
3. Actualizar el firmware de los equipos de la red.

13/02/2020 5 de 72
2 INSTALACIÓN Y CONFIGURACIÓN

2.1 INSTALACIÓN

Encontrará los archivos de instalación del Server KProductAPI en el área de clientes de nuestra web
www.kimaldi.com. Descargue los ficheros adecuados según sea el sistema operativo que utilice.

Para completar la instalación basta con ubicar en un mismo directorio del sistema todos los archivos descargados.
En caso de trabajar con el sistema operativo Linux, recuerde conceder permisos de ejecución al archivo
ejecutable.

En todos los casos se recomienda instalar el Server KProductAPI como un servicio, de forma que arranque
automáticamente al iniciar la máquina que lo hospeda.

2.2 FICHERO DE CONFIGURACIÓN

Al arrancar, las versiones Linux y Windows del Server KProductAPI leen un fichero llamado KProductAPI.cfg,
donde se almacenan parámetros que determinan el comportamiento del servicio. Estos parámetros son:

DEBUG_ON = Booleano que se usa en pruebas de mantenimiento de la KProductAPI

API_HOST = Dirección IP del cliente de la API.


Si es 0.0.0.0 se podrá interrogar a la API desde cualquier dirección IP.
Si es 127.0.0.1 el cliente de la API y la propia API deben ejecutarse en el mismo equipo

API_PORT = Puerto TCP en el que la KProductAPI escuchará peticiones HTTP

SOCKETIO_CLIENT = Booleano que indica si la KProductAPI emite mensajes a un servidor SocketIo

SOCKETIO_HOST_SERVER = IP del servidor SocketIo

SOCKETIO_PORT_SERVER = Puerto TCP del servidor SocketIo

SOCKETIO_EVENT_ECHO = Booleano que indica si la KProductAPI imprime por pantalla eventos SocketIo

SCAN_HIGH_SPEED = Booleano que indica si la red KXP es de respuesta rápida o lenta.


Especifique False sólo en caso que haya productos en la red que usen la conexión de bus CAN.

13/02/2020 6 de 72
PORT_TYPE = Uno de los siguientes valores, SERIAL o UDP

En caso de tener PORT_TYPE = SERIAL:


SERIAL_PORT = Nombre del Puerto serie (COM1, /dev/serial0, …) dependiendo del sistema operativo
utilizado.

SERIAL_BAUD_RATE = Velocidad del Puerto serie en baudios

En caso de tener PORT_TYPE = UDP:

UDP_REMOTE_ADDRESS = Dirección IP del equipo/s con el/los que vamos a comunicarnos

UDP_SUBNET_MASK = Máscara de red del equipo/s con el/los que vamos a comunicarnos

UDP_PORT = Puerto TCP usado para comunicar con con el/los equipo/s

El fichero KProductAPI.cfg no existe para la versión Android. Esta arranca, siempre con el siguiente conjunto
de valores:

DEBUG_ON = False

API_HOST = 127.0.0.1

API_PORT = 9443

# SOCKETIO

SOCKETIO_CLIENT = False

# PORT_TYPE SERIAL

PORT_TYPE = SERIAL

SERIAL_PORT = /dev/ttyS1

SERIAL_BAUD_RATE = 19200

13/02/2020 7 de 72
3 FUNCIONALIDADES DEL SERVER KPRODUCTAPI

3.1 IDENTIFICACIÓN DE LOS EQUIPOS DE LAS REDES KXP

Todos los equipos KXP poseen una “matrícula” única llamada EUI64. Como sugiere su nombre, se trata de un
número compuesto por 64 bits, aunque en este manual lo vamos a representar siempre con una cadena de 16
dígitos hexadecimales.

El formato del EUI64 está regulado por el IEEE. De acuerdo con este organismo internacional los EUI64 de todos
los productos Kimaldi deben empezar por: “001824”, que es el prefijo de fabricante, y durante el proceso de
fabricación se deben asignan los diez dígitos restantes, garantizando siempre una numeración única para cada
equipo.

Como ejemplo, un posible valor de EUI64 podría ser el número: “0018240011223344”.

La interfaz que ofrece el Server KProductAPI usa siempre este valor para identificar los distintos equipos de una
instalación concreta. Si embargo, a bajo nivel el protocolo KXP requiere que cada uno de los equipos de la red
posea una dirección lógica única. La dirección lógica es un número del 1 a 1022 que se encuentra almacenado en
la memoria no volátil del equipo, concretamente en la página 1 de la configuración. El Server KProductAPI se
encarga por completo de gestionar esta forma de direccionamiento, por lo que la aplicación cliente sólo necesita
conocer el EUI64 de los equipos con los que quiere operar.

3.2 ADMINISTRACIÓN DE LAS REDES KXP

La administración de una red KXP abarca dos aspectos:


1. La detección de los equipos.
2. La gestión de direcciones.

El Server KProductAPI, realiza ambas funciones permanente y automáticamente.

La primera se basa en un escaneo de la red cuyo objeto es detectar la conexión y la desconexión de equipos, y
mantener actualizada la lista de equipos conectados. Como veremos más adelante esta lista puede consultarse
en cualquier momento.

La red KXP requiere para su correcto funcionamiento que cada equipo posea una dirección lógica única. Si el
escaneo de la red detecta alguna dirección duplicada, eso constituye un conflicto de direcciones. El Server
KProductAPI lo resolverá automáticamente asignando direcciones libres a los equipos afectados. Una vez
resuelto, los equipos implicados se añadirán a la lista de equipos conectados y podrá operarse normalmente con
ellos. La resolución automática de conflictos se ejecuta normalmente cuando se pone en marcha por primera vez
una red KXP, cuando se añade un nuevo equipo a una red ya existente, o cuando se restaura la configuración de
fábrica de la página 1 de la configuración de alguno de los equipos. En estos casos los dispositivos en conflicto
pueden tardar en aparecer en la lista de dispositivos conectados del Server KProductAPI, y lo harán
automáticamente tan pronto como el proceso de resolución de conflictos concluya.

13/02/2020 8 de 72
3.3 INTERCAMBIO DE DATOS CON LOS EQUIPOS DE LAS REDES KXP

La URI:

http://localhost:9443/api/nodes

devuelve la lista de dispositivos conectados. En ella se especifica el modelo del dispositivo así como su
identificador EUI64.

A partir del momento en que un equipo aparece en la lista de dispositivos conectados es posible operar con él.
La forma de hacerlo es a través de la interfaz del Server KProductAPI, mediante URIs HTTP. Para emitir una
instrucción basta con invocar la URI que lleva el nombre de la operación que se desea ejecutar e informarle de los
parámetros requeridos.

3.3.1 EJEMPLO: PROBANDO LAS COMUNICACIONES CON UN EQUIPO


A modo de ejemplo veamos la URI correspondiente al método TestNodeLink.

La instrucción TestNodeLink sirve para verificar las comunicaciones, y su único parámetro es el identificador del
equipo en la red. Así, para comprobar las comunicaciones con un equipo cuyo EUI64 sea “001824FFFF04001A”
deberemos invocar el método con la URI

http://localhost:9443/api/nodes/001824FFFF04001A/Cpu/TestNodeLink

Para éste y el resto de ejemplos del manual, suponemos que:

1. el protocolo es http (y no https)


2. el cliente y el servidor están en la misma máquina, y por lo tanto el host es “localhost”
3. el puerto del servidor Web es el 9443 (configurable en el parámetro HostLocalPort=9443 del fichero
de configuración)

Dado que las consultas usan protocolo HTTP, sabremos que el Server KProductAPI nos ha respondido si el
“Status” HTTP de la respuesta es 200, o sea, “SUCCESS”.

Cualquier otro “Status” puede consultarse en:

https://es.wikipedia.org/wiki/Anexo:Códigos_de_estado_HTTP

Si el Status” HTTP de la respuesta es 200, en el cuerpo del Mensaje nos aparece la respuesta correspondiente.
En el resto del manual, mostraremos las respuestas en formato JSON
Para nuestro ejemplo de TestNodeLink, una ejecución correcta significa que el cuerpo de la respuesta es el
siguiente:
{
"ucInsRet": 0
}
En la tabla 2, aparecen los posibles valores de la variable ucInsRet.

13/02/2020 9 de 72
3.4 DETECCIÓN DE EVENTOS

Los equipos pueden enviar información como respuesta a peticiones http, pero también pueden hacerlo por
iniciativa propia. Por ejemplo, un terminal de control de acceso puede decidir retransmitir los datos de la tarjeta de
un cierto usuario justo en el momento de ser leída, otro lector de huellas digitales puede originar una
comunicación para indicar que ha detectado la presencia de una huella.

El Server KProductAPI registra dichos eventos junto con el EUI64 del equipo emisor, y pueden estar
acompañados de parámetros adicionales con la información específica enviada por el equipo.

El cliente dispone de dos maneras para conocer los eventos que se han producido: Polling o SocketIo. A
continuación, se detallan ambas modalidades.

3.4.1 DETECCIÓN DE EVENTOS MEDIANTE POLLING


3.4.1.1 LECTURA DE EVENTOS MEDIANTE POLLING
Para la detección de eventos mediante Polling, deberemos hacer llamadas recurrentes (Polling) a las
siguientes URIs.

http://localhost:9443/api/event
http://localhost:9443/api/nodes/{EUI64}/event

La URI http://localhost:9443/api/event permite consultar los eventos generados por todos los equipos,
cualquiera que sea su EUI64. Un ejemplo de respuesta sería (en formato JSON):

{
"msgArg": {
"sEUI64": "001824FFF9000006",
"sTrack": "30303030303030303030303030",
"ucSource": 0,
"ucTrackType": 1
},
"msgTimeStamp": 1552468260.5318043,
"msgType": "on_ttl_track"
}

En este ejemplo vemos un evento del tipo "on_ttl_track" generado por el lector número 0 del equipo con
EUI64 001824FFF9000006.

La URI http://localhost:9443/api/nodes/{EUI64}/event permite consultar sólo los eventos de un


determinado equipo, seleccionado mediante su EUI64. Supongamos que 001824FFFF030158 es el EUI64
del equipo del que queremos conocer sus eventos. Un ejemplo de respuesta sería (en formato JSON):

{
"msgArg": {
"sEUI64": "001824FFFF030158",
"sTrack": "04000208CE1508B2",
"ucTrackType": 1},
"msgTimeStamp": 1552476288.7370284,
"msgType": "on_mifare_track"
}

Cuando se produce un evento el Server KProductAPI lo registra por duplicado. Una primera vez en la lista
asociada a la primera URI y una segunda vez en la lista correspondiente a la segunda URI.

13/02/2020 10 de 72
Cuando se consultan, los eventos se borrarán de la lista pertinente. Para evitar confusiones, se aconseja
que la aplicación cliente elija una de las dos modalidades y evite mezclarlas. Se podrán almacenar un
máximo de 100 eventos en la lista general, y otros 100 por cada EUI64. En todos los casos será el cliente
quien determine las acciones necesarias derivadas de la lectura de eventos mediante “Polling”.

3.4.1.2 BORRADO DE COLAS DE EVENTOS


Los eventos generados en los diferentes equipos KXP se almacenan en colas FIFO.

Existe una cola general para todos los eventos, independiente del equipo KXP. Esta cola puede ser
inicializada (es lo mismo que decir vaciada), enviando el comando HTTP DELETE a través de la URI
http://localhost:9443/api/event
Puede observarse que la URI coincide con la que hemos usado en el apartado anterior. La diferencia es que
ahora usamos HTTP DELETE en lugar de HTTP GET.

Existe una cola de eventos para cada uno de los equipos KXP. Si queremos inicializar/vaciar una de estas
colas, debemos conocer el EUI64 del equipo y utilizar el HTTP DELETE a través de la URI
http://localhost:9443/api/nodes/{EUI64}/event

3.4.2 DETECCIÓN DE EVENTOS MEDIANTE SOCKETIO

La tecnología SocketIo permite conocer los eventos en tiempo real sin usar polling. Para ello es preciso
disponer de un servidor SocketIo. Este servicio será el encargado de leer los mensajes emitidos por la
KProductAPI. Una simplificación del código de emisión de eventos usado por la KProductAPI, es la
siguiente:

if sEvent is not None:


if cfg_SOCKETIO_CLIENT is True:
try:
SocketIo = SocketIo(cfg_SOCKETIO_HOST_SERVER, cfg_SOCKETIO_PORT_SERVER)
SocketIo.emit('event', sEvent)

Esto es, cada vez que se produce un evento, si la KProductAPI está configurada como cliente SocketIo,
establece conexión con el servidor cfg_SOCKETIO_HOST_SERVER a través del puerto
cfg_SOCKETIO_PORT_SERVER, y emite un mensaje llamado 'event' con la información de dicho evento
sEvent.

13/02/2020 11 de 72
3.5 ACTUALIZACIÓN DEL FIRMWARE DE LOS EQUIPOS DE LAS REDES KXP

Si alguno de los equipos de la red requiere de una actualización de firmware, disponemos de la siguiente URI para
llevarlo a cabo:

http://localhost:9443/api/nodes/{sEUI64}/Cpu/UpdateNodeFlash

Donde {sEUI64} debe ser sustituido por el EUI64 del equipo.

La particularidad de este comando es que es un método HTTP POST. En el cuerpo del mensaje, debe aparecer el
parámetro sFileName, con la ruta del archivo de firmware suministrado por Kimaldi para hacer la actualización
requerida. Si en la ruta hay signos “\”, puede ser necesario “escaparlos” (añadiendo el signo de escape delante;
“\\”)

Ejemplo:
"W:\\Productes\\Flexy2_KXP\\Firmware\\Flasher\\Flexy2_KXP_F3.s19"

Sólo se podrá actualizar el firmware de un equipo a la vez. Durante la actualización de un nodo el Server
KProductAPI mantiene la comunicación de instrucciones y eventos con el resto de equipos de la red.

13/02/2020 12 de 72
4 URIS Y MÉTODOS DEL SERVER KPRODUCTAPI

En la descripción de los métodos del Server KProductAPI, si no se indica lo contrario se enviarán con el comando
HTTP GET. Cuando no sea así se detallará el comando a usar, así como las instrucciones adicionales necesarias.

También se detalla el formato de los eventos, que será el mismo tanto si se reciben realizando llamadas
recurrentes (Polling), como si se usa un servidor SocketIo.

13/02/2020 13 de 72
4.1 ACERCA DEL SERVICIO

4.1.1 MÉTODOS
4.1.1.1 GETVERSION
http://localhost:9443/api/version

Descripción Permite consultar la versión del Server KProductAPI.

Argumentos Ninguno

Valores de retorno Este método devuelve una cadena con la versión del Server KProductAPI.

Ejemplo de respuesta:
{"sVersion": "VER 1.0.6"}

4.1.1.1 DESDE LÍNEA DE COMANDO

Es posible conocer la versión desde línea de comando, ejecutando “KProductAPI.py –V”.


El comando “KProductAPI.py –H” ofrece ayuda de las opciones disponibles.

13/02/2020 14 de 72
4.2 INSTRUCCIONES GENÉRICAS (CPU).

4.2.1 MÉTODOS
4.2.1.1 TESTNODELINK
http://localhost:9443/api/nodes/{sEUI64}/Cpu/TestNodeLink

Descripción Permite comprobar las comunicaciones con un determinado equipo.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.2.1.2 HOTRESET
http://localhost:9443/api/nodes/{sEUI64}/Cpu/HotReset

Descripción Este método se emplea para hacer un Reset del equipo.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 15 de 72
4.2.1.3 GETFWVERSION
http://localhost:9443/api/nodes/{sEUI64}/Cpu/GetFwVersion/{ucFlashNumber}

Permite conocer las versiones de los distintos módulos de firmware un


determinado equipo. En función de los equipos, el firmware estará dividido
Descripción en 2, 3 o 4 módulos de flash. Para saber la versión de uno de estos módulos
basta con especificar su número en el parámetro ucFlashNumber.
Siempre se consignará el valor cero al parámetro ucNlevel.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFlashNumber: Identificador de módulo.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno sVersion: Informativo.
ucBootModeIndex: Informativo.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"sVersion": "A4.02.00",
"ucBootModeIndex": 231
}

4.2.1.4 GETNODEINUSEIPADDRESS
http://localhost:9443/api/nodes/{sEUI64}/Cpu/GetNodeInUseIpAddress

Cuando el Server KProductAPI utiliza el puerto UDP-KXP para acceder a la


Descripción red KXP, este método permite conocer la dirección IP a través de la que se
establece comunicación con un nodo determinado.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

ucInsRet: Valor de retorno del método. Ver Tabla 2


Valores de retorno InUseIpAddress: Cadena devuelta, conteniendo la dirección IP que se
usa para establecer contacto con el nodo indicado.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"InUseIpAddress": ["192.168.123.17"]
}

13/02/2020 16 de 72
4.2.1.5 UPDATENODEFLASH

Método POST. La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Cpu/UpdateNodeFlash

En el cuerpo del mensaje HTTP, debe aparecer el parámetro sFileName, con la ruta del archivo de firmware
suministrado por Kimaldi para hacer la actualización requerida. Si la ruta contiene “\”, puede necesitar
presentar los signos \ “escapados” (“\\”);

Descripción Este método se emplea para actualizar el firmware de los equipos.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
sFileName: Nombre del Fichero donde se encuentra el nuevo firmware.

ucInsRet: Valor de retorno del método. Ver Tabla 2


Este valor indica que la actualización ha comenzado correctamente. Para
Valores de retorno
saber si finaliza correctamente, debe consultarse el evento
“on_update_node_flash” (explicado a continuación)

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 17 de 72
4.2.2 EVENTOS

4.2.2.1 ONUPDATENODEFLASH
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

Descripción Este evento informa del progreso de la actualización del equipo

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucProgress: Posibles valores
Valores de retorno • -1 (Ha habido un error)
• 0-99% Porcentaje de actualización realizado
• 100 Actualización completada

Ejemplos de respuesta:

En caso de error:
{
"msgArg": {
"sEUI64": "001824FFFF030158",
"ucProgress": -1
},
"msgTimeStamp": 1552992418.6344202,
"msgType": "on_update_node_flash"
}

Actualización en curso:
{
"msgArg": {
"sEUI64": "001824FFFF030158",
"ucProgress": 34.0
},
"msgTimeStamp": 1552992418.6344202,
"msgType": "on_update_node_flash"
}

Actualización completada:
{
"msgArg": {
"sEUI64": "001824FFFF030158",
"ucProgress": 100},
"msgTimeStamp": 1552992437.7281775,
"msgType": "on_update_node_flash"
}

13/02/2020 18 de 72
4.3 INSTRUCCIONES DE CONFIGURACIÓN (CFG).

4.3.1 MÉTODOS
4.3.1.1 READCFG
http://localhost:9443/api/Nodes/{sEUI64}/Cfg/Read/{ucEepromNumber}/{uiStartIdx}/{ucLen}

Permite leer los bytes configuración de un determinado equipo.


La configuración está dividida en un número de bloques según el equipo.
Cada bloque contendrá una cantidad de bytes que dependerá de cada
Descripción
equipo, y que se numerarán a partir del cero.
También la cantidad de parámetros que podrán obtenerse por medio de una
sola instrucción variará con cada tipo de equipo.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucEepromNumber: El número de bloque que se desea leer.
Argumentos
uiStartIdx: Índice del primer byte a leer.
ucLen: Cantidad de bytes a leer

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno sParameters: Datos leídos

Ejemplo de respuesta:
{
"ucInsRet": 0,
"sParameters": "C20300020011001E01023201016401160132FF06FF0FFF05FFFFFFFFFFFFFFFF"
}

13/02/2020 19 de 72
4.3.1.2 WRITECFG
http://localhost:9443/api/nodes/{sEUI64}/Cfg/Write/{ucEepromNumber}/{uiParameterIdx}/
{ucParameterValue}

Permite cambiar el valor de un byte de configuración de un determinado


equipo.
La configuración está dividida en un número de bloques según el equipo.
Cada bloque contendrá una cantidad de bytes que dependerá de cada
equipo, y que se numerarán a partir del cero.

En determinados equipos, como por ejemplo el terminal Flexy2KXP, esta


Descripción instrucción además de cambiar el valor del parámetro indicado, lo guardará
directamente en EEPROM. Sin embargo, en otros equipos, como por
ejemplo el lector Lexa, se requirirá ejecutar la instrucción Cfg/store para que
los cambios efectuados mediante las distintas instrucciones Cfg/Write se
guarden en memoria.

Consulte el manual de su equipo para conocer el comportamiento.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucEepromNumber: El número de bloque que se desea leer.
Argumentos
uiParameterIdx: Índice del parámetro a escribir.
ucParameterValue: Valor a escribir

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 20 de 72
4.3.1.3 LOADFACTORYCFG
http://localhost:9443/api/nodes/{sEUI64}/Cfg/LoadFactory/{ucEepromNumber}

Este método, permite restaurar los valores de fábrica de cada uno de los
bytes configuración de un determinado equipo.
Dado que la configuración está dividida en dos o más bloques, según se
consigne en el parámetro ucEepromNumber, se podrá operar sobre uno u
otro bloque.

Descripción
En determinados equipos, como por ejemplo el terminal Flexy2KXP, esta
instrucción además de restaurar los valores de fábrica, los guardará
directamente en EEPROM. Sin embargo, en otros equipos, como por
ejemplo el lector Lexa, se requirirá ejecutar la instrucción Cfg/store para que
los cambios efectuados mediante las distintas instrucciones
Cfg/LoadFactory se guarden en memoria.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucEepromNumber: El número de bloque que se desea leer.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.3.1.4 STORECFG
http://localhost:9443/api/nodes/{sEUI64}/Cfg/Store

Esta instrucción es necesaria para guardar en EEPROM los cambios en la


configuración realizados mediante la instrucción Cfg/Write para aquellos
Descripción
equipos en los que Cfg/Write no afecta directamente a la EEPROM.
Guardará en EEPROM todos los cambios pendientes.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 21 de 72
4.4 INSTRUCCIONES INOUT

4.4.1 MÉTODOS
4.4.1.1 INOUTLEDOPERATE
http://localhost:9443/api/nodes/{sEUI64}/InOut/LedOperate/{ucLedNum}/{ucMode}/{ucColor}/
{ucTime_ds}

Este método instruye al equipo para que controle el encendido de uno de


Descripción
sus LEDs.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucLedNum: Identificador del Led (0…N).
ucMode: Modo de encendido / ciclo de trabajo.
ucColor: Color de encendido.
Argumentos ucTime_ds: Duración de la operación de encendido en décimas de
segundo.

Consulte el manual del equipo concreto para conocer los detalles del control
de los LEDs.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 22 de 72
4.4.1.2 INOUTBUZZEROPERATE
http://localhost:9443/api/nodes/{sEUI64}/InOut/BuzzerOperate/{ucBuzzerNum}/{ucMode}/
{ucTime_ds}

Este método instruye al equipo para que controle la activación de uno de


Descripción
sus zumbadores.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucBuzzerNum: Identificador del Buzzer (0…N).
ucMode: Modo de activación/ciclo de trabajo.
ucTime_ds: Duración de la operación de activación en décimas de
Argumentos
segundo.

Consulte el manual del equipo concreto para conocer los detalles del control
de los zumbadores.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.4.1.3 INOUTRELAYOPERATE
http://localhost:9443/api/nodes/{sEUI64}/InOut/RelayOperate/{ucRelayNum}/{ucMode}/
{ucTime_ds}

Este método instruye al equipo para que controle la activación de uno de


Descripción
sus relés.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucRelayNum: Identificador del Relé (0…N).
ucMode: Modo de activación.
Argumentos
0: OFF
1: ON
ucTime_ds: Duración en décimas de segundo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 23 de 72
4.4.1.4 INOUTDIGITALINPUTGET
http://localhost:9443/api/nodes/{sEUI64}/InOut/DigitalInputGet

Este método instruye al equipo para que envíe el estado de sus entradas
Descripción
digitales.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno
ucDinValue: Estado de las entradas digitales.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"ucDinValue": 8
}

4.4.1.5 INOUTLEDSWITCHON
http://localhost:9443/api/nodes/{sEUI64}/InOut/LedSwitchOn/{ucLedNum}/{ucMode}/{ucColor}

Este método instruye al equipo para que controle el encendido de uno de


Descripción
sus LEDs de forma permanente.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucLedNum: Identificador del Led (0…N).
ucMode: Modo de encendido / ciclo de trabajo.
Argumentos ucColor: Color de encendido.

Consulte el manual del equipo concreto para conocer los detalles del control
de los LEDs.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 24 de 72
4.4.1.6 INOUTLEDSWITCHOFF
http://localhost:9443/api/nodes/{sEUI64}/InOut/LedSwitchOff/{ucLedNum}

Descripción Este método instruye al equipo para que apague uno de sus LEDs.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucLedNum: Identificador del Led (0…N).
Argumentos
Consulte el manual del equipo concreto para conocer los detalles del control
de los LEDs.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.4.1.7 INOUTRELAYSWITCHON
http://localhost:9443/api/nodes/{sEUI64}/InOut/RelaySwitchOn/{ucRelayNum}

Este método instruye al equipo para que active permanentemente uno de


Descripción
sus relés.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucRelayNum: Identificador del Relé (0…N).

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 25 de 72
4.4.1.8 INOUTRELAYSWITCHOFF
http://localhost:9443/api/nodes/{sEUI64}/InOut/RelaySwitchOff/{ucRelayNum}

Descripción Este método instruye al equipo para que desactive de uno de sus relés.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucRelayNum: Identificador del Relé (0…N).

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.4.2 EVENTOS
4.4.2.1 ONINOUTDIGITALINPUTGETECHO
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

Este evento se dispara cuando el equipo detecta un cambio en las entradas


Descripción
digitales, siempre que haya sido configurado para tal función.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Valores de retorno
ucDinValue: Estado de las entradas digitales.

Ejemplo de respuesta:
{
'msgTimeStamp': 1552986612.187905,
'msgType': 'on_in_out_digital_input_get_echo',
'msgArg': {
'ucDinValue': 1,
'sEUI64': '001824FFFF030158'
}
}

13/02/2020 26 de 72
4.5 INSTRUCCIONES RTC.

4.5.1 MÉTODOS
4.5.1.1 RTCREAD
http://localhost:9443/api/nodes/{sEUI64}/Rtc/Read

Este método instruye al equipo para que envíe la fecha y hora almacenada
Descripción
en su módulo Real Time Clock (RTC).

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno ucYear, ucMonth, ucDay, ucHour, ucMinute, ucSecond:
ucWeekDay: (0: Domingo,… 6: Sábado)

Ejemplo de respuesta:
{
"ucInsRet": 0,
"ucYear: 19
"ucMonth": 6
"ucDay": 24
"ucHour": 10
"ucMinute": 22
"ucSecond": 34
"ucWeekDay": 01
}

4.5.1.2 RTCWRITE
http://localhost:9443/api/nodes/{sEUI64}/Rtc/Write/{ucYear}/{ucMonth}/{ucDay}/{ucHour}/{
ucMinute}/{ucSecond}/{ucWeekDay}

Este método instruye al equipo para que actualice la fecha y hora de su


Descripción
módulo Real Time Clock (RTC).

uiAddressTo: Dirección lógica del equipo.


sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.
Argumentos
ucYear, ucMonth, ucDay, ucHour, ucMinute, ucSecond:
ucWeekDay: (0: Domingo,… 6: Sábado)

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 27 de 72
4.6 INSTRUCCIONES MIFARE.

4.6.1 MÉTODOS
4.6.1.1 MIFARE ATQA-UID GET
http://localhost:9443/api/nodes/{sEUI64}/Mifare/ATQA_UID_Get

Este método solicita al módulo Mifare el envío del ATQA y el UID del tag que
Descripción actualmente se encuentra en el campo, seleccionado y listo para aceptar
comandos.

uiAddressTo: Dirección lógica del equipo.


Argumentos
sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


sATQA: ATQA.
ucCardType: Tipo de tag. Consultar el manual del equipo para ver la
Valores de retorno
codificación de tipos de tags específica de su módulo Mifare.
ucSAK: SAK, con información complementaria para definir el tipo de Tag.
sData: UID.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"sATQA": "0400",
"ucCardType": 2,
"ucSAK": 8,
"sData": "741EEE1B"
}

13/02/2020 28 de 72
4.6.1.2 MIFAREHALT
http://localhost:9443/api/nodes/{sEUI64}/Mifare/Halt

Este método solicita al módulo Mifare que envíe el comando Mifare “Halt” al
tag seleccionado. Tras su ejecución el módulo Mifare retomará la detección
Descripción
de tags presentes en el campo, excluyendo los que se encuentren en modo
Halt.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.6.1.3 MIFAREWAKEUP
http://localhost:9443/api/nodes/{sEUI64}/Mifare/WakeUp

Este método solicita al módulo Mifare que envíe el comando Mifare


“WakeUp” a los tags que se encuentren en modo Halt. Tras su ejecución el
Descripción
módulo Mifare reiniciará la detección de tags, incluyendo los que acaban de
ser despertados.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno ucErrCode: 0x00: Ok <> 0x00: No se ha detectado ningún tag.
sATQA: ATQA

Ejemplo de respuesta:
{
"ucInsRet": 0,
"ucErrCode": 0,
"sATQA": "0400"
}

13/02/2020 29 de 72
4.6.1.4 MIFARELOGIN
http://localhost:9443/api/nodes/{sEUI64}/Mifare/Login/{ucBlockNumber}/{ucKeyAB}/{sKey}

Este método solicita al módulo Mifare que envíe el comando Mifare “Login”
al tag que se encuentra seleccionado, para poder acceder a uno de sus
sectores. Ten presente que el módulo Mifare podrá emitir autónomamente
este comando justo después de la detección y selección del tag, cuando sea
Descripción
necesario el acceso con login a un cierto bloque o sector para recolectar la
información que debe adjuntar al evento OnMifareTrack. En este caso, no
será preciso emitir de nuevo el comando Login si deseas continuar
accediendo al mismo sector.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucBlockNumber: Número de uno de los bloques contenidos en el sector
que se desea acceder.
ucKeyAB: Tipo de Clave con que hacer el Login.
Especificar el carácter “A” para la clave A
Argumentos
Y el “B” para la Key B.
sKey: Admite dos posibles valores:
-Dos dígitos HEX-ASCII con el índice de Clave grabada en la
EEPROM del lector.
-Doce dígitos HEX-ASCII con la Clave completa a utilizar.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 30 de 72
4.6.1.5 MIFAREBLOCKREAD
http://localhost:9443/api/nodes/{sEUI64}/Mifare/BlockRead/{ucBlockNumber}

Este método solicita al módulo Mifare que lea un bloque del tag que se
Descripción encuentra seleccionado. Ten presente que esta operación puede requerir un
Login previo.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucBlockNumber: Número del bloque que se desea leer.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno
sData: Datos del bloque leído.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"sData":"000102030405060708090A0B0C0D0E0F"
}

4.6.1.6 MIFAREBLOCKWRITE
http://localhost:9443/api/nodes/{sEUI64}/Mifare/BlockWrite/{ucBlockNumber}/{sData}

Este método solicita al módulo Mifare que escriba un bloque del tag
Descripción seleccionado. Ten presente que esta operación puede requerir un Login
previo.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucBlockNumber: Número del bloque que se desea escribir.
Argumentos
sData: Datos a escribir. Consiste en una cadena HEX-ASCII de 32
caracteres.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 31 de 72
4.6.1.7 MIFAREBLOCKBACKUP
http://localhost:9443/api/nodes/{sEUI64}/Mifare/BlockBackUp/{ucBlockNumberFrom}/
{ucBlockNumberTo}

Este método solicita al módulo Mifare que realice una copia de seguridad de
los datos que se encuentran en un bloque determinado del tag seleccionado
Descripción en otro bloque. En caso que los bloques origen y destino requieran Login
para ejecutar las operaciones de lectura/escritura, es necesario que ambos
pertenezcan al mismo sector, y que el Login se haya ejecutado previamente.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos ucBlockNumberFrom: Número del bloque origen.
ucBlockNumberTo: Número del bloque destino.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.6.1.8 MIFARESECTORREAD
http://localhost:9443/api/nodes/{sEUI64}/Mifare/SectorRead/{ucBlockNumber}

Este método solicita al módulo Mifare que lea un sector del tag
Descripción seleccionado. Ten presente que esta operación puede requerir un Login
previo.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos ucBlockNumber: Número de uno de los bloques del sector que se quiere
leer.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno
sData: Datos del sector leído.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"sData":"000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F00010203040
5060708090A0B0C0D0E0F "
}

13/02/2020 32 de 72
4.6.1.9 MIFARESECTORWRITE
http://localhost:9443/api/nodes/{sEUI64}/Mifare/SectorWrite/{ucBlockNumber}/{sData}

Este método solicita al módulo Mifare que escriba un sector del tag
Descripción seleccionado. Ten presente que esta operación puede requerir un Login
previo.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucBlockNumber: Número de uno de los bloques contenidos en el sector
Argumentos que se quiere escribir.
sData: Datos a escribir. Consiste en una cadena HEX-ASCII de 96
caracteres.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.6.1.10 MIFAREVALUEREAD
http://localhost:9443/api/nodes/{sEUI64}/Mifare/ValueRead/{ucBlockNumber}

Este método solicita al módulo Mifare que lea un bloque determinado del tag
Descripción
seleccionado en el que se ha codificado un campo en formato Mifare Value.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucBlockNumber: Número del bloque donde se encuentra el Value.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno i32Value: Valor del campo Value leído.
ucAddress: Valor del campo Address leído.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"i32Value": 12,
"ucAddress":0
}

13/02/2020 33 de 72
4.6.1.11 MIFAREVALUEWRITE
http://localhost:9443/api/nodes/{sEUI64}/Mifare/ValueWrite/{ucBlockNumber}/{i32Value}/
{ucAddress}

Este método solicita al módulo Mifare que escriba un campo en formato


Descripción
Mifare Value en uno de los bloques del tag actualmente seleccionado.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucBlockNumber: Número de Bloque donde escribir el Value.
i32Value: Valor comprendido entre -2.147.483.647 y 2.147.783.647
y que se desea guardar en formato Mifare Value.
Argumentos
ucAddress: Valor byte que acompaña al Value. Puede usarse, como
sugiere la literatura Mifare para informar sobre el número de bloque que
contiene la copia de seguridad del Value, o puede usarse para almacenar un
byte para cualquier otro propósito, o simplemente dejarse a cero.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.6.1.12 MIFAREVALUEINCREMENT
http://localhost:9443/api/nodes/{sEUI64}/Mifare/ValueIncrement/{ucBlockNumber}/{i32Delta}

Este método solicita al módulo Mifare que añada un número positivo a un


Descripción campo en formato Mifare Value almacenado en uno de los bloques del tag
actualmente seleccionado.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos ucBlockNumber: Número del bloque donde se encuentra el Value.
i32Delta: Número a sumar. Comprendido entre 0 y 2.147.783.647

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 34 de 72
4.6.1.13 MIFAREVALUEDECREMENT
http://localhost:9443/api/nodes/{sEUI64}/Mifare/ValueDecrement/{ucBlockNumber}/{i32Delta}

Este método solicita al módulo Mifare que substraiga un número positivo a


Descripción un campo en formato Mifare Value almacenado en uno de los bloques del
tag actualmente seleccionado.

uiAddressTo: Dirección lógica del equipo.


sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.
Argumentos
ucBlockNumber: Número del bloque donde se encuentra el Value.
i32Delta: Número a restar. Comprendido entre 0 y 2.147.783.647

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.6.1.14 MIFAREVALUERESTORE
http://localhost:9443/api/nodes/{sEUI64}/Mifare/ValueRestore/{ucBlockNumberFrom}/
{ucBlockNumberTo}

Este método solicita al módulo Mifare que realice una copia de seguridad de
los datos codificados en formato Mifare Value que se encuentran en un
determinado bloque del tag seleccionado en otro bloque. En caso que los
Descripción
bloques origen y destino requieran Login para ejecutar las operaciones de
lectura/escritura, es necesario que ambos pertenezcan al mismo sector, y
que el Login se haya ejecutado previamente.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos ucBlockNumberFrom: Número del bloque origen.
ucBlockNumberTo: Número del bloque destino.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 35 de 72
4.6.1.15 MIFARESECURITYLEVELREAD
http://localhost:9443/api/nodes/{sEUI64}/Mifare/SecurityLevelRead

Este método solicita al módulo Mifare que envíe el valor del Nivel de
Seguridad con que se está protegiendo el acceso de lectura/escritura de
ciertos campos de la memoria EEPROM relativos al lector Mifare.
Descripción La zona protegida comprende algunos parámetros de configuración así
como claves e información sensible del módulo Mifare. Consulta el manual
del equipo concreto para conocer la política de accesibilidad a las zonas
protegidas y el detalle de las mismas.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno
ucSecurityLevel: Nivel de Seguridad activo.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"ucSecurityLevel":0
}

13/02/2020 36 de 72
4.6.1.16 MIFARESECURITYLEVELWRITE
http://localhost:9443/api/nodes/{sEUI64}/MIFARE/SecurityLevelWrite/{ucSecurityLevel}/
{ucKeyNumber}/{sKey}

Este método solicita al módulo Mifare que cambie el Nivel de Seguridad con
el que está protegiendo el acceso de lectura/escritura de ciertos campos de
Descripción la memoria EEPROM relativos al lector Mifare.
Consulta el manual del equipo concreto para conocer la política de
accesibilidad a las zonas protegidas y el detalle de las mismas.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucSecurityLevel: Valor deseado del Nivel de Seguridad.
ucKeyNumber: Ciertas transiciones entre Niveles de Seguridad exigen el
uso de una de las Clave Mifare almacenadas en la EEPROM del equipo
Argumentos como Password. En este parámetro se indica el índice de la Clave en
cuestión.
sKey: Cadena HEX-ASCII de 12 dígitos conteniendo el Password del
sistema de protección de la EEPROM del módulo Mifare, y que debe
coincidir con la Clave indicada por el parámetro anterior.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno
ucRetryCounter: Número de reintentos de escritura remanentes.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"ucRetryCounter":0
}

13/02/2020 37 de 72
4.6.1.17 MIFAREKEYWRITE
http://localhost:9443/api/nodes/{sEUI64}/Mifare/KeyWrite/{ucKeyNumber}/{sKey}

Este método solicita al módulo Mifare que guarde una Clave Mifare en una
determinada posición de la memoria EEPROM del equipo. Estas claves
podrán ser usadas indistintamente para realizar el Login a zonas de la
memoria del tag, o como Password del sistema de protección de la propia
Descripción
memoria EEPROM relacionada con módulo Mifare. Tenga en cuenta que la
escritura de las claves está regulada por el Nivel de Seguridad. Consulta el
manual del equipo concreto para conocer la política de accesibilidad a las
zonas protegidas y el detalle de las mismas.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucKeyNumber: Índice de la Clave Mifare que se pretende almacenar.
Argumentos
sKey: Cadena HEX-ASCII de 12 dígitos conteniendo el valor deseado para
la Clave Mifare.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 38 de 72
4.6.2 EVENTOS
4.6.2.1 ONMIFARETRACK
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

El módulo Mifare del equipo envía este evento para indicar al Host que
Descripción
acaba de detectar y seleccionar un tag, y que está listo para operar con él.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucTrackType: Tipo de información asociada.
sTrack: Datos del evento.
Valores de retorno
Consulte el manual del equipo para conocer los detalles del formato de los
datos devueltos por el evento OnMifareTrack de su módulo Mifare
específico.

Ejemplo de respuesta:
{ "msgArg":
{"sEUI64": "001824FFFF030158",
"sTrack": "04000208CE1508B2",
"ucTrackType": 1},
"msgTimeStamp": 1553008912.9402754,
"msgType": "on_mifare_track" }

13/02/2020 39 de 72
4.7 INSTRUCCIONES TTL.

4.7.1 EVENTOS
4.7.1.1 ONTTLTRACK
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

El módulo TTL del equipo envía este evento para indicar al Host que se ha
Descripción leído correctamente una trama de datos Clock&Data o Wiegand, según sea
su configuración.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Valores de retorno ucTrackType: Tipo de lectura.
sTrack: Datos leídos.

Ejemplo de respuesta:
[
{
"sEUI64”: "001824FFFF04001A",
"TimeStamp": "2017-09-06T09:39:30.9309559+02:00",
"ucSource": 0,
"ucTrackType": 1,
"sTrack": "0001948184091",
"msgType": "on_ttl_track"
}
]

13/02/2020 40 de 72
4.8 INSTRUCCIONES FIM

4.8.1 MÉTODOS
4.8.1.1 FIMGETDEVICEINFO
http://localhost:9443/api/nodes/{sEUI64}/Fim/GetDeviceInfo/{ucFimNum}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x05 CMD_GET_DEVICE_INFO”. Se utiliza
Descripción para determinar el modelo de sensor biométrico activo. Consulte el manual
de su equipo para determinar los modelos y versiones soportados su
controlador FIM.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFimNum: Identificador del sensor biométrico (0…N).

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
Valores de retorno uiFimParam2: Campo Param2 de la respuesta. Contiene la numeración
del modelo del sensor biométrico.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"uiFimParam2": 21344
}

13/02/2020 41 de 72
4.8.1.2 FIMGETFIRMWAREVERSION
http://localhost:9443/api/nodes/{sEUI64}/Fim/GetFirmwareVersion/{ucFimNum}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x04 CMD_GET_FIRMWARE_VERSION2”.
Descripción Se utiliza para conocer la versión de firmware del sensor biométrico activo.
Consulte el manual de su equipo para determinar los modelos y versiones
soportados su controlador FIM.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFimNum: Identificador del sensor biométrico (0…N).

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
Valores de retorno uiFimParam2: Campo Param2 de la respuesta. Contiene la versión de
firmware del sensor biométrico.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"uiFimParam2": 291
}

13/02/2020 42 de 72
4.8.1.3 FIMGETTEMPLATE
http://localhost:9443/api/nodes/{sEUI64}/Fim/GetTemplate/{ucFimNum}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x16 CMD_GET_TEMPLATE”. Se utiliza
Descripción
para obtener la información “template” de la huella presente en el sensor
biométrico. El template se obtiene en formato Nitgen Emulation None.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFimNum: Identificador del sensor biométrico (0…N).

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
Valores de retorno sFimTemplate: Cuando la ejecución es correcta, devuelve el “template”
de la huella del usuario en formato Nitgen Emulation None.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"sFimTemplate":
"00000003065CC8DAA20EAE8D5ABFFFCB0E14DA32686103F59B04A731EC50626EB3DE63DAF0CFD
CB320B2769501902A5E45D2D16A5420FD51876916A3932FD2FAF84F6B29095AE979D58205C0EA705
806B840EFAC47C51E17272FD6344CFF0933AF94242351346D754DDA23ADDA1AB98609147A256DC
A4AC77142B96F28B1DB7CAE485E0141A2F399169F4ACF42F274BB99C962B4AF7FE360329ECD7553
98F30860D9289D667EAA333736365239C7A86EFC9A413452047015419EADDA08DD1C630C3CAF82B
2E5F59153A9A93EEE00A6FAE810CB1B9D566D95FB2E29A6883DB0ADC20C74874C24DB6EACCDD4
BD309091643AB382D7D1BF6B68862ED8F0F05F706496DA52579636213CC865EEC13D4DE407B27F3
6CAA7A52DE859E1DF18BC410108DEB02A6B4D90E6442BA13D595A6FD5768B51DC27D6FB9169CD
7ED23278F8A0BCADB1F51CBED1A5881AC7E34287440FEFEE692481ED960CA5945D65D107FF6406
5021F3558D886984C79FD45AF3E3726F4C07AB436366D40DF8B402CEDE1433FAF4DA84ACED3F2B
C4B13EE59E096C5101B21A1739"
}

13/02/2020 43 de 72
4.8.1.4 FIMINSTANTMATCHING

Método POST. La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Fim/InstantMatching/{ucFimNum}

En el cuerpo del mensaje HTTP, debe aparecer el parámetro baFimTemplate, con el template de la huella en
formato Nitgen Emulation None.

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x15 CMD_INSTANT_MATCHING”. Se
Descripción
utiliza para comprobar la coherencia entre la huella presente en el sensor
biométrico y el “template” proporcionado.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucFimNum: Identificador del sensor biométrico (0…N).
Argumentos
baFimTemplate: Cadena conteniento el template de la huella en formato
Nitgen Emulation None.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica
coincidencia entre la huella presente en el lector y el template facilitado en la
Valores de retorno
llamada del método FimInstantMatching.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1
}

13/02/2020 44 de 72
4.8.1.5 FIMENTERMASTERMODE
http://localhost:9443/api/nodes/{sEUI64}/Fim/EnterMasterMode/{ucFimNum}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x2F CMD_ENTER_MASTER_MODE2”. Se
Descripción utiliza para poner el sensor biométrico en modo “master”, de forma que
permita la ejecución de las instrucciones de manejo de las bases de datos
de usuarios.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFimNum: Identificador del sensor biométrico (0…N).

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que se
Valores de retorno ha podido entrar satisfactoriamente en modo “master”.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1
}

13/02/2020 45 de 72
4.8.1.6 FIMLEAVEMASTERMODE
http://localhost:9443/api/nodes/{sEUI64}/Fim/LeaveMasterMode/{ucFimNum}

Este método solicita al controlador FIM del equipo que envíe al lector
Descripción biométrico el comando Nitgen “0x26 CMD_LEAVE_MASTER_MODE”. Se
utiliza para que el sensor biométrico salga del modo “master”.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFimNum: Identificador del sensor biométrico (0…N).

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que se
Valores de retorno ha podido entrar satisfactoriamente en modo “master”.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1
}

13/02/2020 46 de 72
4.8.1.7 FIMGETNUMBEROFUSERS
http://localhost:9443/api/nodes/{sEUI64}/Fim/GetNumberOfUsers/{ucFimNum}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x30 CMD_GET_FP_LIST2”. Se utiliza para
Descripción
determinar el número de usuarios registrados en la base de datos interna
del sensor biométrico. Debe ejecutarse en modo “master”.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos
ucFimNum: Identificador del sensor biométrico (0…N).

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
uiFimNumberOfUsers: Cuando la ejecución es correcta devuelve el
Valores de retorno
número de usuarios registrados en la base de datos interna del sensor
biométrico.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"uiFimNumberOfUsers": 157
}

13/02/2020 47 de 72
4.8.1.8 FIMDELETEUSER
http://localhost:9443/api/nodes/{sEUI64}/Fim/DeleteUser/{ucFimNum}/{sFimUserIdent}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x22 CMD_DELETE_FP”. Se utiliza para
Descripción
borrar un usuario de la base de datos del sensor biométrico. Debe
ejecutarse en modo “master”.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucFimNum: Identificador del sensor biométrico (0…N).
Argumentos
sFimUserIdent: Cadena HEX-ASCII de 10 caracteres conteniendo el
número identificativo del usuario.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
Valores de retorno uiFimParam2: Cuando la ejecución es correcta devuelve el número de
usuarios registrados en la base de datos interna del sensor biométrico.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"uiFimParam2": 1
}

13/02/2020 48 de 72
4.8.1.9 FIMDELETEALLUSERS
http://localhost:9443/api/nodes/{sEUI64}/Fim/DeleteAllUsers/{ucFimNum}/{sFimIncludeMaster}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x23 CMD_DELETE_ALL_FP”. Se utiliza
Descripción
para borrar todos los usuarios de la base de datos del sensor biométrico.
Debe ejecutarse en modo “master”.

uiAddressTo: Dirección lógica del equipo.


sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.
ucFimNum: Identificador del sensor biométrico (0…N).
Argumentos
sFimIncludeMaster: Si se especifica el valor “TRUE” se borrarán
también los registros de usuarios grabados como “master”. El valor por
defecto es FALSE.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
Valores de retorno ejecución del comando es correcta.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1
}

13/02/2020 49 de 72
4.8.1.10 FIMADDUSER
Método POST. La cabecera HTTP debe especificar Content-Type →application/json
En el cuerpo del mensaje HTTP, si va a pasar un único template de la huella (en formato Nitgen Emulation None),
la sintaxis será "baFimTemplate0".

Si va a pasar también el parámetro baFimTemplate1, la sintaxis de la cadena será "baFimTemplate0;


baFimTemplate1". La cadena contiene los dos templates separados por un punto y coma.

Admite el siguiente formato de URI, independientemente de si se añade el usuario con uno o dos templates:
http://localhost:9443/api/nodes/{sEUI64}/Fim/AddUser/{ucFimNum}/{sFimUserIdent}

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x35 CMD_ADD_FP”. Se utiliza para
Descripción
registrar un usuario en la base de datos interna del sensor biométrico.
Permite adjuntar una o dos huellas. Debe ejecutarse en modo “master”.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucFimNum: Identificador del sensor biométrico (0…N).
sFimUserIdent: Cadena HEX-ASCII de 10 caracteres conteniendo el
número identificativo del usuario.
baFimTemplate0: Cadena conteniendo el “template” de la primera huella
Argumentos del usuario en formato Nitgen Emulation None. Se registrará con el índice de
template 0.
baFimTemplate1: Cadena conteniendo el “template” de la segunda
huella del usuario en formato Nitgen Emulation None. Se registrará con el
índice de template 1.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
Valores de retorno ejecución del comando es correcta.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1
}

13/02/2020 50 de 72
Ejemplos mediante POSTMAN

Ejemplo 1: Añadir un usuario con una sola huella

Se especifica la instrucción POST, la URL, el BODY del mensaje y su formato tal como se muestra a continuación:

Ejemplo 2: Añadir un usuario con dos huellas

Se especifica la instrucción POST, la URL, el BODY del mensaje y su formato tal como se muestra a continuación:

13/02/2020 51 de 72
4.8.1.11 FIMIDENTIFYUSER

Método que admite 2 posibles formatos de URI:


http://localhost:9443/api/nodes/{sEUI64}/Fim/IdentifyUser/{ucFimNum}
http://localhost:9443/api/nodes/{sEUI64}/Fim/IdentifyUser/{ucFimNum}/{sFimUserIdent}

Este método se utiliza para identificar la huella presente en el sensor


biométrico contra la base de datos interna del sensor biométrico. Para
realizar la identificación 1:1 solicita al controlador FIM del equipo que envíe
Descripción
al lector biométrico el comando Nitgen “0x13 CMD_IDENTIFY_RID_FP".
Para realizar la identificación 1:N solicita al controlador FIM del equipo que
envíe al lector biométrico el comando Nitgen “0x12 CMD_IDENTIFY_FP"..

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucFimNum: Identificador del sensor biométrico (0…N).
sFimUserIdent: Este parámetro admite dos posibles valores, el valor por
defecto causará que el sensor biométrico rastree la totalidad de su base de
datos interna para localizar el usuario entre todos sus registros. Es decir
Argumentos
tendrá lugar una identificación 1 a N. Si por el contrario se especifica una
cadena HEX-ASCII de 10 caracteres conteniendo el número identificativo de
un usuario concreto, entonces el sensor sólo comparará la huella presente
con el “template” correspondiente a ese usuario, es decir procederá a una
identificación 1 a 1.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que se ha
podido identificar la huella presente en el sensor contra la base de datos
interna del sensor.
sFimUserIdent: Cuando la ejecución del comando es correcta, devuelve
Valores de retorno una cadena HEX-ASCII de 10 caracteres conteniendo el número
identificativo del usuario identificado.
ucFimTemplateIdx: Índice del template dentro del registro del usuario
identificado (0 o 1).

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"sFimUserIdent": "0000000011",
"ucFimTemplateIdx": 0
}

13/02/2020 52 de 72
4.8.1.12 FIMVERIFYUSER

Método POST. La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Fim/VerifyUser/{ucFimNum}/{sFimUserIdent}

En el cuerpo del mensaje HTTP, debe aparecer el parámetro baFimTemplate, con el template de la huella en
formato Nitgen Emulation None.

Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen “0x18 CMD_INSTANT_VERIFY”. Se utiliza
Descripción para verificar si el template especificado en el argumento del método consta
en el registro del usuario indicado en la base de datos interna del sensor
biométrico.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucFimNum: Identificador del sensor biométrico (0…N).
sFimUserIdent: Cadena HEX-ASCII de 10 caracteres conteniendo el
número identificativo del usuario.
baFimTemplate: Cadena conteniendo el “template” a comprobar.
Argumentos uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
uiFimParam2: Cuando la ejecución es correcta devuelve el índice del
template dentro del registro del usuario identificado.

Consulte el manual del sensor para mayor detalle.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimParam1: Campo Param1 de la respuesta. El valor 1 indica que la
ejecución del comando es correcta.
Valores de retorno uiFimParam2: Cuando la ejecución es correcta devuelve el índice del
template dentro del registro del usuario identificado.

Consulte el manual del sensor para mayor detalle.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimParam1": 1,
"uiFimParam2": 0
}

13/02/2020 53 de 72
4.8.1.13 FIMTRANSCEIVE

Método POST. La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Fim/Transceive/{ucFimNum}/{uiFimCommand}/
{uiFimParam1}/{uiFimParam2}/{uiFimErrorCode}/{uiRxExpectedDataSize}

Al tratarse de un método POST, en el cuerpo del mensaje HTTP, debe aparecer el parámetro sFimHexData,
aunque sea una cadena vacía.
Este método solicita al controlador FIM del equipo que envíe al lector
biométrico el comando Nitgen especificado en uiFimCommand. Puede
utilizarse para enviar un comando cualquiera al sensor biométrico, y en
especial aquellos para los que el servidor KProductAPI no dispone de
Descripción
método específico. Tenga cuidado de respetar las condiciones generales de
funcionamiento del controlador FIM del equipo, evitando cambiar la
velocidad de las comunicaciones, el modo de emulación, y el modo de
detección auto-on.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucFimNum: Identificador del sensor biométrico (0…N).
uiFimCommand:Valor del campo Command de la trama a enviar.
uiFimParam1:Valor del campo Param1 de la trama a enviar.
uiFimParam2: Valor del campo Param2 de la trama a enviar.
Argumentos
uiFimErrorCode: Valor del campo ErrorCode de la trama a enviar.
baFimData:Valor del campo de datos de la trama a enviar.
uiRxExpectedDataSize: Longitud esperada del campo de datos de la
respuesta del sensor biométrico. Consulte el manual del sensor biométrico
para averiguar los detalles.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


uiFimCommand: Valor del campo Command de la trama recibida.
uiFimParam1: Valor del campo Param1 de la trama recibida.
Valores de retorno uiFimParam2: Valor del campo Param2 de la trama recibida.
uiFimDataSize: Valor del campo Datasize de la trama recibida.
uiFimErrorCode: Valor del campo ErrorCode de la trama recibida.
baFimData: Valor del campo Data de la trama recibida.
Ejemplo de respuesta:
{
"ucInsRet": 0,
"uiFimCommand": 22,
"uiFimParam1": 1,
"uiFimParam2": 0,
"uiFimDataSize": 404,
"uiFimErrorCode": 0,
"sFimHexData": ""
}

13/02/2020 54 de 72
Ejemplos mediante POSTMAN

Ejemplo 1: Consulta del parámetro 0x33 de FIM

Se especifica la instrucción POST, la URL, el BODY del mensaje y su formato tal como se muestra a continuación:

La respuesta obtenida es la siguiente:

13/02/2020 55 de 72
4.8.2 EVENTOS
4.8.2.1 ONFIMFINGER
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

El controlador FIM del equipo envía este evento para indicar al Host que
Descripción acaba de detectar la presencia de una huella en el sensor biométrico, y que
está listo para operar con ella.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Valores de retorno
ucFIMNum: Identificador del sensor biométrico (0…N).

Ejemplo de respuesta:
{"msgArg": {
"sEUI64": "001824FFFF04001A",
"ucFimNum": 1},
"msgTimeStamp": 1553009089.9655204,
"msgType": "on_fim_finger"}

13/02/2020 56 de 72
4.9 INSTRUCCIONES RD

4.9.1 MÉTODOS
4.9.1.1 RDTRACKGET
http://localhost:9443/api/nodes/{sEUI64}/Rd/TrackGet/{ucRdNumber}

Este método instruye al equipo para que envíe la información del track de la
Descripción
tarjeta presente en el lector.

uiAddressTo: Dirección lógica del equipo.


Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.
ucRdNumber: Número del lector RD

ucInsRet: Valor de retorno del método. Ver Tabla 2.


Valores de retorno ucTrackType: Tipo de lectura.
sTrack: Datos leídos.

Ejemplo de respuesta:
{
"ucInsRet": 0,
"ucSource": 0,
"ucTrackType": 1,
"sTrack": "000003D092"
}

13/02/2020 57 de 72
4.9.2 EVENTOS
4.9.2.1 ONRDTRACK
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

El módulo RD del equipo envía este evento para indicar al Host que se ha
Descripción leído correctamente una tarjeta. O bien que se ha retirado una tarjeta en
modo multilectura.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


ucSource: Número de lector RD.
Valores de retorno
ucTrackType: Tipo de lectura.
sTrack: Datos leídos.

Ejemplo de respuesta:
{
"sEUI64”: "001824FFFF04001A",
"TimeStamp": "2017-09-06T09:39:30.9309559+02:00",
"ucSource": 0,
"ucTrackType": 1,
"sTrack": "0001948184091",
"msgType": "on_rd_track"
}

13/02/2020 58 de 72
4.10 INSTRUCCIONES UART.

4.10.1 MÉTODOS
4.10.1.1 UARTSEND
Método POST.
La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Uart/Send/{ucUartNumber}

En el cuerpo del mensaje HTTP, debe aparecer el parámetro sData, cadena con los datos a enviar.

Este método instruye al módulo UART-InOut para que envíe datos a un


Descripción
dispositivo externo conectado vía RS-232 a través de la UART especificada.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Argumentos ucUartNumber: Número de Uart (0…N).
sData: Datos a enviar.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 59 de 72
4.10.2 EVENTOS
4.10.2.1 ONUARTRECEIVE
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

El módulo UART-InOut del equipo envía este evento para informar que se
Descripción
han recibido datos por la conexión serie indicada.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Valores de retorno ucUartNumber: Número de Uart (0…N).
sData: Datos recibidos.

Ejemplo de respuesta:
{ 'msgArg':
{'ucUartNum': 0,
'sData': 'HOLA PEPITO GRILLO',
'sEUI64': '001824FFFF04001A'},
'msgType': 'on_uart_receive',
'msgTimeStamp': 1553068489.1310556
}

13/02/2020 60 de 72
4.11 INSTRUCCIONES KEYBOARD.

4.11.1 EVENTOS
4.11.1.1 ONKEYBOARDECHO
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

El módulo Keyboard del equipo envía este evento para informar que se ha
Descripción
pulsado una tecla del teclado matricial.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


Valores de retorno
sKey: El carácter correspondiente a la tecla pulsada.

Ejemplo de respuesta:
{"msgArg": {
"sEUI64": "001824FFFF04001A",
"sKey": "2"},
"msgTimeStamp": 1553009451.4688141,
"msgType": "on_keyboard_echo"}

13/02/2020 61 de 72
4.12 INSTRUCCIONES DISPLAY.

4.12.1.1 MÉTODOS
4.12.1.2 DISPLAYWRITET0T1
http://localhost:9443/api/nodes/{sEUI64}/Display/WriteT0T1/{sText0}/{sText1}
http://localhost:9443/api/nodes/{sEUI64}/Display/WriteT0T1/{sText0}/{sText1}/
{ucBacklitTime_ds}

Este método permite escribir datos en el display LCD del equipo así como
Descripción
controlar la activación temporizada de la retro-iluminación.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


sText0: Texto a escribir en la línea superior del LCD(*).
sText1: Texto a escribir en la línea inferior del LCD(*).
ucBacklitTime_ds: Tiempo en décimas de segundo durante los que la
Argumentos retro-iluminación del LCD permanecerá activada. No tiene efecto si la retro-
iluminación ya estaba activada de forma permanente antes de enviar esta
instrucción. El valor 0 no tiene tampoco ningún efecto.
(*) El texto debe tener una longitud de 20 caracteres. Si no desea alterar el
texto presente en la línea especifique la cadena vacía “”.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 62 de 72
4.12.1.3 DISPLAYWRITET0
http://localhost:9443/api/nodes/{sEUI64}/Display/WriteT0/{sText0}
http://localhost:9443/api/nodes/{sEUI64}/Display/WriteT0/{sText0}/
{ucBacklitTime_ds}

Este método permite escribir datos en el display LCD del equipo así como
Descripción
controlar la activación temporizada de la retro-iluminación.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


sText0: Texto a escribir en la línea superior del LCD.
ucBacklitTime_ds: Tiempo en décimas de segundo durante los que la
Argumentos
retro-iluminación del LCD permanecerá activada. No tiene efecto si la retro-
iluminación ya estaba activada de forma permanente antes de enviar esta
instrucción. El valor 0 no tiene tampoco ningún efecto.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.12.1.4 DISPLAYWRITET1
http://localhost:9443/api/nodes/{sEUI64}/Display/WriteT1/{sText1}
http://localhost:9443/api/nodes/{sEUI64}/Display/WriteT1/{sText1}/
{ucBacklitTime_ds}

Este método permite escribir datos en el display LCD del equipo así como
Descripción
controlar la activación temporizada de la retro-iluminación.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


sText1: Texto a escribir en la línea inferior del LCD.
ucBacklitTime_ds: Tiempo en décimas de segundo durante los que la
Argumentos
retro-iluminación del LCD permanecerá activada. No tiene efecto si la retro-
iluminación ya estaba activada de forma permanente antes de enviar esta
instrucción. El valor 0 no tiene tampoco ningún efecto.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 63 de 72
4.12.1.5 DISPLAYCLEAR
http://localhost:9443/api/nodes/{sEUI64}/Display/Clear

Descripción Este método permite borrar el display LCD del equipo.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.12.1.6 DISPLAYBACKLITSWITCHON
http://localhost:9443/api/nodes/{sEUI64}/Display/BacklitSwitchOn

Este método permite activar permanentemente la retro-iluminación del


Descripción
display LCD del equipo.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

4.12.1.7 DISPLAYBACKLITSWITCHOFF
http://localhost:9443/api/nodes/{sEUI64}/Display/BacklitSwitchOff

Este método permite desactivar la retro-iluminación del display LCD del


Descripción
equipo.

Argumentos sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0
}

13/02/2020 64 de 72
4.13 INSTRUCCIONES OPEN

4.13.1 MÉTODOS

4.13.1.1 OPENTRANSCEIVE
Método POST.
La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Open/Transceive
En el cuerpo del mensaje HTTP, debe aparecer el parámetro baData, cadena con los datos a enviar.

Este método permite enviar una instrucción Open a un equipo basado en un


módulo embedded para que su librería KCProduct la reciba mediante el
evento OnHostReceiveFrameMustReply. El embedded procesará la
Descripción instrucción y enviará la respuesta usando el método HostSendAnswer de la
KCProduct. Esta respuesta será recibida por el Host a través del evento
AnsOpenTransceive del Server KProductAPI.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


baData: Cadena HEX-ASCII con la instrucción Open que se desee enviar
Argumentos
(hasta 900 bytes, 1800 dígitos Ascii-Hex).
.

ucInsRet: Valor de retorno del método. Ver Tabla 2.


baData: Cadena HEX-ASCII con la respuesta de instrucción Open
Valores de retorno
enviada por el equipo embedded (hasta 900 bytes, 1800 dígitos Ascii-Hex).

Ejemplo de respuesta:
{
"sEUI64”: "001824FFFF04001A",
"baData": "ABC0372674DEF872677383ADCE"
}

13/02/2020 65 de 72
4.13.1.2 OPENSEND
Método POST.
La cabecera HTTP debe especificar Content-Type →application/json

http://localhost:9443/api/nodes/{sEUI64}/Open/Send
En el cuerpo del mensaje HTTP, debe aparecer el parámetro baData, cadena con los datos a enviar.

Este método permite enviar una instrucción Open a un equipo basado en un


módulo embedded para que su librería KCProduct la reciba mediante el
Descripción evento OnHostReceiveFrameDoNotReply. El embedded procesará la
instrucción sin responderla.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


baData: Cadena HEX-ASCII con la instrucción Open que se desee enviar
Argumentos
(hasta 900 bytes, 1800 dígitos Ascii-Hex).
.

Valores de retorno ucInsRet: Valor de retorno del método. Ver Tabla 2.

Ejemplo de respuesta:
{
"ucInsRet": 0"
}

13/02/2020 66 de 72
4.13.2 EVENTOS
4.13.2.1 ONOPENEVENT
http://localhost:9443/api/event
http://localhost:9443/api/nodes/{sEUI64}/event

Evento recibido como consecuencia de que un equipo basado en embedded


ha transmitido una trama al Host usando el método HostSendEvent de la
Descripción librería KCProduct.

sEUI64: Cadena HEX-ASCII con el EUI64 del equipo.


baData: Cadena HEX-ASCII con el evento Open enviado por el equipo
Valores de retorno
embedded (hasta 900 bytes, 1800 dígitos Ascii-Hex).

Ejemplo de respuesta:
{
"ucInsRet": 0",
"baData": "ABC0372674DEF872677383ADCE",
"msgType": "on_open_event"
}

13/02/2020 67 de 72
APENDICE A: CODIFICACIÓN KNET_ID

Según el valor del byte ucKNet_Id, la siguiente tabla permite determinar el tipo de electrónica:

Tabla 1: Valores ucKNet_Id de los equipos Kimaldi


KNet_Id Equipo / Electrónica
0x00 KProductAPI
0xA0 Flexy2 Online KXP
0xA1 CtrlDNI
0xA2 ND125K KXP
0xA3 Bridge KXP
0xA4 BioMax2 Online KXP
0xA5 Kaptio Online KXP
0xA6 FlexyPlus Online KXP
0xAC Flexy Offline KXP
0xAE Lexa

13/02/2020 68 de 72
APENDICE B: CÓDIGOS DE RETORNO

La tabla siguiente muestra el significado de los códigos de retorno de los métodos del Server KProductAPI.

Tabla 2: Valores de retorno de los métodos


Valor KConst Descripción
0 INSRET_OK Método ejecutado correctamente.
1 INSRET_NODENOTAVAILABLE Error: El equipo con el que se pretende
comunicar no está conectado a la red KXP en
ese momento.
2 INSRET_INVALIDINSTRUCTION Error: Instrucción no válida
3 INSRET_INVALIDARGUMENT_EXCEPTION Error: Parámetros incorrectos
4 INSRET_ANSFAILED Error: Fallo en la respuesta del equipo con el
que se pretende comunicar.
254 INSRET_ABORTED Error: El equipo con el que se pretende
comunicar ha cancelado la instrucción
mandada por el método.
255 INSRET_TIMEOUT Error: El método llamado no ha podido ser
ejecutado en el tiempo esperado.

13/02/2020 69 de 72
APENDICE C: EJEMPLO DE FICHEROS DE CONFIGURACIÓN

Veamos un ejemplo de fichero KProductAPI.cfg (Sólo para versiones Linux y Windows):

DEBUG_ON = False
API_PORT = 9443
# SOCKETIO
SOCKETIO_CLIENT = False
SOCKETIO_HOST_SERVER = 10.0.0.114
SOCKETIO_PORT_SERVER = 45679
SOCKETIO_EVENT_ECHO = False
# SCAN_SPEED
SCAN_HIGH_SPEED = True
# PORT_TYPE Possible values SERIAL, UDP
PORT_TYPE = UDP
# PORT_TYPE SERIAL
SERIAL_PORT = /dev/serial0
SERIAL_BAUD_RATE = 19200
# PORT_TYPE UDP
UDP_REMOTE_ADDRESS = 10.0.0.255
UDP_SUBNET_MASK = 255.255.255.0
UDP_PORT = 6000

13/02/2020 70 de 72
CONTROL DE REVISIONES

Nº Versión Fecha Descripción

Versión 1.00 8 noviembre 2019 Primera redacción.

Versión 1.01 13 febrero 2020 Acutalizado a KproductAPI “VER 1.0.17”

13/02/2020 71 de 72
NOTAS

Los módulos biométricos FIM y los softwares eNBSP y eNSearch, son productos de Nitgen Co., Ltd.

13/02/2020 72 de 72

También podría gustarte