kopia lustrzana https://github.com/ge0rg/aprsdroid
224 wiersze
8.1 KiB
Plaintext
224 wiersze
8.1 KiB
Plaintext
![]() |
# 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
|
||
|
* `SERVICE.ONCE` - send one position packet and stop
|
||
|
* `SERVICE_STOP` - stop APRSdroid's tracking service
|
||
|
* `SEND_PACKET` - send a (raw) APRS packet
|
||
|
|
||
|
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 / SERVICE.ONCE
|
||
|
|
||
|
Start the APRSdroid tracking service for an indeterminate runtime
|
||
|
(`SERVICE`) or for one position transmission (`SERVICE.ONCE`).
|
||
|
|
||
|
// launch APRSdroid tracker
|
||
|
Intent i = new Intent("org.aprsdroid.app.SERVICE");
|
||
|
startService(i);
|
||
|
|
||
|
### SERVICE_STOP
|
||
|
|
||
|
Stop the tracking service.
|
||
|
|
||
|
// stop APRSdroid tracker
|
||
|
Intent i = new Intent("org.aprsdroid.app.SERVICE_STOP");
|
||
|
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");
|
||
|
i.putExtra("data", ">third-party APRS status app");
|
||
|
startService(i);
|
||
|
|
||
|
## (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.**
|