| .. | ||
| CMakeLists.txt | ||
| m17demod.cpp | ||
| m17demod.h | ||
| m17demodbaseband.cpp | ||
| m17demodbaseband.h | ||
| m17demodbaudrates.cpp | ||
| m17demodbaudrates.h | ||
| m17demodfilters.cpp | ||
| m17demodfilters.h | ||
| m17demodgui.cpp | ||
| m17demodgui.h | ||
| m17demodgui.ui | ||
| m17demodplugin.cpp | ||
| m17demodplugin.h | ||
| m17demodprocessor.cpp | ||
| m17demodprocessor.h | ||
| m17demodsettings.cpp | ||
| m17demodsettings.h | ||
| m17demodsink.cpp | ||
| m17demodsink.h | ||
| m17demodwebapiadapter.cpp | ||
| m17demodwebapiadapter.h | ||
| m17statustextdialog.cpp | ||
| m17statustextdialog.h | ||
| m17statustextdialog.ui | ||
| readme.md | ||
M17 demodulator
Introduction
This plugin is available only on Linux.
This plugin demodulates and decodes transmissions made in the M17 protocol M17 is a fully Open Source and Open Source audio codec based project (Codec2) for FM based digital voice amateur radio. More information is available here
Main interface
There are 3 main sections
- A General settings: common RF settings analogous to what exists in the DSD demod plugin
- B Digital common: common digital data displays
- C Digital tabs: Four panels are displayed in a tabbed arrangement and each one can be selected by clicking on its corresponding tab on the right. These are from top to bottom:
- Common digital settings and displays
- SMS data
- APRS data
- BER test data
A: General settings
A.1: Frequency shift from center frequency of reception
Use the wheels to adjust the frequency shift in Hz from the center frequency of reception. Left click on a digit sets the cursor position at this digit. Right click on a digit sets all digits on the right to zero. This effectively floors value at the digit position. Wheels are moved with the mousewheel while pointing at the wheel or by selecting the wheel with the left mouse click and using the keyboard arrows. Pressing shift simultaneously moves digit by 5 and pressing control moves it by 2.
A.2: Channel bandwidth before discriminator
This is the bandwidth of the pre-discriminator filter
A.3: Channel power
Total power in dB relative to a ±1.0 amplitude signal received in the pass band.
A.4: Channel power bar graph
This is the same as the one found in many other Rx channels. One should watch that the peaks never exceed the 0dB (right most) mark.
A.5: Activate status text log
Check to send the status text to the log. Uncheck to dismiss sending.
A.6: View status text log
Click to open a dialog to view the status text lines log:
A.6.1: Clear log
Push this button to clear the log
A.6.2: Pin to last line
Use this toggle to pin or unpin the log to the last line
A.6.3: Save log to file
Save the present log content to a file
A.6.4: Timestamp
Each line in the log starts with the timestamp when the status line was fetched from the decoder
A.6.5: Status text
One line per status text. SMS or APRS data if applicable is logged next in the same way.
A.7: Audio volume
Linear multiplication factor.
A.8: Squelch level
The level corresponds to the channel power above which the squelch gate opens.
A.9: Squelch time gate
Number of milliseconds following squelch gate opening after which the signal is declared open. There is a delay line for the samples so samples applied to the decoder actually start at the beginning of the gate period not losing any samples. 0 means squelch is declared open with no delay.
A.10: High-pass filter for audio
Use this switch to toggle high-pass filter on the audio
A.11: Audio mute, squelch indicator and select audio output device
Left click to mute/unmute audio. This button lights in green when the squelch opens.
If you right click on it, it will open a dialog to select the audio output device. See audio management documentation for details.
B: Digital common
B.1: Source callsign
Callsign of the emitter
B.2: Destination callsign
Callsign of the recipient. When an empty callsign is used it means the transmission is addressed to all stations and "BROADCAST" is shown (as on the screenshot).
B.3: Type information
Displays the transmission type information contained in the LSF (Link Setup Frame).
- First word first part (before colon):
- PKT: Packet
- STR: Stream
- First word second part (after colon):
- For packet type:
- UNK: unknown
- RAW: raw packet
- ENC: encapsulated i.e. SMS, APRS...
- For stream type:
- UNK: unknown
- D/D: all data
- V/V: all voice
- V/D: voice and data mix
- For packet type:
- Channel Access Number: this is a 0..15 code displayed after the CAN label
B.4: LSF CRC
This is the 16 bit CRC of the Link Setup Frame.
B.5: Distance to station (QRB)
This is the distance in kilometers to the remote station from the location that is set as the current station location. This information is updated only if GNSS data is available in the meta section of the LSF. The last valid data is displayed.
B.6: Bearing to station (QTF)
This is the bearing in degrees to the remote station from the location that is set as the current station location. This information is updated only if GNSS data s available in the meta section of the LSF. The last valid data is displayed.
C1: Digital tabs: settings
This is activated when the tab with the gear icon (top most) is selected.
C1.1: FM signal scope
This display shows the sampled points of the demodulated FM signal in a XY plane with X as the instantaneous signal and Y as the signal delayed by the symbol period. This effectively shows symbol transitions with an accumulation of points around the 16 possible transitions which ideal position is represented by small crosshairs.
You can adjust FM deviation and demodulator frequency shift to match positions as closely as possible. The figure normally shows a slanted profile as displayed on the screenshot.
C1.2: Baud rate
Symbol rate in Bauds. For now the standard value of 4.8 kBaud is the only possible choice. This is a provision for possible experimentations with protocol derivatives later.
C1.3: Synchronization status
Displays the message synchronization data:
- Unlocked: no synchronization
- BERT: BERT frame
- Stream: Stream type frame
- Raw: Packet of raw type
- AX.25: Packet of AX25 type
- APRS: Packet of APRS type
- 6LoWPAN: Packet of 6LoWPAN type
- IPv4: Packet of IPv4 type
- SMS: Packet of SMS type
- Winlink: Packet of Winlink type
- Unknown: A synchronization is obtained but is not supported
C1.4: Data Carrier Detected
Turns green if DCD status is on
C1.5: Transmission locked
Turns green if the Rx clock is locked to the Tx clock
C1.6: FM discriminator status
Shows status information on FM discriminator:
- EVM: C4FM symbols Error Vector Magnitude
- Dev: FM deviation factor from ideal. Tune FM deviation to make the value closest to 1.0
- Ofs: FM offset. Ideally should be between -0.15 and 0.15 and closest to 0.0. Tune the demodulator offset to make the value closest to 0.0.
C1.7: Decoder status
Shows status information on the decoder:
- Clk: difference between Tx and Rx clocks normalized should be 1.0 when locked
- Samp: sampling point offsets from 0 to 9 as there are 10 samples per symbols at 48 kS/s and 4800 Baud. Numbers are arranged in this order: symbol, sync and clock. The clock offset wins. These numbers should not differ by more than 1 (0 to 9 wrapping considered).
- Vit: Viterbi cost. Should be positive and as low as possible. -1 if unavailable.
C1.8: FM signal scope controls
C1.8.1: Transition constellation or symbol synchronization signal toggle
For now this is ineffective and only transition constellation is available.
C1.8.2: Trace length
This button tunes the length of the trace displayed on C1.1. Units are milliseconds. Default value is 300.
C1.8.3: Trace stroke
This button tunes the stroke of the points displayed on C1.1. The trace has limited persistence based on alpha blending. This is the 8 bit unsigned integer value of the trace alpha blending. Default value is 200.
C1.8.4: Trace decay
This button tunes the persistence decay of the points displayed on C1.1.1. The trace has limited persistence based on alpha blending. This controls the alpha value of the black screen printed at the end of each trace and thus the trace points decay time. The value is 255 minus the displayed value using 8 bit unsigned integers.
- A value of 0 yields no persistence
- A value of 255 yields infinite persistence
- Default value is 200s
C1.9: FM deviation
This is the expected FM deviation. As per M17 standard this should be ±2.4 kHz. A different value may be used for experimentation with the corresponding deviation on the transmitter side.
C2: Digital tabs - SMS
This is activated when the tab with the message chat icon (second from top) is selected and is used to display the content of SMS messages.
C2.1: Header
A header is displayed before each message with the timestamp the source and destination calls
C2.2: Message
The message contents follows
C3: Digital tabs - APRS
This is activated when the tab with the world icon (third from top) is selected and is used to display APRS messages. Note that the M17 demod will connect automatically to the APRS feature and will be displayed in its available sources list.
C3.1: Clear messages
Use this button to clear the messages table (C3.2)
C3.2: Messages table
This is the APRS messages table similar to the one in the packet demodulator. It has the following columns:
- From: The source address / callsign of the sender of the packet.
- To: The destination address.
- Via: List of addresses of repeaters the packet has passed through or directed via.
- Type: The AX.25 frame type.
- PID: Protocol Identifier.
- Data (ASCII): The AX.25 information field displayed as ASCII.
C4: Digital tabs - BERT
This is activated when the tab with the ruler icon (bottom most) is selected.
BERT stands for Bit Error Rate Testing and is a special mode used to test transmission. The M17 modulator must also be set to BERT mode for the complete setup to work. In this mode there is no link information sent (LSF/LICH) just a synchronization word and a predefined pseudo random sequence that gets synchronized at the receiver. Then the total bits and bits in error are counted.
C4.1: Total counts
Toggle total vs current counts (see next)
C4.2: Current counts
Toggle current vs total counts. "Current" counts are calculated over a period of about one second. Thus in this mode all numbers are "per second".
C4.3: Counts
bits in error / total bits.
C4.4: BER vs counts diagram
Select between bit error rate or error count display in the diagram (C4.8)
C4.5: Bit Error Rate
This is the ratio between bits in error over total bits.
C4.6: History length (seconds)
Sets the maximum number of points displayed in the diagram (C4.8) corresponding to this period of time. The diagram keeps filling until this number is reached then it slides over time.
You can choose between 10 to 3600 seconds in 10 seconds steps with a default of 60 seconds.
C4.7: Reset BER PRBS
Resets the pseudo random generator and therefore the counts.
C4.8: Timeline diagrams
A diagram with a timeline on the horizontal axis and various data depending on the current data type selected on vertical axis is displayed. If no valid BER data is received the space remains empty.
There are 4 combinations and therefore 4 possible diagrams:
Total error counts display
Total BER display
As expected the values decay with time if no more errors are received. Note that in BER mode the vertical axis has a logarithmic scale which is more convenient for BER values. The minor ticks are set at tenths of the major ticks intervals
Current error counts display
Current BER display
As this is a logarithmic scale zero values are skipped.