View source for ECF 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==

This article demonstrates how to use the [http://www.eclipse.org/ecf Eclipse Communication Framework (ECF)]  [https://wiki.eclipse.org/ECF#OSGi_Remote_Services Remote Services] to interact with networked devices based upon [http://www.raspberrypi.org/documentation/usage/gpio/ Raspberry Pi GPIO].   The use of [https://wiki.eclipse.org/ECF#OSGi_Remote_Services Remote Services] provides clear advantages:
#The Service Interface provides a simple, clear, and flexible abstraction for accessing individual GPIO pins.  This enables system-wide loose coupling and high cohesion, two desirable design characteristics for networked applications and services.
#There are multiple technical advantages from using Remote Services
##'''Dynamics''' - Hardware-based services come and go (especially when made available via a network), and applications can be notified and adjust appropriately
##'''Service Versioning''' - Hardware capabilities and their associated services may evolve over time, and this may require versioning the Service Interface, and allowing multiple versions to coexist simultaneously in a single runtime.
##'''Support for Multiple Injection Frameworks''' - Declarative Services, Blueprint, Spring, and others can be used as desired to inject services and dependencies
##'''Support for Service-Level Security''' - Flexible policies to control, restrict, and/or manage services may be defined as appropriate for the application
##'''Transport-Independent and Extensible Network Distribution and Discovery''' - [https://wiki.eclipse.org/ECF#OSGi_Remote_Services ECF Remote Services] provides full interoperability through open standards, a [https://wiki.eclipse.org/OSGi_Remote_Services_and_ECF transport-independent architecture], and open, extensible, community-developed APIs and implementations.

In this article, we step through the declaration, implementation, and testing of services for controlling individual GPIO Pins.  After showing how these services can be used to control a simple light application, we then describe how to use ECF Remote Services to distribute these services across a network.   We then demonstrate how these GPIO pin services can be easily used by an Eclipse-based user interface to remotely control the state of individual GPIO Pins.

==Accessing GPIO Pin State==

Each GPIO digital pins have two modes:  output and input.   For output, each pin can be in either the 'HIGH' state, or the 'LOW' state, and the control of the pin state is what we would like to manipulate to give our application runtime behavior.  After connecting a single LED to the Raspberry Pi GPIO, changing the output on a given pin to HIGH will turn the LED on, while setting to low will turn it off.  See [https://projects.drogon.net/raspberry-pi/gpio-examples/tux-crossing/gpio-examples-1-a-single-led/ these instructions] for how to physically connect a single LED to the Raspberry Pi GPIO.  

Below is a picture of my Raspberry Pi with an LED connected to GPIO digital output pin 0, as per the [https://projects.drogon.net/raspberry-pi/gpio-examples/tux-crossing/gpio-examples-1-a-single-led/ these instructions].  

[[File:Ledsetup.png]]

We start by declaring a GPIO pin output  '''service interface'''.    This service interface declares methods for getting and setting the state of a single GPIO pin.  Here is the IGPIOPinOutput service interface:

<source lang="java">
public interface IGPIOPinOutput extends IGPIOPin {

	public boolean getState();

	public void setState(boolean value);

...

}
</source>

For this tutorial, we will be interested only in the '''getState''' and '''setState''' methods from this service interface.  Note that at runtime we may create as many instances of this service interface as desired.   Modern Raspberry Pi's have two rows of 10 pins for a total of 20 physical GPIO pins.    To control our LED, we only need to control a single pin, so will only need a single instance of the IGPIOPinOutput service that communicates with pin id=0.

To find and call methods on an active instance of the IGPIOPinOutput service there are several mechanisms available (e.g. Declarative Services, Blueprint, Spring, ServiceTracker, ServiceReferences, etc.).  For this tutorial, we will use a very simple ServiceTracker.  The complete code for this example can be located in the start method of [https://github.com/ECF/RaspberryPI/blob/master/test/bundles/org.eclipse.ecf.raspberrypi.test.gpio/src/org/eclipse/ecf/raspberrypi/test/gpio/Activator.java this test code].  The important fragments is the implementation of the '''addingService''' method, which is called automatically when instances of IGPIOPinOutput are registered:

<source lang="java">
public IGPIOPinOutput addingService(ServiceReference<IGPIOPinOutput> reference) {
    ....
    // Get the service instance
    IGPIOPinOutput pin = context.getService(reference);
    // Print out info about it's current state
    System.out.println("  current pin state is "+(pin.getState()?"HIGH":"LOW"));
    System.out.println("  setting state to HIGH");
    // Set the pin's state to true/HIGH
    pin.setState(true);
    return pin;
}
</source>

Note that when a IGPIOPinService is added, the service.setState(true) method is called, setting the state of the pin to HIGH, and turning on/lighting the LED connected to that pin.     
When this test code is run on a Raspberry Pi, this appears on the OSGi console:

<pre>
osgi> start 3
Adding GPIO Pin Output service.   id=0
  current pin state is LOW
  setting state to HIGH
</pre>

and as a result of the call to '''pin.setState(true)''' the LED connected to GPIO pin 0 lights up

[[File:Ledhigh.png]]

Here is a [https://www.youtube.com/watch?v=BtS_JDyiKkU&feature=youtu.be short video showing the running of this test code].   Thanks to ECF committer Wim Jongman for duplicating this example and making the video available.

==Exporting the GPIO Pin Output Service for Remote Access ==

To make the control of GPIO pin 0 available for remote access, with ECF Remote Services all we need to do is to provide values for some standardized service properties when registering the IGPIOPinOutput instance.  The names and appropriate types/values of these service properties are standardized by OSGi Remote Services, which is specified by [http://www.osgi.org/Specifications/HomePage OSGi Enterprise specification].

Here is the code to register and export the GPIOPinOutput 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 and export GPIOPin 0
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 Remote Services implementation present, the properties added above will result in the IGPIOPinOutput service being exported as a remote service.  The export happens automatically during the registration of the IGPIOPinOutput service (inside the registerGPIOPinOutput method in the above code).  With the default discovery policy, exporting this remote service will also advertise/publish it for network-based discovery.  For this [https://github.com/ECF/RaspberryPI/tree/master/test/features/org.eclipse.ecf.raspberrypi.test.gpio.feature example], we use the Service Locator Protocol (RFC 2608) for LAN-based network discovery.  ECF Remote Services provides [https://wiki.eclipse.org/ECF#Customization_of_ECF_Remote_Services_.28new_Discovery_and.2For_Distribution_providers.29 multiple alternatives for discovery], with support for both networked an non-network discovery alternatives.

==Discovering Remote GPIOPinOutput Services==

Once exported, remote consumers (clients) may discover and then call methods on the IGPIOPinOutput remote service.  To demonstrate this, here is a simple Eclipse-based user interface to present the discovered IGPIOPinOutput remote service instances.  The code for this Eclipse view 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 the Eclipse ide, 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.

==Summary==

ECF Remote Services provides an easy way to declare arbitrary services, and expose/export them for remote access.   Representing Raspberry Pi GPIO as remote services makes a great example of how such remote services can be a boon for the easy creation and distribution of services between devices that make up the Internet of Things.

==Technical Notes==

# The full source for this example is available via the [https://github.com/ECF/RaspberryPI ECF Raspberry Pi Github Repository].   ECF also maintains a number of other examples and custom providers via it's [https://github.com/ECF Github repositories].
#2 ECF provides asynchronous remote services for non-blocking remote procedure call.  The example Eclipse code uses the IGPIOPinOutputAsync service interface, which 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 for this example uses this asynchronous remote service to control the GPIO Pin 0 '''without any methods that might block the Eclipse UI'''.  The implementation of the IGPIOPinOutputAsync interface is automatically created by the [https://wiki.eclipse.org/ECF#OSGi_Remote_Services ECF Remote Services] proxy creation.  Here is a snippet from the implementation of the GPIO Pin View class, showing the use of the asynchronous remote service, as well as the use of Java 8 lambda expressions.
<source lang="java">
public void toggle() {
	// Set waiting to true
	waiting = true;
	boolean newState = !this.state;
	// If we have asynchronous access to service,
	// then use it
	if (pinOutputAsync != null) {
		// Set state asynchronously to newState,
		// and when complete change the UI state
		// and refresh the viewer
		pinOutputAsync.setStateAsync(newState).whenComplete(
				(result, exception) -> {
					this.waiting = false;
					if (viewer != null) {
						// No exception means success
						if (exception == null) {
							// Set UI state to newState
							state = newState;
							asyncRefresh();
						} else
							showCommErrorDialog(exception);
					}
				});
	} else {
		// If we do not have access to async service, then
		// call pinOutput synchronously
		pinOutput.setState(newState);
		state = newState;
	}
}
</source>
The entire source for this view class is available [https://github.com/ECF/RaspberryPI/blob/master/test/bundles/org.eclipse.ecf.raspberrypi.test.gpio.ide/src/org/eclipse/ecf/raspberrypi/internal/test/gpio/ide/views/RpiGPIOPinView.java here].

More about asynchronous remote services is described in [[ECF/Asynchronous_Remote_Services | Asynchronous Remote Services]].

==Related Articles and Documentation==

[[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]]