feat: add compatibility with mode-s beast

[shawaj]

• add beast-splitter and dependencies to dump1090-fa container
• make container privileged in docker-compose for USB serial device
• add RADIO_DEVICE_TYPE option (defaults to rtlsdr)
• add hackrf, limesdr, soapysdr, bladerf radio options
• add service descriptors to log messages
• fix some comment typos
• add device type selection info to README

Closes: #99
Relates-to: #93

To do:

• test with mode-s beast, hackrf, limesdr, soapysdr, bladerf
• is it necessary to add bladerf/hackrf/limesdr/soapysdr specific options from the dump1090 help shown below?

dump1090 help

root@dd0f7681dade:/tmp# dump1090-fa --help
-----------------------------------------------------------------------------
| dump1090 ModeS Receiver                                   dump1090-fa 9.0 |
| build options: ENABLE_RTLSDR ENABLE_BLADERF ENABLE_HACKRF ENABLE_LIMESDR  |
-----------------------------------------------------------------------------
--device-type <type>     Select SDR type (default: rtlsdr)

      rtlsdr-specific options (use with --device-type rtlsdr)

--device <index|serial>  select device by index or serial number
--enable-agc             enable digital AGC (not tuner AGC!)
--ppm <correction>       set oscillator frequency correction in PPM
--direct <0|1|2>         set direct sampling mode

      bladeRF-specific options (use with --device-type bladerf)

--device <ident>         select device by bladeRF 'device identifier'
--bladerf-fpga <path>    use alternative FPGA bitstream ('' to disable FPGA load)
--bladerf-decimation <N> assume FPGA decimates by a factor of N
--bladerf-bandwidth <hz> set LPF bandwidth ('bypass' to bypass the LPF)

      HackRF-specific options (use with --device-type hackrf)

--enable-amp             enable amplifier (disabled unless specified)
--enable-antenna-power   enable DC power to the antenna connector (disabled unless specified)
--lna-gain               set LNA gain (default: 32dB. Range 0-40 in 8dB steps)
--vga-gain               set VGA gain (default: 50dB. Range 0-62 in 2dB steps)
--samplerate             set sample rate (default: 2400000Hz)
--ppm                    ppm correction (default: 0)

      limesdr-specific options (use with --device-type limesdr)

--limesdr-verbosity      set verbosity level for LimeSDR messages
--limesdr-serial         serial number of desired device
--limesdr-channel        set number of an RX channel
--limesdr-oversample     set RF oversampling ratio
--limesdr-gain           set normalized gain (range: 0.0 to 1.0)
--limesdr-lpfbw          set LPF bandwidth
--limesdr-bw             set bandwidth

      SoapySDR-specific options (use with --device-type soapy)

--device <string>          select/configure device
--channel <num>            select channel if device supports multiple channels (default: 0)
--antenna <string>         select antenna (default depends on device)
--bandwidth <hz>           set the baseband filter width (default: 3MHz, SDRPlay: 5MHz)
--enable-agc               enable Automatic Gain Control if supported by device
--gain-element <name>:<db> set gain in dB for a named gain element

      ifile-specific options (use with --ifile)

--ifile <path>           read samples from given file ('-' for stdin)
--iformat <type>         set sample format (UC8, SC16, SC16Q11)
--throttle               process samples at the original capture speed

      Output modes

--raw                    Show only messages hex values
--modeac                 Enable decoding of SSR Modes 3/A & 3/C
--mlat                   display raw messages in Beast ascii mode
--onlyaddr               Show only ICAO addresses (testing purposes)
--metric                 Use metric units (meters, km/h, ...)
--gnss                   Show altitudes as HAE/GNSS when available
--quiet                  Disable output to stdout. Use for daemon applications
--show-only <addr>       Show only messages from the given ICAO on stdout
--snip <level>           Strip IQ file removing samples < level

      Decoder settings

--gain <db>              Set gain in dB (default: varies by SDR type)
--freq <hz>              Set frequency (default: 1090 Mhz)
--fix                    Enable single-bit error correction using CRC
--fix-2bit               Enable two-bit error correction using CRC
                          (use with caution!)
--no-fix                 Disable error correction using CRC
--no-fix-df              Disable error correction of the DF message field
                          (reduces CPU requirements)
--enable-df24            Enable decoding of DF24 Comm-D ELM messages
--lat <latitude>         Reference/receiver latitude for surface positions
--lon <longitude>        Reference/receiver longitude for surface positions
--max-range <distance>   Absolute maximum range for position decoding (in NM)

      Adaptive gain

--adaptive-burst                     Adjust gain for too-loud message bursts
--adaptive-burst-change-delay <s>     Set delay after changing gain before
                                       resuming burst control (seconds)
--adaptive-burst-alpha <a>            Set burst rate smoothing factor
                                       (0..1, smaller=more smoothing)
--adaptive-burst-loud-rate <r>        Set burst rate for gain decrease
--adaptive-burst-loud-runlength <l>   Set burst runlength for gain decrease
--adaptive-burst-quiet-rate <r>       Set burst rate for gain increase
--adaptive-burst-quiet-runlength <l>  Set burst runlength for gain increase
--adaptive-range                     Adjust gain for target dynamic range
--adaptive-range-target <db>          Set target dynamic range in dB
--adaptive-range-alpha <a>            Set dynamic range noise smoothing factor
                                       (0..1, smaller=more smoothing)
--adaptive-range-percentile <p>       Set dynamic range noise percentile
--adaptive-range-change-delay <s>     Set delay after changing gain before
                                       resuming dynamic range control (seconds)
--adaptive-range-scan-delay <s>       Set scan interval for dynamic range
                                       gain scanning following a gain decrease
                                       due to an increase in noise (seconds)
--adaptive-range-rescan-delay <s>     Set periodic rescan interval for dynamic
                                       range gain scanning (seconds)
--adaptive-min-gain <g>              Set gain adjustment range lower limit (dB)
--adaptive-max-gain <g>              Set gain adjustment range upper limit (dB)
--adaptive-duty-cycle <p>            Set adaptive gain duty cycle % (1..100)

      Network connections

--net                    Enable networking with default ports unless overridden
--no-modeac-auto         Don't enable Mode A/C if requested by a net connection
--net-only               Enable just networking, no RTL device or file used
--net-bind-address <ip>  IP address to bind to (use 127.0.0.1 for private)
--net-ri-port <ports>    TCP raw input listen ports  (default: 30001)
--net-ro-port <ports>    TCP raw output listen ports (default: 30002)
--net-sbs-port <ports>   TCP BaseStation output listen ports (default: 30003)
--net-bi-port <ports>    TCP Beast input listen ports  (default: 30004,30104)
--net-bo-port <ports>    TCP Beast output listen ports (default: 30005)
--net-stratux-port <ports>  TCP Stratux output listen ports (default: disabled)
--net-ro-size <size>     TCP output minimum size (default: 0)
--net-ro-interval <rate> TCP output memory flush rate in seconds (default: 0)
--net-heartbeat <rate>   TCP heartbeat rate in seconds
                          (default: 60 sec; 0 to disable)
--net-buffer <n>         TCP buffer size 64Kb * (2^n) (default: n=0, 64Kb)
--net-verbatim           Make output connections default to verbatim mode
                           (forward all messages without correction)
--forward-mlat           Allow forwarding of received mlat results

      Stats and json output

--stats                  Show stats summary at exit.
--stats-every <seconds>  Show and reset stats every <seconds> seconds
--stats-range            Collect/show range histogram
--write-json <dir>       Periodically write json output to <dir>
                          (for serving by a separate webserver)
--write-json-every <t>   Write json aircraft output every t seconds (default 1)
--json-stats-every <t>   Write json stats output every t seconds (default 60)
--json-location-accuracy <n>  Accuracy of receiver location in json metadata
                          (0=no location, 1=approximate, 2=exact)

      Interactive mode

--interactive                       Interactive mode refreshing data on screen.
                                     Implies --throttle
--interactive-ttl <sec>             Remove from list if idle for <sec>
--interactive-show-distance         Show aircraft distance and bearing
                                     (requires --lat and --lon)
--interactive-distance-units <u>    Distance units ('km', 'sm', 'nm')
--interactive-callsign-filter <r>   Filter rows by callsign against regex

      Misc

--wisdom <path>          Read DSP wisdom from given path
--version                Show version, build and DSP options
--help                   Show this help
root@dd0f7681dade:/tmp# dump1090-fa --help

[shawaj]

have set this as a draft for now, as my mode-s beast hasn't arrived yet so can't actually physically test it right now.

@nowiresfil - do you have a mode-s beast you could try it with? or one you could attach to balena device and I could poke around at. if not, no worries - just i will have to wait until i have the hardware to test.

also, i do not have a hackrf, bladerf, limesdr or soapysdr to test with...so if there are any volunteers?

once tested, I will add readme docs/setup instructions (hence leaving as draft for now)

[nowiresfil]

I can test with modesbeast, or setup a spare pi with remote access and spare beast so you can test, but I'm currently working away and not due to return home until around mid June. Cheers ...phil

…

On Wed, 29 May 2024, 09:13 Aaron Shaw, ***@***.***> wrote: have set this as a draft for now, as my mode-s beast hasn't arrived yet so can't actually physically test it right now. @nowiresfil <https://github.com/nowiresfil> - do you have a mode-s beast you could try it with? or one you could attach to balena device and I could poke around at. if not, no worries - just i will have to wait until i have the hardware to test. also, i do not have a hackrf, bladerf, limesdr or soapysdr to test with...so if there are any volunteers? once tested, I will add readme docs/setup instructions (hence leaving as draft for now) — Reply to this email directly, view it on GitHub <#104 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/APBVZIIHHU5AVJOYKM3INJLZEUFQDAVCNFSM6AAAAABIN2AV2KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCMZWGI2TCMJQGA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[shawaj]

@nowiresfil no probs - i think i should receive the hardware by then for testing, but if not ping back here when you return home and we can set something up :-)

[ketilmo]

Awesome work! Feel free to let me know if you need any support on this.

[shawaj]

Will do @ketilmo - mainly just need help with testing.

So unless you have the hardware then I'll just wait for the postman 😂

[ketilmo]

That sounds good, @shawaj! Unfortunately, I don't have the Mode-S Beast, so I won't be much help with testing. I'm excited to hear how it goes!

[shawaj]

got my beast now and have soldered it. so will start testing this week

[ketilmo]

Great, I'm looking forward to hearing how it goes. Fingers crossed for a smooth deployment.

[shawaj]

Currently getting following error:

 dump1090-fa  [beast-splitter]    serial(/dev/beast): opening port at 3000000bps
 dump1090-fa  [beast-splitter]    serial(/dev/beast): i/o error: No such file or directory

Guessing it is a balena permissions error but investigating :-)

[shawaj]

ok - all good now. Got it working.

Just need to do one more commit and then will mark as ready :-)

[shawaj]

Unfortunately, adding device /dev/ttyUSB0 to the docker-compose.yml messes things up for any people who do not have a serial device connected to their Pi. But this is needed for the Mode-S Beast.

The only way around this, as far as I can tell, is to use privileged: true for dump1090-fa container.

I don't see that this would cause any problems but just wanted to mention it.

[shawaj]

@ketilmo all tested and working now, both with Mode-S Beast and with RTL-SDR based devices.

I also have some people testing with the other hardware options too :-)

Oh and just FYI, I decided to work on #109 separately, to avoid things never getting merged due to my limited time 👍

[ketilmo]

What a massive achievement, @shawaj! A big thanks for implementing this! 👏🏻

I have reviewed the pull request, and it looks great. Good work on recruiting testers for the alternative hardware, too.

Now, I’m very tempted to order a Mode-S Beast. Where did you order yours from?

[ketilmo]

Unfortunately, adding device /dev/ttyUSB0 to the docker-compose.yml messes things up for any people who do not have a serial device connected to their Pi. But this is needed for the Mode-S Beast.

The only way around this, as far as I can tell, is to use privileged: true for dump1090-fa container.

I don't see that this would cause any problems but just wanted to mention it.

I agree, that should be fine.

[shawaj]

What a massive achievement, @shawaj! A big thanks for implementing this! 👏🏻

I have reviewed the pull request, and it looks great. Good work on recruiting testers for the alternative hardware, too.

Now, I’m very tempted to order a Mode-S Beast. Where did you order yours from?

I think the only place to get them from is https://webshop.jetvision.de/en/mode-s-beast/?v=79cba1185463

But there might be resellers I'm not sure.

They sell the case and you can have it assembled too but that adds a bit extra on top.

Not cheap but I'd been looking for a good excuse to get one for a while 😂😂😂

[ketilmo]

Thanks a lot for sharing, @shawaj! And for giving me a good excuse for ordering this hardware, too! 😄 Does it perform well so far?

[shawaj]

Thanks a lot for sharing, @shawaj! And for giving me a good excuse for ordering this hardware, too! 😄 Does it perform well so far?

Unclear yet to be honest. At the moment it is sat on my desk with an indoor spring antenna for dev purposes so it's not picking up much. I need to go and put it on my proper setup outside at some point!

Also realised I've soldered the LEDs the wrong way around. Doh!🤦😂

[ketilmo]

Stuff like that happens! Hope the permanent installation will deliver rewards in terms of great reception! 🚀😊

[ketilmo]

PS! Is this board enough: https://webshop.jetvision.de/en/product/mode-s-beast-kit/?v=c2f3f489a005?

Or will you need one of the listed
GPS modules in addition? The docs seem a bit minimal.

[shawaj]

Yes I just got that one.

I didn't get a GPS. I don't know exactly what those additional boards are for to be honest.

[ketilmo]

Great, thanks!