kopia lustrzana https://github.com/ge0rg/aprsdroid
249 wiersze
9.0 KiB
Markdown
249 wiersze
9.0 KiB
Markdown
# APRSdroid Inter-App API
|
|
|
|
This document describes how Android applications can interact with
|
|
[APRSdroid](https://aprsdroid.org/). 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](https://developer.android.com/reference/android/content/BroadcastReceiver.html)
|
|
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](https://developer.android.com/reference/android/location/Location.html)):
|
|
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](https://developer.android.com/reference/android/content/Context.html#startService(android.content.Intent)).
|
|
|
|
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:
|
|
|
|
* `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](http://www.aprs.org/info/freqspec.txt) 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.**
|