APRSdroid Inter-App API

This document describes how Android applications can interact with APRSdroid. If you are an app developer aiming to do interesting things with APRS, this is for you.

Features

APRSdroid exposes the following data via broadcast Intents ("events"):

Furthermore, it is possible to influence APRSdroid with the following Intents ("actions"):

All uppercase strings mentioned in this document are suffixes to "org.aprsdroid.app." and need to be concatenated for the effective Intent action names.

If you want to write a third-party app that is using APRSdroid's service, the recommended way is to make a service that listens to APRSdroid's SERVICE_STARTED event, launches its own service with the according configuration, sends and receives packets within that service, and terminates when a SERVICE_STOPPED event is received. That way, all installed third party applications can be launched automatically together with APRSdroid. You can use your own application's main activity to configure (and optionally disable) your add-on.

Events - Getting Data from APRSdroid

APRSdroid will inform applications using a broadcast Intent about all relevant status changes. You need to register a BroadcastReceiver that will process APRSdroid's events, either in your app's manifest or using the registerReceiver code.

<!-- AndroidManifest.xml example to get a service started on
     APRSdroid intents -->
<receiver android:name=".APRSdroidEventReceiver">
    <intent-filter>
       <action android:name="org.aprsdroid.app.SERVICE_STARTED" />
       <action android:name="org.aprsdroid.app.SERVICE_STOPPED" />
    </intent-filter>
</receiver>

Example code to listen for broadcasts:

public class APRSdroidEventReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (!intent.getAction().startsWith("org.aprsdroid.app"))
            return;
        String a = intent.getAction().replace("org.aprsdroid.app.", "");
        switch (a) {
        case "SERVICE_STARTED":
            aprsdroid_running = true;
            break;
        case "SERVICE_STOPPED":
            aprsdroid_running = false;
            break;
        case "MESSAGE":
            String source = intent.getStringExtra("source");
            String message = intent.getStringExtra("body");
            Log.d("APRS Event", "message from " + source + ": " + body);
            break;
        case "POSITION":
            String callsign = intent.getStringExtra("callsign");
            Location location = intent.getParcelableExtra("location");
            Log.d("APRS Event", callsign + " position: " + location);
            break;
        }
    }
}

SERVICE_STARTED

This event will be triggered whenever APRSdroid's service is started and successfully connects to the backend. After this event, it should be safe to send out packets. Please note that packet delivery can not be guaranteed despite all efforts.

Intent extras:

SERVICE_STOPPED

This event will be triggered when APRSdroid's service terminates. It is not guaranteed to be called (i.e. when the app is force-closed, the event will not be triggered).

UPDATE

The UPDATE event comes with the following extras:

MESSAGE / MESSAGETX

When the user sends a message or when a new message is received, the MESSAGETX / MESSAGE events are fired. They are not fired for retransmissions of outgoing messages, and neither for incoming ACKs / REJs.

Both event types have the following extras:

POSITION

A POSITION event is triggered every time when a position packet is decoded (station, item or object) or transmitted. It contains the following extras:

Actions - Influencing APRSdroid

Generic Intent Construction

To influence APRSdroid, you need to create an Intent with a string action starting with "org.aprsdroid.app.", followed by the uppercase action name. The intent should have additional parameters according to the action description, and must be delivered using startService.

The individual actions are described in the following.

SERVICE / ONCE

Start the APRSdroid tracking service for an indeterminate runtime (SERVICE) or for one position transmission (ONCE).

// launch APRSdroid tracker
Intent i = new Intent("org.aprsdroid.app.SERVICE").setPackage("org.aprsdroid.app");
startService(i);

SERVICE_STOP

Stop the tracking service.

// stop APRSdroid tracker
Intent i = new Intent("org.aprsdroid.app.SERVICE_STOP").setPackage("org.aprsdroid.app");
startService(i);

SEND_PACKET

Send a raw APRS packet via the (already running) APRSdroid service. Only the packet payload needs to be configured, APRSdroid will automatically complete the header (your callsign and the ARPS path) from its configuration.

Intent extras:

Example for sending a raw status packet:

// send raw status packet
Intent i = new Intent("org.aprsdroid.app.SEND_PACKET").setPackage("org.aprsdroid.app");
i.putExtra("data", ">third-party APRS status app");
startService(i);

FREQUENCY (APRSdroid 1.4.1)

Update the frequency field in the position reports sent by APRSdroid. If the APRSdroid service is running, this will immediately generate a position packet with the new frequency.

Intent extras:

Example for updating the frequency:

// send raw status packet
Intent i = new Intent("org.aprsdroid.app.FREQUENCY").setPackage("org.aprsdroid.app");
i.putExtra("frequency", "438.750");
startService(i);

Invocation from the adb shell:

am startservice -a org.aprsdroid.app.FREQUENCY -e frequency "438.750"

(In-)Security

Currently, APRSdroid exposes the following personal information via global broadcast to all applications:

As APRS (and ham radio in general) is considered public information, access to this data is not limited in any way. A future version of APRSdroid might require third-party apps to have the "Access Fine Location" permission.

APRSdroid can be influenced by third-party applications, in that they can start the service, stop it, and send unlimited amounts of data packets (over the air) in your name.

A future version of APRSdroid will display an API key in its preferences, which must be entered into third-party apps and supplied in the Intents sent to APRSdroid.