Setup - W3AXL/python-radio-console GitHub Wiki

This page outlines how to get the console set up and operational.

First Steps

  1. Clone the repo to a local directory of your choice.
  2. Open a terminal window in this directory and create a new python virtualenv using python3 -m venv . If you have multiple python installations, make sure you're using python3.9 or greater.
  3. Install the required libraries using pip and the requirements.txt file using python -m pip install -r requirements.txt. See below for more information.

Installing Dependencies

Potential Netiface Installation Errors

If you encounter errors during the installation of the netifaces package, you may need to install the Microsoft Visual C++ Build Tools as outlined on this page.

Thanks to Bill, WA8WG, for running into this error and emailing me the solution!

Installing PyAudio

PyAudio is not included in requirements.txt because the installation process differs depending on your operating system.

On Linux

Installing pyaudio on a linux system requires you to first build the portaudio library from source. See the portaudio documentation for information.

Once portaudio is installed, pyaudio can be installed simple by running pip install pyaudio inside the python virtual environment.

I've run into some issues on Debian systems where PyAV can't find the alsa container - this is solved by building PyAV from source and copying the resulting av folder into the root directory of this project.

On Windows

Pip is not able to install pyaudio properly on windows, at least for me. I had to follow the steps in this StackOverflow answer to get it to work:

  1. Find your python version with python --version
  2. Identify if you're running 32 bit or 64 bit python. The easiest way to find out is to run python and view the build information:
    Python 3.9.4 (tags/v3.9.4:1f2e308, Apr 6 2021, 13:40:21) [MSC v.1928 64 bit (AMD64)] on win32
  3. Download the correct pyaudio .whl file for your python installation from this website.
  4. Move the whl file to the console directory, and install using pip install <pyaudio whl file>

libsamplerate installation for Linux

The python samplerate package depends on the libsamplerate library. On Windows and Mac, it's included with the package, but it must be installed manually on linux. For Debian-based systems the package is libsamplerate0.

XCMP Keys for TRBO operation

You'll need to obtain XCMP authentication keys to use this console with TRBO radios. These are normally distributed by Motorola for developers only. However, they can be found around the internet relatively easily, or within CPS itself if you know where to look.

Currently, there's a pastebin with XCMP keys that seems to work. Place these inside the interface/xcmp_keys.sample.py file and rename to xcmp_keys.py. The console should now launch without any import errors.

Hardware

Hardware Block Diagram

(Note that the server & client machines can be the same - that's what I've been using for testing)

You'll need at least one radio to control before you can get the server up and running.

Control interface - SB9600

Most modern Motorola radios should have an SB9600 bus with four signals: BUS+, BUS-, BUSY, and ground. You'll need a RIB (radio interface box) to translate these signals into standard serial. If you're having issues getting the radio to connect, try switching the BUSY signal for the /BUSY signal (active low vs active high) as the RIB output has both available.

I've been working on a small board to do USB -> Serial -> SB9600 all in one compact package. More to come on that!

Audio Interface

I used a cheapo USB soundcard with mic & headphone plugs. Wire RX audio from the radio's accessory connector (for example, RX_FILT_AUD on the XTL5000) to the mic input, and wire TX audio from the soundcard headphone jack to the MIC line that will work with your radio.

A note on mic audio input

Currently this console controls PTT by sending the SB9600 command for a PTT button press. On the radio I tested with (an XTL5000 with an O5 head), mic audio could only be input to the radio via the front microphone connector. The MIC_IN pin on the radio's TIB was disabled, and AUX_MIC/AUX_TX require a hardware signal (AUX_PTT) to be triggered before they get enabled.

Configuration Files

Client Configuration

Radio connections for the console client are defined in radios.json inside the console-client/ directory:

radios.json:

{
    "RadioList": [
        {
            "name": "Motorola XTL",
            "address": "1.2.3.4",
            "port": 9501,
            "color": "blue"
        },
        {
            "name": "Motorola XPR",
            "address": "5.6.7.8",
            "port": 9502,
            "color": "purple"
        }
    ]
}

Daemon Configuration

Each daemon expects a config json file, passed with the -c parameter, formatted as follows:

config.json:

{
    "Radio":
    {
        "name": "Testbed W9",
        "desc": "S-Split XTL5000",
        "ctrlMode": "Motorola-W9",
        "ctrlPort": "/dev/ttyUSB0",
        "txDev": "plughw:CARD=Set,DEV=0",
        "rxDev": "plughw:CARD=Set,DEV=0",
        "chanLookup":
        {
            "YB 70SPX": "W9YB 70cm Simplex"
        },
        "zoneLookup":
        {
            "Z1": "Zone 1: Testing"
        },
        "btnBinding":
        {
            "btn_top_1": "MON",
            "btn_top_2": "",
            "btn_top_3": "SCAN",
            "btn_top_4": "PWR",
            "btn_top_5": "DIR",
            "btn_top_6": "",
            "btn_kp_1": "",
            "btn_kp_2": "",
            "btn_kp_3": "",
            "btn_kp_4": "",
            "btn_kp_5": "",
            "btn_kp_6": "",
            "btn_kp_7": "",
            "btn_kp_8": "",
            "btn_kp_9": "",
            "btn_kp_*": "RCL",
            "btn_kp_0": "",
            "btn_kp_#": "NUIS",
            "btn_home": "HOME",
            "btn_sel": "SEL"
        },
        "softkeyList": [
            "MON",
            "NUIS",
            "PWR",
            "SCAN",
            "DIR",
            "CALL",
            "PAGE",
            "PHONE",
            "RCL",
            "SEL"
        ]
    },
    "Certfile": "certs/private/testbed.w3axl.com.crt",
    "Keyfile": "certs/private/testbed.w3axl.com.key"
}
  • name: Radio name. Shown in the console radio headers. Be sensible in your name lengths. There's no limit but it'll look bad.
  • desc: Radio description. Not used anywhere yet, but might be at some point. Can be blank I suppose.
  • ctrlMode: Radio control mode. Options are
    • Implemented:
      • Motorola-O5: XTL5000/2500 or APX with O5 control head
      • Motorola-W9: XTL5000/Astro Spectra with W9 control head
    • Planned:
      • Motorola-M3: MCS2000 with model 3 control head
      • Soundcard-CM108: CM108B/CM119 soundcard PTT control (for a generic radio. No control besides PTT will be available)
      • Soundcard-VOX: VOX-based PTT control. Same as above except relying on radio VOX circuit for PTT. Don't ever use this and I probably won't actually do it.
  • ctrlPort: Serial port the above interface is connected to. COMx for Windows, /dev/ttySx for linux.
  • txDev: transmit audio device name. For linux, query device names with aplay -L. For windows, this is the name shown in the sound manager.
  • rxDev: receive audio device name. For linux, query device names with arecord -L. For windows, this is the name shown in the sound manager.
  • chanLookup & zoneLookup (optional): these are lookup tables to allow for mapping shorter text strings to longer ones (for limited-display radios). Case-insensitive, and zone text will match before channel text. Play around with it to figure out the quirks.
  • btnBinding (W9 only): this is used to map desired softkeys to physical buttons on the W9 control head. Make sure this matches the radio's control head programming. Button names & their hex code mappings can be found at the top of interface/motorola.py
  • softkeyList (W9 only): this is used to specify a list of scrollable softkeys. Together with the btnBinding above, this allows for softkey control of a radio that does not normally support softkeys.
  • certfile & keyfile: used for HTTPS websocket & webRTC connections, see the section below for information on how to generate these

HTTPS certificates for a locally-hosted server

The console client uses several new-ish javascript features, some of which require the webpage to be served over an SSL connection (in Chrome at least). It's annoying but I haven't found a workaround for this yet. The python server runtime starts its own https webserver, but it needs valid certificates otherwise the client-side portion will run into all kinds of issues.

You can generate your own CA & certificate using this answer from StackOverflow. You'll have to overwrite the existing keys & certs in the certs/ folder of this repo, but if you use the same names everything should "just work." You'll then need to trust the root CA you made (the CA.pem file created from the link above) in your operating system as a trusted root certificate authority.

Once you go through these annoying steps, the https connection should then work without a bunch of errors and issues. There's probably a better and more secure way to do this but for now I've also included the CA & cert files I used. If you don't care too much about the security implications of trusting a random CA from a Github repo, you can trust the localCA.pem authority in Chrome/Windows and things should work with minimal effort.

Another important note - the server addresses you specify when generating these certificates must match exactly what you type in the address bar. I.E. if you're using IP addresses, make sure they match. Same goes for domains. This also means if you run multiple radio daemons from different server addresses, you'll need to generate a unique certificate for each address and use that in it's specific daemon config.

Running the Console

THIS IS ALL OUTDATED FOR VERSION 2 OF THE CONSOLE, I WILL UPDATE THIS EVENTUALLY

Okay, you've got your hardware set up, a configuration file made, and the certs for the console configured. How do we actually use the damn thing?

Note: the console has so far only been tested with Windows 10 and Google Chrome, with everything running on the same machine. The python libraries used should be cross-platform but the software is super-early alpha and no guarantees are made.

  1. Activate the virtual environment you made above from a terminal prompt:
    .\Scripts\activate (Windows) or source ./bin/activate (Linux)
  2. Start the console with your config file and specify ports for the webserver and client-to-server messaging service:
    python server-runtime.py -c config.json -sp 9995 -wp 4443
    The connected radios will be reset. You can follow the server launch in the console. It will also print out any errors or warnings. Very handy.
  3. Navigate to server.address:webport (example: localhost:4443) and an empty console should load.
    Console server menu
    If you've gotten this far, you're in the home stretch now.
  4. Set up your connection to the server. Enter the address and port of the server you started earlier. Press connect and you should see the status change from Disconnected to Connected. The auto-connect parameter will automatically connect to the server when the page loads. Click save to store these settings as a local cookie.
    Server setup
  5. You should see your radios in the main console window. You can select one by clicking anywhere on it. PTT is done using the spacebar when a radio is selected. The radio card border should go red to inidicate transmit. The web client will use whatever is specified as the default microphone. Todo: allow microphone device selection. Receive is indicated by a green border.
    Main server window