This section of the document describes how an application interfaces to the µH Router using AppleScripts. If you are only interested in using the router, please go directly to the
Set Up page.


AppleScript


The µH Router projects contains a folder called Examples. Within that folder are complete example AppleScripts.

With AppleScripts, you can access all the ports that the named pipe interface can access. In addition, there are scripts to conditionally terminate the router, scripts to manage the connection and scripts for turning on debugging messages.


Keyers

The three keyers that are supported by the µH Router can be accessed by the variables microKEYER, digiKEYER or cwKEYER. Furthermore, you can use the boolean connected to find out if a physical keyer is available. E.g.,

tell application "µH Router"
  tell microKEYER
    if connected then
      -- GET VERSION
      copy "0585" to CONTROL
      delay 0.05
      get CONTROL
    end if
  end tell
end tell

In the example above, the boolean connected returns true if the router has found a microKEYER.


Ports in a Keyer

Each keyer has a set of ports for communicating with a function on the keyer.

The following are variables that correspond to ports on a keyer:

CW (boolean, read/write)
PTT (boolean, read/write)
RTS (boolean, read/write)
FSK (text, write only)
WINKEY (text, write-only)
WINKEYhex (text, write-only)
FLAGS (text, read-only)
CONTROL(text, read/write)
RADIO (text, read/write)

PTT, CW and RTS are boolean (states). The WINKEY characters are sent as an ASCII string. The remaining variables, including WINKEYhex are as sent as hex values in a text string. I.e., each byte is sent as two characters ("0" through "9" and "a" through "f"). E,g,.

tell application "µH Router"
  tell cwKEYER
    copy "08150040000000009E88" to CONTROL
    set PTT to true
    copy "0904" to WINKEYhex -- turn WinKey PTT off for break-in keying
    copy "CQ TEST" to WINKEY
    get RADIO
  end tell
end tell

Note that the CONTROL channel is treated in a special way, as explained in the Router Interface page. Because the first and last byte of a CONTROL command are specially tagged, each text string that is sent to the CONTROL port should contain exactly one command.

When reading back a reply, the first byte and last byte of a CONTROL status are encoded differently from the standard hex encoding.

The body of the status (bytes that are not the first or the last)are encoded with "0" through "9" and the lower cased "a" through "f".

Instead of "0" through "9", the digits of the first data byte and last data byte of a CONTROL status are encoded as "P" through "X." (P=0, Q=1, R=2, S=3, etc, i.e., the ASCII table is shifted by 32 (decimal)) and the characters "a" through "f" are encoded as upper cased "A" through "F."

E.g., the following string from the CONTROL port

...PU01021006020008950895000fXU...

is decoded into the byte array: 0x07 (P=0,U=5), 0x01, 0x
02, 0x10, 0x06, 0x06, 0x02, 0x00, 0x08, 0x95, 0x08, 0x95, 0x00, 0x0f and 0x85 (X=8,U=5).

Note that the first data byte (0x07 above) itself always has the MSB turned off and the last byte (0x85 above) always have the MSB turned on.
In this manner, you will be able to uniquely spot which bytes are the first and last bytes of a status string that the keyer sends even if you don't poll the stream at the "right" moment. In the microHAM Keyer Protocol document, the first and last byte of a CONTROL stream are indicated by bold faced print.

The digiKEYER does not come with the WINKEY and WINKEYhex ports and the cwKEYER does not come with an FSK port. There are two read-only boolean variables that can be used to find out if a keyer supports either of these ports. E.g.,

tell application "µH Router"
  tell digiKEYER
    if hasFSK then
      -- CAN USE FSK PORT
    end if
    if hasWINKEY then
      -- CAN USE WINKEY PORT
    end if
  end tell
end tell


Maintaining Connection to a Keyer

Although not mandatory, it is highly recommended that you send a retain message to a keyer on the router before you use the functions on it, and send a release message when you are done. E.g.,

tell application "µH Router"
  tell microKEYER
     retain
  end tell
end tell

If the retain count of any keyer is non-zero, or if any of the keyers are still connected to a named pipe, the quitIfNotInUse command will not terminate the router. Each retain message will increment the count by one and each release will decrement the retain count by one.

retain and release return the actual return count (integer) after they have incremented or decremented the count.

If you don't use retain, you run the risk that some other application can terminate the router while you are still using it. Similarly, if you don't release the keyer when you are done, no one else can use quitIfNotInUse to terminate the router.

Each keyer (microKEYER, cwKEYER and digiKEYER) maintains its own independent retain count.


Terminating the µH Router

You can unconditionally terminate the µH Router with the AppleScript quit command. This is however not recommended since other applications may still be using the router. Instead, after releasing all the keyers (as explained above), use the quitIfNotInUse command instead. E.g.,

tell application "µH Router"
  quitIfNotInUse
end tell

quitIfNotInUse returns true if it is able to quit. It will return false if there are others who are still using the keyer (or the keyer hasn't been completely released by other AppleScript users).

The µH Router also supports a quitIfNoKeyer command. When the µH Router wakes up, it looks to find any serial port that is associated with a microHAM device. It it does not find any keyer and if it receives a subsequent quitIfNoKeyer command, the µH Router will terminate itself. The following will cause the router to quit if it could not find any keyer. quitIfNoKeyer returns true if it is able to quit.

tell application "µH Router"
  quitIfNoKeyer
end tell


Turning on Debugging

The router activity can be monitored by turning on the debugger. The output is logged to the MacOS X console. E.g.,

tell application "µH Router"
  set debug to true
end tell

An individual keyer's activity can be also monitored by turning on the debugger for the keyer. The output is logged to the MacOS X console. E.g.,

tell application "µH Router"
  tell microKEYER
    set debug to true
  end tell
end
tell