PRIMEIROS PASSOS COM A PLATAFORMA SOFIA2 FEVEREIRO 2015 Versão 6
Guia de Primeiros Passos Página 2/33
1 ÍNDICE 1 ÍNDICE... 3 2 INTRODUÇÃO... 4 2.1 REQUISITOS... 4 2.2 OBJETIVOS E ÂMBITO DO PRESENTE DOCUMENTO... 4 3 SDK E API SOFIA2... 5 3.1 INSTALAR O SDK DE SOFIA2... 5 3.2 ABRIR O IDE SOFIA2... 7 3.3 CARREGAR O EXEMPLO DA API DE JAVA SOFIA2... 8 4 COMO DESENVOLVER UMA APP SOFIA2 (ROL UTILIZADOR)... 12 4.1 ENTRAR NA INSTÂNCIA SOFIA2 INCLOUDLAB... 12 4.2 ACEDER À CONSOLA WEB DE SOFIA2 CLOUDLAB... 14 4.2.1 Pesquisa e subscrição a Ontologias... 15 4.2.2 Criação de um KP... 17 4.2.3 Consultar informação a partir da Consola acesso BDTR... 19 4.3 DESENVOLVIMENTO DA APP SOFIA2 DE CONSULTA... 23 4.3.1 APP em Javascript... 23 4.3.2 APP em Java... 28 4.4 DESENVOLVIMENTO DE UMA APP SOFIA2 QUE INSIRA DADOS.... 32 Guia de Primeiros Passos Página 3/33
2 INTRODUÇÃO 2.1 Requisitos Antes de ler este guia, recomenda-se a leitura do guia SOFIA2-Conceitos SOFIA2.doc 2.2 Objetivos e âmbito do presente documento Este guia pretende introduzir a plataforma SOFIA2, para que de uma forma muito rápida, um utilizador possa estar a comunicar com a plataforma, enviando e recebendo dados através de um KP. Para isso, é necessário ter em consideração: SOFIA2 On Cloud: é uma versão da Plataforma pública concebida para realizar testes de integração na Plataforma. É a instância do SIB sobre a qual os KPs oferecidos como exemplo enviarão e receberão informação. O SDK Sofia2 que nos permite desenvolver APPs Sofia2 de forma simples. No é imprescindível mas simplifica o seu desenvolvimento. O API Java que contém uma APP Sofia2 como exemplo (KP) que envia dados simulados de Temperatura e Humidade. A API Javascript, que contém uma APP Sofia2 HTML como exemplo que representa visualmente os dados introduzidos pelo KP Java. Guia de Primeiros Passos Página 4/33
3 SDK E API SOFIA2 3.1 Instalar o SDK de Sofia2 Para transferir o SDK de Sofia2, vá ao menu de Desenvolvimento de Sofia2: http://sofia2.com/desarrollador.html Na secção DOWNLOADS, aceda ao SDK do respetivo Sistema Operativo, a título de exemplo, utilizar-se-á o SDK do Windows: O SDK do Windows é fornecido em formato ZIP e contém todos os elementos necessário para desenvolver APPs Sofia2 sem precisar de instalar outros elementos na sua máquina, isto é: IDE Eclipse configurado JVM Java 7 Maven 3 Scripts Os passos para proceder à sua utilização são os seguintes: 1. Descarregar o SDK de Sofia2 (Windows) em http://sofia2.org/sdk/sofia2_sdk_win.zip 2. Uma vez descarregado o ZIP, extraia-o para uma pasta, como se indica a seguir c:\sofia2_sdk_win\ Guia de Primeiros Passos Página 5/33
Após a extração: Ter-se-á gerado a pasta com este conteúdo: O ficheiro LEEME_WINDOWS.txt descreve os passos a seguir para configurar e lançar o SDK e executar os exemplos. 3. Uma vez o conteúdo extraído, vá à pasta (c:\sofia2_sdk_win\) e execute o script Sofia2_SDK-START.bat. Este deve abrir uma linha de comandos em S: com esta informação: Guia de Primeiros Passos Página 6/33
3.2 Abrir o IDE Sofia2 Uma vez instalado o SDK, já pode lançar o IDE Eclipse incluído. Para isso: 1. A partir da unidade S:\ execute S:\Sofia2_IDE.bat, que abrirá uma janela de comandos: E finalmente abrir-se-á o Eclipse. Guia de Primeiros Passos Página 7/33
2. Agora é necessário proceder à configuração do repositório de Maven de Eclipse. Para isso, vá a Window>Preferences>Maven>User Settings (Janela>Preferências>Maven>Definições Utilizador) E em User Settings (Definições de Utilizador) selecione: s:\sofia2- SDK\MAVEN\conf\settings.xml e selecione Update Settings (Atualizar Definições). De seguida, clique em OK. 3.3 Carregar o exemplo da API de Java Sofia2 Agora, é necessário proceder ao carregamento no IDE de um exemplo Java incluído na API Java Sofia2. Para isso: 1. A partir do menu de Desenvolvimento da web de Sofia2 http://sofia2.com/desarrollador.html na secção Downloads, selecione a API Java: http://sofia2.org/apis/sofia2_api_java/sofia2_api_java.zip 2. Transfira a API Java para o diretório onde instalou previamente o SDK (no nosso caso em c:\sofia2_sdk_win\) E extraia-o diretamente para essa pasta. No final terá uma pasta c:\sofia2_sdk_win\sofia2_api_java_30102014\ : Guia de Primeiros Passos Página 8/33
3. Se ainda não tinha procedido ao seu carregamento, execute o IDE que contém o SDK de Sofia2 com o comando s:\sofia2_ide.bat. Ao fim de algum tempo deve abrir-se o Eclipse. 4. A seguir, tem de carregar no IDE o exemplo mais básico incluído na API Java. Para isso, selecione em Eclipse File>Import>General>Existing Projects into Workspace> (Ficheiro>Importar>Geral>Projetos existentes para a área de trabalho) s:\sofia2_api_java_30102014\ejemplos\sofia2_kp_eclipse\" E clique em Concluir. Visualizar-se-á o projeto carregado e compilado sem problemas: Guia de Primeiros Passos Página 9/33
5. No projeto dispõe de 3 classes: KpGatewayRestFuncional faz a ligação via REST com a instância de Sofia2 na cloud. KpMqttFuncional faz a ligação via MQTT com a instância de Sofia2 na cloud. KpWebSocketFuncional faz a ligação via MQTT com a instância de Sofia2 na cloud. 6. Estas 3 classes estão implementadas como Tests JUnit e têm os Tokens necessários configurados para inserir a instância de Sofia2 na cloud. Para as testar, selecione com o botão direito qualquer uma e Run As>JUnit Test Ao executar as mesmas, obterá o seguinte: Guia de Primeiros Passos Página 10/33
Ao rever o conteúdo das classes pode verificar que estas estão a executar consecutivamente contra o SIB de Sofia2 operações de: o JOIN para autenticar o Insert em modo nativo (inserindo a ontologia): Com o Insert através de SQL o Update nativo e SQL o Query em SQL, Query para BDC (Ativos) o BULK para enviar várias mensagens numa só mensagem SSAP. Guia de Primeiros Passos Página 11/33
4 COMO DESENVOLVER UMA APP SOFIA2 (ROL UTILIZADOR) No ponto anterior, transferimos o SDK assim como as APIS e executamos os exemplos básicos incluídos. Neste ponto explicaremos os passos necessários para desenvolver uma APP Sofia2 na instância de Sofia2 disponibilizada em http://sofia2.com. Esta instância de Sofia2: Sofia2 CloudLab oferece um ambiente de teste que permite começar a desenvolver com a plataforma e através de uma conta gratuita, tendo acesso a todas as funcionalidades de Sofia2 e acedendo à multitude de dados disponibilizados. O processo para desenvolver uma APP Sofia2 consiste basicamente em: Entrar na instância Sofia2 CloudLab Aceder à Consola Web de configuração de Sofia2 CloudLab o Pesquisar e subscrever ontologias o Criar APP (KP e Token) o Consultar a informação destas ontologias a partir da Consolam com acesso BDTR Desenvolvimento da APP Sofia2 de consulta sobre as ontologias em Javascript e Java Desenvolvimento de APP Sofia2 que insere em Java e que publica medidas de Temperatura e Humidade. 4.1 Entrar na instância Sofia2 incloudlab Na secção Produtos da Web de Sofia2 (http://sofia2.com/sofia2incloud.html) pode aceder-se a Sofia2 CloudLab: Também se pode aceder via: http://sofia2.com/console/gestionutilizadors/registeruser Guia de Primeiros Passos Página 12/33
Nesta URL pode registar-se: Uma vez o registo efetuado, ser-lhe-á atribuído o rol de UTILIZADOR, este rol permite consumir informação pública da plataforma, mas não lhe permite transferir para a mesma informação. Com este rol pode criar APPs Sofia2 que consomem (consultam, subscrevem) as ontologias que outros utilizadores tenham definido como públicas. NOTA: Mais tarde veremos como solicitar o rol COLABORADOR, que permite transferir informação para a plataforma. Guia de Primeiros Passos Página 13/33
Ao criar o utilizador é importante seguir as regras que se indicam, como por exemplo: a palavra-passe deve conter letras, números e letras maiúsculas e minúsculas. 4.2 Aceder à Consola Web de Sofia2 CloudLab Ao ter os dados de utilizador de Sofia2 CloudLab, na página principal de Sofia2 pode efetuar o Login: Ou através deste link: http://sofia2.com/console/login Do nosso lado, efetuaremos o login com o utilizador criado no ponto anterior, a janela principal tem o aspecto seguinte: Guia de Primeiros Passos Página 14/33
4.2.1 Pesquisa e subscrição a Ontologias Ao entrar na consola web, o próximo passo é procurar ontologias públicas que possa consumir a partir da minha APP e subscrever às mesmas para poder utilizá-las. Uma Ontologia representa uma Entidade viva na Plataforma: Um utilizador COLABORADOR pode criar Ontologias O proprietário de uma Ontologia pode utilizar o padrão CRUD (INSERIR/ATUALIZAR/APAGAR/CONSULTAR) na Ontologia. O proprietário de uma Ontologia pode dar permissões a outros utilizadores para consultar, criar, modificar e apagar. O proprietário de uma Ontologia pode torná-la PÚBLICA, neste caso qualquer utilizador da Plataforma pode consultar essa mesma Ontologia. Para procurar e subscrever as Ontologias, é necessário ir à ONTOLOGÍAS>Mis suscripciones (ONTOLOGIAS>Minhas subscrições): opção do Menu Colocar um critério de pesquisa, procurar-se-á primeiro o SensorTemperatura: Guia de Primeiros Passos Página 15/33
Uma vez encontrada a ontologia, selecione o ícone Ver Na janela de detalhe, pode verificar se uma instância está Ativa, o respetivo esquema e um exemplo da Instância dessa Ontologia: Selecione de a minha APP., a subscrição permitir-lhe-á utilizar esta Ontologia (consultá-la) a partir Na janela principal poderá visualizá-la: Guia de Primeiros Passos Página 16/33
A seguir, executar-se-á com o mesmo procedimento na Ontologia SensorHumidade. 4.2.2 Criação de um KP Após subscrever as Ontologias, deve criar um KP através da Consola Web. Um KP representa uma aplicação Sofia2 ou de uma forma mais precisa representa uma ligação de uma aplicação Sofia2 com a Plataforma. O primeiro passo é Criar um KP, para isso selecione a opção de menu KPs/APPs SOFIA2>Mis KPs/APPs (KPs/APPs SOFIA2>Minhas KPs/APPs): A partir desta janela selecione. Ao criar um KP deve dar-lhe um nome, descrição e selecionar as ontologias que serão manuseadas nesse KP: Ao criá-lo, apresentará a informação a seguir: Guia de Primeiros Passos Página 17/33
Sobre estes dados: O nome do KP: KP_Ejemplo_Meteo O Token de autenticação (d62b89cbb82a44589baad5966aedb0f6) é a informação necessária para se ligar a partir de uma APP Sofia2 à Plataforma. o Os Tokens podem ser geridos a partir da opção Mis Tokens (Meus Tokens), que permite desativar o token criado, criar novos, etc. A chave de encriptação é apenas necessária se pretender utilizar o XXTEA como protocolo de encriptação, que se utiliza em dispositivos que não suportam HTTPS como Arduinos. A seguir, poderá visualizar o KP criado em Mis KPs (Meus KPs), nesta janela pode visualizá-lo, editá-lo ou apagá-lo. Guia de Primeiros Passos Página 18/33
4.2.3 Consultar informação a partir da Consola acesso BDTR A partir da Consola acederá à opção do menu FERRAMENTAS>Consola BDTR e BDH. A partir desta consola, pode inserir queries nas ontologias, onde tem permissões: As consultas podem ser efetuadas até a BDTR (armazena informação em tempo real) ou BDH (informação histórica) e podem igualmente efetuar-se em SQL (recomendado) ou na linguagem nativa. Se selecionar uma Ontologia e clicar 2 vezes, carregar-se-á no campo de texto Query, ao clicar em executar-se-á a query: Guia de Primeiros Passos Página 19/33
Para cada registo, apresenta-se a informação do contexto (KP de inserção, utilizador de inserção, etc.) e a informação da medição, neste caso as coordenadas geográficas onde se registou a medição, o identificador do sensor, a medição e unidade, assim como o momento em que se realizou. Guia de Primeiros Passos Página 20/33
Também pode executar consultas com filtros: como esta: Guia de Primeiros Passos Página 21/33
E: Guia de Primeiros Passos Página 22/33
4.3 Desenvolvimento da APP Sofia2 de consulta Até agora: Efetuamos a subscrição a 2 ontologias públicas, que lhe permite consultar as mesmas Criámos um KP com um Token Consultamos a informação que existe na BDTR para as ontologias selecionadas. Neste passo, iremos criar uma APP Sofia2 em Javascript e em Java que nos permita consultar a informação destas ontologias. Como o objetivo desta é ser didática, construir-se-á ao estilo da Consola de consultas à BDTR. 4.3.1 APP em Javascript Para o exemplo da APP Javascript, teremos um exemplo muito simples que podemos transferir em: http://sofia2.com/docs/query_html.zip Efetuar-se-á esta transferência para a unidade s:\ na qual coloquei o SDK. Proceda à extração numa pasta em s:\query_html. O exemplo é composto por um único ficheiro HTML query.html que utiliza as bibliotecas Javascript de Sofia2 em http://sofia2.com. Se abrirmos o exemplo, encontraremos uma interface muito básica: Guia de Primeiros Passos Página 23/33
Na qual aparece: Instância de KP: é composta pelo nome do KP criado no ponto 4.2. + : + um nome de instância. No nosso caso concreto, chama-se: KP_Ejemplo_Meteo:Instance01 Ontologia: é o nome da ontologia sobre a qual realizar-se-á a consulta, para isso tem de ser o proprietário desta ou estar subscrito à mesma, como no nosso caso. Token: introduzir-se-á aqui o Token criado no passo 4.2.2: d62b89cbb82a44589baad5966aedb0f6 Query: representa a query em SQL que será executada na instância CloudLab de Sofia2. Botão Join: este botão encarrega-se de efetuar o login na instância com o Token e a instância de KP. Terá de introduzir o Token no campo e carregar no botão Join: Guia de Primeiros Passos Página 24/33
Uma SessionKey será facultada, com a indicação de que está ligado à instância de Sofia2 CloudLab com esta Session Key. Esta Session Key tem uma data de caducidade, assim se não se utilizar a sessão no tempo determinado, esta caducará. Ao ter a Session Key, pode carregar no botão ontologia e formatá-la no campo de texto: que nos permite executar a query na Guia de Primeiros Passos Página 25/33
Pode executar outras queries como: Guia de Primeiros Passos Página 26/33
Podemos verificar que o código Javascript é muito simples e podemos depurá-lo através das ferramentas de desenvolvimento de qualquer navegador, por exemplo no Chrome em que me permite ver ao mesmo tempo, por onde passa o código. Guia de Primeiros Passos Página 27/33
A partir de aqui, com um pouco de conhecimentos em Javascript, pode criar aplicações muito mais complexas, como pode verificar nas demos Sofia2: http://sofia2.com. 4.3.2 APP em Java Seguindo o procedimento que temos seguido com a APP Javascript, agora proceder-se-á à transferência do exemplo base Java a partir de http://sofia2.com/docs/query_java.zip. Este será transferido para a minha unidade s:\ na qual foi colocado o SDK. Nessa unidade, proceda à sua extração para uma pasta s:\query_java. O exemplo é composto por um projeto Maven (pom.xml) que contém uma única classe AppQuerySofia.java Uma vez que se trata de um projeto Maven, pode executá-lo através do comando mvn, para isso: 1. Abra uma linha de comandos s:\query_java 2. A partir desta linha de comandos execute s:\sofia2_variablesentorno.bat que estabelece as variáveis do ambiente, entre as quais JAVA_HOME, MAVEN_HOME Guia de Primeiros Passos Página 28/33
3. De seguida, já pode lançar o Maven, o primeiro passo será construir o projeto através de Maven, que se executa com o comando mvn install. Em primeiro lugar tem de descarregar todas as dependências necessárias a partir do seu repositório: Da primeira vez, a transferência pode demorar vários minutos. Se correu tudo bem, obterá finalmente o seguinte: NOTA: Se ocorrer um erro, este normalmente dever-se-á ao proxy para o acesso à Internet, neste caso terá que editar o ficheiro s:\sofia2- SDK\MAVEN\conf\settings.xml adicionando uma entrada <proxy> em <proxies> Guia de Primeiros Passos Página 29/33
4. A seguir, terá de gerar o projeto de Eclipse e carregar o mesmo no IDE de Sofia2. Para compilar, a partir da linha de comandos aberta, execute o mvn eclipse:eclipse. Sendo assim ao finalizar este procedimento terá criado os ficheiros.classpath e.project de Eclipse. 5. Se não estiver aberto, abra o IDE Sofia2 com o comando S:\Sofia2_IDE.bat e importará o projeto como se indica no ponto 3.3: Executar exemplo: File>Import>General>Existing Projects into Workspace (Ficheiro>Importar>Geral>Projetos existentes para a área de trabalho) > "s:\query_java\" 6. Com projeto aberto no Eclipse pode executar a classe AppQuerySofia2. Guia de Primeiros Passos Página 30/33
Que executará na Consola esta aplicação: A partir de aqui, conforme procedemos na APP Javascript, pode ir alternando o Token, KP, query, etc. Altere o Token pelo nosso: d62b89cbb82a44589baad5966aedb0f6 Guia de Primeiros Passos Página 31/33
De seguida, pode executar o Join para iniciar uma sessão com a Plataforma: e finalmente uma query: Apenas falta rever o código do exemplo ou depurar o mesmo. 4.4 Desenvolvimento de uma APP Sofia2 que insira dados. (Esta parte do manual está pendente de uma revisão completa). Até agora vimos como desenvolver APPs de consumo de informação. Estas mesmas aplicações podem inserir informação, sempre que tenham permissões para inserir dados na Plataforma, da forma seguinte: 1. Com o rol COLABORADOR, o que nos permite criar Ontologias e de seguida inserir dados conforme as mesmas. Guia de Primeiros Passos Página 32/33
o Na plataforma Sofia2 CloudLab pode solicitar-se o rol COLABORADOR, a partir da janela principal da consola: http://sofia2.com/console/ através do link: O administrador validará o pedido, se este for recusado, ser-lhe-ão comunicados os motivos. 2. Um utilizador com o rol COLABORADOR, que nos crie um Token com permissões para inserir instâncias de uma Ontologia de que é proprietário. Guia de Primeiros Passos Página 33/33