iPlace SDK

iPlace cuenta con un SDK que permite la integración de cualquier dispositivo IP.

Para realizar una integración sencilla va a ser necesario seguir los pasos que se detallan a continuación. El tipo de integración descrita va permitir, por una parte, recibir los cambios relativos a las entradas del dispositivo, y por otra, actuar sobre las salidas del mismo.

Crear un fichero descriptor del dispositivo a integrar.

Para comenzar será necesario crear un fichero descriptor del dispositivo hardware a integrar. Este fichero, con extensión .conf, deberá presentar una estructura similar a la mostrada en la siguiente tabla.

Las propiedades controller.device.container y controller.device.implementation van a determinar los ficheros encargados de la implementación desarrollada. La primera de ellas indica el contenedor de las clases desarrolladas, por lo que será necesario indicar el nombre del fichero .jar que las contiene. La segunda propiedad hace referencia a la clase encargada de implementar el comportamiento del dispositivo hardware a integrar.

Por otra parte, las propiedades controller.digitaloutputX van a identificar los registros que van a funcionar como salidas digitales. El número asociado a esa etiqueta será el identificador con el que después se va a trabajar en el dispositivo en cuestión para hacer referencia a ese registro. Es decir, toda acción enviada al dispositivo va a ser realizada con este identificador. El número de elementos va a depender de la cantidad de salidas digitales que posea el dispositivo físico. Lo mismo sucede con la propiedad controller.analogicoutputX, pero en el caso de las salidas analógicas.

En cuanto a las entradas identificadas por las propiedades controller.digitalinputX y controller.analogicinputX, estos identificadores estarán asociados a las entradas del dispositivo IP. Por lo tanto serán utilizados para referenciar las actualizaciones recibidas. De esta manera, toda actualización procedente del dispositivo ha de venir acompañada de éste identificador para que el sistema sepa que tipo de entrada es y a que registro pertenece ese cambio de valor.

Crear un proyecto nuevo.

Para comenzar a desarrollar la implementación que va a permitir integrar el dispositivo IP es necesario crear un nuevo proyecto JAVA. Para ello se pueden utilizar IDEs como Netbeans o Eclipse. Una vez creado el proyecto, es necesario incorporar las librerías QuarkSDK.jar y log4j-1.X.XX.jar, lo que va a permitir disponer de los métodos necesarios para desarrollar nuestro propio Device. Para ello será necesario crear una clase que extienda de CustomDevice. En la siguiente imagen se puede ver una clase ejemplo (ExampleDevice).

Los métodos que debe sobrescribir nuestra clase ejemplo son los siguientes:

  • initialize(): una vez el dispositivo IP establece conexión con la plataforma, se inicia el intercambio de información. Es en este momento cuando se ejecuta el método initialize(). Éste método puede ser útil para el envío de información de interés para el dispositivo. Por ejemplo se pueden enviar el conjunto de inputs de los cuales se desea recibir información, de esta manera se puede optimizar el intercambio de datos, obviando el resto de elementos del dispositivo.
  • processReceivedData(String data): cada vez que el dispositivo IP envía datos, este método es el encargado de recibir esa información y procesarla según convenga. Por ejemplo, en caso de tratarse del cambio de una entrada dada, este método será el responsable de analizar los datos recibidos en busca del registro actualizado y del nuevo valor recibido.
  • processDataToSend(String id, String value): cuando se envía una acción al dispositivo, este método es el encargado de construir la petición. Como parámetros recibe el identificador del registro y el nuevo valor. Por lo tanto, este método va a ser el responsable de confeccionar el paquete que será enviado al dispositivo.
  • destroy(): antes de que el sistema se detenga, iPlace realiza una parada controlada de la monitorización de cada dispositivo. Por lo tanto éste método puede ser utilizado para llevar a cabo ciertas tareas como cerrar conexiones auxiliares o liberar otro tipo de estructuras.

Métodos del SDK.

Métodos Descripción
List getDigitalOutputs() lista las entradas digitales del dispositivo
List getDigitalInputs() lista las entradas digitales del dispositivo
 List getAnalogicOutputs() lista las salidas analógicas del dispositivo
 List getAnalogicInputs() lista las entradas analógicas del dispositivo
String getPreviousValue(String element) devuelve el valor actual del elemento
boolean isNewValue(String element,String value) devuelve si el valor es diferente al anterior
boolean containsInput(String element): devuelve si el elemento está cargado como entrada
boolean containsOutput(String element): devuelve si el elemento está cargado como salida
boolean updateInputValue(String element, String value) Envía la actualización del elemento a iPlace
boolean sendAction(String element, String value) Envía la acción cambio al dispositivo
Para probar de forma unitaria la implementación desarrollada, se puede crear un método main de la siguiente manera:
Con este sencillo ejemplo, el sistema se mantiene a la escucha en el puerto 5000 a la espera de recibir cambios de valor de las entradas del dispositivo. También se envía una acción usando el método sendAction.

Añadir el dispositivo desarrollado a iPlace

Una vez desarrollada y probada la implementación de nuestro Device, para poder disponer de dicho dispositivo en la plataforma iPlace será necesario seguir los pasos detallados a continuación:

  • Disponer de una licencia para desarrollador. La demo habilitada para la integración de nuevos dispositivos cuenta con una licencia de desarrollador. Dicha licencia ofrece la posibilidad de trabajar con 5 dispositivos. Los números de serie de prueba coinciden con iplacesn1, iplacesn2, iplacesn3, iplacesn4 y iplacesn5. Por lo tanto para probar nuestro dispositivo, usaremos alguno de esos cinco números de serie ficticios. En caso de necesitar un número de serie en concreto es necesario solicitar una licencia personalizada.
  • Añadir la implementación: Una vez compilado el proyecto desarrollado, el .jar resultante debe ser incluido en las carpetas donde iPlace tiene sus ejecutables. Concretamente, el .jar debe ser ubicado en la ruta iplace/core/extension.
  • Añadir los datos al sistema. Para que iPlace conozca los datos relativos al nuevo dispositivo será necesario añadir un nuevo controlador encargado de monitorizar al Device implementado. Para llevar a cabo esta tarea se utiliza la interfaz de configuración de iPlace, concretamente será necesario acceder a la pestaña Controladores Domóticos. Pulsando en Añadir se mostrará el siguiente formulario para crear un controlador.
Le pondremos un nombre e indicaremos el puerto donde estará escuchando a la espera de una conexión IP por parte del dispositivo. No es necesario rellenar el campo IP. Una vez creado el controlador, lo seleccionaremos y pincharemos en Añadir extensión. En el formulario mostrado en la siguiente imagen será necesario introducir el número de serie e indicar el número de entradas y salidas que va a tener el dispositivo. Una vez hecho esto adjuntaremos el fichero de configuración que hemos creado y pulsaremos en Guardar.
Finalmente, será necesario pulsar en el botón Recargar, ubicado en la esquina superior derecha, para que el sistema recargue la configuración del sistema en busca de nuevos dispositivos.