[aprssig] What is a position report?
Iain R. Learmonth
irl at hambsd.org
Sat May 23 15:40:08 EDT 2020
Hi,
In attempting to write code that produces position reports for stations,
objects, and items I have ended up with some notes. They are far from
being complete but I'm already starting to find some contradictions and
perhaps some things that need changing now time has moved on.
In particular, I think there needs to be some application of Postel's
Law to the specs. We should determine what the correct thing is to send
now, and what things you might be expected to receive. We should also
consider what the correct thing to send might be in the future, and
prepare implementations for that change.
Items are not recommended in APRS 1.1, however this appears to be a
mistake according to an email from Bob that recommends only against the
compressed format for items, which I guess also applies to objects? So
it's not really clear if we should be avoiding compressed formats
everywhere.
There is also the Mic-E format, which I haven't looked at at all yet. I
wonder to what extent that can be treated as an extension to the APRS
specification rather than a core part of it. Would it be recommended to
implement Mic-E position reports over an uncompressed/compressed
position report?
Finally, has anyone worked on combining the spec addendums with the spec
to form a coherent document? The editing process for that would surely
work out some of the bugs. I might volunteer to do this if it has not
been done and there is support for such a thing.
My notes so far are attached. The references section at the end contains
all the documents that were drawn on in order to put together the notes
so far, but as you'll see there are still lots of holes.
Thanks,
Iain.
-------------- next part --------------
I.R. Learmonth
HamBSD
23 May 2020
APRS Entities
notes-hambsd-aprs-entities-00
Abstract
APRS entities include APRS stations, and any other physical or
conceptual object that has a geographical position. These notes
describe the data model for entities and formats for exchanging these
entities between APRS stations.
Note
This document forms part of a series of notes used for HamBSD
development. They are not intended to supercede the APRS
specifications. It is inappropriate to use this document as
reference material or to cite it as anything other than a secondary
source.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2
2. Entity Types . . . . . . . . . . . . . . . . . . . . . . . . 2
3. Entity Data Model . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Entity Source/Owner . . . . . . . . . . . . . . . . . . . 3
3.2. Entity Names . . . . . . . . . . . . . . . . . . . . . . 3
3.3. Entity Liveness . . . . . . . . . . . . . . . . . . . . . 4
3.4. Entity Timestamps . . . . . . . . . . . . . . . . . . . . 4
3.5. Entity Position . . . . . . . . . . . . . . . . . . . . . 4
3.6. Entity Symbol . . . . . . . . . . . . . . . . . . . . . . 4
3.7. Entity Extended Data . . . . . . . . . . . . . . . . . . 4
3.8. Entity Comment . . . . . . . . . . . . . . . . . . . . . 4
4. Entities Database . . . . . . . . . . . . . . . . . . . . . . 4
4.1. Entity Replacement . . . . . . . . . . . . . . . . . . . 4
4.2. Entity Ownership . . . . . . . . . . . . . . . . . . . . 5
4.3. Timestamping . . . . . . . . . . . . . . . . . . . . . . 5
5. Entity Reporting . . . . . . . . . . . . . . . . . . . . . . 5
5.1. Report Formats . . . . . . . . . . . . . . . . . . . . . 5
5.1.1. Base Entity Report Format . . . . . . . . . . . . . . 5
5.1.2. Station Report Formats . . . . . . . . . . . . . . . 6
5.1.3. Object Report Formats . . . . . . . . . . . . . . . . 6
5.1.4. Item Report Formats . . . . . . . . . . . . . . . . . 6
6. User Interface Considerations . . . . . . . . . . . . . . . . 6
Learmonth Informational [Page 1]
APRS Entities May 2020
7. Logging Considerations . . . . . . . . . . . . . . . . . . . 6
8. Security Considerations . . . . . . . . . . . . . . . . . . . 6
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6
9.1. Normative References . . . . . . . . . . . . . . . . . . 6
9.2. Informative References . . . . . . . . . . . . . . . . . 7
Appendix A. Summary of APRS Data Type Identifiers . . . . . . . 7
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction
APRS [APRS101] entities include APRS stations, and any other physical
or conceptual object that has a geographical position. These notes
describe the data model for entities and formats for exchanging these
entities between APRS stations.
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
2. Entity Types
APRS stations can report their own position and status. Any APRS
station can report the position and status of any APRS entity (e.g.
another station or a weather phenomenon). This is intended for
situations where the entity is not capable of reporting its own
position.
There are three types of entity defined:
Stations Stations are APRS entities that report their own positions.
Station reports MAY include a timestamp. Station reports also
include whether or not they support APRS messaging.
Objects Objects are APRS entities that have their positions reported
by another APRS station. Object reports include a timestamp.
Items Items are APRS entities that have their positions reported by
another APRS station. Item reports do not include a timestamp.
It is intended that inanimate things are reported as items, while
things that move are reported as that reported as objects.
The data model for stations, objects and items are identical
[aprs11-objects] however the format for reports differs.
Learmonth Informational [Page 2]
APRS Entities May 2020
3. Entity Data Model
* Source/Owner (Section 3.1)
* Name (Section 3.2)
* Liveness (Section 3.3)
* Timestamp (Section 3.4)
* Position (Section 3.5)
* Symbol (Section 3.6)
* Extended Data (Section 3.7)
* Comment (Section 3.8)
3.1. Entity Source/Owner
Every APRS entity will have an owner. For the case of APRS Stations,
the Station will own itself. For the case of Objects and Items, this
is the station that currently has reporting responsibility of the
Object or Item. Rules for ownership are detailed in Section 4.2.
3.2. Entity Names
Entities are distinguished from each other by having different names.
Stations, Objects and Items all share the same namespace
[aprs11-names]. Names MUST:
* start with an alpha-numeric ASCII codepoint
* contain only printable ASCII codepoints
* be at most 9 characters in length
Names are case-sensitive. When displaying names, or performing
equality checks, trailing spaces (ASCII codepoint 0x20) MUST be
stripped.
APRS station names when using AX.25 are restricted by the
requirements for AX.25 addresses [AX25], which allows only a strict
subset of the names allowed for APRS entities. Such station names:
* MUST begin with between 3 and 6 upper-case alpha and numeric ASCII
characters
Learmonth Informational [Page 3]
APRS Entities May 2020
* MAY be followed by an SSID consisting of:
- a dash (ASCII codepoint 0x2D)
- ASCII encoding of a value between 1 and 15
For non-AX.25 APRS stations, e.g. APRS-IS stations, the futher
restrictions to station names do not apply. There is no reason
according to the specification that use of a non-AX.25 valid station
name would prevent two-way communication between stations, however it
is possible that specific implementations would handle this case
badly. It is therefore RECOMMENDED that only AX.25 valid names are
used for APRS stations supporting APRS messaging.
3.3. Entity Liveness
APRS entities are either "live" or "killed".
3.4. Entity Timestamps
All APRS entities have an associated timestamp to indicate the
freshness of their position report. Some reports do not carry a
timestamp and must be timestamped on receipt [aprs11-timestamps].
More details on timestamps can be found in Section 4.3.
3.5. Entity Position
XXX: Latitude, longitude, altitude
XXX: Null position
3.6. Entity Symbol
3.7. Entity Extended Data
3.8. Entity Comment
4. Entities Database
An APRS station MAY maintain a database of APRS entities.
4.1. Entity Replacement
[aprs12-perm]
XXX: killed objects
Learmonth Informational [Page 4]
APRS Entities May 2020
An Entity MUST only be killed by the owner of that Entity
[aprs11-objects].
4.2. Entity Ownership
Any APRS Station may take reporting responsibility for an entity, by
simply transmitting a report with the entity's name. The report may
specify the existing location or a new location. If another station
had previously taken responsibility for reporting an entity, the
original station will cease transmitting reports when it sees an
incoming report with the same name from another station.
An APRS Station is always responsible for itself. A Station is
converted to an Object or Item, however, when another Station reports
an Object or Item with the same name. In this case, a Station MAY
continue to report itself as a Station instead of relinquishing
ownership.
If ownership of an Object or Item has been relinquished, but a
Station has an updated report, it MAY resume ownership of the Object
or Item to send that report.
4.3. Timestamping
APRS is a real-time tactical communications system. When reports are
received without a timestamp, they should be assumed to be in real-
time and should be timestamped upon receipt.
If a report format that does include a time stamp is used, then that
time stamp must be honored as the time when that data was valid,
regardles of time of receipt [aprs11-timestamps].
5. Entity Reporting
5.1. Report Formats
This section describes the format for uncompressed reports. The use
of compressed reports is NOT RECOMMENDED due to incompatibilities
with existing hardware [aprssig-objitem].
5.1.1. Base Entity Report Format
All Entity Reports consist of the same base report format:
Learmonth Informational [Page 5]
APRS Entities May 2020
+----------------+--------------+--------------+
| Field | Size (Bytes) | Example Data |
+================+==============+==============+
| Latitude | 8 | 5709.88N |
+----------------+--------------+--------------+
| Symbol Table | 1 | / |
+----------------+--------------+--------------+
| Longitude | 9 | 00209.67W |
+----------------+--------------+--------------+
| Symbol Code | 1 | * |
+----------------+--------------+--------------+
| Data Extension | 0 or 7 | 088/036 |
+----------------+--------------+--------------+
| Comment | 0 or more | Hello |
+----------------+--------------+--------------+
Table 1
The example data in this table represents an entity at 57 deg 9.88' N
2 deg 9.67' W with a course of 88 deg travelling at 36 knots. It has
the snowmobile symbol and comment text "Hello".
5.1.2. Station Report Formats
5.1.3. Object Report Formats
5.1.4. Item Report Formats
6. User Interface Considerations
When an APRS Object/Item is displayed in a map or table view, the
callsign of the station sending the report should be associated with
the Object/Item.
7. Logging Considerations
APRS Stations that record raw logs of received packets SHOULD
timestamp all packets as many do not contain timestamp information
[aprs11-timestamps].
8. Security Considerations
Requires considering.
9. References
9.1. Normative References
Learmonth Informational [Page 6]
APRS Entities May 2020
[APRS101] The APRS Working Group and I. Wade, Ed., "APRS Protocol
Reference Version 1.0.1", ISBN 0-9644707-6-4, TAPR
Publication Number 99-4, 29 August 2000,
<http://www.aprs.org/doc/APRS101.PDF>.
[aprs11-names]
Bruninga, B., "APRS Object Names and Callsign Equality",
25 April 2016,
<http://www.aprs.org/aprs11/aprs-names-and-spaces.txt>.
[aprs11-objects]
Bruninga, B., "Amplifying Comments About Objects In APRS",
<http://www.aprs.org/aprs11/Objects.txt>.
[aprs11-timestamps]
Bruninga, B., "APRS Time Stamps", 12 February 2004,
<http://www.aprs.org/aprs11/timestamps.txt>.
[aprs12-perm]
Bruninga, B., "Object Name Permanence", 10 December 2014,
<http://www.aprs.org/info/object-perm.txt>.
[aprssig-objitem]
Bruninga, B., "[aprssig] Difference between Objects and
Items?", 3 February 2007,
<http://lists.tapr.org/pipermail/
aprssig_lists.tapr.org/2014-December/043870.html>.
[AX25] Beech, W.A., Nielsen, D.E., Taylor, J., and L. Knoper,
Ed., "AX.25 Link Access Protocol for Amateur Packet
Radio", July 1998,
<https://www.tapr.org/pdf/AX25.2.2.pdf>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
9.2. Informative References
Appendix A. Summary of APRS Data Type Identifiers
The following APRS Data Type Identifiers are used:
Learmonth Informational [Page 7]
APRS Entities May 2020
+-----+-----------------+----------------------------------+
| DTI | ASCII codepoint | Description |
+=====+=================+==================================+
| = | 0x3D | Station Report without Timestamp |
| | | (Message Capable) Section 5.1.2 |
+-----+-----------------+----------------------------------+
| @ | 0x40 | Station Report with Timestamp |
| | | (Message Capable) Section 5.1.2 |
+-----+-----------------+----------------------------------+
| ! | 0x21 | Station Report without Timestamp |
| | | (No Messaging) Section 5.1.2 |
+-----+-----------------+----------------------------------+
| / | 0x2F | Station Report with Timestamp |
| | | (No Messaging) Section 5.1.2 |
+-----+-----------------+----------------------------------+
| ; | 0x3B | Object Reports Section 5.1.3 |
+-----+-----------------+----------------------------------+
| ) | 0x29 | Item Reports Section 5.1.4 |
+-----+-----------------+----------------------------------+
Table 2
Author's Address
Iain R. Learmonth
HamBSD
United Kingdom
Email: irl at hambsd.org
Learmonth Informational [Page 8]
More information about the aprssig
mailing list