Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
249 lines (186 sloc) 9.02 KB

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"):

  • SERVICE_STARTED - APRSdroid's tracking service was launched
  • SERVICE_STOPPED - APRSdroid's tracking service was terminated
  • POSITION - an incoming/outgoing position packet (user, object or item)
  • MESSAGE - text messages received by APRSdroid
  • MESSAGETX - text messages sent by APRSdroid
  • UPDATE - any text added to APRSdroid's log, including raw packets

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

  • SERVICE - start APRSdroid's tracking service
  • ONCE - send one position packet and stop
  • SERVICE_STOP - stop APRSdroid's tracking service
  • SEND_PACKET - send a (raw) APRS packet
  • FREQUENCY - change the frequency announced in position packets (requires APRSdroid 1.4.1)

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:

  • "api_version" (int): the API version code implemented by the installed version of APRSdroid. This document corresponds to API version 1, changes / additions will lead to higher version numbers.
  • "callsign" (String): callsign and SSID of the APRSdroid user, in the format "N0CALL-5" or "N0CALL" (if no SSID was configured).

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:

  • "type" (int): the type of the log entry. Possible values:
    • 0: sent packet (generated by APRSdroid)
    • 1: info (APRSdroid's internal information message)
    • 2: error (something went wrong)
    • 3: incoming packet (received from APRS)
  • "status" (String): the text that was added to the log. For type 0 and 3 this is the full raw packet content, header and data.

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:

  • "source" (String): callsign of the sender (your own one for MESSAGETX)
  • "dest" (String): callsign of the receiver (might have a different SSID on incoming messages to your callsign)
  • "body" (String): content of the message

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:

  • "source" (String): callsign that sent this packet.
  • "callsign" (String): callsign for which the position event was sent (this is the object/item name for objects/items, and equals to "source" for regular position packets).
  • "location" (Location): the geo-coordinates of the position. This extra will have latitude, longitude, and time set. The accuracy fields is an approximation according to the original APRS position ambiguity. Bearing and speed will be set if they were present in the original packet.
  • "packet" (String): the raw packet that was parsed into this position report.

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 (do not use setData(), it doesn't work!):

  • data (String): raw packet payload

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:

  • frequency (String): the new frequency value, e.g. "438.750MHz", "145.500" or "" to disable, decimal separator must be a dot (".")

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:

  • Your location and the location of your peers
  • Your callsign and callsigns from all nearby stations
  • The content of APRS messages sent and received
  • Any other data sent and received by APRSdroid
  • The times when APRSdroid is active and in which configuration

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.

You can’t perform that action at this time.