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,
0x02, 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