@tak-ps/node-cot 7.1.0 → 7.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +4 -0
- package/dist/package.json +2 -2
- package/dist/proto/contact.proto +14 -0
- package/dist/proto/cotevent.proto +44 -0
- package/dist/proto/detail.proto +78 -0
- package/dist/proto/group.proto +13 -0
- package/dist/proto/precisionlocation.proto +13 -0
- package/dist/proto/protocol.txt +352 -0
- package/dist/proto/status.proto +12 -0
- package/dist/proto/takcontrol.proto +24 -0
- package/dist/proto/takmessage.proto +18 -0
- package/dist/proto/takv.proto +15 -0
- package/dist/proto/track.proto +13 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
package/dist/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tak-ps/node-cot",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "7.1
|
|
4
|
+
"version": "7.2.1",
|
|
5
5
|
"description": "Lightweight JavaScript library for parsing and manipulating TAK messages",
|
|
6
6
|
"author": "Nick Ingalls <nick@ingalls.ca>",
|
|
7
7
|
"main": "dist/index.js",
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
"test": "ts-node-test test/",
|
|
11
11
|
"lint": "eslint *.ts lib/*.ts test/*.ts",
|
|
12
12
|
"doc": "typedoc index.ts",
|
|
13
|
-
"build": "tsc --build && cp package.json dist/",
|
|
13
|
+
"build": "tsc --build && cp package.json dist/ && mkdir -p ./dist/proto/ && cp lib/proto/* ./dist/proto/",
|
|
14
14
|
"pretest": "npm run lint"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// All items are required unless otherwise noted!
|
|
7
|
+
// "required" means if they are missing on send, the conversion
|
|
8
|
+
// to the message format will be rejected and fall back to opaque
|
|
9
|
+
// XML representation
|
|
10
|
+
message Contact {
|
|
11
|
+
// Endpoint is optional; if missing/empty do not populate.
|
|
12
|
+
string endpoint = 1; // endpoint=
|
|
13
|
+
string callsign = 2; // callsign=
|
|
14
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
|
|
3
|
+
option optimize_for = LITE_RUNTIME;
|
|
4
|
+
|
|
5
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
6
|
+
|
|
7
|
+
import "detail.proto";
|
|
8
|
+
|
|
9
|
+
// A note about timestamps:
|
|
10
|
+
// Uses "timeMs" units, which is number of milliseconds since
|
|
11
|
+
// 1970-01-01 00:00:00 UTC
|
|
12
|
+
//
|
|
13
|
+
// All items are required unless otherwise noted!
|
|
14
|
+
// "required" means if they are missing in the XML during outbound
|
|
15
|
+
// conversion to protobuf, the message will be
|
|
16
|
+
// rejected
|
|
17
|
+
message CotEvent {
|
|
18
|
+
// <event>
|
|
19
|
+
|
|
20
|
+
string type = 1; // <event type="x">
|
|
21
|
+
|
|
22
|
+
string access = 2; // optional
|
|
23
|
+
string qos = 3; // optional
|
|
24
|
+
string opex = 4; // optional
|
|
25
|
+
|
|
26
|
+
string uid = 5; // <event uid="x">
|
|
27
|
+
uint64 sendTime = 6; // <event time="x"> converted to timeMs
|
|
28
|
+
uint64 startTime = 7; // <event start="x"> converted to timeMs
|
|
29
|
+
uint64 staleTime = 8; // <event stale="x"> converted to timeMs
|
|
30
|
+
string how = 9; // <event how="x">
|
|
31
|
+
|
|
32
|
+
// <point>
|
|
33
|
+
double lat = 10; // <point lat="x">
|
|
34
|
+
double lon = 11; // <point lon="x">
|
|
35
|
+
double hae = 12; // <point hae="x"> use 999999 for unknown
|
|
36
|
+
double ce = 13; // <point ce="x"> use 999999 for unknown
|
|
37
|
+
double le = 14; // <point ce="x"> use 999999 for unknown
|
|
38
|
+
|
|
39
|
+
// comprises children of <detail>
|
|
40
|
+
// This is optional - if omitted, then the cot message
|
|
41
|
+
// had no data under <detail>
|
|
42
|
+
Detail detail = 15;
|
|
43
|
+
}
|
|
44
|
+
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
import "contact.proto";
|
|
7
|
+
import "group.proto";
|
|
8
|
+
import "precisionlocation.proto";
|
|
9
|
+
import "status.proto";
|
|
10
|
+
import "takv.proto";
|
|
11
|
+
import "track.proto";
|
|
12
|
+
|
|
13
|
+
// CotEvent detail
|
|
14
|
+
// The strong typed message fields are optional. If used, they *MUST* adhere
|
|
15
|
+
// to the requirements of the message (see their proto file) and
|
|
16
|
+
// their XML source element used to populate the message MUST
|
|
17
|
+
// be omitted from the xmlDetail.
|
|
18
|
+
// WHOLE ELEMENTS MUST BE CONVERTED TO MESSAGES. Do not try to
|
|
19
|
+
// put part of the data from a given element into one of the messages
|
|
20
|
+
// and put other parts of the data in an element of xmlDetail! This applies
|
|
21
|
+
// especially if you add new things to the XML representation which do not
|
|
22
|
+
// have a place in the equivalent protobuf message. Instead, omit the
|
|
23
|
+
// message and put the entire element in xmlDetail!
|
|
24
|
+
//
|
|
25
|
+
// xmlDetail is optional. If omitted, all Detail data has been
|
|
26
|
+
// converted to the strongly typed message fields.
|
|
27
|
+
// If present, this contains any remaining detail data that has NOT been
|
|
28
|
+
// included in one of the strongly typed message fields. To process the
|
|
29
|
+
// xmlDetail, the following rules MUST be followed:
|
|
30
|
+
// Senders of this message MUST:
|
|
31
|
+
// 1. Remove child elements used to populate the other message
|
|
32
|
+
// fields. If the same child element appears more times than an
|
|
33
|
+
// associated message field(s) is intended to encompass, or if any
|
|
34
|
+
// error occurs mapping to the message equivalent, do not remove
|
|
35
|
+
// the element(s) in question and do not populate the message
|
|
36
|
+
// equivalent.
|
|
37
|
+
// 2. If no data under <detail> remains, STOP - do not populate
|
|
38
|
+
// xmlDetail
|
|
39
|
+
// 3. Serialize the remaining XML tree under <detail>....</detail>
|
|
40
|
+
// as XML in UTF-8 encoding
|
|
41
|
+
// 4. Remove the <detail> and </detail> element tags
|
|
42
|
+
// 5. Remove the XML header
|
|
43
|
+
// 6. Place the result in xmlDetail
|
|
44
|
+
// Receivers of this message MUST do the equivalent of the following:
|
|
45
|
+
// 1. If the field is not present (zero length), stop - do nothing
|
|
46
|
+
// 2. Prepend <detail> and append </detail>
|
|
47
|
+
// 3. Prepend an XML header for UTF-8 encoding, version 1.0
|
|
48
|
+
// (<?xml version="1.0" encoding="UTF-8"?> or similar)
|
|
49
|
+
// 4. Read the result, expecting a valid XML document with a document
|
|
50
|
+
// root of <detail>
|
|
51
|
+
// 5. Merge in XML equivalents of each of the strongly typed
|
|
52
|
+
// messages present in this Detail message.
|
|
53
|
+
// In the event that a sending application does not follow
|
|
54
|
+
// sending rule #1 above properly and data for the same element
|
|
55
|
+
// appears in xmlDetail, the data in xmlDetail should be left alone
|
|
56
|
+
// and the data in the equivalent message should ignored.
|
|
57
|
+
|
|
58
|
+
message Detail {
|
|
59
|
+
string xmlDetail = 1;
|
|
60
|
+
|
|
61
|
+
// <contact>
|
|
62
|
+
Contact contact = 2;
|
|
63
|
+
|
|
64
|
+
// <__group>
|
|
65
|
+
Group group = 3;
|
|
66
|
+
|
|
67
|
+
// <precisionlocation>
|
|
68
|
+
PrecisionLocation precisionLocation = 4;
|
|
69
|
+
|
|
70
|
+
// <status>
|
|
71
|
+
Status status = 5;
|
|
72
|
+
|
|
73
|
+
// <takv>
|
|
74
|
+
Takv takv = 6;
|
|
75
|
+
|
|
76
|
+
// <track>
|
|
77
|
+
Track track = 7;
|
|
78
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// All items are required unless otherwise noted!
|
|
7
|
+
// "required" means if they are missing on send, the conversion
|
|
8
|
+
// to the message format will be rejected and fall back to opaque
|
|
9
|
+
// XML representation
|
|
10
|
+
message Group {
|
|
11
|
+
string name = 1; // name=
|
|
12
|
+
string role = 2; // role=
|
|
13
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// All items are required unless otherwise noted!
|
|
7
|
+
// "required" means if they are missing on send, the conversion
|
|
8
|
+
// to the message format will be rejected and fall back to opaque
|
|
9
|
+
// XML representation
|
|
10
|
+
message PrecisionLocation {
|
|
11
|
+
string geopointsrc = 1; // geopointsrc=
|
|
12
|
+
string altsrc = 2; // altsrc=
|
|
13
|
+
}
|
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
*** Traditional Protocol - "Protocol Version 0"
|
|
2
|
+
|
|
3
|
+
Clients send and receive XML CoT <event> messages.
|
|
4
|
+
"Mesh" network participants announce via "SA" messages via UDP datagrams
|
|
5
|
+
over multicast to a well known address and port. Each UDP datagram contains
|
|
6
|
+
one (and only one) CoT XML message as its payload.
|
|
7
|
+
|
|
8
|
+
Messages directed only to specific network participants are send by making
|
|
9
|
+
TCP connection to the remote recipient, sending the CoT XML, then closing
|
|
10
|
+
the connection.
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
Streaming connections (to TAK servers) send the same XML-based CoT payloads
|
|
14
|
+
over TCP sockets. The TCP stream is comprised of one CoT <event> after
|
|
15
|
+
another. Messages are delimited and broken apart by searching for the token
|
|
16
|
+
"</event>" and breaking apart immediately after that token.
|
|
17
|
+
When sending, messages must be prefaced by XML header (<?xml ... ?>),
|
|
18
|
+
followed by a newline, followed by the complete XML <event>. TAK servers
|
|
19
|
+
require that no arbitrary newlines follow the </event> end of message and
|
|
20
|
+
that the next character immediate commences the next <?xml ... ?> header.
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
*** TAK Protocol - Design Goals
|
|
25
|
+
|
|
26
|
+
The goal of the new TAK Protocol design is to allow interoperation with
|
|
27
|
+
other legacy clients and TAK server, as well as to strongly identify
|
|
28
|
+
what rendition of communication will be used in a session. This is to allow
|
|
29
|
+
for future expansion or complete revision of the protocol while allowing
|
|
30
|
+
an opportunity to support mixed client versions (and varying versions of TAK
|
|
31
|
+
servers).
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
*** TAK Protocol - Ground Rules
|
|
35
|
+
|
|
36
|
+
All clients obey the following basic rules regardless of the version(s)
|
|
37
|
+
of TAK protocol that they support. These rules are important base rules
|
|
38
|
+
upon which the protocol version negotiations detailed in subsequent sections
|
|
39
|
+
rely:
|
|
40
|
+
|
|
41
|
+
1. A client sending TAK protocol version "V" is also capable of receiving
|
|
42
|
+
and decoding version "V"
|
|
43
|
+
2. All clients must support decoding TAK protocol version "0" (legacy XML)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
*** TAK Protocol - Generic Framework - Mesh Networks
|
|
47
|
+
|
|
48
|
+
Mesh networks broadcasts (SA announces, etc) will reuse the existing UDP
|
|
49
|
+
datagram-based networking already in place. Directed (unicasted) TCP
|
|
50
|
+
messages will reuse the existing connect, send 1 message, disconnect
|
|
51
|
+
networking.
|
|
52
|
+
|
|
53
|
+
For both TCP and UDP, instead of sending CoT as XML, clients will send data
|
|
54
|
+
packets whose payloads contain one message complying with the new "TAK
|
|
55
|
+
Protocol".
|
|
56
|
+
Both types of messages will utilize a data payload that begins with the "TAK
|
|
57
|
+
Protocol Header" followed by the "TAK Protocol Payload". The header
|
|
58
|
+
serves to self-identify as a TAK Protocol message, as well as indicate a
|
|
59
|
+
particular version number to which the subsequent Payload comforms.
|
|
60
|
+
|
|
61
|
+
TAK Protocol Message: <TAK Protocol Header> <TAK Protocol Payload>
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
The "TAK Protocol Header" is nothing more than a set of "magic numbers" to
|
|
65
|
+
identify the message header as such, and a version identifier to indicate
|
|
66
|
+
what TAK Protocol version the remainder of the payload is comprised of.
|
|
67
|
+
|
|
68
|
+
TAK Protocol Header: <magic byte> <tak protocol version> <magic byte>
|
|
69
|
+
Where....
|
|
70
|
+
<magic byte> is the single byte 0xbf
|
|
71
|
+
<tak protocol version> is the version number of the TAK Protocol the payload
|
|
72
|
+
in the remainder of the message conforms to. This is encoded as a "varint".
|
|
73
|
+
See "TAK Protocol Varint Encoding".
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
*** TAK Protocol - Generic Framework - Streaming Connections
|
|
78
|
+
|
|
79
|
+
Steaming connections (TAK server connections) use a different message style
|
|
80
|
+
as the repeating protocol version information in every message that is done
|
|
81
|
+
in mesh TAK Protocol Messages would be a waste of resources in the streaming
|
|
82
|
+
environment (since all messages will use the same Version).
|
|
83
|
+
The TAK Protocol Stream Message is instead defined to provide the length of
|
|
84
|
+
the streaming message (necessary to break apart the message from its
|
|
85
|
+
neighbors to avoid need to scan for special tokens).
|
|
86
|
+
|
|
87
|
+
In a streaming connection, "TAK Protocol Streaming Messages" are sent one
|
|
88
|
+
after another (with no intervening data) over the streaming connection.
|
|
89
|
+
|
|
90
|
+
TAK Protocol Stream Message:
|
|
91
|
+
<TAK Protocol Streaming Header> <TAK Protocol Payload>
|
|
92
|
+
|
|
93
|
+
Important to note here is that the "TAK Protocol Payload" is precisely the
|
|
94
|
+
same in form and content to that which is used for mesh network messages for
|
|
95
|
+
a given protocol version.
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
The "TAK Protocol Streaming Header" is as follows:
|
|
100
|
+
|
|
101
|
+
TAK Protocol Streaming Header:
|
|
102
|
+
<magic byte> <message length>
|
|
103
|
+
Where...
|
|
104
|
+
<magic byte> is the single byte 0xbf
|
|
105
|
+
<message length> is the number of bytes in the "TAK Protocol Payload" which
|
|
106
|
+
follows the header. This is encoded as a "varint".
|
|
107
|
+
|
|
108
|
+
As mentioned prior, the version identification for the message's payload
|
|
109
|
+
format is omitted from the streaming header. Protocol version negotiation
|
|
110
|
+
is expected to occur outside of core TAK Protocol message exchange.
|
|
111
|
+
See "Streaming Connection Protocol Negotiation".
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
*** TAK Protocol Payload - Version 1
|
|
117
|
+
|
|
118
|
+
Version 1 of the TAK Protocol Payload is a Google Protocol Buffer based
|
|
119
|
+
payload. Each Payload consists of one (and only one)
|
|
120
|
+
atakmap::commoncommo::v1::TakMessage message which is serialized using
|
|
121
|
+
Google protocol buffers version 3.
|
|
122
|
+
|
|
123
|
+
See the .proto files for more information on the specific messages and their
|
|
124
|
+
fields, as well as the mapping to/from CoT XML.
|
|
125
|
+
|
|
126
|
+
Revising the messages used by Version 1 may be done in accordance with the
|
|
127
|
+
following rules:
|
|
128
|
+
|
|
129
|
+
1. Additional message fields MAY be added to the end of existing messages
|
|
130
|
+
following normal google protobuf rules if and only if
|
|
131
|
+
ignorance of the new fields on decoding is 100% irrelevant to correct
|
|
132
|
+
semantic operation at the TAK application level of ALL TAK applications.
|
|
133
|
+
2. Otherwise, any and all changes must be tied to a protocol version change.
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
This version of TAK Protocol does not define any additional attributes to be
|
|
137
|
+
used during Streaming Connection Protocol Negotiation.
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
*** Streaming Connection Protocol Negotiation
|
|
142
|
+
|
|
143
|
+
TAK clients often connect to a variety of TAK servers, each of which may be
|
|
144
|
+
a different version of software capable of different versions of the TAK
|
|
145
|
+
Protocol (or indeed not capable of the TAK Protocol and simply only
|
|
146
|
+
supporting traditional streaming CoT as XML).
|
|
147
|
+
|
|
148
|
+
Because of the desire to allow operation of various client and server
|
|
149
|
+
versions, and the desire to keep the traditional XML encoding available, the
|
|
150
|
+
following negotiation is performed when connecting to a TAK server with a
|
|
151
|
+
client that supports the TAK Protocol.
|
|
152
|
+
|
|
153
|
+
1. Once the connection is established, client and server should expect to
|
|
154
|
+
exchange traditional CoT XML messages per "Traditional Protocol" section.
|
|
155
|
+
Note, however, if the server requires authentication, the auth XML message
|
|
156
|
+
MUST be the first message sent to the TAK server by the client.
|
|
157
|
+
Even if awaiting auth, the server MAY send CoT XML. Upon supplying an
|
|
158
|
+
auth message (when required), one of two things happens:
|
|
159
|
+
1a. If the server accepts the auth, proceed to 2.
|
|
160
|
+
1b. If the server denies the auth, the connection is closed.
|
|
161
|
+
2. Client and server continue to expect to exchange traditional
|
|
162
|
+
CoT XML messages per "Traditional Protocol" section.
|
|
163
|
+
3. A server which supports the TAK Protocol MAY send the following CoT XML
|
|
164
|
+
message to indicate this support (whitespace added, xml header omitted):
|
|
165
|
+
<event version='2.0' uid='protouid' type='t-x-takp-v' time='TIME' start='TIME' stale='TIME' how='m-g'>
|
|
166
|
+
<point lat='0.0' lon='0.0' hae='0.0' ce='999999' le='999999'/>
|
|
167
|
+
<detail>
|
|
168
|
+
<TakControl>
|
|
169
|
+
<TakProtocolSupport version="1"/>
|
|
170
|
+
</TakControl>
|
|
171
|
+
</detail>
|
|
172
|
+
</event>
|
|
173
|
+
|
|
174
|
+
... where the version attribute is an integer number specifying
|
|
175
|
+
a version of the TAK Protocol the server supports. This message
|
|
176
|
+
may contain one or more TakProtocolSupport elements inside the single
|
|
177
|
+
<TakControl> detail, each specifying a supported version.
|
|
178
|
+
The TAK server MUST send this message no more than once per connection.
|
|
179
|
+
|
|
180
|
+
To allow for ancillary information in the negotiation, the
|
|
181
|
+
TakProtocolSupport element MAY contain additional attributes compliant
|
|
182
|
+
with the Protocol version indicated.
|
|
183
|
+
4. Client and server continue to expect to exchange traditional CoT XML
|
|
184
|
+
messages per "Traditional Protocol" section.
|
|
185
|
+
5. If the client wishes to initiate a transfer to TAK Protocol encoding, it
|
|
186
|
+
selects one of the supported versions advertised in the server's message
|
|
187
|
+
from step 3. It then sends the following CoT XML:
|
|
188
|
+
<event version='2.0' uid='protouid' type='t-x-takp-q' time='TIME' start='TIME' stale='TIME' how='m-g'>
|
|
189
|
+
<point lat='0.0' lon='0.0' hae='0.0' ce='999999' le='999999'/>
|
|
190
|
+
<detail>
|
|
191
|
+
<TakControl>
|
|
192
|
+
<TakRequest version="1"/>
|
|
193
|
+
</TakControl>
|
|
194
|
+
</detail>
|
|
195
|
+
</event>
|
|
196
|
+
|
|
197
|
+
... where the version attribute is the integer version chosen above.
|
|
198
|
+
Only ONE TakRequest element is allowed.
|
|
199
|
+
|
|
200
|
+
To allow for ancillary information in the negotiation, the
|
|
201
|
+
TakRequest element MAY contain additional attributes compliant
|
|
202
|
+
with the Protocol version indicated.
|
|
203
|
+
|
|
204
|
+
Clients SHALL NOT send this message unless they have observed the
|
|
205
|
+
message from step #3, above, first.
|
|
206
|
+
Server MUST examine all receive CoT events for this message from the point
|
|
207
|
+
in time when the message in #3 is sent until at least one minute following
|
|
208
|
+
that point in time. If a "false" status is subsequently issued per step #6
|
|
209
|
+
below step, this time limit SHALL be extended to at least one minute
|
|
210
|
+
from the point in time the failure response message specified in
|
|
211
|
+
#6 is issued to allow the client additional time to retry.
|
|
212
|
+
|
|
213
|
+
6. Once the client sends the message in #5, it MUST NOT send additional
|
|
214
|
+
CoT XML to the server. Client also MUST still process incoming CoT XML
|
|
215
|
+
from the server. The client MUST wait in this state for a response per
|
|
216
|
+
the following for at least one minute.
|
|
217
|
+
The server MAY still send CoT XML messages up until it notices the
|
|
218
|
+
control request from the client (from step #5) and is ready to respond.
|
|
219
|
+
The server MUST then respond as soon as possible to the client with the
|
|
220
|
+
following message to indicate either acceptance or denial of the request:
|
|
221
|
+
<event version='2.0' uid='protouid' type='t-x-takp-r' time='TIME' start='TIME' stale='TIME' how='m-g'>
|
|
222
|
+
<point lat='0.0' lon='0.0' hae='0.0' ce='999999' le='999999'/>
|
|
223
|
+
<detail>
|
|
224
|
+
<TakControl>
|
|
225
|
+
<TakResponse status="true"/>
|
|
226
|
+
</TakControl>
|
|
227
|
+
</detail>
|
|
228
|
+
</event>
|
|
229
|
+
|
|
230
|
+
... where the status attribute is either true (to indicate the server
|
|
231
|
+
accepts the requested version) or false (to indicate that the server
|
|
232
|
+
denies the request).
|
|
233
|
+
Only ONE TakResponse element is allowed.
|
|
234
|
+
|
|
235
|
+
To allow for ancillary information in the negotiation, the
|
|
236
|
+
TakResponse element MAY contain additional attributes compliant
|
|
237
|
+
with the Protocol version selected in the request that this response
|
|
238
|
+
applies to.
|
|
239
|
+
|
|
240
|
+
If no response is received by the client before its timeout elapses,
|
|
241
|
+
the client SHALL disconnect as the entire negotiation is in an
|
|
242
|
+
indeterminate state. The client SHOULD reconnect and begin again at step
|
|
243
|
+
1, possibly with a longer timeout or alternate protocol version choice.
|
|
244
|
+
|
|
245
|
+
7. Operation at this point depends on the response send in #6:
|
|
246
|
+
7a. If status was true: The server MUST NOT send additiona CoT XML after the
|
|
247
|
+
"true" response in #6. Instead, the server SHALL send all future data
|
|
248
|
+
in accordance with the TAK Protocol Streaming Connection framework
|
|
249
|
+
and containing TAK Payloads of the negotiated version.
|
|
250
|
+
The client MAY resume sending messages at this time but MUST immediately
|
|
251
|
+
send said messages in accordance with the TAK Protocol Streaming
|
|
252
|
+
Connection framework and containing TAK Payloads of the negotiated
|
|
253
|
+
version. NOTE: the negotiated version SHALL be the same for both
|
|
254
|
+
directions of the streaming connection!
|
|
255
|
+
7b. If status was false: Both client and server resume operation as though
|
|
256
|
+
they were back at step #4. The client may attempt a new negotiation
|
|
257
|
+
if it wishes, or may simply continue to exchange traditional XML-based
|
|
258
|
+
CoT messages.
|
|
259
|
+
|
|
260
|
+
In the messages in 3, 5, and 6 above, the following common rules apply:
|
|
261
|
+
a. "protouid" is any valid UID representing the negotiation transaction.
|
|
262
|
+
The server generates this when offering protocol versions. The client
|
|
263
|
+
re-uses it when placing request(s) and the server re-uses it when
|
|
264
|
+
issuing the response to a request.
|
|
265
|
+
The UID SHALL be unique from UIDs used for other messages and purposes.
|
|
266
|
+
b. "TIME" is filled with a valid time representation per the CoT schemas.
|
|
267
|
+
The TIME values may be different from each other as needed.
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
*** "Mesh Network" Protocol Negotiation
|
|
271
|
+
|
|
272
|
+
Mesh networking in TAK products relies on repeated broadcasting of
|
|
273
|
+
device presence and "SA" data that gives basic information on how to reach
|
|
274
|
+
local network participants. To allow for clients with mixed TAK protocol
|
|
275
|
+
versions (as well as legacy XML only capabilities), the following protocol
|
|
276
|
+
selection and support advertisement shall be performed on each device:
|
|
277
|
+
|
|
278
|
+
1. All devices supporting TAK Protocol versions > 0 (legacy xml) MUST
|
|
279
|
+
broadcast to all configured and active non-TAK server broadcast destinations
|
|
280
|
+
the TakControl message in a TakMessage at least once every 60 seconds.
|
|
281
|
+
This information MAY be sent alongside CotEvent data or standalone.
|
|
282
|
+
This message indicates the minimum and maximum versions of TAK protocol
|
|
283
|
+
that the device can **decode**.
|
|
284
|
+
Note that devices not supporting TAK protocol > 0 will not be sending these
|
|
285
|
+
messages.
|
|
286
|
+
It is RECOMMENDED that devices do *not* frequently change the
|
|
287
|
+
version information in these messages as receivers may optimize around
|
|
288
|
+
the information being mostly static/fixed.
|
|
289
|
+
This information SHALL be sent using the protocol level
|
|
290
|
+
determined under the rule in 4 except when rule 4 results in
|
|
291
|
+
protocol level 0, in which case TakControl information
|
|
292
|
+
SHALL be sent using the lowest protocol version > 0 supported by the
|
|
293
|
+
sender.
|
|
294
|
+
2. Each device MUST examine and decode the TakControl message in any message
|
|
295
|
+
it receives and knows how to decode. If for a version that the device
|
|
296
|
+
does not support, it MAY discard the message.
|
|
297
|
+
3. Each device MUST maintain the minimum and maximum supported TAK protocol
|
|
298
|
+
versions known from every client known to exist on the network based on
|
|
299
|
+
the following ruleset:
|
|
300
|
+
3a. Newly detected clients are assigned a min/max supported version
|
|
301
|
+
equal to the version used to relay the message that resulted
|
|
302
|
+
in discovery of the client. Note that this could be version 0
|
|
303
|
+
(legacy XML)
|
|
304
|
+
3b. Upon receipt of a TakControl message, the min/max version info
|
|
305
|
+
is updated to match the information in the message. Optimizing
|
|
306
|
+
for infrequent changes of this info is recommended.
|
|
307
|
+
Note that TakControl messages do NOT allow versions of 0 in them.
|
|
308
|
+
Support for version 0 is implied (see base rules) and need not be
|
|
309
|
+
tracked except for those clients which support *only* version 0.
|
|
310
|
+
3c. Known clients that have not sent any TakControl messages in the previous
|
|
311
|
+
2 minutes shall revert to a minimum and maximum version equal
|
|
312
|
+
to the version used in the most recently received message that
|
|
313
|
+
keeps the client from becoming entirely stale. Note that this could
|
|
314
|
+
be version 0 (legacy XML).
|
|
315
|
+
3d. Received messages that are not decodable by the receiver should
|
|
316
|
+
continue to be treated as not having received TakControl messages
|
|
317
|
+
under 3c.
|
|
318
|
+
4. Devices MUST send out broadcast messages using the highest protocol version
|
|
319
|
+
supported by *all* known contacts (including consideration of the
|
|
320
|
+
sending device itself) tracked based on the rules in (3) at the time
|
|
321
|
+
of sending.
|
|
322
|
+
This includes SA announcements/broadcasts.
|
|
323
|
+
If there is no version overlap suitable for all versions, then protocol
|
|
324
|
+
"version 0" must be used.
|
|
325
|
+
If this is "version 0" (legacy xml), then XML shall be used.
|
|
326
|
+
5. Whenever the version computed via rule 5 changes, clients SHALL immediately
|
|
327
|
+
send out a TakControl message using the new version per rule 1.
|
|
328
|
+
This must be done even if not otherwise broadcasting a message.
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
*** TAK Protocol Varint Encoding
|
|
333
|
+
|
|
334
|
+
The varints used in the headers of the TAK Protocol are encoded in
|
|
335
|
+
accordance with the UNSIGNED varint rules for Google protocol buffers.
|
|
336
|
+
This encoding is summarized here:
|
|
337
|
+
|
|
338
|
+
1. The value must be UNSIGNED. Only values equal to or greater than zero
|
|
339
|
+
are allowed.
|
|
340
|
+
2. The value to be encoded is taken 7 bits at a time, starting with the
|
|
341
|
+
least significant 7 bits (bits 7 -> 0), then the next least significant bits
|
|
342
|
+
(14 -> 8), etc. This repeats over all 7 bit values that are significant
|
|
343
|
+
(that is, up to and including the most significant '1' bit).
|
|
344
|
+
3. For each 7 bit group:
|
|
345
|
+
3a. Let S = 0 if this is the the last 7 bit group, else let S = 1
|
|
346
|
+
3b. Output a byte that is (S << 7) | (the 7 bits)
|
|
347
|
+
|
|
348
|
+
The TAK Protocol use of Varints limits use to 64-bit values. This
|
|
349
|
+
effectively limits the range as [ 0, (2^63 - 1) ] and the varint coded value
|
|
350
|
+
to be limited to 10 bytes.
|
|
351
|
+
|
|
352
|
+
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// All items are required unless otherwise noted!
|
|
7
|
+
// "required" means if they are missing on send, the conversion
|
|
8
|
+
// to the message format will be rejected and fall back to opaque
|
|
9
|
+
// XML representation
|
|
10
|
+
message Status {
|
|
11
|
+
uint32 battery = 1; // battery=
|
|
12
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// TAK Protocol control message
|
|
7
|
+
// This specifies to a recipient what versions
|
|
8
|
+
// of protocol elements this sender supports during
|
|
9
|
+
// decoding.
|
|
10
|
+
message TakControl {
|
|
11
|
+
// Lowest TAK protocol version supported
|
|
12
|
+
// If not filled in (reads as 0), version 1 is assumed
|
|
13
|
+
uint32 minProtoVersion = 1;
|
|
14
|
+
|
|
15
|
+
// Highest TAK protocol version supported
|
|
16
|
+
// If not filled in (reads as 0), version 1 is assumed
|
|
17
|
+
uint32 maxProtoVersion = 2;
|
|
18
|
+
|
|
19
|
+
// UID of the sending contact. May be omitted if
|
|
20
|
+
// this message is paired in a TakMessage with a CotEvent
|
|
21
|
+
// and the CotEvent contains this information
|
|
22
|
+
string contactUid = 3;
|
|
23
|
+
}
|
|
24
|
+
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
import "cotevent.proto";
|
|
5
|
+
import "takcontrol.proto";
|
|
6
|
+
|
|
7
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
8
|
+
|
|
9
|
+
// Top level message sent for TAK Messaging Protocol Version 1.
|
|
10
|
+
message TakMessage {
|
|
11
|
+
// Optional - if omitted, continue using last reported control
|
|
12
|
+
// information
|
|
13
|
+
TakControl takControl = 1;
|
|
14
|
+
|
|
15
|
+
// Optional - if omitted, no event data in this message
|
|
16
|
+
CotEvent cotEvent = 2;
|
|
17
|
+
}
|
|
18
|
+
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// All items are required unless otherwise noted!
|
|
7
|
+
// "required" means if they are missing on send, the conversion
|
|
8
|
+
// to the message format will be rejected and fall back to opaque
|
|
9
|
+
// XML representation
|
|
10
|
+
message Takv {
|
|
11
|
+
string device = 1; // device=
|
|
12
|
+
string platform = 2; // platform=
|
|
13
|
+
string os = 3; // os=
|
|
14
|
+
string version = 4; // version=
|
|
15
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
option optimize_for = LITE_RUNTIME;
|
|
3
|
+
|
|
4
|
+
package atakmap.commoncommo.protobuf.v1;
|
|
5
|
+
|
|
6
|
+
// All items are required unless otherwise noted!
|
|
7
|
+
// "required" means if they are missing on send, the conversion
|
|
8
|
+
// to the message format will be rejected and fall back to opaque
|
|
9
|
+
// XML representation
|
|
10
|
+
message Track {
|
|
11
|
+
double speed = 1; // speed=
|
|
12
|
+
double course = 2; // course=
|
|
13
|
+
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tak-ps/node-cot",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "7.1
|
|
4
|
+
"version": "7.2.1",
|
|
5
5
|
"description": "Lightweight JavaScript library for parsing and manipulating TAK messages",
|
|
6
6
|
"author": "Nick Ingalls <nick@ingalls.ca>",
|
|
7
7
|
"main": "dist/index.js",
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
"test": "ts-node-test test/",
|
|
11
11
|
"lint": "eslint *.ts lib/*.ts test/*.ts",
|
|
12
12
|
"doc": "typedoc index.ts",
|
|
13
|
-
"build": "tsc --build && cp package.json dist/",
|
|
13
|
+
"build": "tsc --build && cp package.json dist/ && mkdir -p ./dist/proto/ && cp lib/proto/* ./dist/proto/",
|
|
14
14
|
"pretest": "npm run lint"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|