pud: move the config sample into the readme
[olsrd.git] / lib / pud / README
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.2.2.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     # RX Parameters
61     #
62
63     # rxNonOlsrIf is a network interface on the host on which the plugin will
64     #             listen for GPS multicasts. Multiple such interfaces can be
65     #             specified by specifying the parameter multiple times.
66     #
67     # Default: none
68     #
69     # PlParam     "rxNonOlsrIf"                  ""
70
71     # rxAllowedSourceIpAddress is an IP address from which the plugin is
72     #                          allowed to process/parse GPS sentences. When
73     #                          this parameter is not configured then GPS
74     #                          sentences from ALL IP addresses are processed.
75     #                          Multiple IP addresses can be specified by
76     #                          specifying the parameter multiple times.
77     #
78     # Default: none
79     #
80     # PlParam     "rxAllowedSourceIpAddress"     ""
81
82     # rxMcAddr is the multicast address on which the plugin will listen for GPS
83     #          multicasts.
84     #
85     # Default: 224.0.0.224 (IPv4) or FF02:0:0:0:0:0:0:1 (IPv6)
86     #
87     # PlParam     "rxMcAddr"                     "224.0.0.224"
88
89     # rxMcPort is the UDP port on which the plugin will listen for GPS
90     #          multicasts.
91     #
92     # Default: 2240
93     #
94     # PlParam     "rxMcPort"                     "2240"
95
96     # positionFile is the file that contains the position information that the
97     #              plugin should use. When this parameter is set then the
98     #              file is read during olsrd startup. An example file is
99     #              available in the doc directory of olsrd.
100     #
101     # Default: none
102     #
103     # PlParam     "positionFile"                 ""
104
105     # Specifies the period in milliseconds on which to read the positionFile
106     # (if it changed) and activate its new setting for the position.
107     # This setting is only relevant if positionFile has been configured.
108     # A setting of zero disables dynamic updates, the positionFile is then only
109     # read during olsrd startup.
110     #
111     # Default: 0
112     #
113     # PlParam     "positionFilePeriod" "0"
114
115
116     #
117     # TX Parameters
118     #
119
120     # txNonOlsrIf is a network interface on the host on which the plugin will
121     #             transmit GPS multicasts that were received through the OLSR
122     #             network. Multiple such interfaces can be specified by
123     #             specifying the parameter multiple times.
124     #
125     # Default: none
126     #
127     # PlParam     "txNonOlsrIf"                  ""
128
129     # txMcAddr is the multicast address on which the plugin will transmit GPS
130     #          multicasts that were received through the OLSR network.
131     #
132     # Default: 224.0.0.224 (IPv4) or FF02:0:0:0:0:0:0:1 (IPv6)
133     #
134     # PlParam     "txMcAddr"                     "224.0.0.224"
135
136     # txMcPort is the UDP port on which the plugin will transmit GPS multicasts
137     #          that were received through the OLSR network.
138     #
139     # Default: 2240
140     #
141     # PlParam     "txMcPort"                     "2240"
142
143     # txTtl is the TTL that is used when transmitting GPS multicasts that were
144     #       received through the OLSR network
145     #
146     # Default: 1
147     #
148     # PlParam     "txTtl"                        "1"
149
150     # txNmeaMessagePrefix is the NMEA message prefix of GPS multicasts that the
151     #                     plugin transmits. It must be exactly 4 characters
152     #                     long.
153     #
154     # Default: NBSX
155     #
156     # PlParam     "txNmeaMessagePrefix"          "NBSX"
157
158
159     #
160     # Uplink Parameters
161     #
162
163     # uplinkAddr is the IP address to which the plugin will transmit GPS
164     #            position updates. When not set, no uplink messages will be
165     #            sent.
166     #
167     # Default: none
168     #
169     # PlParam     "uplinkAddr"                   ""
170
171     # uplinkPort is the UDP port to which the plugin will transmit GPS position
172     #            updates. Can't be the same as the downlink port.
173     #
174     # Default: 2241
175     #
176     # PlParam     "uplinkPort"                   "2241"
177
178     # downlinkPort is the UDP port on which the plugin will receive GPS position
179     #              updates. Can't be the same as the uplink port.
180     #              The downlink is only active when a proper uplink has been
181     #              configured.
182     #
183     # Default: 2242
184     #
185     # PlParam     "downlinkPort"                 "2242"
186
187
188     #
189     # OLSR Parameters
190     #
191
192     # olsrTtl is the TTL that is used when sending messages over the OLSR
193     #         networks. Setting this to 0 (zero) will disable distribution
194     #         of position updates over the OLSR networks.
195     #
196     # Default: 64
197     #
198     # PlParam     "olsrTtl"                      "64"
199
200
201     #
202     # Update Parameters
203     #
204
205     # updateIntervalStationary is the interval (in seconds) between position
206     #                          updates sent over the OLSR network when the
207     #                          node is stationary
208     #
209     # Default: 60
210     #
211     # PlParam     "updateIntervalStationary"     "60"
212
213     # updateIntervalMoving is the interval (in seconds) between position
214     #                      updates sent over the OLSR network when the
215     #                      node is moving
216     #
217     # Default: 5
218     #
219     # PlParam     "updateIntervalMoving"         "5"
220
221     # uplinkUpdateIntervalStationary is the interval (in seconds) between
222     #                                position updates sent over the uplink when
223     #                                the node is stationary
224     #
225     # Default: 180
226     #
227     # PlParam     "uplinkUpdateIntervalStationary" "180"
228
229     # uplinkUpdateIntervalMoving is the interval (in seconds) between position
230     #                            updates sent over the OLSR network when the
231     #                            node is moving
232     #
233     # Default: 15
234     #
235     # PlParam     "uplinkUpdateIntervalMoving"   "15"
236
237     # gatewayDeterminationInterval is the interval (in seconds) on which
238     #                              determination of the best gateway is
239     #                              performed
240     #
241     # Default: 1
242     #
243     # PlParam     "gatewayDeterminationInterval" "1"
244
245     # movingSpeedThreshold is the speed from which we consider the node is
246     #                      moving
247     #
248     # Default: 9
249     #
250     # PlParam     "movingSpeedThreshold"         "9"
251
252     # movingDistanceThreshold is the distance from the previous position from
253     #                         which we consider the node is moving
254     #
255     # Default: 50
256     #
257     # PlParam     "movingDistanceThreshold"      "50"
258
259     # dopMultiplier One of the situations that is seen as movement is when the
260     #               current position with its uncertainty circle no longer
261     #               overlaps the last transmitted position with its uncertainty
262     #               circle. This parameter is used to adjust the sizes of these
263     #               uncertainty circles: setting it to a value less than 1.0
264     #               will make both uncertainty circles smaller by this factor,
265     #               resulting in earlier movement detection. Setting it to a
266     #               value larger than 1.0 will detect movement later.
267     #
268     # Default: 2.5
269     #
270     # PlParam     "dopMultiplier"                "2.5"
271
272     # defaultHdop is the default value that is taken for HDOP (in meters) in
273     #             determining whether we are moving when there is a position
274     #             available but no HDOP.
275     #
276     # Default: 50
277     #
278     # PlParam     "defaultHdop"                  "50"
279
280     # defaultVdop is the default value that is taken for VDOP (in meters) in
281     #             determining whether we are moving when there is a position
282     #             available but no VDOP.
283     #
284     # Default: 50
285     #
286     # PlParam     "defaultVdop"                  "50"
287
288     # averageDepth is the depth of the position average list, or the number
289     #              of positions that are averaged to obtain the average
290     #              position
291     #
292     # Default: 5
293     #
294     # PlParam     "averageDepth"                 "5"
295
296     # hysteresisCountToStationary is the number of position updates that
297     #                             effectuate a state transition from moving to
298     #                             stationary that must be received before the
299     #                             actual transition is taken
300     #
301     # Default: 17
302     #
303     # PlParam     "hysteresisCountToStationary"  "17"
304
305     # hysteresisCountToMoving is the number of position updates that effectuate
306     #                         a state transition from stationary to moving that
307     #                         must be received before the actual transition is
308     #                         taken
309     #
310     # Default: 5
311     #
312     # PlParam     "hysteresisCountToMoving"      "5"
313
314     # gatewayHysteresisCountToStationary is the number of times the gateway
315     #                             must be the same that effectuate a state transition from
316     #                             moving to stationary that must be received
317     #                             before the actual transition is taken
318     #
319     # Default: 17
320     #
321     # PlParam     "gatewayHysteresisCountToStationary" "17"
322
323     # gatewayHysteresisCountToMoving is the number of gateway updates that
324     #                         effectuate a state transition from stationary to
325     #                         moving that must be received before the actual
326     #                         transition is taken
327     #
328     # Default: 5
329     #
330     # PlParam     "gatewayHysteresisCountToMoving" "5"
331
332
333     #
334     # Other Plugin Parameters
335     #
336
337     # useDeDup determines whether duplicate message detection is to be
338     #          performed. When 0 then no such detection is performed, when 1
339     #          then the detection is performed 
340     #
341     # Default: true
342     #
343     # PlParam     "useDeDup"                     "true"
344
345     # deDupDepth the number of messages that are tracked to detect duplucates
346     #            messages received from the OLSR network
347     #
348     # Default: 256
349     #
350     # PlParam     "deDupDepth"                   "256"
351
352     # useLoopback determines whether the message that is sent over the OLSR
353     #             network should be immediately looped back, thus pretending
354     #             that the message (that is sent by this node) is received from
355     #             the OLSR network. When 0 then no loopback is performed, when
356     #             1 then the loopback is performed
357     #
358     # Default: false
359     #
360     # PlParam     "useLoopback"                  "true"
361 }