diff --git a/README.md b/README.md index e04dcd0..07c4cc4 100644 --- a/README.md +++ b/README.md @@ -177,8 +177,8 @@ The following parameters must be set (mandatory) for the container to function: | Environment Variable | Purpose | Default | |----------------------|---------|---------| -| `LAT` or `READSB_LAT` | The latitude of your antenna | | -| `LONG` or `READSB_LON` | The longitude of your antenna | | +| `LAT` or `READSB_LAT` | The latitude of your antenna. Use either parameter, but not both | | +| `LONG` or `READSB_LON` | The longitude of your antenna. Use either parameter, but not both | | | `ALT` or `READSB_ALT` | The altitude of your antenna above sea level. For example, `15m` or `45ft` | | | `TZ` | Your local timezone in [TZ-database-name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format | | @@ -287,6 +287,10 @@ The ULTRAFEEDER_CONFIG parameter can have multiple config strings, separated by - ULTRAFEEDER_CONFIG=mlathub,host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX][,extra-arguments] ``` +- To connect to an external ADSB (for input or output), UAT, or MLAT results source, use `- ULTRAFEEDER_CONFIG=adsb,host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX][,extra-arguments]` +- To connect and send data to an MLAT Server, use `- ULTRAFEEDER_CONFIG=mlat,host,port[,return_port][,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX][,input_connect=remote-host:port,lat=xx.xxxx,lon=yy.yyyy,alt=zzz][,extra-arguments]`. For the optional parts in this structure, see [MLAT configuration](#mlat-configuration). Note - any MLAT results data received from the MLAT Server will automatically be aggregated in an [MLAT Hub](#configuring-the-built-in-mlat-hub) and shared with `tar1090` +- To add MLAT results from additional MLAT Servers not configured with Ultrafeeder (for example, MLAT results from FlightRadar24 or FlightAware/piaware), use `- ULTRAFEEDER_CONFIG=mlathub,host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX][,extra-arguments]`. You can further configure this MLAT Hub as described in the section [Configuring the built-in MLAT Hub](#configuring-the-built-in-mlat-hub) + In the above configuration strings: - `host` is an IP address. Specify an IP/hostname/containername for incoming or outgoing connections. @@ -300,13 +304,8 @@ In the above configuration strings: - `raw_in`: Raw input - `sbs_out`: SBS-format output - `vrs_out`: SBS-format output -- `uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` is an optional parameter that sets the UUID for this specific instance. It will override the global `UUID` parameter. This is only needed when you want to send different UUIDs to different aggregators. -- `extra-arguments` can be any additional command line argument you want to pass to readsb, mlathub, or mlat-client. Example: `--net-only`. Please make sure to only once pass in an extra argument for each of the adsb|mlat|mlathub service. -- To connect to a remote receiver and send MLAT data to a MLAT Server, create a `mlat` instance with these additional parameters - `input_connect=remote-host:port,lat=xx.xxxx,lon=yy.yyyy,alt=zzz`, where: - - `input_connect=remote-host:port` defines the remote receiver's hostname or IP address and the port number where BEAST output data is available - - `lat=xx.xxxx` defines the remote receiver's latitude - - `lon=yy.yyyy` defines the remote receiver's longitude - - `alt=zzz` defines the remote receiver's altitude in meters above the eliptoid (~above sea level) + - `uat_in`: "special" RAW format input as generated by the `dump978` container on port 30978. It is advisable to use this protocol and port to get UAT data from dump978, for example: `- ULTRAFEEDER_CONFIG=adsb,dump978,30978,uat_in` +- `uuid` is a Universally Unique Identifier. You can reuse the one you generated for AdsbExchange, or you can generate a new one with this Linux command: `cat /proc/sys/kernel/random/uuid`. If omitted, it will use the UUID environment parameter, or if that one doesn't exist, it will leave the field empty. ##### Networking parameters @@ -319,27 +318,14 @@ In the above configuration strings: ##### Alternate Configuration Method with `READSB_NET_CONNECTOR` -Instead of (or in addition to) using `BEASTHOST`, you can also define ADSB data ingests using the `READSB_NET_CONNECTOR` parameter. This is the preferred way if you have multiple sources or destinations for your ADSB data. This variable allows you to configure incoming and outgoing connections. The variable takes a semicolon (`;`) separated list of `host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX]`, where: - -- `host` is an IP address. Specify an IP/hostname/containername for incoming or outgoing connections. -- `port` is a TCP port number -- `protocol` can be one of the following: - - `beast_reduce_out`: Beast-format output with lower data throughput (saves bandwidth and CPU) - - `beast_reduce_plus_out`: Beast-format output with extra data (UUID). This is the preferred format when feeding the "new" aggregator services - - `beast_out`: Beast-format output - - `beast_in`: Beast-format input - - `raw_out`: Raw output - - `raw_in`: Raw input - - `sbs_out`: SBS-format output - - `vrs_out`: SBS-format output -- `uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` is an optional parameter that sets the UUID for this specific instance. It will override the global `UUID` parameter. This is only needed when you want to send different UUIDs to different aggregators. +Instead of (or in addition to) using `BEASTHOST`, you can also define ADSB data ingests using the `READSB_NET_CONNECTOR` parameter. This is the preferred way if you have multiple sources or destinations for your ADSB data. This variable allows you to configure incoming and outgoing connections. The variable takes a semicolon (`;`) separated list of `host,port,protocol[,uuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX]`, see the section [All-in-One Configuration using `ULTRAFEEDER_CONFIG`](#all-in-one-configuration-using-ultrafeeder_config) for explanation of these parameters. NOTE: If you have a UAT dongle and use `dump978` to decode this, you should use `READSB_NET_CONNECTOR` to ingest UAT data from `dump978`. See example below ```yaml environment: ... - - READSB_NET_CONNECTOR=dump978,37981,raw_in;another-data-aggregator.com,30005,beast_reduce_plus_out + - READSB_NET_CONNECTOR=dump978,30978,uat_in;... ... ``` @@ -382,24 +368,28 @@ It will create a separate instance of `mlat-client` for each defined MLAT server ```yaml environment: ... - - MLAT_NET_CONNECTOR= - mlat-server1.com,port1,return_port1,uuid=1234-5678-90123,--extra-argument hello; - mlat-server2.com,port2,return_port2,uuid=5678-9012-34567,--extra-argument hello - ... + - ULTRAFEEDERCONFIG= + ... + mlat,mlat-server1.com,port1,return_port1,uuid=1234-5678-90123,inputconnect=remote_receiver1:30005,lat=12.3456,lon=45.6789,alt=18m,--arg1 hello --arg2 world; + mlat,mlat-server2.com,port2,return_port2,uuid=5678-9012-34567,inputconnect=remote_receiver2:30005,-lat=12.3456,lon=45.6789,alt=18m,--arg1 hello-again --arg2 universe ``` where: -- `mlat-server.com` is the domain name or ip address of the target MLAT server (mandatory) -- `port` is the port (TCP or UDP) of the target MLAT server (mandatory) -- `return_port` is the port at which the MLAT results are made available in BEAST format. We recommend to sequentially number them starting at 39000 (optional) -- `uuid=xxxx` defines a unique user ID for this MLAT server instance. If included, the string must start with `uuid=` (optional) -- `input_connect=hostname:port` / `lat=xxxx` / `lon=xxxx` / `alt=xxxx` defines a unique input connection/latitude/longitude/altitude. This can be used to connect to a remote Beast source and forward MLAT data to an MLAT server -- `extra-arguments` are any additional command line arguments that you would like to use for this MLAT Client instance (optional) +| Parameter | Mandatory/Optional | Description | +|-------------------|--------------------|-------------| +| `mlat` | Mandatory | indicates that the line container MLAT-client configuration parameters | +| `mlat-server.com` | Mandatory | the domain name or ip address of the target MLAT server | +| `port` | Mandatory | the port (TCP or UDP) of the target MLAT server | +| `return_port` | Optional | the port at which the MLAT results are made available in BEAST format. We recommend to sequentially number them starting at 39000 | +| `uuid` | Optional | a unique user ID for this MLAT server instance. If included, the string must start with `uuid=`. If not included, it will use the value of the `UUID` parameter if it exists | +| `input_connect` | Optional | a unique input connection in the form `input_connect=remotehost:port`, where `remotehost:` is the hostname or IP address and TCP port of your remote BEAST source. This can be used to connect to a remote Beast source and forward MLAT data to an MLAT server | +| `lat` | Optional | the latitude to be sent to the MLAT server in the form `lat=xx.xxxxx`. If omitted, the `LAT` / `READSB_LAT` parameter will be used. This is meant to be used in combination with `input_connect` for connecting to a remote Beast source and forward MLAT data to an MLAT server | +| `lon` | Optional | the longitude to be sent to the MLAT server in the form `lon=xx.xxxxx`. If omitted, the `LONG` / `READSB_LON` parameter will be used. This is meant to be used in combination with `input_connect` for connecting to a remote Beast source and forward MLAT data to an MLAT server | +| `alt` | Optional | the altitude to be sent to the MLAT server in the form `alt=xx.xxxxx`. If omitted, the `ALT` / `READSB_ALT` parameter will be used. This is meant to be used in combination with `input_connect` for connecting to a remote Beast source and forward MLAT data to an MLAT server | +| `extra-arguments` | Optional | Any extra parameter you want to pass to the `mlat-client` program. Will be added verbatim to the command line | -Note - the three optional parameters (`return_port`, `uuid=`, and `extra-arguments`) can be given in any order. - -If no UUID is specified with the `MLAT_CONFIG` parameter, it will use the value of the `UUID` parameter if it exists. If that fails, a random UUID will be generated for each instance of `mlat-client` with format `00000000-ffff-aaaa-rrrr-tttttttttttt` where `rrrr` is a random hexadecimal number and `tttttttttttt` contains the UUID creation time (secs since epoch) in hexadecimal format. +Note - the optional parameters can be given in any order. ### Web Gui (`tar1090`) Configuration