Implement an Android ASAP application

• Intro
• Concepts: Service and application side
• Setup
• ASAPActivity
  • Access ASAPPeer interface
  • Layer 2 Protocols

Start with Java

We strongly suggest to implement you application logic as free as possible from Android. In any case, read the Implement an ASAP application before you go on with Android. It is not long. Have look.

This documentation assumes that your ASAP related code is implemented and tested with Java and you plan to run use it on Android.

Concept of this lib: service and application side

This library has two major components: There is a service in which an ASAPPeer runs. The service tries to (re-)created ad-hoc connections whenever possible and granted. ASAP sessions are performed in that service. You do not have to care about this service at all. We call it service side.

You implement an Android application. That is what we call the application side. Both side communicate with messages (application to service side) and broadcasts (service to application side). You will not get in contact with any of these details but on one occasions: When you setup your application. Afterwards, you will not be bothered with any details of ASAP or layer 2 protocols. Your Java code will work without any change if you used the interfaces explained in Implement an ASAP application.

Setup

You have already learned about the ASAPPeer interface and its usage. We now explain how to setup the system and how to get an object that implements ASAPPeer.

There is one ASAP peer running in the service. This peer requires two parameters to be constructed: A list of supported formats and a name. The format parameter is discussed here. A unique name can be produced by calling ASAP.createUniqueID().

The setup process must be performed in two steps: 1. The library is initialized with required parameters 2. The library is started: The service is launched and within the ASAP peer.

There are two classes on application side which handle communication with service side: ASAPActivity and ASAPAndroidPeer. You will deal with the later only during setup. You need to derive any of your activity from ASAPActivity if you want to use ASAP, though.

There seams to be a chicken-egg-problem: An activity is required to setup the ASAPAndroidPeer. Each ASAPActivity (and derived classes) can only be created after an ASAPAndroidPeer has successfully been set up. The solution is very simple: There must be an initial activity that does not derive from ASAPActivity which sets up the systems. Afterwards it launches another activity.

Follow this rule of thumb: Derive any of your activities from ASAPActivity but this initial one. Here is an example of such an initial activity.

public class ASAPInitialExampleActivity extends AppCompatActivity {
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        try {
            // step 1: initialize ASAP peer (application side)
            if(!ASAPAndroidPeer.peerInitialized()) {
                Collection<CharSequence> formats = new ArrayList<>();
                formats.add(ExampleAppDefinitions.ASAP_EXAMPLE_APPNAME);
                // generate a name for this peer
                String peerName = ASAP.createUniqueID();
                ASAPAndroidPeer.initializePeer(peerName, formats, this);
            }

            // step 2: launch whole system (and ASAP peer service side)
            if(!ASAPAndroidPeer.peerStarted()) {
                ASAPAndroidPeer.startPeer();
            }
        } catch (IOException | ASAPException e) {
            e.printStackTrace();
        }

        // launch real first activity
        this.finish();
        Intent intent = new Intent(this, ASAPExampleActivity.class);
        this.startActivity(intent);
    }
}

See also ASAPInitialExampleActivity.

There are no surprises in the code. A collection of supported formats is created. A single format is added in this example (ASAP_EXAMPLE_APPNAME). A unique id is created which serves as peer name. There are better ways. Users might better choose their own name and you store it with e.g. shared preferences for later usage. That is all we need to initialize the ASAPAndroidPeer.

Do not forget to start the system by calling ASAPAndroidPeer.startPeer(). Finally, this initial activity terminates itself and launches another activity: ASAPExampleActivity.

That’s it. ASAPExampleActivity derives from ASAPActivity but requires no further code.

ASAPActivity

Follow this rule of thumb: Derive any of your activities from ASAPActivity but the initial one, see setup.

No more code is required. Ensure that all life cycle methods are also called on ASAPActivity. In other words: Do not forget to call e.g. super.doStart() if you overwrite this method.

Access ASAPPeer interface

The most important method from ASAP application perspective is this one:

public class ASAPExampleActivity extends ASAPActivity { ... 
    ...
    // somewhere in your code
    ASAPPeer asapPeer = this.getASAPPeer();
    // now you have got an object reference to ASAPPeer
}

Now, you have an object that implements ASAPPeer. You could work with it as described in Implement an ASAP application

Layer 2 Protocols

This library support Bluetooth and it is going to support Wifi-direct and LoRa.

Protocol management is simple.

public class ASAPExampleActivity extends ASAPActivity { ... 
    ...
    // somewhere in your code
    this.startBluetooth(); // starts bluetooth
    this.stopBluetooth(); // stops bluetooth

    // for paring
    this.startBluetoothDiscoverable(); // device becomes discoverable for a while
    this.startBluetoothDiscovery(); // device tries to discover other BT devices 

    // we work on this
    this.startWifiP2P(); // wifi-direct 
    this.stopWifiP2P();
    this.startLoRa(); // Long range wifi
    this.stopLoRa();
}