PyFT8 2.0.0__tar.gz → 2.1.0__tar.gz

{pyft8-2.0.0 → pyft8-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFT8
-Version: 2.0.0
+Version: 2.1.0
 Summary: FT8 Decoding and Encoding in Python with test/loopback code
 Author-email: G1OJS <g1ojs@yahoo.com>
 License-Expression: GPL-3.0-or-later
@@ -22,7 +22,18 @@ Dynamic: license-file
 
 This repository contains the source code for PyFT8, an all-Python open source FT8 transceiver that you can run as a basic GUI or from the command line to receive and transmit. Decoding performance (number of decodes) is about 70% of that achieved by WSJT-x in NORM mode, but (tbc) slightly above ft8_lib. At the time of writing (3-3-26) this new version 2.0.0 establishes the prior cli functionality plus an interesting GUI, on which I intend to build a transceiver function shortly. 
 
-<img width="714" height="968" alt="image" src="https://github.com/user-attachments/assets/be165135-d18d-42d9-848c-c455b9d99275" />
+PyFT8 is somewhat experimental, with a focus on demonstrating FT8 written in Python, but can be used as a standalone replacement for WSJT-x and other software. However, please see [Rig control](https://github.com/G1OJS/PyFT8/blob/main/README.md#rig-control) below.
+
+## Features
+ - Doesn't try to do everything, so launches quickly (~2 seconds on my old Dell Optiplex 790)
+ - use with or without gui (receive and send messages via command line commands)
+ - GUI provides simultaneous views of odd and even cycles
+ - messages overlaid on waterfall signals that produce them
+ - automatically chooses clearest Tx frequency
+ - modern programming language throughout
+ - finds sound cards by keywords so follows them if windows moves them ...
+
+https://github.com/user-attachments/assets/1a2e6b24-a6cc-4360-af50-6f810b99da33
 
 ## Motivation
 This started out as me thinking "How hard can it be, really?" after some frustration with Windows moving sound devices around and wanting to get a minimal decoder running that I can fully control. 
@@ -36,7 +47,7 @@ If you want to install this software without getting into the code, you can inst
 pip install PyFT8
 ```
 
-Once installed, you can use the following commands to run it. 
+Once installed, you can use the following commands to run it. Otherwise, please download or browse the code, or fork the repo and play with it! If you do fork it, please check back here as I'm constantly (as of Jan 2026) rewriting and improving.
 
 |Usage | Command example| Notes |
 |----------------------|----------------------|----------------------|
@@ -45,8 +56,12 @@ Once installed, you can use the following commands to run it.
 | Command line Rx without a GUI | pyft8 -i "Keyword1, Keyword2" -n| |
 | Command line transmit | pyft8 -o "Keyword1, Keyword2" -m "CQ G1OJS IO90"| Tx on next cycle. You supply the PTT control method.|
 | Command line create a wav file | pyft8 -w "Mywav.wav" -m "CQ G1OJS IO90"| -w "Mywav.wav" can be omitted |
+| Launch configured GUI|pyft8 -i "Keyword1, Keyword2" -o "Keyword1, Keyword2" -c {config folder}| Config folder stores PyFT8.ini (your callsign, grid, buttons) and PyFT8.adi log file. Run this once to create default PyFT8.ini file.|
+
+### Rig control 
+PyFT8 doesn't currently support CAT control for rigs in general. However, I've included the Python code that I use with my Icom IC-7100 in the file 'rigctrl.py'. You can modify this to control your own rig of course if you know Python.
 
-Otherwise, please download or browse the code, or fork the repo and play with it! If you do fork it, please check back here as I'm constantly (as of Jan 2026) rewriting and improving.
+Alternatively, you can run PyFT8 without rig control; if there is no rig found, PyFT8 defaults to running without a rig connected. In this case, you need to provide your own PTT method and note that the band buttons will only set the information used for logging QSOs to the PyFT8.adi file. Or you can use PyFT8 as Rx-only.
 
 ## Performance Compared with FT8_lib and WSJT-x
 
@@ -70,6 +85,12 @@ and distributed under the GNU General Public License v3 (GPL-3.0), hence the use
 Also thanks to [Robert Morris](https://github.com/rtmrtmrtmrtm) for [basicft8(*1)](https://github.com/rtmrtmrtmrtm/basicft8) - the first code I properly read when I was wondering whether to start this journey. (*1 note: applies to FT8 pre V2)
 
 ## Useful resources:
+**The QEX paper**
+ - [The FT4 and FT8 Communication Protocols](https://wsjt.sourceforge.io/FT4_FT8_QEX.pdf)
+ - [Ref 14 from the above paper at the Internet Archive](https://web.archive.org/web/20250409140104/https://www.arrl.org/files/file/QEX%20Binaries/2020/ft4_ft8_protocols.tgz)
+
+Note - section 9 of the paper states that the above 2 resources are in the public domain, with some restrictions. All other resources including the source code are protected by copyright but licensed under Version 3 of the GNU General Public License (GPLv3).
+
 **WSJTx - focussed:**
  - [WSJT-X on Sourceforge](https://sourceforge.net/p/wsjt)
  - [W4KEK WSJT-x git mirror](https://www.repo.radio/w4kek/WSJT-X) (searchable)

pyft8-2.1.0/PyFT8/gui.py

@@ -0,0 +1,108 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import time, queue
+from matplotlib import rcParams
+from matplotlib.animation import FuncAnimation
+from matplotlib.widgets import Slider, Button
+
+rcParams['toolbar'] = 'None'
+# ================== WATERFALL ======================================================
+
+class Msg_box:
+    def __init__(self, fig, ax, tbin, fbin, w, h, text, colors, attached_params, onclick, expire = 0):
+        from matplotlib.patches import Rectangle
+        self.onclick = onclick
+        self.origin = (tbin, fbin)
+        rect = Rectangle(self.origin, width=w, height=h, alpha=0.6, edgecolor='lime', lw=2)
+        self.patch = ax.add_patch(rect)
+        self.text_inst = ax.text(tbin, fbin+2, text, fontsize='small', fontweight='bold' )
+        self.cid = fig.canvas.mpl_connect('button_press_event', self._onclick)
+        self.set_properties(tbin, text, colors, attached_params, expire)
+
+    def set_properties(self, tbin, text, colors, attached_params, expire):
+        self.patch.set_x(tbin)
+        self.attached_params = attached_params
+        self.text_inst.set_x(tbin)
+        self.text_inst.set_text(text)
+        self.text_inst.set_color(colors[1])
+        self.expire = expire
+        self.patch.set_facecolor(colors[0])
+        self.patch.set_visible(True)
+        self.text_inst.set_visible(True)
+
+    def hide_if_expired(self):
+        if time.time() > self.expire > 0:
+            self.patch.set_visible(False)
+            self.text_inst.set_visible(False)
+
+    def _onclick(self, event):
+        b, _ = self.patch.contains(event)
+        if(b):
+            self.onclick(self.text_inst.get_text(), self.attached_params)
+
+class Gui:
+    def __init__(self, dBgrid, hps, bpt, config, on_msg_click, on_control_click):
+        self.mStation = {'c':config['station']['call'], 'g':config['station']['grid']}
+        self.on_msg_click = on_msg_click
+        self.on_control_click = on_control_click
+        self.dBgrid = dBgrid
+        self.hps, self.bpt = hps, bpt
+        self.msg_boxes = {}
+        self.decode_queue = queue.Queue()
+        self.make_layout(config)
+
+    def make_layout(self, config):
+        self.fig, self.ax_wf = plt.subplots(figsize=(10,10), frameon = False)
+        self.fig.canvas.manager.set_window_title('PyFT8 by G1OJS')
+        #self.fig.suptitle("PyFT8 by G1OJS")
+        self.plt = plt
+        plt.tight_layout()
+        self.image = self.ax_wf.imshow(self.dBgrid.T,vmax=120,vmin=90,origin='lower',interpolation='none')
+        wf_ylim = self.ax_wf.get_ylim()
+        self.ax_wf.set_axis_off()
+        
+        self.buttons = []
+        styles = {'ctrl':{'fc':'grey','c':'black'}, 'band':{'fc':'green','c':'white'}}
+        control_buttons = [{'label':'CQ','style':'ctrl','data':None}, {'label':'Repeat last','style':'ctrl','data':None},
+                           {'label':'Tx off','style':'ctrl','data':None}]
+                           #{'label':'Averaging','style':'ctrl','data':None}]
+        for band, freq in config['bands'].items():
+            control_buttons.append({'label':band,'style':'band','data':freq})
+            
+        btn_axs = []
+        for i, btn in enumerate(control_buttons):
+            btn_axs.append(plt.axes([0.05, 0.9 - 0.022 * i, 0.1, 0.02]))
+            style = styles[btn['style']]
+            btn_widg = Button(btn_axs[-1], btn['label'], color=style['fc'], hovercolor='skyblue')
+            btn_widg.data = btn['data']
+            btn_widg.on_clicked(lambda event, btn_widg=btn_widg: self.on_control_click(btn_widg))
+            self.buttons.append(btn_widg)
+        self.ani = FuncAnimation(self.fig, self._animate, interval = 40, frames=(100000), blit=True)
+
+    def post_decode(self, decode):
+        self.decode_queue.put(decode)
+
+    def _show_decode(self, queued_decode):
+        h0_idx, f0_idx, msg, attached_params = queued_decode
+        colors = ['blue', 'white']
+        if msg.startswith("CQ"): colors = ['green', 'white']
+        if self.mStation['c'] in msg: colors = ['yellow', 'black']
+        if msg.startswith(self.mStation['c']): colors = ['red', 'white']
+        if not f0_idx in self.msg_boxes:
+            btn = Msg_box(self.fig, self.ax_wf, h0_idx, f0_idx, 79*self.hps, 8*self.bpt, msg, colors, attached_params, onclick = self.on_msg_click)
+            self.msg_boxes[f0_idx] = btn
+        self.msg_boxes[f0_idx].set_properties(h0_idx, msg, colors, attached_params, expire = time.time() + 28)
+        
+    def _tidy_msg_boxes(self):
+        for fb in self.msg_boxes:
+            self.msg_boxes[fb].hide_if_expired()
+
+    def _animate(self, frame):
+        self.image.set_data(self.dBgrid.T)
+        while not self.decode_queue.empty():
+            self._show_decode(self.decode_queue.get())
+        if (frame % 10 == 0):
+            self._tidy_msg_boxes()
+        return [self.image, *self.ax_wf.patches, *self.ax_wf.texts]
+
+                                    

pyft8-2.1.0/PyFT8/pyft8.py

@@ -0,0 +1,248 @@
+import argparse
+import time
+import os
+import threading
+import numpy as np
+from PyFT8.receiver import Receiver, AudioIn
+from PyFT8.gui import Gui
+from PyFT8.transmitter import AudioOut
+from PyFT8.time_utils import global_time_utils
+
+MAX_TX_START_SECONDS = 2.5
+T_CYC = 15
+
+def load_rigctrl():
+    try:
+        from PyFT8.rigctrl import Rig
+        print("Loaded Rig control")
+        return Rig()
+    except ImportError:
+        print("No Rig control found")
+        return None
+        
+def get_config():
+    import configparser
+    global config
+    config = configparser.ConfigParser()
+    if not os.path.exists(ini_file):
+        config['station'] = {'call':'station_callsign', 'grid':'station_grid'}
+        config['bands'] = {'20m':14.074}
+        with open(ini_file, 'w') as f:
+            config.write(f)
+        print(f"Wrote default config to {ini_file}")
+    print(f"Reading config from {ini_file}")
+    config.read(ini_file)
+
+class FT8_QSO:
+    def __init__(self):
+        self.mStation = {'c':config['station']['call'], 'g':config['station']['grid']}
+        self.band_info = {'b':'20m', 'f':14.074}
+        self.start()
+
+    def start(self):
+        self.last_tx = {'msg':None,'cycle':None}
+        self.oStation = {'c':None, 'g':None}
+        self.times = {'time_on':None, 'time_off':None}
+        self.rpts = {'sent': None, 'rcvd': None}
+        
+    def log_to_adif(self):
+        log_dict = {'call':self.oStation['c'], 'gridsquare':self.oStation['g'], 'mode':'FT8',
+        'operator':self.mStation['c'], 'station_callsign':self.mStation['c'], 'my_gridsquare':self.mStation['g'], 
+        'rst_sent':self.rpts['sent'], 'rst_rcvd':self.rpts['rcvd'], 
+        'qso_date':time.strftime("%Y%m%d", self.times['time_on']), 'qso_date_off':time.strftime("%Y%m%d", self.times['time_off']),
+        'time_on':time.strftime("%H%M%S", self.times['time_on']), 'time_off':time.strftime("%H%M%S", self.times['time_on']),
+        'band':self.band_info['b'], 'freq':self.band_info['f']}
+        if(not os.path.exists(logfile)):
+            with open(adif_log_file, 'w') as f:
+                f.write("header <eoh>")
+        with open(adif_log_file,'a') as f:
+            f.write(f"\n")
+            for k, v in log_dict.items():
+                v = str(v)
+                f.write(f"<{k}:{len(v)}>{v} ")
+            f.write(f"<eor>\n")
+
+def isReport(grid_rpt):     return "+" in grid_rpt or "-" in grid_rpt
+def isRReport(grid_rpt):    return isReport(grid_rpt) and 'R' in grid_rpt
+def isRRR(grid_rpt):        return 'RRR' in grid_rpt
+def isRR73(grid_rpt):       return 'RR73' in grid_rpt
+def is73(grid_rpt):         return '73' in grid_rpt and not isRR73(grid_rpt)
+def isGrid(grid_rpt):       return not isReport(grid_rpt) and not is73(grid_rpt) and not isRR73(grid_rpt) and not isRRR(grid_rpt) 
+
+def progress_qso(clicked_msg, msg_params):
+    global qso
+    their_snr, their_cycle_start_time = msg_params
+    if time.time() - their_cycle_start_time > (15 + MAX_TX_START_SECONDS):
+        print("Try next cycle")
+        return
+    
+    call_a, call_b, grid_rpt, _ = clicked_msg.split()
+    my_station = qso.mStation
+    reply = ""
+
+    if call_a == "CQ":
+        qso.start()
+        qso.times['time_on'] = time.gmtime()
+        qso.oStation = {'c': call_b, 'g': grid_rpt}
+        reply = f"{qso.oStation['c']} {my_station['c']} {my_station['g']}"
+        transmit_threaded(reply)
+        return
+
+    if call_a == my_station['c']:
+        if qso.times['time_on'] is None:
+            qso.times['time_on'] = time.gmtime()
+        qso.oStation['c'] = call_b
+        if isGrid(grid_rpt):
+            qso.oStation = {'c': call_b, 'g': grid_rpt}
+            qso.rpts['sent'] = f"{their_snr:+03d}"
+            reply = f"{qso.oStation['c']} {my_station['c']} {their_snr:+03d}"
+        if isReport(grid_rpt):
+            reply = f"{qso.oStation['c']} {my_station['c']} R{their_snr:+03d}"
+            qso.rpts['rcvd'] = grid_rpt[-3:]
+        if isRReport(grid_rpt) or isRRR(grid_rpt):
+            reply = f"{qso.oStation['c']} {my_station['c']} RR73"
+        if isRR73(grid_rpt):
+            reply = f"{qso.oStation['c']} {my_station['c']} 73"
+        transmit_threaded(reply)
+        
+    if is73(grid_rpt) or " 73" in reply or isRR73(grid_rpt):
+        qso.times['time_off'] = time.gmtime()
+        qso.log_to_adif()
+
+def make_wav(msg, wave_output_file): # move to transmitter.py?
+    symbols = audio_out.create_ft8_symbols(msg)
+    audio_data = audio_out.create_ft8_wave(symbols)
+    audio_out.write_to_wave_file(audio_data, wave_output_file)
+    print(f"Created wave file {wave_output_file}")    
+
+def transmit_threaded(msg, cycle = None): # move to transmitter.py?
+    threading.Thread(target = transmit, args = (msg, cycle,), daemon = True).start()
+
+def transmit(msg, cycle = None): # move to transmitter.py?
+    if output_device_idx is None:
+        print("No output device")
+        return
+    if msg is None:
+        return
+    ct = global_time_utils.cycle_time()
+    print(f"Cycle requested: {cycle}")
+    if cycle is None: # transmit asap
+        cycle = global_time_utils.curr_cycle_from_time()
+        print(f"Cycle clicked: {cycle}")
+        if ct > MAX_TX_START_SECONDS:
+            cycle = 1-cycle # transmit next cycle
+    print(f"Transmit {msg} cycle = {cycle}")
+    symbols = audio_out.create_ft8_symbols(msg)
+    audio_data = audio_out.create_ft8_wave(symbols, f_base = clear_frequencies[cycle])
+    if ct > MAX_TX_START_SECONDS:
+        delay = 15.25 - ct
+        time.sleep(delay)
+    if cycle != global_time_utils.curr_cycle_from_time():
+        time.sleep(T_CYC)
+    if qso:
+        qso.last_tx = {'msg':msg,'cycle':global_time_utils.curr_cycle_from_time()}
+    print(f"Transmitting {qso.last_tx['msg']} cycle = {qso.last_tx['cycle']}")
+    rig.PyFT8_ptt_on()
+    audio_out.play_data_to_soundcard(audio_data, output_device_idx)
+    rig.PyFT8_ptt_off()
+    return True
+
+def wait_for_keyboard():
+    import time
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+
+#============= Callbacks for GUI ==========================================================
+def on_decode(c):
+    if gui:
+        message_cycle_started = global_time_utils.cyclestart_time(time.time())
+        txt = f"{c.msg} ({c.snr:+03d})"
+        gui.post_decode((c.h0_idx, c.f0_idx, txt, (c.snr, message_cycle_started)))
+    print(f"{c.cyclestart_str} {c.snr} {c.dt:4.1f} {c.fHz} ~ {c.msg}")
+
+def on_busy_profile(busy_profile, cycle):
+    if output_device_idx is None:
+        return
+    fmax = 950 if qso.band_info['b']=='60m' else 2000
+    f0_idx, fn_idx = int(500/audio_in.df), int(fmax/audio_in.df)
+    idx = np.argmin(busy_profile[f0_idx:fn_idx])
+    clear_frequencies[cycle] = (f0_idx + idx) * audio_in.df
+    print(f"Set Tx freq to {clear_frequencies[cycle]:6.1f} for cycle {cycle}")
+
+def on_control_click(btn_widg):
+    btn_text, btn_data = btn_widg.label.get_text(), btn_widg.data
+    print(btn_text, btn_data)
+    if btn_text == "CQ":
+        mc, mg = config['station']['call'], config['station']['grid']
+        transmit_threaded(f"CQ {mc} {mg}")
+    if btn_text == "Repeat last":
+        transmit_threaded(qso.last_tx['msg'], cycle =  qso.last_tx['cycle'])
+    if btn_text == "Tx off":
+        rig.PyFT8_ptt_off()
+    if('m' in btn_text):
+        qso.band_info = {'b':btn_text, 'f':btn_data}
+        rig.PyFT8_set_freq_Hz(int(1000000*float(qso.band_info['f'])))
+
+def on_msg_click(clicked_msg, msg_params):
+    progress_qso(clicked_msg, msg_params)
+
+#=============== CLI ========================================================================        
+def cli():
+    global audio_in, audio_out, output_device_idx, rig, gui, qso, ini_file, adif_log_file, clear_frequencies
+    import time
+    parser = argparse.ArgumentParser(prog='PyFT8rx', description = 'Command Line FT8 decoder')
+    parser.add_argument('-c', '--config_folder', help = 'Location of config folder e.g. C:/Users/drala/Documents/Projects/GitHub/G1OJS/PyFT8_cfg', default = './') 
+    parser.add_argument('-i', '--inputcard_keywords', help = 'Comma-separated keywords to identify the input sound device') 
+    parser.add_argument('-v','--verbose',  action='store_true',  help = 'Verbose: include debugging output')    
+    parser.add_argument('-o','--outputcard_keywords', help = 'Comma-separated keywords to identify the output sound device')
+    parser.add_argument('-n','--no_gui',  action='store_true',  help = "Don't create a gui")
+    parser.add_argument('-m','--transmit_message', nargs='?', help = 'Transmit a message')
+    parser.add_argument('-w','--wave_output_file', nargs='?', help = 'Wave output file name', default = 'PyFT8.wav')
+    args = parser.parse_args()
+
+    output_device_idx = None
+    ini_file = f"{args.config_folder}/PyFT8.ini".strip()
+    get_config()
+    qso = FT8_QSO()
+    rig = load_rigctrl()
+
+    if args.transmit_message or args.outputcard_keywords:
+        audio_out = AudioOut()
+        clear_frequencies = [760, 760]
+    
+    if args.outputcard_keywords:
+        outputcard_keywords = args.outputcard_keywords.replace(' ','').split(',')
+        output_device_idx = audio_out.find_device(outputcard_keywords)
+        adif_log_file = f"{args.config_folder}/PyFT8.adi"
+            
+    if args.transmit_message:
+        if not transmit(args.transmit_message):
+            make_wav(args.transmit_message, f"{args.config_folder}/{args.wave_output_file}")      
+    else:
+        audio_in = AudioIn(3100)
+        input_device_idx = audio_in.find_device(args.inputcard_keywords.replace(' ','').split(','))
+        if not input_device_idx:
+            print("No input device")
+        else:
+            gui = None if args.no_gui else Gui(audio_in.dBgrid_main, 4, 2, config, on_msg_click, on_control_click)
+            rx = Receiver(audio_in, [200, 3100], on_decode, on_busy_profile)
+            audio_in.start_streamed_audio(input_device_idx)
+            if gui is not None:
+                gui.plt.show()
+            else:
+                wait_for_keyboard()
+
+
+#================== TEST CODE ============================================================
+print(__name__)
+if __name__ == "__main__":
+    import mock
+    #with mock.patch('sys.argv', ['pyft8', '-i Mic, CODEC', '-o Speak, CODEC', '-cC:/Users/drala/Documents/Projects/GitHub/G1OJS/PyFT8_cfg']):
+    #with mock.patch('sys.argv', ['pyft8', '-i Mic, CODEC']):
+    #with mock.patch('sys.argv', ['pyft8', '-i Mic, CODEC', '-n']):
+    with mock.patch('sys.argv', ['pyft8', '-m',  "CQ G1OJS IO90", '-cC:/Users/drala/Documents/Projects/GitHub/G1OJS/PyFT8_cfg']):
+    #with mock.patch('sys.argv', ['pyft8', '-m',  "CQ G1OJS IO90", '-o', "Speak, CODEC"]):
+        cli()