Metadata-Version: 2.5
Name: kc8jclogger
Version: 1.0.2
Summary: A terminal logger for amateur radio, built for POTA activations
Project-URL: Homepage, https://www.kc8jc.com/kc8jclogger/
Author: James C. Wilson
License-Expression: AGPL-3.0-only
License-File: LICENSE
Keywords: POTA,amateur radio,ham radio,hamlib,logging,rigctld
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Ham Radio
Requires-Python: >=3.11
Requires-Dist: requests>=2.32.3
Requires-Dist: rich>=15.0.0
Requires-Dist: textual>=8.2.8
Requires-Dist: tinydb>=4.8.2
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# KC8JCLogger

## The Logging Software No One Asked For.

KC8JCLogger is a program for logging amateur radio contacts in the terminal. It uses a Text User Interface courtesy of the Textual module for Python. The intent is to provide a simple interface that will run with very, very low computing requirements. It should be able to run anywhere that Python runs (that also has a console of some sort).

The application itself grew out of a utility written to list current POTA activation spots and issue commands through Hamlib to set a transceiver to the frequency and mode of the selected spot. It got a little out of control and grew into something that is *approaching* a real logging package. *Note: I said* **approaching** *for a reason.*

The user interface was chosen very intentionally. I wanted to be able to do all of the things that I needed to do but do them with or without a mouse. I also love the 80s computing aesthetic and color scheme. If you looked at the screenshot and said, “Oh heck yeah!” then this might be for you.

## Features / Options

- Low-friction user interface for fast data entry - Never take your fingers off of the keyboard!  
    (Or use the mouse! I’m not your boss!)
    
- Lists all current POTA activation spots filtered by mode (if desired).
    
- Optional QRZ integration for XML account subscribers.
    
- ADIF export of data based on date range.
    
- Super-slick-kinda-80s-DOS-style-UI via TUI.
    
- Hamlib integration using rigctld and Python bindings.
    
- Database kept in JSON for easy manipulation/consumption by other applications.
    
- Simple configuration in app or via editing plain text files.
    
- Runs anywhere Python can.
    
- Free *as in Libre \[Insert 'Fanfare For The Common Man' Here\]*.
    

## Requirements

- Python3.13.x (latest)
- Hamlib 4.6.x (latest)
    - REQUIRES PYTHON BINDINGS (this could be tricky...see below.)
- Hamlib utilities including rigctld
    - You will need to make sure rigctld is configured correctly and running *before* any of the rig integration will work.
- Textual Python Module
- TinyDB Python Module
- Requests Python Module
- Rich Python Module (if it doesn’t tag along with Textual which it should)
- Configparser Python Module (which is standard on some distros)

## OS Support

I have run this application successfully on Debian and Ubuntu Linux *and* Mac OSX.

*Debian Note:* I’m a wild man and run Debian unstable because most packages on, say, Bookworm are a bit stale for what I was trying to do. Your mileage on different distros will undoubtedly vary.

*Mac Note:* I was able to get everything I needed using [MacPorts](https://www.macports.org). You do need to go into the configuration for the Hamlib package and make sure that it is set up to compile with Python bindings. [This Ticket](https://trac.macports.org/ticket/62580) gives details on how to do that. Of course you can simply compile Hamlib from source on the Mac and get on with your life, but I find that using the package manager with Python modules keeps things nice and clean.

*Windows Note:* I have none. I haven’t tried it on Windows as I don’t have a machine lying around and I don’t use it with my radio stuff anyway.

## Things It WILL NOT Do (Yet?)

- Post contacts to LotW or QRZ or anywhere else.
    
- That thing you were hoping it would do that’s not centered around simple logging or POTA Hunting.
    
- Run on a mobile device. (This is kind of untrue…see the Party Tricks below if you dare!)
    

## Miscellaneous Notes

Here are a few things that might be useful if you try to run this thing.

- There is a file called “POTA_Entities.json”. This was generated by hitting an endpoint on the POTA.app website and consuming all POTA Entities. If there isn’t yet, there will be a button somewhere for updating this file. It. Will. Take. Forever. I’m pulling it down and jamming it into a JSON file so I can query it with the TinyDB module. As a guy who used to develop real applications with databases it makes me cringe, but it was the fastest way for me to get where I was going. And it works. So I’m shipping it. I will probably update that file once in a while. Again, I don’t recommend updating it with any regularity. The entities don’t change that fast.
    
- There is an entry in kc8jclogger.py that reads:  
    *sys.path.append(‘/usr/local/lib/python3.13/site-packages’)*  
    There was a note on one of the 10 million issues I went through that talked about why this needed to be there and emphasized that it wouldn’t be needed in the future. I don’t live in the future, so here it is. You MIGHT have something go sideways with the Hamlib module and altering that path MIGHT fix it. I dunno. It’s all magic to me.
    

## Party Tricks

Why did you read this far? There’s nothing useful beyond this point. Here goes…

Textual has a neat feature that lets an app run on the web. I’ve had great success setting up the app on the machine that is connected to my transceiver and then running the app in a browser on a separate computer.

Why? I dunno. Seemed cool.

How? Like this:

`textual serve --dev -h YOURCOMPUTER -p 8080 kc8jclogger.py`

Then go to https://YOURCOMPUTER:8080 and you will see the app. It will read the config on the host machine and write data to the host. It also does all of the rig control.

You can also start up rigctld on the computer attached to the transceiver and then run rigctld on another computer like this:

`rigctld -m 2 -r YOURCOMPUTER`

YOURCOMPUTER should be the IP address or name of the computer attached to the rig. Then you can run the logger and it will, again, do all of the cool stuff but *this time* all of the data will be local to the machine you’re running the application on. I’m sure there’s a use for this but I don’t know what it is. Be careful and don’t wreck your stuff.