Skip to content

Latest commit

 

History

History
153 lines (123 loc) · 9.18 KB

README.md

File metadata and controls

153 lines (123 loc) · 9.18 KB
Raw

hamChat

Consider this software unstable and subject to extreme changes

This program is a desktop application that allows amatuer radio operators to do almost whatever they want within the context of text or binary data transfer, via a plugin system. Usually, this means using an audio baseband over a radio link with a modem. Such as:

hamChat                        Radio
---rig control ------>PTT/CAT |     |\___>Radio link to another station
---sound modem ------>AUDIO   |     |/   >Also running hamChat

image

Currently, the following features are implemented:

  • Graphical Desktop Interface
  • Keyboard-to-Keyboard text chat
  • ARDOP FEC mode transport
  • hamlib rig control (PTT and frequency/mode display)
  • Simple File Transfer
  • autoACK message acknowledgment
  • Recently heard stations list

Usage

If you have already run amatuer software before, like direwolf, then runing this program is relatively straight forward.

To use this program, you need:

  1. Graphical Environment (Linux Recommended, Windows instructions not provided as I don't use it, although it has been reported to work on Windows)
  2. Python 3.8+ interpreter -> https://www.python.org/downloads/ (or your system repositories)
  3. The ARDOPCF modem -> https://github.com/pflarue/ardop/releases/
  4. A way to connect to a radio (one of the following)
    1. Signalink USB -> https://tigertronics.com/slusbmain.htm
      1. Uses VOX to trigger the PTT line, but may have issues with timing/delay.
      2. May also trigger PTT with CAT/RTS/DTR, this is preferred but dependant on radio.
    2. Digirig Mobile -> https://digirig.net/
      1. Uses CAT or Serial RTS for PTT. Requires Hamlib.
      2. Works with BaoFeng
    3. Built-in USB interface (such as Yaesu FT-991A)
      1. Requires Hamlib

To run this program:

  • start ardopcf

    • https://github.com/pflarue/ardop/releases/
    • run like ./ardopcf 8515 plughw:1,0 plughw:1,0
    • plughw:1,0 is whatever audio interface your radio is hooked up to. Yes, you must repeat it twice. 8515 is the TCP port that hamChat will default to.
    • If you get audio errors, like "cannot open playback audio device" - check your device identifier. You may need to reboot or reload alsa/pulseaudio, or just wait a few seconds for any other application to 'let it go'. Or you invoked ardopcf incorrectly.

  • start rigctld (this is part of hamlib)

    • On Ubuntu, install the package libhamlib-utils or wherever you can get binaries
    • Check if you have a supported radio (or like model) with rigctl -l
    • If supported, run like rigctld -m your_radio_id -r /dev/ttyUSB0
      • where your_radio_id is the number you got from rigctl -l, and /dev/ttyUSB0 is whatever serial port you have your radio connected to
    • If NOT supported, try a similar model. If that doesn't work, and you are using something like a digirig for PTT:
      • Try: rigctld --ptt-file=/dev/ttyUSB0 --ptt-type=RTS
    • If you get a "Permission Denied" error - you either need to get ownership of the virtual serial port or add yourself to the dialout group. Don't run rigctld as sudo.
      • sudo chown $USER:$USER /dev/ttyUSB0 and/or
      • sudo adduser $USER dialout (then log out and back in)

  • hamChat

    • Download or clone this repository
    • Run hamchat with python3 ./main.py

Some notes:

  • The layout is simple. On the left is the chat window for message composition and addressing. On the right are the settings of plugins.
  • The default chat mode is an ARQ session. You will not be able to see traffic from 3rd parties in this mode by default. Use FEC mode in for group chats/nets.
  • The "recipients" window is comma-delimitted. ARQ will only use the first callsign.
  • Addressing is optional in FEC mode, but used in conjuction with the AutoACK plugin to let you know if the other station got your message.

Known Bugs

  1. See ARDOPCF FEC bugs.md for FEC mode related bugs that are likely part of the ARDOPCF modem implementation.
  2. If an internal thread crashes, it's not always made apparent to the user (they must check the console), and certain features will stop working. The program may need to be restarted if this happens.
  3. If the main thread crashes, the program will not exit cleanly. Multiple CTRL+C in the terminal window may be needed.
  4. The UI may not be properly scaled at runtime, and may require the user to resize it where the elements are visible.
  5. Reconnects to the ardopcf and rigctld don't always work right, you may need to restart the program if those programs are shut down.

Troubleshooting

  1. When using ardopcf, sometimes you need to send one packet/recieve at least one frame for ardopcf to start giving you good data.
  2. If your data never sends, make sure you are running ardopcf with the proper arguments.

For Developers

DO NOT WRITE PLUGINS FOR THIS YET!

Plugins are python files that inherit the hamChatPlugin class, and are located in the plugins folder.

Events will be called by hamChat, and if a plugin has a hook for it, it will be called when appropriate.

Plugins can add new windows or widgets, directly issue commands to the TNC, or do pretty much anything.

The reason why you should not write plugins yet is because I haven't decided the amount of control I will let them have, and there may be an issue with resolving conflict, if, for example, more than one plugin trys to mess with the same UI element or the chat window. Certain things are also currently unavaliable in a sane way. Additionally, I want to rewrite this program from the ground up with better UI and asyncronous operation as a priority.

Plugin Rules

  1. Plugins files (python) go in the plugins folder (plugin authors should write any settings files here too)
  2. All classes in that folder that inherit from hamChatPlugin will be loaded.
  3. Plugin class initialization must accept one argument, which is the GUI instance object.
    • See plugin folder for examples

Writing Plugins

STOP! - It's not ready. If you decide to anyway:

  1. Be WARNED that the plugin interface may change in the future. If this does, the 'Core' plugin version will increment.
  2. Copy hamChatPlugin.py to your new plugin file name, into the plugins folder
  3. Rename the hamChatPlugin class name to whatever you like, and inherit from hamChatPlugin.
  4. Write your self.description. Be sure to declare any new handlers if you expect to send or receive messages over a transport.
  5. Read the entirity of the comments and examples in __init__, they tell you how best to interface with the main program.
  6. Read all the default methods and their descriptions to figure out when you want your code to run. Take note:
    1. Except for on_transport_state_update() and on_get_data() - all other methods run on the same thread as the UI.
    2. Don't write anything in these methods that is blocking/dependant on another plugin to perform a task.
    3. It is better for you to start your own worker thread to manage all of the internal state requirements.
    4. Code written in these methods should have robust error handling. If they fail, they will crash the main thread. I do not want to get bug reports on this repository for custom plugin issues.
  7. Keep It Simple, Stupid!
    1. Plugins can communicate with one another. Each plugin should add ONE function/feature. There is no need to pack 10 features into one plugin. This makes them harder to interface with.
  8. If another plugin doesn't provide a hook that you need, feel free to fork it and submit a pull request.
    1. When testing plugin revisions on-air, be sure to change the version number if the changes you make are incompatible with the source version.
  9. TEST THESE ON AIR WITH MULTPLE STATIONS BEFORE COMMITTING! Avoid WOMM (Works On My Machine) syndrome as much as possible.
  10. Provide feedback on how development went. For me, because I wrote the whole ting, it's easy to remember how to work around issues. If there is a problem where doing something is harder than it should be, and you've reviewed all the example plugins, please send an email or open an issue.

Ideas for Plugins

  • Automatic Link Establishment
    • Use rigctld to hop around frequencies waiting to be 'called'
  • Advanced Rig Control (virtual VFO/frequency favorites)
  • Data Mode Negotiation
    • If you have a large file, auto negotiate the fastest data rate avaliable for the channel.
    • (may be rolled in with ARQ modes)
  • Data Relay Request
    • A -> B went OK, but C wanted it too. C can request B to give it to them.
  • gpsd Squaking
    • Send an APRS-compatible message (or whatever message we might want)
  • Notification System
    • Ding on message reciept, send you an email or text message, or connect to a custom phone app
  • BBS Server
    • If clients connect to you, you can post and respond to messages in a local database.
  • Callsign resolving
    • Fetch from QRZ or something
  • Cross-transport forwarding
    • If someone is on TCP, you can relay their messaged through ardop or something.
  • Message translation
    • If someone is chatting in another language, automatically translate to and from their language.
  • Winlink client compatibility