Posts Tagged ‘Radio programming software’

Wouxun, Woux Off, Machopper!

Thursday, October 18th, ©2012 Marcus Brooks
Wouxun KG-UV3P Dual-Band HT

Yes, you can program the Wouxun KG-UV3P from a Macintosh.

(Apologies in advance for the long post.)

Recently I bought a cheap Chinese ham radio on impulse: a Wouxun KG-UV3D dual-bander. (I pronounce it “woah shun,” but I’m apparently wrong.) I had drifted off the air for one reason and another, but the prospect of working UHF caught my attention. It’s said the 70cm UHF band (420-450 MHz) is better suited for urban use than the old-standby 2m VHF band (144-148 MHz). Also, UHF seems to be getting more popular in my area (Austin, TX).

The Wouxun handles both bands, and is much cheaper than corresponding iCom or Yaesu/Vertex handheld radios. It seems to be more than functional and sturdy enough for my main purpose, which is just to get back on the air.

I tried working the UV3D manually, just to see if I could. It works, but happily I paid a few bucks more to get the programming cable. Unhappily the “official” programming software is Windows only, and for the moment I can’t access my throw-down PC. I had to look for a Mac OS X alternative.

What I found was OWX (Open Wouxon), an open-source utility being developed by Adam Wysocki, SP5GOF. OWX is a work in progress, but it can already program repeater transmit and receive frequencies into the radio’s channel memories, which is enough to make it worthwhile.

OWX is a GNU/Linux shell (command-line) utility, but the Mac OS X shell is similar enough that I got OWX running with little trouble. I hope this post will help you do likewise.

Important: Before building OWX, you need to install Apple’s XCode Tools. This is an option in the additional software installer on the Mac OS X Installation DVD. For the record, I’m using Mac OS X 10.6, Snow Leopard.

Warning: OWX is not Wouxun-approved software. With it, you can make changes that render your radio useless and void your warranty. What is worse, such a change is practically impossible to repair. “Playing Safe,” later in this post, explains this danger and what I do to avoid it (I hope!).

Setting Up the Radio Interface

The Wouxun programming cable uses a Prolific PL2303 USB-to-serial interface. Getting the current Mac OS X PL2303 driver is about the hardest part of setting up OWX (not too hard, though):

  1. First, go to the PL2303 support page and download the appropriate zip file.
  2. Open your browser’s Downoads window, Ctrl-click the download name, and select the Show in Finder menu item. This opens your designated downloads folder and selects the new file.
  3. Now double-click to unzip the file; then open the driver folder that is created.
  4. Now double-click the driver DMG file. This mounts a virtual disk containing the actual installation program.
  5. Finally, double-click the installer “package” icon and follow the instructions on the screen. The installer will do what it does, then prompt you to reset the computer to complete the installation.

After you install the driver, you can set an environment variable to identify it for OWX (this will save you some typing later):

  1. Open the Mac OS X Terminal program. You’ll find it in the Applications/Utilities folder.
  2. Plug in the programming cable. A “New network interface” window is displayed; just click Cancel to dismiss it.
  3. In the Terminal window, enter this command:

    ls /dev/cu.*
  4. Two entries in the list are of interest: “cu.usbserial” and “cu.PL2303-xxxxxxxx“, where xxxxxxxx changes with the driver version. Drag-select this second device name and press Ctrl-C to copy it.
  5. Enter the following command (after the equal sign, paste the “/dev/cu.PL2303-xxxxxxxx” name that you just copied):

    echo export OWX_PORT=port_name  >> ~/.profile

Do this only once. It adds a variable definition to “.profile” in your home directory, so the definition executes every time you  open Terminal. (The OWX doc says use .bashrc to do this, but it didn’t work for me.)

To test the variable definition, enter the following commands:

sh ~/.profile
echo $OWX_PORT

If this displays the port name you specified, then you’re ready for the next step.

Tip: The port name “/dev/cu.usbserial” should also work, but when I tried it OWX would work once, then when I tried again, it displayed “owx: Radio not responding.” (Yes, the radio was still connected and turned on.) I was able to fix this by unplugging and re-inserting the cable’s USB end each time. The “/dev/cu.PL2303-xxxxxxxx” port name seems to work much better.

Installing OWX

Someday, when OWX is actually finished, it may have a nice installer for various operating systems. For now it is distributed as source code, but don’t worry! OWX comes with a Linux MakeFile so it’s easy to build and install, and it works just fine for me on the Mac. (Although as I mentioned before, Apple’s optional XCode Tools software must be installed first.)

Go to http://owx.chmurka.net/ and download the latest source code gzip file. As with the cable driver, Ctrl-click the file in the Downloads window and select “Show in Finder.”

This time, drag the OWX gzip file to your home folder, then double-click the file to unzip it.

Back in the Terminal window, type “cd ” at the prompt (don’t forget the following space), then drag the new OWX folder from your home folder into the Terminal window. This doesn’t move the actual folder, but it copies the folder’s path onto the command line. Press Enter now to change directories into the OWX folder.

Now you need to build OWX, but that’s easy. Just enter this command:

make

This uses instructions in the current directory’s “MakeFile” to automagically build (compile and link) OWX. When I ran make, the build displayed several warning messages, but it completed OK. What you see may be different, depending on the program’s state of development.

I suppose the build might fail sometimes—this is a work in progress. If it fails, I suggest waiting for the next version and trying again. (Watch the changes file to see if anything actually changed.) The author might welcome a detailed report of the failure, including system information and the messages displayed.

Installing OWX is almost as easy. Enter this command:

sudo make install

“Sudo” gives you temporary superuser status, so it has to prompt you for your user password. Enter the same password you use to install commercial applications, like the Prolific driver. The OWX installer will print several messages as it installs and links files.

From this point on, OWX works pretty much as described in its documentation. For editing the CSV file, I use OpenOffice. The Mac’s bundled NeoOffice application should also work, or, if you insist, use Microsloth Multiplan… er, Excel.

One last item that gave me pause: I didn’t see how to import the CSV as text, at first, so I was editing the various cell formats to set the prescribed decimal places (which is very important!). Later I found the trick is to select all the sample column headers in the CSV import window, then select “Text” in the associated pull-down menu. This preserves the text formats created by OWC in the CSV file. (BTW: this is easier to do in OpenOffice than in NeoOffice.)

Playing Safe

The OWX utility gives you access to the radio’s frequency range settings. Do not change these unless you know exactly what you are doing! An incorrect setting might be illegal. Worse, if the radio can’t lock the frequency, then it simply won’t turn on again. Ever. And there’s no practical way to correct the error. Read the OWX readme file for more about this issue.

Fortunately, there’s a way you can make sure you haven’t changed the range settings before you “put” the edited memory image back in the radio. I’ll assume you ran cp file.bin backup.bin, as the OWX readme recommends, right after “getting” the memory image. If not, get the binary again and make a backup!

After editing the CSV and importing it back to the binary image, perform the following steps before you “put” the binary image.

hexdump -Cv backup.bin > backup.txt
hexdump -Cv file.bin > file.txt
diff backup.txt file.txt

The hexdump commands convert the binary images to text files that can be compared, then diff displays every change that occurred. The output contains a decimal notation of the changed line numbers, like “386c386,” followed by the actual changed lines, prefixed with “<” to indicate the data removed and “>” to indicate the data inserted. Each text line begins with an eight-digit hexadecimal number indicating the data’s offset (location) in the binary files. For example:

386c386
 < 00001820  01 00 05 00 00 00 00 50  52 4f 47 52 4d ff ff ff  |.......PROGRM...|
 ---
 > 00001820  01 00 05 00 00 00 00 4b  35 4d 57 42 20 ff ff ff  |.......K5MWB ...|

This display indicates that line 386 in backup.txt was changed, and the changes are in line 386 of file.txt. The lines displayed show the 16-byte block at  location 0x1820 in each binary file. By comparing the lines, you can see that bytes 0x1827 to 0x182C were changed.

This may seem complicated, but if nothing else you can examine the changed lines to make sure no change occurred at offset 0x970 in the data, (the hexdump line that begins with “00000970”). The radio’s frequency range data is encoded in locations 0x970 to 0x97F. I don’t know if any change elsewhere in the file can damage the radio, but a wrong value in these 16 bytes will turn it into a $120 brick!

By the way, the change shown here reflects an apparent bug in OWX. Changing the text field at 0x1827 had no effect on my radio’s welcome message (which was “WELCOM” originally, not “PROGRM.”) I notified SP5GOF, so by the time you read this OWX might edit the actual welcome message location, 0xE06.

73, K5MWB