FIRST STEPS WITH SOFIA2

Transcription

1 FIRST STEPS WITH SOFIA2 DECEMBER 2014 Version 5

2 1 INDEX 1 INDEX INTRODUCTION REQUIREMENTS CURRENT DOCUMENT GOALS AND SCOPE STEPS TO FOLLOW... ERROR! MARCADOR NO DEFINIDO. 3.1 REGISTRATION AT SOFIA2 ON CLOUD PLATFORM LOGIN AT SOFIA2 ON CLOUD SEARCH AND SUBSCRIPTION TO ONTOLOGIES CREATE A KP AT SOFIA2 ON CLOUD CREATE KP S TOKEN... ERROR! MARCADOR NO DEFINIDO. 3.6 DOWNLOAD AND UNZIP SOFIA2 SDK.... ERROR! MARCADOR NO DEFINIDO Download and unzip SOFIA2 SDK... Error! Marcador no definido. 3.7 SOURCE CODE OF EXAMPLE KPS... ERROR! MARCADOR NO DEFINIDO. 3.8 JAVA KP WITH TOKEN SUPPLIED... ERROR! MARCADOR NO DEFINIDO Set up a KP for the insertion of data from Sensors... Error! Marcador no definido A glance at Java Mock KP of data insertion... Error! Marcador no definido. 3.9 JAVASCRIPT KP SUBSCRIBED TO ONTOLOGIES... ERROR! MARCADOR NO DEFINIDO Set up a KP for the insertion of data from Sensors... Error! Marcador no definido A glance at JavaScript KP... Error! Marcador no definido. First Steps Guide 2/30

3 2 INTRODUCTION 2.1 Requirements Before following this guide you should read the guide (EN) SOFIA2-SOFIA2 Concepts 2.2 Current document goals and scope This guide aims to introduce Sofia2 platform, so that in a very fast way a user could be able to communicate with the platform sending and receiving data through a KP. For that purpose, the following is needed: SOFIA2 On Cloud: is a version of the public platform designed for doing integration tests at the Platform. It is the instance of the SIB that the Sample KPs offered use to send and receive information. SOFIA2 SDK allows developing Sofia2 APPs easily. It is not essential but it simplifies the development. Java API: Includes a Sofia2 example APP (Kp) that publishes simulated data of Temperature and Humidity. JavaScript APi: Includes a Sofia2 HTML example APP (Kp) that visually represents the data introduced by the Java KP. First Steps Guide 3/30

4 3 SDK & APIS SOFIA2 3.1 Download and unzip SOFIA2 SDK. To download Sofia2 SDK visit the developer section at Sofia2 website: At Downloads section, download SOFIA2 SDK. It is a zipped file that contains everything needed to develop Sofia2 APPS without installing anything on the computer: IDE Eclipse JVM Java 7 Maven 3 Scripts The steps to follow are: 1. Download SDK Sofia2 (Windows) 2. Once unzipped in a folder, i.e. c:\sofia2_sdk_win\, it will create the following directory structure: First Steps Guide 4/30

5 The Readme.txt file describes the steps to configure and launch the SDK and run the examples. 3. At the unzipped directory structure we execute the file SOFIA-START.bat. Then, the command console window will open and mount virtual disk S: 3.2 Download and unzip SOFIA2 SDK. Once the SDK is installed, the included Eclipse IDE can be launched. For that: 1. At S:\, run S:\Sofia2_IDE.bat. This will open a command prompt: And Eclipse will be opened. First Steps Guide 5/30

6 2. Now its necessary to configure the maven repository in Eclipse. In Window> Preferences> Maven> User Settings Browse s:\sofia2-sdk\maven\conf\settings.xml in User Settings. Click Update Settings and then click OK. 3.3 Run Sofia2 Java API example. To import a Java example included in Sofia2 Java API: 1. Download Java API from the developer section from the Sofia2 webpage At Downloads section, download Java API: 2. Download and unzip Java API in the Path where the SDK where previously installed (c:\sofia2_sdk_win\). A folder c:\sofia2_sdk_win\sofia2_api_java will be created. First Steps Guide 6/30

7 3. Launch the Eclipse IDE if it was not already launched. 4. Import the basic example included in the Java API. In Eclipse click on import: File> Import> General> Existing Projects into Workspace> s:\sofia2_api_java_ \ejemplos\sofia2_kp_eclipse\" Click Finish. The project will be loaded and compiled. First Steps Guide 7/30

8 5. The project has 3 classes: KpGatewayRestFuncional connect via REST with the instance of Sofia2 on cloud. KpMqttFuncional connect via MQTT with the instance of Sofia2 on cloud. KpWebSocketFuncional connect via WebSocket with the instance of Sofia2 on cloud. 6. These classes are implemented as JUnit Test and the necessary Tokens to insert in the instance of Sofia2 on cloud are configured. To run them, right click over any of them and click on Run As>JUnit Test The result will be: First Steps Guide 8/30

9 Checking the code of the classes these operations are being launched to Sofia2 SIB: o JOIN to authenticate o Insert in native mode (inserting the ontology): with o Insert in SQL o Native and SQL Update o SQL Query, Query to the BDC (Assets) o BULK for sending several messages in only one message SSAP. First Steps Guide 9/30

10 4 HOW TO DEVELOP A SOFIA2 APP (USER ROL) In the previous section we have downloaded the SDK and APIs and we have run the basic included examples. In this section the steps to develop a Sofia2 APP at Sofia2 on cloud platform available at The distribution of Sofia On Cloud provides an environment that allows to start developing with the platform with a free account having access to all functionality of Sofia2 and having access to multitude of data available. The steps to develop a Sofia2 APP consist of: Registration at sofia2 on CloudLab. Login to the Web Configuration Console on sofia2 on cloud o Search and subscription to ontologies o Create an APP (KP and Token) o Query information from these ontologies from RTDB console access Development of a Sofia2 APP to make request from ontologies in Javascript and Java Development of a Sofia2 APP to insert to ontologies. 4.1 Registration at SOFIA2 On Cloud Platform Sofia2 CloudLab can be found from the Product section at the Sofia2 Webpage ( Also visiting the website we can register to the platform. First Steps Guide 10/30

11 Once we are registered as USER_ROL it will allow us to subscribe to public ontologies and make requests about them. For the user registration, it is important to follow the rules, the password, for example, must contains numbers, uppercase and lowercase letters. NOTE: Later we will see how to apply for the role CONTRIBUTOR, that allows to dump information to the platform. 4.2 Login at SOFIA2 On Cloud Web Console At the website or at the homepage of Sofia2 we can log in with the new user created and we will be able to access to the platform: First Steps Guide 11/30

12 First Steps Guide 12/30

13 4.2.1 Search and Subscription to Ontologies Once we are logged in, we can search for public ontologies and subscribe to them. A COLABORATOR user can create Ontologies. The owner of an ontology can make CRUDS(Create, Read, Update,Delete) The owner of an ontology can give permission to other users to read, create, modify or delete. The owner of an ontology can make it public. A public ontology can be consulted by any user of the platform. From Ontology Subscription option, we can find those ontologies that are public and subscribe to them, allowing us to perform query operations on them. We can search through the Ontologies List. Search for SensorTemperatura. In order to see in detail SensorTemperatura we will click the show button side column. at the right First Steps Guide 13/30

14 In the Ontology Information screen we can see if it is active and public and the schema of the ontology. Click on. It will allow us to request information from this ontology from mi APP. Once we are subscribed, at subscriptions search will appear the ontologies at which we are subscribed. First Steps Guide 14/30

15 We do the same for the ontology SensorHumedad Create a KP at SOFIA2 On Cloud From the option New KP, we can register a KP, associating it to its corresponding ontology. When you create a KP, you must give it a name and description and select the ontologies to be managed from that KP: List KPs will show all KP created by the user, being able to see their details or modify their data or delete it. First Steps Guide 15/30

16 The details are: Identification: Kp name Authentication Token: It is needed to connect from a Sofia2 App to the platform. Encription Key: It needed only if you use XXTEA protocol. It is used in devices that don t support HTTPS, like Arduino. First Steps Guide 16/30

17 From the option Tokens Management we can generate new Tokens. The KP registered will connect with the platform through these Tokens. By clicking at the KP from the list, we will see the auto-generated token in the list below. This token is activated by default. In order to generate new Tokens we will select the KP for which we want to generate them and the number of Tokens desired, then we should click the button Generate Tokens. Now a new table with the new generated Tokens and the auto-generated one will appear. First Steps Guide 17/30

18 By default, the new Tokens are deactivated, we can active them by clicking at the check. First Steps Guide 18/30

19 4.2.3 Query from RTBD console From the left menu Tools> RTDB & BDH Console we can perform queries to the available Ontologies The queries can be done to the RTDB (Real Time DataBase) or to the HDB (Historic DataBase). It can be done in SQL (recommended) or in native language. Double click on a Ontology and the query appears in the textfield, click on. First Steps Guide 19/30

20 For each register the context information (KP,user, ) is shown. And the measure information, in this case, GPS coordinates, id and timestamp: First Steps Guide 20/30

21 It is also possible to perform queries with filters: First Steps Guide 21/30

22 4.3 Development of query Sofia2 APP Until now: We have subscribed to 2 public ontologies that allow us to request information. We have created a KP and a Token We have performed queries to the RTDB for the selected ontologies. In this section we will develop a Sofia2 APP in Javascript and Java that allows us to request information from these ontologies. They will be similar to the RTDB query Console Javascript APP A very simple example can be downloaded from Download and unzip in the disk where the SDK were mounted s:\query_html. First Steps Guide 22/30

23 The exmple is a HTML file that uses the Javascript libraries from It open a very simple interface: Instancia KP: KP name created in section : + instance name. In that case: KP_Ejemplo_Meteo:Instance01 Ontología: The ontology name we will perform the query. Token: the Token we created in 4.2.2: d62b89cbb82a44589baad5966aedb0f6 Query: the query in SQL i will perform to Sofia2 CloudLab. Button Join: This button manages in the instance with the Token and the KP. Type the token and click on Join First Steps Guide 23/30

24 This will return a SessionKey showing that we are conecting to the instance of Sofia2 CloudLab with this Session Key. This Session Key has an expiration date, so if we do not use this session it will expire in time. Once the session is joined we can click on the button that performs the query and shows the information in the textfied. Other queries can be performed: First Steps Guide 24/30

25 The Javascript code can be checked and debugged with the tools of the browsers, for example in Chrome: First Steps Guide 25/30

26 A much more complex apps can be created from here with a litle knowleadge of Javascript. We can see the Sofia2 demos at Java APP Following the same procedure than in Javascript, download now the Java example from Download and unzip in the disk where the SDK were mounted s:\query_java. The example is a Maven project (pom.xml) that contains the AppQuerySofia.java class. To open the maven project: 1. Open a command prompt at s:\query_java 2. Run s:\sofia2_variablesentorno.bat that sets the environment variables including JAVA_HOME, MAVEN_HOME. First Steps Guide 26/30

27 3. Build the Maven project. Type mvn install. This will download all the necessary dependencies from the repository. This can take a while. If everything went well we get: NOTE: If an error occurs probably it is due a proxy for access to Internet. Then, modify the file s:\sofia2-sdk\maven\conf\settings.xml adding an entry <proxy> in <proxies> 4. After that, the eclipse project can be generated and importing to the Sofia2 IDE. Run mvn eclipse:eclipse. First Steps Guide 27/30

28 This creates the eclipse files.classpath y.project. 5. Open the Sofia2 IDE by running S:\Sofia2_IDE.bat and load the project as before in section 3.3. File>Import>General>Existing Projects into Workspace >"s:\query_java\" 6. Run the class AppQuerySofia2 from the eclipse Project. First Steps Guide 28/30

29 This will shows in the console the app: Change the token,kp, query,etc as needed. Type the token created. Join to start a session with the platform: First Steps Guide 29/30

30 And finally perform a query: Check or debugg the code if needed. 4.4 Sofia2 APP development to insert data. (This part of the manual is pending a full review). So far we have seen how to develop APPs to query information. These same applications can insert information if they have permission to insert data into the platform. this can be achieved: 1. Having a CONTRIBUTOR role. This allows us to create ontologies and then insert data in accordance with these. a. In Sofia2 CloudLab platform a CONTRIBUTOR role can be requested from the main console screen: 2. A CONTRIBUTOR user can create a Token and give us permissions to insert instances of an Ontology First Steps Guide 30/30