Merge branch 'PolynomialDivision-feature/add_workflow'
[olsrd.git] / lib / pud / README_PUD
1 This plugin depends on the (included) NMEA parsing library that can be found at:
2
3         https://github.com/AHR-Project/nmealib
4
5 See the document doc/pud.odt for a detailed specification of the module.
6
7 LoadPlugin "<olsrd plugin library path>/olsrd_pud.so.3.0.0"
8 {
9     # nodeId contains the node identification. It first describes the semantics
10     #        (meaning/code) of the identification and then specifies the node
11     #        identification itself.
12     #        For some codes the identification itself is not relevant and
13     #        therefore ignored (specified if so).
14     #
15     #        The format is "number,identification"
16     #
17     #        "Number" is a number in the range 0-255, with the following
18     #        meaning:
19     #           0 : MAC address of sending interface
20     #               (identification is not relevant)
21     #           1 : an MSISDN number with 15 digits
22     #           2 : a Tetra number with 17 digits
23     #           3 : a DNS name
24     #               (identification can be empty, in which case the hostname is
25     #                used)
26     #           4 : IPv4 address (OLSR main address) of the sending node
27     #               (identification is not relevant)
28     #           5 : an UUID number with 32 hexadecimal digits
29     #           6 : IPv6 address (OLSR main address) of the sending node
30     #               (identification is not relevant)
31     #           7 : an AIS MMSI number with 9 digits
32     #           8 : a URN number (a plain 24 bits number) with 8 digits. See
33     #               http://www.dtic.mil/cjcs_directives/cdata/unlimit/3156_01.pdf
34     #           9 : a MIP OID number with 20 digits. See
35     #               http://www.mip-site.org/publicsite (IR Annex D – DMWG,
36     #               20081211, Edition 3.7, Annex D Key Management for the MIP
37     #               Data Model, (MIR Annex D - Key Management-JC3IEDM-3.0.9.pdf)
38     #         192 : a 7 digit number conforming to 'Nationaal Nummerplan
39     #               Brandweer Nederland'
40     #         193 : a 6 digit number conforming to 'Nationaal Nummerplan
41     #               Ambulancezorg Nederland'
42     #         194 : a 4 digit number in the range [1, 8191]
43     #
44     #         other numbers are reserved
45     #
46     # Note: setting "number" to 4 or 6 is the same for olsrd: both mean 'use
47     #       the main IP address, which is either an IPv4 or an IPv6 address,
48     #       depending on the IP version under which olsrd is run.
49     #
50     # Note: Both the number and the identification are transported over OLSR,
51     #       so care must be taken to keep the size of the identification down.
52     #
53     # Default: "4" (when olsrd is run under IPv4)
54     #          "6" (when olsrd is run under IPv6)
55     #
56     # PlParam     "nodeId"                       "4"
57
58
59     #
60     # gpsd Parameters
61     #
62
63     # gpsdUse determines whether the gpsd daemon should be used for position
64     #         information
65     #
66     # Default: true
67     #
68     # PlParam     "gpsdUse"                      "true"
69
70     # gpsd is the gpsd source spec of the gpsd daemon to connect to
71     #
72     # Default: localhost:2947
73     #
74     # PlParam     "gpsd"                         "localhost:2947"
75
76
77     #
78     # Position Input File Parameters
79     #
80
81     # positionFile is the file that contains the position information that the
82     #              plugin should use. When this parameter is set then the
83     #              file is read during olsrd startup. An example file is
84     #              available in the doc directory of olsrd.
85     #
86     # Default: none
87     #
88     # PlParam     "positionFile"                 ""
89
90     # Specifies the period in milliseconds on which to read the positionFile
91     # (if it changed) and activate its new setting for the position.
92     # This setting is only relevant if positionFile has been configured.
93     # A setting of zero disables dynamic updates, the positionFile is then only
94     # read during olsrd startup.
95     #
96     # Default: 0
97     #
98     # PlParam     "positionFilePeriod" "0"
99
100
101     #
102     # TX Parameters
103     #
104
105     # txNonOlsrIf is a network interface on the host on which the plugin will
106     #             transmit GPS multicasts that were received through the OLSR
107     #             network. Multiple such interfaces can be specified by
108     #             specifying the parameter multiple times.
109     #
110     # Default: none
111     #
112     # PlParam     "txNonOlsrIf"                  ""
113
114     # txMcAddr is the multicast address on which the plugin will transmit GPS
115     #          multicasts that were received through the OLSR network.
116     #
117     # Default: 224.0.0.224 (IPv4) or FF02:0:0:0:0:0:0:1 (IPv6)
118     #
119     # PlParam     "txMcAddr"                     "224.0.0.224"
120
121     # txMcPort is the UDP port on which the plugin will transmit GPS multicasts
122     #          that were received through the OLSR network.
123     #
124     # Default: 2240
125     #
126     # PlParam     "txMcPort"                     "2240"
127
128     # txTtl is the TTL that is used when transmitting GPS multicasts that were
129     #       received through the OLSR network
130     #
131     # Default: 1
132     #
133     # PlParam     "txTtl"                        "1"
134
135     # txNmeaMessagePrefix is the NMEA message prefix of GPS multicasts that the
136     #                     plugin transmits. It must be exactly 4 characters
137     #                     long.
138     #
139     # Default: NBSX
140     #
141     # PlParam     "txNmeaMessagePrefix"          "NBSX"
142
143
144     #
145     # Position Output File Parameters
146     #
147
148     # positionOutputFile is the file into which the position is written when it
149     #                    changes. The file will contain all position parameters
150     #                    in a bash compatible format. The file will be removed
151     #                    when olsrd stops.
152     #
153     # Default: none
154     #
155     # PlParam     "positionOutputFile"           ""
156
157
158     #
159     # Uplink Parameters
160     #
161
162     # uplinkAddr is the IP address to which the plugin will transmit GPS
163     #            position updates. When not set, no uplink messages will be
164     #            sent.
165     #
166     # Default: none
167     #
168     # PlParam     "uplinkAddr"                   ""
169
170     # uplinkPort is the UDP port to which the plugin will transmit GPS position
171     #            updates. Can't be the same as the downlink port.
172     #
173     # Default: 2241
174     #
175     # PlParam     "uplinkPort"                   "2241"
176
177     # downlinkPort is the UDP port on which the plugin will receive GPS position
178     #              updates. Can't be the same as the uplink port.
179     #              The downlink is only active when a proper uplink has been
180     #              configured.
181     #
182     # Default: 2242
183     #
184     # PlParam     "downlinkPort"                 "2242"
185
186
187     #
188     # OLSR Parameters
189     #
190
191     # olsrTtl is the TTL that is used when sending messages over the OLSR
192     #         networks. Setting this to 0 (zero) will disable distribution
193     #         of position updates over the OLSR networks.
194     #
195     # Default: 64
196     #
197     # PlParam     "olsrTtl"                      "64"
198
199
200     #
201     # Update Parameters
202     #
203
204     # updateIntervalStationary is the interval (in seconds) between position
205     #                          updates sent over the OLSR network when the
206     #                          node is stationary
207     #
208     # Default: 60
209     #
210     # PlParam     "updateIntervalStationary"     "60"
211
212     # updateIntervalMoving is the interval (in seconds) between position
213     #                      updates sent over the OLSR network when the
214     #                      node is moving
215     #
216     # Default: 5
217     #
218     # PlParam     "updateIntervalMoving"         "5"
219
220     # uplinkUpdateIntervalStationary is the interval (in seconds) between
221     #                                position updates sent over the uplink when
222     #                                the node is stationary
223     #
224     # Default: 180
225     #
226     # PlParam     "uplinkUpdateIntervalStationary" "180"
227
228     # uplinkUpdateIntervalMoving is the interval (in seconds) between position
229     #                            updates sent over the OLSR network when the
230     #                            node is moving
231     #
232     # Default: 15
233     #
234     # PlParam     "uplinkUpdateIntervalMoving"   "15"
235
236     # gatewayDeterminationInterval is the interval (in seconds) on which
237     #                              determination of the best gateway is
238     #                              performed
239     #
240     # Default: 1
241     #
242     # PlParam     "gatewayDeterminationInterval" "1"
243
244     # movingSpeedThreshold is the speed from which we consider the node is
245     #                      moving
246     #
247     # Default: 9
248     #
249     # PlParam     "movingSpeedThreshold"         "9"
250
251     # movingDistanceThreshold is the distance from the previous position from
252     #                         which we consider the node is moving
253     #
254     # Default: 50
255     #
256     # PlParam     "movingDistanceThreshold"      "50"
257
258     # dopMultiplier One of the situations that is seen as movement is when the
259     #               current position with its uncertainty circle no longer
260     #               overlaps the last transmitted position with its uncertainty
261     #               circle. This parameter is used to adjust the sizes of these
262     #               uncertainty circles: setting it to a value less than 1.0
263     #               will make both uncertainty circles smaller by this factor,
264     #               resulting in earlier movement detection. Setting it to a
265     #               value larger than 1.0 will detect movement later.
266     #
267     # Default: 2.5
268     #
269     # PlParam     "dopMultiplier"                "2.5"
270
271     # defaultHdop is the default value that is taken for HDOP (in meters) in
272     #             determining whether we are moving when there is a position
273     #             available but no HDOP.
274     #
275     # Default: 50
276     #
277     # PlParam     "defaultHdop"                  "50"
278
279     # defaultVdop is the default value that is taken for VDOP (in meters) in
280     #             determining whether we are moving when there is a position
281     #             available but no VDOP.
282     #
283     # Default: 50
284     #
285     # PlParam     "defaultVdop"                  "50"
286
287     # averageDepth is the depth of the position average list, or the number
288     #              of positions that are averaged to obtain the average
289     #              position
290     #
291     # Default: 5
292     #
293     # PlParam     "averageDepth"                 "5"
294
295     # hysteresisCountToStationary is the number of position updates that
296     #                             effectuate a state transition from moving to
297     #                             stationary that must be received before the
298     #                             actual transition is taken
299     #
300     # Default: 17
301     #
302     # PlParam     "hysteresisCountToStationary"  "17"
303
304     # hysteresisCountToMoving is the number of position updates that effectuate
305     #                         a state transition from stationary to moving that
306     #                         must be received before the actual transition is
307     #                         taken
308     #
309     # Default: 5
310     #
311     # PlParam     "hysteresisCountToMoving"      "5"
312
313     # gatewayHysteresisCountToStationary is the number of times the gateway
314     #                             must be the same that effectuate a state transition from
315     #                             moving to stationary that must be received
316     #                             before the actual transition is taken
317     #
318     # Default: 17
319     #
320     # PlParam     "gatewayHysteresisCountToStationary" "17"
321
322     # gatewayHysteresisCountToMoving is the number of gateway updates that
323     #                         effectuate a state transition from stationary to
324     #                         moving that must be received before the actual
325     #                         transition is taken
326     #
327     # Default: 5
328     #
329     # PlParam     "gatewayHysteresisCountToMoving" "5"
330
331
332     #
333     # Other Plugin Parameters
334     #
335
336     # useDeDup determines whether duplicate message detection is to be
337     #          performed. When 0 then no such detection is performed, when 1
338     #          then the detection is performed 
339     #
340     # Default: true
341     #
342     # PlParam     "useDeDup"                     "true"
343
344     # deDupDepth the number of messages that are tracked to detect duplucates
345     #            messages received from the OLSR network
346     #
347     # Default: 256
348     #
349     # PlParam     "deDupDepth"                   "256"
350
351     # useLoopback determines whether the message that is sent over the OLSR
352     #             network should be immediately looped back, thus pretending
353     #             that the message (that is sent by this node) is received from
354     #             the OLSR network. When 0 then no loopback is performed, when
355     #             1 then the loopback is performed
356     #
357     # Default: false
358     #
359     # PlParam     "useLoopback"                  "true"
360 }
361
362
363
364 ===================
365 Postion Output File
366 ===================
367
368 +---------------------------------+--------------------------+------------------------------+-------------------------+
369 | Parameter                       | Type                     | Unit                         | Range / Values          |
370 +---------------------------------+--------------------------+------------------------------+-------------------------+
371 | OLSRD_PUD_NODE_ID               | string                   | -                            | -                       |
372 +---------------------------------+--------------------------+------------------------------+-------------------------+
373 | OLSRD_PUD_SIGNAL                | string                   | -                            | INVALID                 |
374 |                                 |                          |                              | FIX                     |
375 |                                 |                          |                              | DIFFERENTIAL            |
376 |                                 |                          |                              | SENSITIVE               |
377 |                                 |                          |                              | REALTIME                |
378 |                                 |                          |                              | FLOAT                   |
379 |                                 |                          |                              | ESTIMATED               |
380 |                                 |                          |                              | MANUAL                  |
381 |                                 |                          |                              | SIMULATED               |
382 |                                 |                          |                              | <integer number>        |
383 +---------------------------------+--------------------------+------------------------------+-------------------------+
384 | OLSRD_PUD_FIX                   | string                   | -                            | NONE                    |
385 |                                 |                          |                              | 2D                      |
386 |                                 |                          |                              | 3D                      |
387 |                                 |                          |                              | <integer number>        |
388 +---------------------------------+--------------------------+------------------------------+-------------------------+
389 | OLSRD_PUD_YEAR                  | integer number           | year                         | [    1900,         inf) |
390 | OLSRD_PUD_MONTH                 | integer number           | month                        | [       1,          12] |
391 | OLSRD_PUD_DAY                   | integer number           | day                          | [       1,          31] |
392 | OLSRD_PUD_HOUR                  | integer number           | hour                         | [       0,          23] |
393 | OLSRD_PUD_MINUTE                | integer number           | minute                       | [       0,          59] |
394 | OLSRD_PUD_SECONDS               | integer number           | second                       | [       0,          60] |
395 | OLSRD_PUD_MILLISECONDS          | integer number           | millisecond                  | [       0,         999] |
396 | OLSRD_PUD_PDOP                  | floating point number    | -                            | [     0.0,         inf) |
397 | OLSRD_PUD_HDOP                  | floating point number    | -                            | [     0.0,         inf) |
398 | OLSRD_PUD_VDOP                  | floating point number    | -                            | [     0.0,         inf) |
399 | OLSRD_PUD_LATTITUDE             | floating point number    | NDEG: [degree][min].[sec/60] | [ -9000.0,      9000.0] |
400 | OLSRD_PUD_LONGITUDE             | floating point number    | NDEG: [degree][min].[sec/60] | [-18000.0,     18000.0] |
401 | OLSRD_PUD_ELEVATION             | floating point number    | meter (geoid)                | [ -6371.0,         inf) |
402 | OLSRD_PUD_SPEED                 | floating point number    | km/h                         | [     0.0,         inf) |
403 | OLSRD_PUD_TRACK                 | floating point number    | decimal degrees              | [     0.0,       360.0) |
404 | OLSRD_PUD_MAGNETIC_TRACK        | floating point number    | decimal degrees              | [     0.0,       360.0) |
405 | OLSRD_PUD_MAGNETIC_VARIATION    | floating point number    | decimal degrees              | [     0.0,       360.0) |
406 +---------------------------------+--------------------------+------------------------------+-------------------------+
407
408
409 +---------+
410 | Example |
411 +---------+
412 OLSRD_PUD_NODE_ID="example.node.id"
413 OLSRD_PUD_SIGNAL=DIFFERENTIAL
414 OLSRD_PUD_FIX=3D
415 OLSRD_PUD_YEAR=2016
416 OLSRD_PUD_MONTH=06
417 OLSRD_PUD_DAY=02
418 OLSRD_PUD_HOUR=13
419 OLSRD_PUD_MINUTE=56
420 OLSRD_PUD_SECONDS=25
421 OLSRD_PUD_MILLISECONDS=000
422 OLSRD_PUD_PDOP=132.000000
423 OLSRD_PUD_HDOP=6.000000
424 OLSRD_PUD_VDOP=88.500000
425 OLSRD_PUD_LATTITUDE=-12.147138
426 OLSRD_PUD_LONGITUDE=-5.346317
427 OLSRD_PUD_ELEVATION=47.840000
428 OLSRD_PUD_SPEED=0.825251
429 OLSRD_PUD_TRACK=133.816000
430 OLSRD_PUD_MAGNETIC_TRACK=0.000000
431 OLSRD_PUD_MAGNETIC_VARIATION=0.000000