View source for Tutorial: OSGi Remote Services for Raspberry Pi GPIO

<!-- This CSS wraps code blocks in pretty boxes -->
<css>
.mw-code { 
  background-color: #fafafa; 
  padding: 20px; 
  border-color: #ddd; 
  border-width: 3px; 
  border-style: solid; 
  border-radius: 5px; 
  margin-left: 10px; 
  margin-right: 10px; 
  overflow-x: auto; 
}

.mw-headline {
  font-family: Helvetica Neue,Helvetica,Arial,sans-serif;
  color: rgb(51, 51, 51);
}

p {
  font-family: Helvetica Neue,Helvetica,Arial,sans-serif;
  text-align: justify;
}

h1 {
  border-bottom-color: rgb(238, 238, 238);
  font-weight: bold;
  padding-bottom: 17px;
  font-size: 30px;
  line-height: 36px;
}

h2 {
  border-bottom-color: rgb(238, 238, 238);
  padding-bottom: 12px;
  font-weight: bold;
  font-size: 24px;
  line-height: 36px;
}

h3 {
  border-bottom-width: 1px;
  border-bottom-style: solid;
  border-bottom-color: rgb(238, 238, 238);
  padding-bottom: 8px;
  font-size: 18px;
  line-height: 27px;
}

h4 {
  font-size: 14px;
}

h5 {
  font-size: 12px;
}

h6 {
  font-size: 11px;
  color: #EBEBEB;
  text-transform: uppercase;
}

a {
  color: rgb(0, 105, 214);
  font-family: Helvetica Neue,Helvetica,Arial,sans-serif;
}

a:visited {
  color: rgb(0, 105, 214);
}
</css>

==Introduction==

In a [[Tutorial:_Raspberry_Pi_GPIO_with_OSGi_Services | previous tutorial]] we showed how to abstract the Raspberry Pi's GPIO device as a set of very simple OSGi Services.  This tutorial will show how to '''export''' those services for remote access over a network via a simple and standard mechanism.  We also show how to create and use a very simple Eclipse-based user interface as a client for controlling devices connected to the Pi's GPIO.

See the [[Tutorial:_Raspberry_Pi_GPIO_with_OSGi_Services | previous tutorial]] for the declaration and description of the GPIO Pin Output service interface.

To make the control of GPIO pin 0 available for remote access, all that's necessary is to provide some service properties when registering the instance of the IGPIOPinOutput instance.  The service properties are standardized by the OSGi Remote Services chapter 100 in the [http://www.osgi.org/Specifications/HomePage OSGi Enterprise specification].

Here is the code to export the IGPIOPinOutput service

<source lang="java">
Map<String, Object> pinProps = new HashMap<String, Object>();
pinProps.put("service.exported.interfaces", "*");
pinProps.put("service.exported.configs", "ecf.generic.server");
pinProps.put("ecf.generic.server.port", "3288");
pinProps.put("ecf.generic.server.hostname",InetAddress.getLocalHost().getHostAddress());
pinProps.put("ecf.exported.async.interfaces", "*");
...

// register GPIOPin 0 with the above export properties
reg = Pi4jGPIOPinOutput.registerGPIOPinOutput(0, pinProps, context);
</source>

See [https://github.com/ECF/RaspberryPI/blob/master/test/bundles/org.eclipse.ecf.raspberrypi.test.gpio/src/org/eclipse/ecf/raspberrypi/test/gpio/Activator.java here for the entire source for this example].

With ECF's implementation of [[ECF#OSGi_Remote_Services | OSGi Remote Services]] present in the target framework, this registration will export an OSGi Remote Service, and make it available for discovery and use by other processes.  In the case of the [https://github.com/ECF/RaspberryPI/tree/master/test/features/org.eclipse.ecf.raspberrypi.test.gpio.feature example], the SLP protocol is used for LAN-based network discovery.  

Once exported, remote consumers may discover, import, and then use the IGPIOPinOutput service.  To demonstrate this, here is simple Eclipse View present the discovered IGPIOPinOutput remote service instances.  The code for this Eclipse plugin is [https://github.com/ECF/RaspberryPI/tree/master/test/bundles/org.eclipse.ecf.raspberrypi.test.gpio.ide in the test/bundles/org.eclipse.ecf.raspberrypi.test.gpio.ide] project.   When run in Eclipse, the empty view (no discovered IGPIOPinOutput services) looks like this

[[File:eclipsenopins.png]]

After discovering an instance of IGPIOPinOutput remote service via SLP LAN-based discovery the view is automatically updated with the IGPIOPinOutput proxy, which is automatically created by the OSGi Remote Services implementation.

[[File:eclipsepinlow.png]]

With the discovery of this IGPIOPinOutput remote service, and it's appearance in this view, a simple click on the 'State (click to toggle)' cell results in the pin toggling it's state via a call to IGPIOPinUpdate.setState, resulting in both the Eclipse UI being updated with a different icon

[[File:eclipsepinhigh.png]]

and the LED that's connected to the Raspberry Pi lights up

[[File:leghigheclipse.png]]

The same as if we had accessed the IGPIOPinOutput service from the Raspberry Pi directly.  

Note

OSGi Remote Services allows service consumers to ignore the underlying communications transport used for the remoting of the IGPIOPinOutput service.  The code implementing the Eclipse view does not access *any* transport-specific mechanisms, allowing both the Raspberry Pi (service host) and the Eclipse view to use whatever provider transport they prefer.

The dynamics of unreliable remote services (i.e. that services come and go over time) is handled extremely well by OSGi services. 

ECF provides support for using the [[ECF/Asynchronous_Remote_Services | Java8 CompletableFuture for asynchronous remote services]], eliminating the potential for user interface blocking, without complicated threading code.  On the remote service consumer (Eclipse UI in this case), the ECF proxy  automatically implements this asynchronous service type


<source lang="java">
package org.eclipse.ecf.raspberrypi.gpio;

import java.util.concurrent.CompletableFuture;

public interface IGPIOPinOutputAsync {

	public CompletableFuture<Boolean> getStateAsync();

	public CompletableFuture<Void> setStateAsync(boolean value);

...

}
</source>

The full source for this asynchronous service interface is available [https://github.com/ECF/RaspberryPI/blob/master/bundles/org.eclipse.ecf.raspberrypi.gpio/src/org/eclipse/ecf/raspberrypi/gpio/IGPIOPinOutputAsync.java here].

The Eclipse UI code can then use this asynchronous service to remotely control the GPIO Pin 0 without any blocking operations.  The implementation of the IGPIOPinOutputAsync interface is created on the Eclipse client/consumer by the ECF Remote Services proxy creation.  More about asynchronous remote services is described in [[ECF/Asynchronous_Remote_Services | Asynchronous Remote Services]].

==Related Articles==

[[Tutorial:_Raspberry_Pi_GPIO_with_OSGi_Services | Tutorial:Raspberry Pi GPIO with OSGi Services

[[ECF/Asynchronous_Remote_Services | Asynchronous Remote Services]]

[[Getting Started with ECF's OSGi Remote Services Implementation]]

[[EIG:Download|Download ECF Remote Services/RSA Implementation]]

[[EIG:Add to Target Platform|How to Add Remote Services/RSA to Your Target Platform]]