HamSearch

HamSearch is a Mystic BBS add-on for looking up amateur radio callsigns using FCC ULS data from inside the BBS.

It runs as a Python 3 MPY script in Mystic and uses a local SQLite database for faster lookups, with fallback support for the FCC flat data files.

• Search amateur radio callsigns from inside Mystic BBS
• Uses locally downloaded FCC ULS data
• Builds a local SQLite database for faster searches
• Can fall back to FCC flat files if needed
• Displays:
  • callsign
  • operator class
  • license status
  • grant / expiration / cancellation dates when available
  • name and mailing address
  • previous callsign references when available
  • recent history/status entries when available

• Mystic BBS with Python 3 MPY support
• Python 3 installed on the host system
• Internet access on the host system for FCC downloads
• Disk space for FCC data files and SQLite database

``getdb.py`` downloads the current FCC amateur ULS ZIP archive, extracts the needed files into a local ``data/`` directory, and builds:

data/hamsearch.db

The Mystic script ``hamserach.mpy`` then uses that SQLite database for lookups.

If SQLite is not available, the script can still fall back to the FCC flat files.

The current builder is designed to work with these FCC files when present:

• ``AM.dat``
• ``EN.dat``
• ``HD.dat``
• ``HS.dat``

These are used for current license data, operator class, mailing information, and historical references such as previous callsigns and status history.

Create a directory for HamSearch inside your Mystic scripts area.

Example:

/mystic/themes/default/scripts/hamsearch/

Place these files in that directory:

• ``hamsearch.mpy``
• ``getdb.py``
• ``hshdr.ans``

Run the database builder from the HamSearch directory on your host system:

python3 getdb.py

This should:

• download the FCC amateur ZIP file
• create a ``data/`` directory if needed
• extract the FCC data files
• build ``data/hamsearch.db``

After it finishes, your directory should look something like this:

hamsearch/
  hamserach.mpy
  getdb.py
  hshdr.ans
  hamsearch.log
  data/
    AM.dat
    EN.dat
    HD.dat
    HS.dat
    hamsearch.db

Open ``hamserach.mpy`` and set the ``DB_FOLDER`` value to point to your HamSearch data directory.

Example:

DB_FOLDER = "/home/youruser/mystic/themes/default/scripts/hamsearch/data/"

This path should point to the folder containing:

• ``hamsearch.db``
• ``EN.dat``
• ``AM.dat``
• ``HD.dat``
• ``HS.dat``

Make sure the Mystic process/user can read:

• ``hamsearch.mpy``
• ``hshdr.ans``
• the ``data/`` directory
• ``hamsearch.db``
• the extracted FCC ``.dat`` files

In Mystic, create a menu item for HamSearch and use the Python 3 MPY menu command:

GZ

For the script path/data, point it to your HamSearch script.

Example concept:

After adding the menu item, log into the BBS and test:

• a valid callsign
• an invalid callsign
• pressing Enter on a blank input
• a callsign with previous callsign data, if available

• The preferred mode is SQLite for faster lookups.
• If SQLite is missing, HamSearch can fall back to flat FCC files.
• Re-running ``getdb.py`` later should refresh the data and rebuild the SQLite DB.
• ``hamsearch.log`` can be used to review the update/build process.

If HamSearch says it cannot find the database:

• verify ``DB_FOLDER`` in ``hamserach.mpy``
• verify ``data/hamsearch.db`` exists
• verify Mystic can read the files
• verify ``getdb.py`` completed successfully

Check the following:

• confirm you used ``GZ``
• confirm Mystic is configured for Python 3 MPY scripts
• confirm the script path is correct

Try the following:

• re-run ``getdb.py``
• inspect ``hamsearch.log``
• verify the FCC files were extracted into the ``data/`` directory

The main script filename in the repo is currently:

hamsearch.mpy

That spelling is preserved for compatibility with the current repository layout.

At some point, it would be a good idea to rename it to:

hamsearch.mpy

If that rename happens later, make sure to also update:

• the Mystic menu entry
• install documentation
• any wiki references
• any paths/scripts that call it directly

• Better formatting of results
• About/info screen with database build date
• More advanced search options
• Better handling of historical callsign data
• Better handling of silent key related status/history records
• Logging / maintenance tools
• Repo filename cleanup

• GitHub Repo: HamSearch on GitHub
• Mystic BBS Wiki: Mystic BBS Documentation

Things worth remembering:

• ``getdb.py`` is run from the host OS, not from inside Mystic
• ``hamsearch.mpy`` is what Mystic runs
• ``hshdr.ans`` is optional display polish, but should stay with the script
• SQLite should be the default operational mode going forward

mystic bbs hamradio amateur_radio python sqlite fcc projects