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.

Applications that use this infrastructure require that the middleware application (Android/giraff.android/middleware folder from the svn checkout) and at least one communication connector application (there is only one by now in the communicationconnector.mqtt Android/giraff.android/ folder from the svn checkout) are previously installed to the device.

Also, the middleware needs to be configured before using any of the clients applications, this can be done using the middleware launcher icon. The configuration includes the mandatory parameters:

• URI of the MQTT broker (“tcp://xxx.yyy.zzz.www”);
• user of the MQTT broker;
• password of the MQTT broker;
• location string.

Make sure to kill the “middleware” Android process after further changes. Note that these parameters may change in the future. Refer to the wiki for more information on the Giraff+ system.

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”.

Files provided in the archive come with in-code documentation.

Follows a quick tutorial that explains step-by-step how to implement a full working example application (source code can be found in the folder from the svn checkout). This application probes the sensors of the device and announces the ones it finds, then starts sending the gathered values to the middleware.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 official documentation.

The example application is composed of a main activity that launches a service in charge of listening on sensors changes:

public class MainActivity extends Activity implements OnCheckedChangeListener {
 
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);
	ToggleButton startstop = (ToggleButton) findViewById(R.id.startstop);
 
	// order matters to avoid unwanted onCheckedChanged
	startstop.setChecked(SensorsService.isEnabled());
	startstop.setOnCheckedChangeListener(this);
    }
 
    @Override
    public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {
        // start
        if (isChecked) {
	    startService(new Intent(this, SensorsService.class));
	}
	// stop
	else {
	    stopService(new Intent(this, SensorsService.class));
	}
    }
}

A ToggleButton starts or stops the service:

The SensorsService class initializes sensors (creating for each sensors present on the device a descriptor by means of android Bundle done in the SensorsDescriptors class), than calls methods of the middleware to announce sensors and publish data to the context bus. To do this the SensorsService follows these steps:

1. Import middleware clsses
2. Implement a service connection
3. Implement the callback logic (optional)
4. Implement an error callback (optional)
5. Request a connection to the middleware
6. Call methods of the middleware interface

Make sure to add the following import:

import it.cnr.isti.giraff.android.interfaces.middleware.IMiddleware;

In order to request the binding to the service you need to implement a ServiceConnection object that manages the connection to the middleware:

private IMiddleware middleware;
private SensorsDescriptors sensorsDescriptors;
 
private ServiceConnection middlewareConnection = new ServiceConnection() {
 
    @Override
    public void onServiceConnected(ComponentName className, IBinder binder) {
        middleware = IMiddleware.Stub.asInterface(binder);
 
        // enter foreground state
	startForeground(1, notificationBuilder.build());
 
	// announce all descriptors and register sensor listener
	sensorsDescriptors.initialize(middleware);
    }
 
    @Override
    public void onServiceDisconnected(ComponentName className) {
        middleware = null;
 
        // unregister sensor listener and remove all descriptors
	sensorsDescriptors.finalize();
 
	// exit foreground state
	stopForeground(true);
    }
};

Some methods requires a listener that need to be implemented on the service application:

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 {
        // ...
    }
};

Each method in the API takes an optional (can be null) errorListener parameter used to asynchronously report errors:

private IMiddlewareErrorCallback.Stub errorCallback = new IMiddlewareErrorCallback.Stub() {
 
    @Override
    public void error(Bundle info) throws RemoteException {
        // ...
    }
};

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:

Intent intent = new Intent("it.cnr.isti.giraff.android.BIND_TO_MIDDLEWARE");
bindService(intent, middlewareConnection, Context.BIND_AUTO_CREATE);

Make sure to unbind from the middleware when you’re done, for example in the onDestroy method of your main activity:

@Override
protected void onDestroy() {
    super.onDestroy();
    if (middlewareConnection != null) {
        unbindService(middlewareConnection);
    }
}

Once you have the IMiddleware object you can call remote methods on it, for example for announcing sensors on the sensor bus or to publish data on the context bus.

In the onCreate() method of the SensorsService class we create the SensorsDescriptors class:

public void onCreate() {
    super.onCreate();
    Log.d(TAG, "onCreate()");
 
    // foreground notification builder
    Intent intent = new Intent(SensorsService.this, MainActivity.class);
    notificationBuilder = new NotificationCompat.Builder(SensorsService.this);
    notificationBuilder.setSmallIcon(R.drawable.icon);
    notificationBuilder.setContentTitle(getResources().getText(R.string.app_name));
    notificationBuilder.setContentText(getResources().getText(R.string.foreground_message));
    notificationBuilder.setContentIntent(PendingIntent.getActivity(SensorsService.this, -1, intent, 0));
 
    sensorsDescriptors = new SensorsDescriptors(this);
}

The SensorsDescriptors constructor creates a descriptor for each sensor present on the device (for sake of consistency with the GiraffPlus ecosystem we choose to publish data on the subtree sensor/ of the context bus, please respect this constraint):

private final static int SENSORS_DELAY = SensorManager.SENSOR_DELAY_NORMAL;
private final static SparseArray<String> SENSORS = new SparseArray<String>()
private SparseArray<Pair<Sensor, Bundle>> SERVICE_DESCRIPTORS = new SparseArray<Pair<Sensor, Bundle>>();
private SensorManager sensorManager;
static {
    // desirable sensors
    SENSORS.append(Sensor.TYPE_ACCELEROMETER, "TYPE_ACCELEROMETER");
    SENSORS.append(Sensor.TYPE_AMBIENT_TEMPERATURE, "TYPE_AMBIENT_TEMPERATURE");
    SENSORS.append(Sensor.TYPE_GRAVITY, "TYPE_GRAVITY");
    SENSORS.append(Sensor.TYPE_GYROSCOPE, "TYPE_GYROSCOPE");
    SENSORS.append(Sensor.TYPE_LIGHT, "TYPE_LIGHT");
    SENSORS.append(Sensor.TYPE_LINEAR_ACCELERATION, "TYPE_LINEAR_ACCELERATION");
    SENSORS.append(Sensor.TYPE_MAGNETIC_FIELD, "TYPE_MAGNETIC_FIELD");
    SENSORS.append(Sensor.TYPE_PRESSURE, "TYPE_PRESSURE");
    SENSORS.append(Sensor.TYPE_PROXIMITY, "TYPE_PROXIMITY");
    SENSORS.append(Sensor.TYPE_RELATIVE_HUMIDITY, "TYPE_RELATIVE_HUMIDITY");
    SENSORS.append(Sensor.TYPE_ROTATION_VECTOR, "TYPE_ROTATION_VECTOR");
}
 
public SensorsDescriptors(Context context) {
    Sensor sensor;
    Bundle serviceDescriptor;
 
    sensorManager = (SensorManager) context.getSystemService(Context.SENSOR_SERVICE);
 
    // get device id
    TelephonyManager telephonyManager = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
    String id = telephonyManager.getDeviceId();
 
    // for each desirable sensor
    for (int i = 0; i < SENSORS.size(); i++) {
        int sensorType = SENSORS.keyAt(i);
	String sensorName = SENSORS.get(sensorType);
 
	// probe sensor and add to the list
	sensor = sensorManager.getDefaultSensor(sensorType);
	if (sensor != null) {
	    serviceDescriptor = new Bundle();
	    serviceDescriptor.putString("serviceBusTopic", id + "/" + sensorName);
	    serviceDescriptor.putString("id", id + "/" + sensorName);
	    serviceDescriptor.putString("type", "sensor");
	    serviceDescriptor.putString("category", sensorName);
	    serviceDescriptor.putString("contextBusTopic", "sensor/" + id + "/" + sensorName);
	    serviceDescriptor.putString("description", sensor.toString());
	    SERVICE_DESCRIPTORS.put(sensorType, new Pair<Sensor, Bundle>(sensor, serviceDescriptor));
	}
    }
}

We called the method sensorsDescriptors.initialize(middleware) in the SensorsService class when we implemented the service connection. This method announce the descriptors created before and register to sensors changes:

public void initialize(IMiddleware middleware) {
    try {
	announce(middleware);
	register();
    } catch (RemoteException e) {
	Log.e(TAG, "cannot announce");
    }
}

private void announce(IMiddleware middleware) throws RemoteException {
    this.middleware = middleware;
    for (int i = 0; i < SERVICE_DESCRIPTORS.size(); i++) {
	Bundle serviceDescriptor = SERVICE_DESCRIPTORS.get(SERVICE_DESCRIPTORS.keyAt(i)).second;
        // CALL TO THE MIDDLEWARE API - ANNOUNCE
	middleware.announce(serviceDescriptor, errorCallbackImpl);
    }
}

private void register() {
    for (int i = 0; i < SERVICE_DESCRIPTORS.size(); i++) {
	Sensor sensor = SERVICE_DESCRIPTORS.get(SERVICE_DESCRIPTORS.keyAt(i)).first;
	sensorManager.registerListener(this, sensor, SENSORS_DELAY);
    }
}

Once we have announced the sensors on the service bus we can begin to publish sensed data. We call the publish method of the middleware each time a sensor change is detected:

public void onSensorChanged(SensorEvent event) {
    Bundle serviceDescriptor = SERVICE_DESCRIPTORS.get(event.sensor.getType()).second;
    String topic = serviceDescriptor.getString("contextBusTopic");
 
    // build payload
    JSONObject payload = new JSONObject();
    try {
	payload.put("sensor_id", serviceDescriptor.getString("id"));
	payload.put("timestamp", event.timestamp);
	JSONArray values = new JSONArray();
	JSONObject array_value = new JSONObject();
	array_value.put("x", event.values[0]);
	array_value.put("y", event.values[1]);
	array_value.put("z", event.values[2]);
	values.put(array_value);
	payload.put("values", values);
    } catch (JSONException e) {
        return;
    }
 
    // publish message
    try {
	middleware.publish(topic, payload.toString(), false, errorCallbackImpl);
    } catch (RemoteException e) {
	Log.e(TAG, "cannot publish");
    }
}

When we close our application it is mandatory to remove announced sensors from the service bus (for sake of consistency in the GiraffPlus ecosystem). This is done when we disconnect from service in the onServiceDisconnected method, when we call the onServiceDisconnected method:

public void finalize() {
    try {
	remove();
	unregister();
    } catch (RemoteException e) {
	Log.e(TAG, "cannot remove");
    }
}

private void remove() throws RemoteException {
    for (int i = 0; i < SERVICE_DESCRIPTORS.size(); i++) {
	Bundle serviceDescriptor = SERVICE_DESCRIPTORS.get(SERVICE_DESCRIPTORS.keyAt(i)).second;
	middleware.remove(serviceDescriptor, errorCallbackImpl);
    }
}

private void unregister() {
    sensorManager.unregisterListener(this);
}