{{:projects:hs_logo.jpg?400 |}}====== 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.

----

===== Project Info =====

^ Item ^ Details ^
| Project Name | HamSearch |
| Purpose | Amateur radio callsign lookup inside Mystic BBS |
| Platform | Mystic BBS |
| Language | Python 3 |
| Data Source | FCC ULS Amateur Radio database |
| Current Search Script | ``hamserach.mpy`` |
| Database Builder | ``getdb.py`` |
| Header File | ``hshdr.ans`` |

----

===== Features =====

  * 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

----

===== Included Files =====

^ File ^ Purpose ^
| ``hamsearch.mpy`` | Main Mystic Python 3 search script |
| ``getdb.py`` | Downloads FCC data, extracts files, builds SQLite DB |
| ``hshdr.ans`` | ANSI header / display file |
| ``install.txt`` | Plain text install instructions |

----

===== Requirements =====

  * 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

----

===== How It Works =====

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

<code>
data/hamsearch.db
</code>

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.

----

===== FCC Data Files Used =====

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.

----

===== Installation =====

===== 1. Create a HamSearch directory =====

Create a directory for HamSearch inside your Mystic scripts area.

Example:

<code>
/mystic/themes/default/scripts/hamsearch/
</code>

----

===== 2. Copy the project files =====

Place these files in that directory:

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

----

===== 3. Run getdb.py =====

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

<code bash>
python3 getdb.py
</code>

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:

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

----

===== 4. Edit the database path in hamserach.mpy =====

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

Example:

<code python>
DB_FOLDER = "/home/youruser/mystic/themes/default/scripts/hamsearch/data/"
</code>

This path should point to the folder containing:

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

----

===== 5. Set file permissions =====

Make sure the Mystic process/user can read:

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

----

===== 6. Add a Mystic menu command =====

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

<code>
GZ
</code>

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

Example concept:

^ Field ^ Value ^
| Command | ``GZ`` |
| Data | ``/full/path/to/hamsearch.mpy`` |

----

===== 7. Test the script =====

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

----

===== Notes =====

  * 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.

----

===== Troubleshooting =====

==== Database not found ====

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

==== Menu item does not work ====

Check the following:

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

==== Searches fail ====

Try the following:

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

----

===== Current Cleanup Note =====

The main script filename in the repo is currently:

<code>
hamsearch.mpy
</code>

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

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

<code>
hamsearch.mpy
</code>

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

----

===== Planned Improvements =====

  * 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

----

===== Links =====

  * GitHub Repo: [[https://github.com/mobbyg/hamsearch|HamSearch on GitHub]]
  * Mystic BBS Wiki: [[https://wiki.mysticbbs.com|Mystic BBS Documentation]]

----

===== SysOp Notes =====

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

----

{{tag>mystic bbs hamradio amateur_radio python sqlite fcc projects}}