| Next revision | Previous revision |
| giraffplus:middleware [2013-06-03 13:11] – created filippo | giraffplus:middleware [2016-07-28 14:40] (current) – [Basic Concepts] davide |
|---|
| ====== Giraff+ Middleware ====== | ====== GiraffPlus Middleware ====== |
| ===== Overview ===== | ===== Overview ===== |
| Giraff+ is a set of software modules that helps to build so-called "assistive systems" by connecting various, heterogeneous technical devices to a single, unified network. Assistive systems perceive the state of their environment using sensors, consider the perceived state if it is desirable or not and if the latter is the case, they try to find a way of how to influence their environment by way of their actuators to reach a more desirable state. | GiraffPlus is a set of software modules that helps to build so-called "assistive systems" by connecting various, heterogeneous technical devices to a single, unified network. Assistive systems perceive the state of their environment using sensors, consider the perceived state if it is desirable or not and if the latter is the case, they try to find a way of how to influence their environment by way of their actuators to reach a more desirable state. |
| |
| Of course, a prerequisite for being able to show this kind of behavior is that all devices involved are connected to the same system. In Giraff+, a single device that is connected to the system is referred to as being a "node". In principle, there are two ways of how to integrate a device into Giraff+ system, assuming that the device in question is networked (can send and receive data using a network protocol, either wired or wireless). The first way is to install a specific piece of the Giraff+ platform on the device, the so-called "**Middleware**" (as in the case of the Giraff Robot). The Middleware software contains the communication infrastructure of the Giraff+ platform and all devices that run the Middleware can actively participate in the communication of the system. The second way of connecting devices to the Giraff+ system does not require a given device to run the Giraff+ Middleware (as in the case of Tunstall and Intellicare sensors). The device in question is rather connected to a node that runs this Middleware, and this node is used as an intermediary by the system in order to control the additional device. For many devices, such as low-power wireless sensors, this is the only way of connecting them to the system, simply because they cannot run any additional software beyond their firmware. And although these slave-devices cannot actively participate in the communication with the rest of the system (as they are just queried for data), their advantage over regular nodes is that they can (oftentimes) simply be "plug-and-played" into a running system. | Of course, a prerequisite for being able to show this kind of behavior is that all devices involved are connected to the same system. In GiraffPlus, a single device that is connected to the system is referred to as being a "node". In principle, there are two ways of how to integrate a device into GiraffPlus system, assuming that the device in question is networked (can send and receive data using a network protocol, either wired or wireless). The first way is to install a specific piece of the GiraffPlus platform on the device, the so-called "**Middleware**" (as in the case of the Giraff Robot). The Middleware software contains the communication infrastructure of the GiraffPlus platform and all devices that run the Middleware can actively participate in the communication of the system. The second way of connecting devices to the GiraffPlus system does not require a given device to run the GiraffPlus Middleware (as in the case of Tunstall and Intellicare sensors). The device in question is rather connected to a node that runs this Middleware, and this node is used as an intermediary by the system in order to control the additional device. For many devices, such as low-power wireless sensors, this is the only way of connecting them to the system, simply because they cannot run any additional software beyond their firmware. And although these slave-devices cannot actively participate in the communication with the rest of the system (as they are just queried for data), their advantage over regular nodes is that they can (oftentimes) simply be "plug-and-played" into a running system. |
| |
| Besides the Middleware, the Giraff+ platform is made up of various other software parts which we will refer to as "higher level components". The Middleware is the basis for all of these higher level components, meaning that you cannot run any of them if the Middleware is not available. The Middleware, however, does not provide a functionality that an end-user would find very useful. It is rather the basis for the higher level platform components to provide application functionalities. Components relies upon it, as the Middleware is capable of hiding the distribution and heterogeneity of the diverse devices that make up the system at its core. From an application programmer's perspective, this means that you do not need to worry about the fact that some of the applications (and higher level platform components) that your application talks to may actually be running on other devices than the one your application is. You will simply forward all of your application's messages and requests to the Middleware component, which will take it from there, making sure that each message reaches its recipient. Note that the Middleware does of course not hinder your application from accessing a device's operating system API. It simply takes the hassle of resolving dependencies off your shoulders. | Besides the Middleware, the GiraffPlus platform is made up of various other software parts which we will refer to as "higher level components". The Middleware is the basis for all of these higher level components, meaning that you cannot run any of them if the Middleware is not available. The Middleware, however, does not provide a functionality that an end-user would find very useful. It is rather the basis for the higher level platform components to provide application functionalities. Components relies upon it, as the Middleware is capable of hiding the distribution and heterogeneity of the diverse devices that make up the system at its core. From an application programmer's perspective, this means that you do not need to worry about the fact that some of the applications (and higher level platform components) that your application talks to may actually be running on other devices than the one your application is. You will simply forward all of your application's messages and requests to the Middleware component, which will take it from there, making sure that each message reaches its recipient. Note that the Middleware does of course not hinder your application from accessing a device's operating system API. It simply takes the hassle of resolving dependencies off your shoulders. |
| | |
| | Hiding the distribution and heterogeneity of the devices is actually just part of the Middleware's job. Its main task lies in what is usually summarized as "seamless connectivity and goal-based interoperability". As at its core, an assistive system is nothing else but a local private network of technical devices. When additional nodes try to (re-)join the system, the discovery mechanisms of the Middleware automatically recognize and integrate all qualified nodes within reach. The GiraffPlus Middleware has two mediators to discover nodes and reach them, and each of them is responsible for the delivery of a certain message category: **the buses**. |
| |
| Hiding the distribution and heterogeneity of the devices is actually just part of the Middleware's job. Its main task lies in what is usually summarized as "seamless connectivity and goal-based interoperability". As at its core, an assistive system is nothing else but a local private network of technical devices. When additional nodes try to (re-)join the system, the discovery mechanisms of the Middleware automatically recognize and integrate all qualified nodes within reach. The Giraff+ Middleware has two mediators to discover nodes and reach them, and each of them is responsible for the delivery of a certain message category: **the buses**. | |
| ===== Basic Concepts ===== | |
| //ToDo.// | |
| ==== Middleware Architecture ==== | |
| //ToDo.// | |
| ==== The Context Bus ==== | |
| //ToDo.// | |
| ==== The Service Bus ==== | |
| //ToDo.// | |
| ==== The Connectors ==== | |
| //ToDo.// | |
| ===== Getting Started ===== | ===== Getting Started ===== |
| This section provides information about how to setup the development environment and about how to execute and run the Giraff+ middleware. | This section provides information about how to setup the development environment and about how to execute and run the GiraffPlus middleware. |
| ==== Setting up the Development Environment ==== | ==== Setting up the Development Environment ==== |
| There are a few steps you need to perform before you can actually start with setting up your development environment for Giraff+ and with writing your first application. Please note that we will implicitly assume that you have a Windows 7 system, although deriving the installation steps for other versions of the Windows OS should not be very difficult. Also be aware that you will need to have administrator rights on your PC to be able to perform many of the steps as described below. | There are a few steps you need to perform before you can actually start with setting up your development environment for GiraffPlus and with writing your first application. Please note that we will implicitly assume that you have a Windows 7 system, although deriving the installation steps for other versions of the Windows OS should not be very difficult. Also be aware that you will need to have administrator rights on your PC to be able to perform many of the steps as described below. |
| === Installing an SVN client === | === Installing an SVN client === |
| ---- | ---- |
| When multiple programmers work on a software project, it is always a good idea to have a revision control system in place that tracks changes to shared documents (such as the source code files) and which allows to coordinate parallel editing, to resolve possible conflicts, or even to revert a document to a former version if that should become necessary. One of the most widespread revision control systems is certainly [[http://subversion.apache.org/|Apache Subversion]]. Subversion, usually abbreviated to SVN, allows a team to create shared repositories of files on a server, from which programmers can "pull" a file to have its latest version locally available, manipulate it, and then "push" the updated file back to the repository to make it available to the rest of the team. Each of the Giraff+ project's work packages has its own SVN repository. From these repositories, application developers can pull the source code files to have them locally available. One way of doing this is via a Subversion-Client, which we will install now. | When multiple programmers work on a software project, it is always a good idea to have a revision control system in place that tracks changes to shared documents (such as the source code files) and which allows to coordinate parallel editing, to resolve possible conflicts, or even to revert a document to a former version if that should become necessary. One of the most widespread revision control systems is certainly [[http://subversion.apache.org/|Apache Subversion]]. Subversion, usually abbreviated to SVN, allows a team to create shared repositories of files on a server, from which programmers can "pull" a file to have its latest version locally available, manipulate it, and then "push" the updated file back to the repository to make it available to the rest of the team. Each of the GiraffPlus project's work packages has its own SVN repository. From these repositories, application developers can pull the source code files to have them locally available. One way of doing this is via a Subversion-Client, which we will install now. |
| |
| First of all, you need software for talking to Subversion repositories. You may want to use one that comes with a graphical user interface, such as [[http://tortoisesvn.net/|TortoiseSVN]]. Go to http://tortoisesvn.net/downloads.html and download the TortoiseSVN installer (a thing you obviously do not need to do if you already have TortoiseSVN installed on your system). The great thing about TortoiseSVN is that it hooks itself up to your Windows explorer, which means a right click on a folder will give you the additional option of matching it against a certain online repository (thus checking for updated files within both your local folder and the online repository). Once its downloaded, just double click the installer and follow the instructions to install TortoiseSVN to its default path. You will then be asked to restart the system, which you should do. | First of all, you need software for talking to Subversion repositories. You may want to use one that comes with a graphical user interface, such as [[http://tortoisesvn.net/|TortoiseSVN]]. Go to http://tortoisesvn.net/downloads.html and download the TortoiseSVN installer (a thing you obviously do not need to do if you already have TortoiseSVN installed on your system). The great thing about TortoiseSVN is that it hooks itself up to your Windows explorer, which means a right click on a folder will give you the additional option of matching it against a certain online repository (thus checking for updated files within both your local folder and the online repository). Once its downloaded, just double click the installer and follow the instructions to install TortoiseSVN to its default path. You will then be asked to restart the system, which you should do. |
| === Getting the sources === | === Getting the sources === |
| ---- | ---- |
| Once you have access to the Giraff+ project, the next step is to download all files from these repositories to your PC. This will allow you to work with the tester application provided by the WP2. The Middleware project, on the other hand, has the sources for the Middleware component of the Giraff+ platform. While you may not need these initially, at a later point in time you will probably find that having access to the classes that make up Giraff+'s Middleware will help you when writing more sophisticated applications. The first thing you need to do now is to create the folder that will serve as your local mirror of the online repository, then right click the folder and from the context-menu, select "SVN Checkout...". | Once you have access to the GiraffPlus project, the next step is to download all files from these repositories to your PC. This will allow you to work with the tester application provided by the WP2. The Middleware project, on the other hand, has the sources for the Middleware component of the GiraffPlus platform. While you may not need these initially, at a later point in time you will probably find that having access to the classes that make up GiraffPlus's Middleware will help you when writing more sophisticated applications. The first thing you need to do now is to create the folder that will serve as your local mirror of the online repository, then right click the folder and from the context-menu, select "SVN Checkout...". |
| |
| For the Middleware project, the address is https://giraff.xlab.si/svn/giraff/src/WP2/ . After clicking OK, you will be asked to identify yourself by entering your username and password. Do so, and the checkout process should start. | For the Middleware project, the address is https://giraff.xlab.si/svn/giraff/src/WP2/ . After clicking OK, you will be asked to identify yourself by entering your username and password. Do so, and the checkout process should start. |
| === Installing Java === | === Installing Java === |
| ---- | ---- |
| The Giraff+ platform is based on the programming language Java. Consequently we need to install the Java programming libraries to your system, so that you can work with these (the so-called Java Development Kit, or JDK for short). Please go to [[http://www.oracle.com/technetwork/java/javase/downloads/index.html|JDK 6 download page]] and download it to your system. If you are not sure whether to download the 32-bit version or the 64-bit version of the JDK, just choose the one for 32-bit systems. | The GiraffPlus platform is based on the programming language Java. Consequently we need to install the Java programming libraries to your system, so that you can work with these (the so-called Java Development Kit, or JDK for short). Please go to [[http://www.oracle.com/technetwork/java/javase/downloads/index.html|JDK 6 download page]] and download it to your system. If you are not sure whether to download the 32-bit version or the 64-bit version of the JDK, just choose the one for 32-bit systems. |
| |
| Once the JDK has successfully been installed, the installer may ask you to where it should install an additional JRE to. Simply install this "public JRE" to its default installation path, as it will not be part of the Giraff+ development environment. Afterwards, the installer may also want to install the "JavaFX SDK". Again, simply click through the installation wizard without changing any of the default settings. | Once the JDK has successfully been installed, the installer may ask you to where it should install an additional JRE to. Simply install this "public JRE" to its default installation path, as it will not be part of the GiraffPlus development environment. Afterwards, the installer may also want to install the "JavaFX SDK". Again, simply click through the installation wizard without changing any of the default settings. |
| === Installing Maven === | === Installing Maven === |
| ---- | ---- |
| Giraff+ uses [[http://maven.apache.org/|Apache Maven]] as software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. | GiraffPlus uses [[http://maven.apache.org/|Apache Maven]] as software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information. |
| |
| Maven is distributed in several formats for your convenience. Use a source archive if you intend to build Maven yourself. Otherwise, simply pick a ready-made binary distribution from the [[http://maven.apache.org/download.cgi|download page]]. To install Maven follow these steps: | Maven is distributed in several formats for your convenience. Use a source archive if you intend to build Maven yourself. Otherwise, simply pick a ready-made binary distribution from the [[http://maven.apache.org/download.cgi|download page]]. To install Maven follow these steps: |
| * **giraff.pom**: the parent pom bundle | * **giraff.pom**: the parent pom bundle |
| * **giraff.rest**: the rest connector implementation | * **giraff.rest**: the rest connector implementation |
| * **giraff.tester**: a tester bundle to run the test instance of the Giraff+ system | * **giraff.tester**: a tester bundle to run the test instance of the GiraffPlus system |
| as well as other bundles that will be analyzed in the next sections. You can now compile the Middleware by using the Maven tool. Move to the giraff.pom directory and type: | as well as other bundles that will be analyzed in the next sections. You can now compile the Middleware by using the Maven tool. Move to the giraff.pom directory and type: |
| |
| ''mvn install -DskipTests'' | ''mvn install -DskipTests'' |
| |
| After this, the Giraff+ middleware has been installed in your local maven repository (look inside your .m2 dir). | After this, the GiraffPlus middleware has been installed in your local maven repository (look inside your .m2 dir). |
| === Middleware configurations === | === Middleware configurations === |
| ---- | ---- |
| We use the [[http://felix.apache.org/site/apache-felix-config-admin.html|Config Admin Specification]] for the configuration stuff of Giraff+ Middleware. In the folder \rundir\confadmin\services you can find a set of files containing the configuration properties for each bundle. You need to set properties for the connectors (MQTT and Rest) and the middleware in order to run your Middleware instance. | We use the [[http://felix.apache.org/site/apache-felix-config-admin.html|Config Admin Specification]] for the configuration stuff of GiraffPlus Middleware. In the folder \rundir\confadmin\services you can find a set of files containing the configuration properties for each bundle. You need to set properties for the connectors (MQTT and Rest) and the middleware in order to run your Middleware instance. |
| == giraff.mqtt.pid.properties == | == giraff.mqtt.pid.properties == |
| <code> | <code> |
| address = 146.48.81.82 | address = 146.48.81.82 |
| </code> | </code> |
| In the above properties we are setting up an host:port and user:pwd for the MQTT broker (you can leave as it if you want to use the CNR broker instance), the ip of the [[http://www.eclipse.org/jetty/|jetty]] engine of the Middleware instance (the local ip of the machine where the instance is running, leave other properties as it), and the location identifier of your Giraff+ system. | In the above properties we are setting up an host:port and user:pwd for the MQTT broker (you can leave as it if you want to use the CNR broker instance), the ip of the [[http://www.eclipse.org/jetty/|jetty]] engine of the Middleware instance (the local ip of the machine where the instance is running, leave other properties as it), and the location identifier of your GiraffPlus system. |
| |
| **N.B. You need to set up these properties temporarly. As soon as the autoconfiguration bundle will be ready, the only properties needed will be username, password and location.** | **N.B. You need to set up these properties temporarly. As soon as the autoconfiguration bundle will be ready, the only properties needed will be username, password and location.** |
| mvn:org.ops4j.pax.logging/pax-logging-api/1.7.0 | mvn:org.ops4j.pax.logging/pax-logging-api/1.7.0 |
| |
| # GIRAFF+ API | # GiraffPlus API |
| mvn:it.cnr.isti.giraff/giraff.api | mvn:it.cnr.isti.giraff/giraff.api |
| |
| # GIRAFF+ UTIL | # GiraffPlus UTIL |
| mvn:it.cnr.isti.giraff/giraff.util | mvn:it.cnr.isti.giraff/giraff.util |
| |
| # GIRAFF+ MQTT | # GiraffPlus MQTT |
| mvn:it.cnr.isti.giraff/giraff.mqtt | mvn:it.cnr.isti.giraff/giraff.mqtt |
| |
| # GIRAFF+ REST | # GiraffPlus REST |
| mvn:it.cnr.isti.giraff/giraff.rest | mvn:it.cnr.isti.giraff/giraff.rest |
| |
| # GIRAFF+ MIDDLEWARE | # GiraffPlus MIDDLEWARE |
| mvn:it.cnr.isti.giraff/giraff.middleware | mvn:it.cnr.isti.giraff/giraff.middleware |
| |
| <organization> | <organization> |
| <url>http://giraffplus.eu/</url> | <url>http://giraffplus.eu/</url> |
| <name>giraff+</name> | <name>GiraffPlus</name> |
| </organization> | </organization> |
| | |
| <organization> | <organization> |
| <url>http://giraffplus.eu/</url> | <url>http://giraffplus.eu/</url> |
| <name>giraff+</name> | <name>GiraffPlus</name> |
| </organization> | </organization> |
| | |
| </project> | </project> |
| </code> | </code> |
| ===== Giraff+ on Android ===== | |
| Make sure you’ve obtained the archive interfaces.middleware.zip (it is in the Android\giraff.android folder from the svn checkout). This file contains the AIDL interface needed to communicate with the middleware. In order to setup your application you need to extract this file to the src/ directory of the project. | |
| ==== Service Binding ==== | |
| The middleware is implemented as an Android’s bound service that can be activated with the action **"it.cnr.isti.giraff.android.BIND_TO_MIDDLEWARE"**. | |
| ==== Interface API ==== | |
| Files provided in the archive come with in-code documentation. | |
| ==== Implementing a service ==== | |
| Follows a quick tutorial that explains step-by-step how to implement a service. | |
| |
| Note that all you need to know is the documentation of the interface, everything else follows the standard Android’s **AIDL** practices so you can refer the [[http://developer.android.com/guide/components/aidl.html|official documentation]]. | |
| === Import classes === | |
| ---- | |
| Make sure to add the following import: | |
| |
| <code java>import it.cnr.isti.giraff.android.interfaces.middleware.*;</code> | |
| === Implement a service connection === | |
| ---- | |
| In order to request the binding to the service you need to implement a **ServiceConnection** object that manages the connection to the middleware: | |
| <code java> | |
| private IMiddleware middleware; | |
| |
| private ServiceConnection middlewareConnection = new ServiceConnection() { | |
| | |
| @Override | |
| public void onServiceConnected(ComponentName className, IBinder binder) { | |
| middleware = IMiddleware.Stub.asInterface(binder); | |
| } | |
| | |
| @Override | |
| public void onServiceDisconnected(ComponentName className) { | |
| middleware = null; | |
| } | |
| }; | |
| </code> | |
| === Implement the callback logic === | |
| ---- | |
| Some methods requires a listener that need to be implemented on the service application: | |
| <code java> | |
| private IMiddlewareCallback.Stub callback = new IMiddlewareCallback.Stub() { | |
| |
| @Override | |
| public void serviceFound(Bundle descriptor) throws RemoteException { | |
| // ... | |
| } | |
| | |
| @Override | |
| public void serviceRemoved(Bundle descriptor) throws RemoteException { | |
| // ... | |
| } | |
| | |
| @Override | |
| public void serviceChanged(Bundle descriptor) throws RemoteException { | |
| // ... | |
| } | |
| |
| @Override | |
| public void messageReceived(String topic, String payload) throws RemoteException { | |
| // ... | |
| } | |
| }; | |
| </code> | |
| === Implement an error callback === | |
| ---- | |
| Each method in the API takes an optional (can be null) errorListener parameter used to asynchronously report errors: | |
| <code java> | |
| private IMiddlewareErrorCallback.Stub errorCallback = new IMiddlewareErrorCallback.Stub() { | |
| | |
| @Override | |
| public void error(Bundle info) throws RemoteException { | |
| // ... | |
| } | |
| }; | |
| </code> | |
| === Request a connection to the middleware === | |
| ---- | |
| Your application must request a connection to the middleware by using an intent with a specific action string and passing the previously created **ServiceConnection** object: | |
| <code java> | |
| Intent intent = new Intent("it.cnr.isti.giraff.android.BIND_TO_MIDDLEWARE"); | |
| bindService(intent, middlewareConnection, Context.BIND_AUTO_CREATE); | |
| </code> | |
| Make sure to unbind from the middleware when you’re done, for example in the **onDestroy** method of your main activity: | |
| <code java> | |
| @Override | |
| protected void onDestroy() { | |
| super.onDestroy(); | |
| if (middlewareConnection != null) { | |
| unbindService(middlewareConnection); | |
| } | |
| } | |
| </code> | |
| === Call methods === | |
| ---- | |
| Once you have the **IMiddleware** object you can call remote methods on it, for example: | |
| <code java>middleware.subscribe("topic", callback, errorCallback);</code> | |
