How to write your own Amarino Plug-In

tl_files/images/screenshots/3activeEvents.png

Amarino 2.0 introduces a new plug-in concept allowing third-party developers to extend Amarino's event list.

In order to send data from your phone to your Arduino, you would add one or more events to a certain Bluetooth device. This is done by selecting "Add event" within the event management module. The list which shows up is a list of all available events on your phone. This list can easily be extended by installing new plug-ins on your phone. Each plug-in corresponds to at least one event.

On the Amarino website you find the Amarino Plug-in Bundle. By installing the Bundle, it adds more than 10 events to that event list. These events cover most of todays available sensors on modern handsets (compass, lightsensor, etc.).

Amarino's framework will provide you a convenient way to integrate your own events (plug-ins) into Amarino. Means you can extend the event list by developing an Amarino plug-in.

Detailed description of how to develop your own plug-in

So if you want to send data from your phone to Arduino you have basically two choices:

  • Send data using your very own application utilizing Amarino's library functions like Amarino.sendDataToArduino(...) or
  • Build a plug-in which integrates nicely with Amarino.

A plug-in is always a background service, and can never be a foreground application. If you need users to interact with your phone's touchscreen or keyboard, then a plug-in is not the right choice. Plug-ins are ideal if you like to do background stuff, like reading sensor data, location-based services or querying the internet.

The Amarino Plug-in Bundle provides already plug-ins for most sensors available on modern handsets. However, you might want to write your own plug-in to have more control of how data are sent, or you might want to pre-process data on your phone before you hand them over to your Arduino. Either way, writing a plug-in is fun and once you see your own plug-in appearing in Amarino's event list, I am sure you will be happy.

Okay, so let's start.
  1. First download the AmarinoPluginSkeleton project.
  2. Building your plug-in upon this skeleton project is much easier than developing it from scratch. This section describes in detail how you can develop your own plug-in based on this prepared eclipse project skeleton. In this tutorial we are going to build a time plug-in which sends the actual time to Arduino. I know you won't win a innovation price with a time plug-in but let's keep complexity low at the beginning. Once you know how to build a plug-in on your own you can get all your crazy ideas out into the wild.

  3. To start with, import the downloaded project into your Eclipse workspace (General->Existing Projects into Workspace). Next you should rename the imported AmarinoPluginSkeleton project to a name describing your plug-in. Surprise, we call our project AmarinoPluginTime (select the project and hit F2 to rename)
  4. Renaming is not done yet. We have to rename the package, too. In your Package Explorer open the folder src and you will see the package at.abraxas.amarino.plugin.skeleton. Select it, again hit F2 and give your package a new name, let's call it earth.amarino.plugin.time.
  5. Still not done yet, the AndroidManifest.xml file got a red mark, telling us there is something wrong with it. Open the manifest file and change also the package name to earth.amarino.plugin.time. Save it and the red mark magically disapears.
  6. Oh no, what's that. Two more red marks within the renamed package. Don't worry we'll fix this immediately. Open the package and you'll see that two classes are affected, EditActivity.java and MyEditActivity.java. Open up each file and hit CTRL-SHIFT-o. This will correct the import statements to match our new package name. (Remember the CTRL-SHIFT-o shortcut, it comes in quite handy when you develop on Eclipse.) Save and the red marks should vanish quickly.
  7. Puh! First huge step done. Great!

    That was hard, wasn't it? But believe me, once you are used to it, this is a matter of seconds. But the first time, I know, it seems to be complicated. When you create your own plug-in, repeat these renaming steps and rename the skeleton project to whatever you think is best describing your plugin.

    And here we go. This is where we can start putting some code together.

    Each plug-in has a description and a name which will be shown to the user when he/she is about to add that plug-in to a device in Amarino. So we have to give our project a nice name and a little descripton of what it does and which kind of data it is going to send.

  8. Open the string.xml file (find it in folder res->values). Change the string app_name, plugin_name and plugin_desc so that it looks like the snippet below.
  9.  
    <!-- General -->
    <string name="app_name">AmarinoPluginTime</string>
    <string name="plugin_name">Time</string>
    <string name="plugin_desc">
    Sends every second the actual time as an int array {h,m,s}</string>
    <string name="service_class_name">MyBackgroundService</string>
    
    Save string.xml and close it.

    There are two important classes which we need to change for our need, MyEditActivity.java and MyBackgroundService.java.

    • MyEditActivity.java defines the configuration Activity (in Android they call a UI an Activity, since it requires the user to do something) shown to the user when he/she selects your plug-in in Amarino. I pretty am sure you saw that configuration activity before, when you played around with Amarino and its PluginBundles.
    • The MyBackgroundService.java class however defines what your plug-in does once it is activated. In our case, the MyBackgroundService.java class will every second send the actual time to Arduino.

  10. We start with MyEditActivity.java because we don't have to do much there. Normally, we could implement a drop-down box that a user selects to alter the frequency of how often the time should be sent (1 sec, 5 sec, 30 sec), but for now we don't let her/him choose anything. Means the configuration screen will just show the name and the descritpion of our time plug-in (and a visualizer dropdown box). I uploaded a special version of the Amarino time plug-in, AmarinoPluginTimeConfigurable.zip (coming soon), with this configuration function added. If you have to write a more configurable plug-in, look at the example code to see how its done. All we do in this tutorial is change the visualizer bounds to values we are about to send. The lowest value we will send is 0 and the highest will be 59. All other values will be in between that range. So change the parameters of the setVisualizerBounds method in onSaveBtnClick(View v) to
    setVisualizerBounds(0, 59);
    In Amarino you saw that data sent from plug-ins are visualized in real-time. In the configuration screen a user can select between different visualizers. Graph and Bars for example need to know which data to expect. So that is why we have to set visualizer boundaries. That said, we are done in MyEditActivity.java. Let's head over to MyBackgroundService.java.
  11. In MyBackgroundService.java, all the hard work of your plug-in is done. If a user has added your plug-in to a certain Bluetooth device and he/she hits the connect button of that device, Amarino takes care of starting your BackgroundService immediately. It respectively stops it when the user hits disconnect. You find two methods in MyBackgroundService.java, one is called init() and the other is called cleanup(). When Amarino starts your plug-in it will call init(), when it stops it, Amarino calls cleanup(). Our strategy is to start a timer in init() which sends the current time every second. In cleanup() we stop our timer.

    In Android there is a nice class called Timer which will take care of executing a TimerTask periodically. We are going to use these Android SDK classes to build our time plug-in.

  12. Add two new instance variables to your BackgroundService directly under the line private static final boolean DEBUG = true;
     
    private Timer timer;
    private TimerTask task = new TimerTask(){
    
      @Override
      public void run() {
        Date now = new Date();
        int[] data = { now.getHours(), now.getMinutes(), now.getSeconds() };
    
        // we want to see the data in our logcat terminal
        if (DEGUG) 
          Log.d(TAG, "h:m:s - " + data[0] + ":" + data[1] + ":" + data[2]);
    	
        Amarino.sendDataFromPlugin(MyBackgroundService.this, pluginId, data);
       }
    };
    
    The TimerTask declares an abstract method public void run() which needs to be overwritten in order to define what our TimerTask should do once it is called. This is where we retrieve the current time, put it into an array and use the static method Amarino.sendDataFromPlugin(MyBackgroundService.this, pluginId, data) to send the data to Amarino, which in turn will forward the data to Arduino.
  13. In init() all we do is creating the timer instance by calling
    timer = new Timer();
    
    and then we start the timer invoking its scheduling method
    timer.scheduleAtFixedRate(task, 1000, 1000);
    
    don't forget to return true at the end of your init() method, to indicate Amarino that the initialization was successful.
    return true;
    
  14. In cleanup() we simply write
    timer.cancel();
    
    to stop our timer from beeing executed again, once the plug-in has been disabled.
Okay that's it. Congratulations!!!
The time plug-in is considered finished. Install it on your Android phone, start Amarino and see if your plug-in works as expected.

You can also download the completed source code to this tutorial (AmarinoPluginTime.zip)

Android is a trademark of Google Inc. Use of this trademark is subject to Google Permissions.