n8acl/hammy_bot repository overview

⁠Hammy, a Ham Radio Discord Bot

Python based Ham Radio Callsign/APRS Discord lookup bot.

⁠Description

This is a Python based, self-hosted, Ham Radio Discord bot that can be added to Ham Radio Discord Servers to add some functionality for various Amatuer Radio Callsign related searches.

⁠Searches

• Search for callsign and get callbook info.
• Search for callsign+ssid on the APRS network to see the last beaconed packet by a station.

Note that this software is intended for use by Amateur Radio Operators only.

⁠API's Used

This bot pulls data from the following locations:

⁠Installation/Setup

⁠Installation Steps

1. Obtain API Keys/Logins
2. Install needed packages, clone Repo and install library dependencies
3. Configure the script

Remember that all the commands shared here are for Linux. So if you want you can run this on a Linux Server or even a Raspberry Pi. (Mine is running on a Raspberry Pi 4 2 GB model with many other bots and scripts running with no issues.)

If you want to run this on a Windows or Mac machine, you will need to install Python3 and be familiar installing from a requirements.txt.

⁠Obtaining API Keys/Logins

The first step in this process will be obtaining the API keys that you need.

⁠APRS.fi API Key

• First and foremost, you will need an APRS.fi⁠ account. On your account page is the API key you will need.

⁠HamQTH.com Login

• To be able to use HamQTH.com for searching (especially International Callsigns), you will need to obtain a username and password for HamQTH.com. Click here to register.⁠

⁠Discord

• Go to: https://discord.com/developers/applications⁠
• Click New Application
• Give it a name (I called it Hammy)
• On the next screen, you can upload an avatar for the bot.
• Click the bot selection under settings
• Click Add Bot
• Give it a Name (I used the same name )
• Then Copy the Bot Token (you will need this for the config.py part of the script along with the APRS.fi keys)
• Turn off Public Bot
• Make sure to turn on the Message Intents Setting under Privileged Gateway Intents.
• Save Settings
• Click OAuth2 and then URL Generator
• For Scope Choose bot and appplications.commands
• For Permissions, choose the following:
  • Under General Permissions:
    • Read Messages/View Channels
  • Under Text Permissions:
    • Send messages
    • Send Messages in threads
    • Embed Links
    • Attach Files
    • Read message History
    • Use Slash Commands
• Copy the generated URL
• Paste it into a browser window Address bar
• Choose the Server you want to authorize it to and then click authorize.
• It should pop into the server.
• Next you will need to get your server id.
  • To get this, you will need to, on Discord, go into User Settings->Advanced and turn on Developer Mode (if it is not already on.)
  • Then just right click on your server's icon and click Copy ID. Then go back into your config.py and paste that ID in the discord_server_id field.

Once you have the keys you need and the bot authorized into your server, you will eventually copy them into the appropriate places in the config.py file, but now we need to get the files and get things installed.

⁠Installing the Script

The next step is installing the needed packages, cloning the repo to get the script and then installing the needed libraries for the script to work properly.

This is probably the easiest step to accomplish.

Please run the following commands:

sudo apt-get update && sudo apt-get -y upgrade && sudo apt-get -y dist-upgrade

sudo apt-get install python3 python3-pip git screen

git clone https://github.com/n8acl/hammy-discord-bot.git

cd hammy-discord-bot

pip3 install -r requirements.txt

Now you have everything installed and are ready to configure the script.

⁠Configure the Script

Once you have your API Keys, have cloned the repo and installed everything, you can now start configuring the bot. Open the config.py file in your editor of choice and copy in the keys you obtained from APRS.fi and Discord into the appropriate spots.

⁠Running the Script

Once you have the config file edited, start the bot by typing the following:

screen -R hammy-discord-bot

Then in the new window:

cd hammy-discord-bot

python3 hammy_bot.py

Once that is done, hit CTRL-A-D to disconnect from the screen session. If something ever happens, you can reconnect to the session by typing:

screen -R hammy-discord-bot

And see why it errored or quit and restart. This is useful if you need to contact me for support.

⁠Bot Commands

All Commands can be issued from any text channel and the message will be returned in a message that only you can see. While callbook data is available online publicly, this helps to keep it at least a little private on the server.

⁠Contact

If you have questions, please feel free to reach out to me. You can reach me in one of the following ways:

• Twitter: @n8acl
• Discord: Ravendos#7364
• Mastodon: @[email protected]⁠
• E-mail: [email protected]⁠

Or open an issue on Github. I will respond to it, and of course you, when I can. Remember, this is a hobby and there are other daily distractors that come first, like work, school and family.

If you reach out to me and have an error, please include what error you are getting and what you were doing. I may also ask you to send me certain files to look at. Otherwise just reach out to me :).

⁠Change Log

• 05/30/2022 - Removed returning data in a DM to returning it as an ephemeral message using slash commands.

• 05/25/2022 - Version 4.0 Release

  • Migrated to pycord discord library for slash command support. This replaces the interactions.py library and the discord.py library.

• 03/14/2022 - Version 3.0 Release

  • Migrated to interactions.py for slash command support
  • Removed Repeater lookup for now. interactions.py does not support file sending at this point and the returns are too large to send via a message.

• 02/19/2022 - Version 2.0 Release

  • Added ability to look up North American Repeaters via RepeaterBook.com

• 01/18/2022 - Minor Release

  • Added HamQTH.com for international callsign lookups. If a callsign is not found at callook.info, it will then try to retreive information on that callsign from HamQTH.com.

• 01/15/2022 - Initial Release 1.0