generación automática de documentación a través de un archivo xml

Generación Automática de Documentación

Página 0

GENERACIÓN AUTOMÁTICA DE

DOCUMENTACIÓN A TRAVÉS DE

UN ARCHIVO XML

Mikel Belausteguigoitia

Oihane Crucelaegui

Maialen Magalhaes

Imanol Vellón


Índice

Página 1

Índice

1 Introducción ....................................................................................................... 2

2 Objetivo ............................................................................................................. 4

3 Lenguaje de Modelado UML ............................................................................. 5

4 Metodología de Trabajo ..................................................................................... 7

5 Formato de la Documentación ........................................................................... 8

5.1 Lista de Componentes Hardware ................................................................ 8

5.2 Lista de la Arquitectura Hardware de los Nodos ........................................ 8

5.2.1 Nodo Procesador ........................................................................................ 8

5.2.2 Nodos Entrada/Salida ............................................................................... 10

5.2.3 Segmentos de Bus ..................................................................................... 12

6 Implementación ............................................................................................... 14

7 Resultados Obtenidos ...................................................................................... 18

8 Conclusiones .................................................................................................... 19


Grupo 2

Página 2

1 Introducción

En el proceso de diseño de sistemas de control industrial no solo se deben tener en

cuenta las especificaciones funcionales, qué hace el sistema, sino también las no funcionales,

cómo lo hace y qué restricciones existen.

Cuando se diseña un sistema de control una de las mayores dificultades es

precisamente definir correctamente las especificaciones en todos los niveles, conocer las

restricciones y gestionar la relación entre ellas. Como solución a este problema, cuya

complejidad se deriva principalmente del tamaño del sistema, surge la idea de realizar el

diseño basado en modelos.

Lo que se hace es definir distintos puntos de vista, llamados dominios: dominio

funcional, dominio de la arquitectura software y dominio de la arquitectura hardware. Una vez

definidos los dominios se realiza un modelo1 del sistema para cada dominio, para lo cual se

define un lenguaje o metamodelo2 especifico de cada dominio.

El modelo completo del sistema está compuesto por el modelo de cada dominio más

las relaciones entre los dominios.

En este proyecto se ha realizado el modelado de un sistema de control a través de los

modelos funcional, hardware y software.

El diseño basado en modelos además de ayudar en la gestión de la complejidad en el

diseño de un sistema conlleva otras ventajas entre las que destacan la trazabilidad de los

requisitos y la generación de código.

1Modelo: representación parcial o simplificada de la realidad que recoge aquellos aspectos de relevancia

para las intenciones del modelador, y de la que se pretende extraer conclusiones de tipo predictivo. Se

modela para comprender mejor o explicar mejor un proceso o unas observaciones. Un mismo objeto

puede ser modelado con distintas técnicas y distintas intenciones, de forma que cada modelo resalta sólo

ciertos aspectos del objeto.

2Metamodelado: es el análisis, construcción y desarrollo de los marcos, las reglas, las limitaciones, los

modelos y teorías aplicables y útiles para el modelado de una clase predefinida de los problemas.


Grupo 2

Página 3

El objetivo de este proyecto es la generación automática de documentación a partir de

un modelo. Esto es posible porque un modelo realizado en UML puede ser exportado a un

fichero de texto en XML y se ha definido el estándar XMI (XML Metada Interchange) que

especifica la forma en la que es posible intercambiar modelos UML entre distintas

herramientas de modelado. En definitiva, el objetivo es extraer la información referente al

modelo contenido en el XMI y generar la documentación requerida.


Grupo 2

Página 4

2 Objetivo

El objetivo del presente proyecto es generar de forma automática la documentación de

la Estación 1- Ubicación Base. Concretamente, se trata de generar la siguiente

documentación:

• La lista general de componentes hardware por la que está compuesta la

estación.

• La lista de la arquitectura hardware de los nodos, distinguiendo entre:

� Nodo Procesador.

� Nodos Entrada/Salida.

� Segmentos de bus.

Para la consecución de dicho objetivo, vamos a partir del modelo de la Estación 1, que

se ha realizado con el lenguaje de modelado UML.


Grupo 2

Página 5

3 Lenguaje de Modelado UML

Tal y como se ha comentado en el punto 2, objetivo del proyecto, tenemos que partir

del modelo de la Estación 1. Para ello, vamos a utilizar el lenguaje de modelado UML.

El Lenguaje Unificado de Modelado (UML) es un lenguaje gráfico para visualizar,

especificar, construir y documentar un sistema. Es decir, es un lenguaje de modelado que

permite la representación conceptual y física de un sistema.

Hay que resaltar que UML es un "lenguaje de modelado" para especificar o para

describir métodos o procesos. Se utiliza para definir un sistema, para detallar los artefactos en

el sistema y para documentar y construir. En otras palabras, es el lenguaje en el que está

descrito el modelo.

UML cuenta con varios tipos de diagramas, los cuales muestran diferentes aspectos de

las entidades representadas. En nuestro caso, los más importantes son los siguientes.

• Diagrama de clases: es un tipo de diagrama estático que describe la estructura del

sistema mostrando sus clases, atributos y las relaciones entre ellos. Se utilizan durante

el proceso de diseño, donde se crea el diseño conceptual de la información que se

manejará en el sistema, y los componentes que se encargaran del funcionamiento y la

relación entre uno y otro.

• Diagrama de componentes: representa cómo un sistema de software es dividido en

componentes y muestra las dependencias entre estos componentes. Pueden ser usados

para modelar y documentar cualquier arquitectura de sistema.

• Diagramas de objetos: se puede considerar un caso especial de un diagrama de clases

en el que se muestran instancias específicas de clases (objetos) en un momento

particular del sistema. Los diagramas de objetos utilizan un subconjunto de los

elementos de un diagrama de clase. Los diagramas de objetos no muestran la

multiplicidad ni los roles, aunque su notación es similar a los diagramas de clase.

• Diagrama de Despliegue: es un tipo de diagrama que se utiliza para modelar el

hardware utilizado en las implementaciones de sistemas y las relaciones entre sus

componentes. Los elementos usados por este tipo de diagrama son nodos,

componentes y asociaciones.


Grupo 2

Página 6

Es indudable que el modelo de la estación va a contener particularidades que ningún

lenguaje, va a poder describirlas todos a la vez. Es por esto que parte de la especificación del

UML se dedica a definir mecanismos de extensión con miras a incrementar el campo de

aplicación del lenguaje. El mecanismo de extensión, que hemos utilizado nosotros, es el

llamado estereotipo; Un estereotipo representa una distinción de uso. Se trata de pequeñas

etiquetas que aplicadas a los elementos o relaciones de un diagrama indican significado

adicional.

Una vez que tenemos el modelo completo estereotipado de la Estación 1, generamos el

archivo XML que es el documento de base sobre el que realizaremos la búsqueda de

información. Notar que es posible ampliar el modelo de la estación, pero gracias a la ventaja

de que XML es extensible, solo hay que extenderlo con la adicción de nuevas etiquetas, de

modo que se puede continuar utilizando sin mayor complicación.

A continuación se muestra un ejemplo para ver la estructura del documento XML generado:

<nestedNode xmi:type="uml:Device" xmi:id="Ue9cfb082-bc42-4930-b20d-a41fe088a3de" xmi:uuid="e9cfb082-bc42-4930-b20d-a41fe088a3de" name="S1_PowerSupply">

<xmi:Extension extender="UModel"> <appliedStereotype xmi:type="uml:StereotypeApplication" xmi:id="U04213ff2-6f9b-40ad-8f3a-ae2bbffa7bc8" xmi:uuid="04213ff2-6f9b-40ad-8f3a-ae2bbffa7bc8" visibility="unspecified" classifier="U44640d98-4882-42fd-8bf5-47ab398ee58d"> <slot xmi:type="uml:Slot" xmi:id="U3c8c722f-6f28-4c54-a0ee-ab65a5c9ecca" xmi:uuid="3c8c722f-6f28-4c54-a0ee-ab65a5c9ecca" definingFeature="U00c24948-68a6-4ba2-9f1c-17628f21de84"> <value xmi:type="uml:LiteralString" xmi:id="U7a4620ea-a7fc-4f5c-b13b-ad93a052d2bf" xmi:uuid="7a4620ea-a7fc-4f5c-b13b-ad93a052d2bf" value="S1_PowerSupply"/>

El motivo de usar la tecnología XML es porque expresa la información de forma

estructurada, esto es, la información se compone de partes bien definidas, y esas partes se

componen a su vez de otras partes. . Entonces se tiene un árbol de trozos de información.

Estas partes se denominan elementos, y se las señala mediante etiquetas. Los elementos XML

pueden tener contenido, o bien ser elementos vacíos. A su vez, los elementos pueden tener

atributos, que son una manera de incorporar características o propiedades a dichos elementos.

Por otra parte, los documentos XML sólo permiten un elemento raíz del que todos los demás

sean parte, es decir, solo pueden tener un elemento inicial.

En base a esta estructura, construiremos un algoritmo iterativo que recorra el

documento XML para encontrar la información que nos interesa y mostrarla por pantalla.


Grupo 2

Página 7

4 Metodología de Trabajo

El proceso de trabajo que seguimos, consta de las siguientes etapas:

- Modelado de la Estación 1.

- Generación de código XML a partir del modelo creado.

- Construcción de un algoritmo iterativo que nos proporcione la información que

requerimos para generar la documentación.

- Por último, generación de un archivo para presentar la información filtrada.


Grupo 2

Página 8

5 Formato de la Documentación

A continuación se muestra el formato que queremos generar para documentar la

información. El objetivo es resumir toda la información disponible en una tabla que refleje y

resuma dicha información, para que en un solo vistazo nos hagamos una idea de la

composición Hardware de la Estación 1.

5.1 Lista de Componentes Hardware

Esta lista refleja todos los dispositivos que contiene el modelo de la estación, los

cuales se resumen a continuación:

Unit Description Serial Number

3 Fuente de Alimentación S1_PS

1 Procesador S1_P

5 Digital Input S1_DI

5 Digital Output S1_DO

3 Enlace Ethernet S1_ETHERNET

5.2 Lista de la Arquitectura Hardware de los Nodos

El objetivo de esta lista es obtener las características principales tales como nombre,

número de serie, posición y descripción de todos los dispositivos que componen cada nodo. A

su vez, también vamos a obtener una tabla resumen que nos va a indicar los nodos que une el

segmento de bus.

5.2.1 Nodo Procesador

El Autómata programable de la estación 1 (S1_PLC) es nuestro Nodo Procesador,

que va estar compuesto por los siguientes dispositivos (ver figura nº1):

- Un procesador

- Una fuente de alimentación

- Cuatro tarjetas de Entradas/Salidas

- Una tarjeta Ethernet


Grupo 2

Página 9

La documentación que habría que generar, tendría el siguiente aspecto:

Name Serial Number Position Description

Power Supply S1_PowerSupply S1_PS 1 Fuente de

Alimentación

Proccesor S1_P 2222 2 Procesador

IO Board

S1_DI_1 S1_DI 3 Digital Input


S1_DO_1 S1_DO 5 Digital Output


Communication

Board S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet

Figura Nº1. Nodo Procesador (S1_PLC) de la estación 1- Ubicación Base.


Grupo 2

Página 10

5.2.2 Nodos Entrada/Salida

Se trata de los nodos que hemos denominado Esclavo_profibus_1 y

Esclavo_profibus_2. La característica que hace que se diferencien del nodo procesador, es

que no disponen del dispositivo procesador. A continuación, se enumeran los dispositivos que

los componen:

- Una fuente de alimentación

- Una tarjeta Ethernet

- Cuatro tarjetas de Entradas/Salidas para el Esclavo_Profibus_1 (ver figura nº3)

- Dos tarjetas de Entradas/Salidas para el Esclavo_Profibus_2 (ver figura nº4)

Figura Nº2. Nodo Esclavo_Profibus_1 de la estación 1- Ubicación Base.


Grupo 2

Página 11

La tabla resumen que contiene la información de dichos nodos, se presenta a

continuación:

• Esclavo_Profibus_1



Alimentación

IO Board





Communication


Figura Nº3. Nodo Esclavo_Profibus_2 de la estación 1- Ubicación Base.


Grupo 2

Página 12

• Esclavo_Profibus_2



Alimentación

IO Board



Communication


5.2.3 Segmentos de Bus

Es el elemento que realiza la conexión entre los nodos que hemos generado. Para

obtener información de este elemento y poder generar la documentación, partimos de las

asociaciones que hemos creado para unir dichos nodos (ver figura nº4).

Figura Nº4. Bus Profibus_DP1.


Grupo 2

Página 13

La información resumida queda de la siguiente manera:

Node Serial Number

S1_PLC Processing Node

Esclavo_Profibus_1 IO Node

Esclavo_Profibus_2 IO Node


Grupo 2

Página 14

6 Implementación

A continuación, se explica el algoritmo implementado para obtener la tabla de los

componentes Hardware. Para generar el resto de documentación se reutilizara la mayor parte

del código, indicando puntualmente las diferencias encontradas.

El primer paso, consiste en decirle al programa donde se encuentra el fichero .xmi,

para ello utilizamos la instrucción Load y le indicamos el path donde se encuentra el fichero.

A continuación, nos situamos en el elemento raíz del documento .xmi (NodoRaíz) y

generamos MiLista, que contiene los nestedNode.

MiXml->Load("..\\docxmi\\Celula 1_v1.xmi"); XmlElement^ NodoRaiz = MiXml->DocumentElement XmlNodeList^ MiLista = NodoRaiz->GetElementsByTagName("nestedNode");

El siguiente paso, es hallar los identificadores serialNumber y description, que genera

el .xmi que por defecto se asocia al perfil que hemos aplicado en el modelo de la Estación.

Para lograr dicho objetivo se crea MiLista2, que contiene los ownedAttribute y MiLista3, que

contiene los packagedElement y se recorren ambas listas para guardar en SerialId y el

descrptionId.

//Para hallar el identificador del SerialNumber XmlNodeList^ MiLista2 = NodoRaiz->GetElementsByTagName("ownedAttribute");

for(int i = 0; i<MiLista2->Count; i++) {if(((XmlElement^)MiLista2[i])->GetAttribute("name")->Equals("serialNumber"))

{SerialId = ((XmlElement^)MiLista2[i])->GetAttribute("xmi:id");} } //Para hallar el identificador de Description

XmlNodeList^ MiLista3 = NodoRaiz->GetElementsByTagName("packagedElement"); for(int i = 0; i<MiLista3->Count; i++)

{if(((XmlElement^)MiLista3[i])->GetAttribute("name")->Equals("GenericComponent"))

{lista_gc->Add(MiLista3[i]); XmlNodeList^ lista_gc1 = lista_gc[0]->ChildNodes; for(int j = 0; j<lista_gc1->Count; j++) {if(((XmlElement^)lista_gc1[j])->GetAttribute("name")->Equals("description")) {descriptionId = ((XmlElement^)lista_gc1[j])->GetAttribute("xmi:id");}}}}


Grupo 2

Página 15

A continuación, se genera una lista de dispositivos, lista_device, a partir de MiLista

que contiene todos los dispositivos que cuelgan de los nodos.

for(int i = 0; i<MiLista->Count; i++) { if(((XmlElement^)MiLista[i])->GetAttribute("xmi:type")->Equals("uml:Device")) { lista_device->Add(MiLista[i]); Prueba = ((XmlElement^)lista_device[0])->GetAttribute("name");}}

En las siguientes líneas, se muestra la creación de la lista_slot, que contiene los

atributos de los dispositivos. Se identifican los slots del serialNumber y description y se

guardan dichos valores en serial_value y en description. También se comprueban aquellos

dispositivos que tienen el mismo serialNumber, para realizar su suma.

for (int j=0; j<lista_device->Count; j++) { XmlNodeList^ lista_slot = lista_device[j]->ChildNodes[0]->ChildNodes[0]->ChildNodes; for(int i=0; i<lista_slot->Count; i++) { if(((XmlElement^)lista_slot[i])->GetAttribute("definingFeature")==SerialId) {for(int k=0; k<a; k++) { if(serial_value[k]==((XmlElement^)((XmlElement^)lista_slot[i])->ChildNodes[0])->GetAttribute("value")) { contador[k]++; salto=1;}} if (salto==0){ serial_value[a] = ((XmlElement^)((XmlElement^)lista_slot[i])->ChildNodes[0])->GetAttribute("value"); for(int l=0; l<lista_slot->Count; l++) {if(((XmlElement^)lista_slot[l])->GetAttribute("definingFeature")==descriptionId) {description[a] = ((XmlElement^)((XmlElement^)lista_slot[l])->ChildNodes[0])->GetAttribute("value"); }} contador[a]++; a++;} else salto=0;}}}


Grupo 2

Página 16

Por último, se muestra por pantalla, los resultados obtenidos.

if (myfile.is_open()) { myfile<<"<table border=1>\n"; myfile<<"<tr><th>Unit</th>"; myfile<<"<th>Description</th>"; myfile<<"<th>Serial Number</th></tr>\n"; for(int fil = 0; fil<devices_max; fil++) { myfile<<"<tr><td align=center>"; myfile<<devDoc[fil].contador; myfile<<"</td><td align=center>"; myfile<<devDoc[fil].Description; myfile<<"</td><td align=center>"; myfile<<devDoc[fil].Serial_ID; myfile<<"</td></tr>\n"; } myfile<<"</table>"; myfile.close(); }

Para obtener la tabla de la arquitectura Hardware de los Nodos, la primera apreciación

que hay que tener en cuenta, es la de poder diferenciar entre Nodo Procesador y Nodo

Entrada/Salida. Debido a la imposibilidad de realizar esta distinción y con objeto de poder

generar la documentación de acuerdo a los requisitos demandados, optamos por declarar el

atributo serialNumber del estereotipo aplicado Nodo (ver figura nº 4). De esta manera,

tenemos nuestro punto de partida para distinguir ambos nodos.

for(int i = 0; i<lista_nodos->Count; i++) { for(int j = 0; j<lista_nodos[i]->ChildNodes->Count; j++) {if(lista_nodos[i]->ChildNodes[j]->HasChildNodes) {AppliedStereotypeSlots = ((XmlElement^)lista_nodos[i]->ChildNodes[j]->ChildNodes[0])->GetElementsByTagName("slot"); for(int k = 0; k<AppliedStereotypeSlots->Count; k++) {if(((XmlElement^)AppliedStereotypeSlots[k])->GetAttribute("definingFeature")->Equals(SerialId)) {if(((XmlElement^)((XmlElement^)AppliedStereotypeSlots[k])->ChildNodes[0])->GetAttribute("value")->Equals("Processing Node")) {lista_nodos_procesador->Add(lista_nodos[i]); }

if(((XmlElement^)((XmlElement^)AppliedStereotypeSlots[k])->ChildNodes[0])->GetAttribute("value")->Equals("IO Node")) {lista_nodos_IO->Add(lista_nodos[i]); }}}}}}


Grupo 2

Página 17

Con el propósito de identificar a que nodo corresponde cada dispositivo, se añaden los

dispositivos como elementos nuevos creados directamente a partir del nodo en cuestión (ver

figura nº 5).

En este caso, necesitamos hallar la lista de los identificadores (classifier) Processor,

PowerSupply, IOBoard y CommunicationBoard. Dichos identificadores se almacenaran en las

variables ProccesorClassifier, PowSupplyClassifier, IOBoardClassifier y

ComBoardClassifier respectivamente, que utilizaremos para conocer qué tipo de dispositivo

cuelga de cada nodo.

for(int i = 0; i<lista_classifiers->Count; i++) {if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("Processor")) {ProcessorClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");} if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("PowerSupply")) {PowSupplyClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");} if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("IOBoard")) {IOBoardClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");} if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")->Equals("CommunicationBoard")) {ComBoardClassifier = ((XmlElement^)lista_classifiers[i])->GetAttribute("xmi:id");}}

Una vez conocido el tipo de dispositivo que es, se obtienen los valores de los atributos

que tiene definido. Y por último, al igual que el caso anterior, se muestra por pantalla la tabla

generada.

//El codigo es similar al caso de la lista de los dispositivos

Figura Nº5. Ventana Model Tree del programa Altova U-Model


Grupo 2

Página 18

7 Resultados Obtenidos

Las siguientes imágenes, muestran el contenido de la documentación generada.

Figura Nº6. Tabla de Componentes Hardware.

Figura Nº7. Tabla de Arquitectura Hardware de los Nodos.


Grupo 2

Página 19

8 Conclusiones

El algoritmo que hemos generado nos permitiría obtener de forma automática la

documentación de cualquier estación que se modele, siempre y cuando se apliquen los

mismos perfiles que se han utilizado a la hora de modelar esta estación. Por lo tanto, la mayor

ventaja que nos proporciona este código es la posibilidad de reutilización que nos brinda.

Esto se debe gracias al lenguaje de esquema que utiliza XML, donde la estructura y las

restricciones de los contenidos de los documentos se describen de una forma muy precisa.

Otra característica importante es que se trata de un código robusto y confiable,

entendiendo como tal, aquel código donde se minimizan los errores de compilación.

generación automática de documentación a través de un archivo xml

Documents