cocoaPath
cocoaPath User's Manual
version 0.30

Kok Chen W7AY [w7ay (at) arrl . net], Russ Carpenter AA7QU [russ (at) natworld . com]
Last updated: September 26, 2008





1 Introduction

cocoaPath is an HF Channel Simulator, used primarily for testing new modem algorithms and setting demodulator parameters. cocoaPath consists of an input channel, an output channel, and an ionospheric propagation model to connect the input to the output.

An audio signal is created by the input section of cocoaPath. The input signal can come from a sound card, a collection of built-in signal generators (PSK31, RTTY, CW or steady carriers), or an AIFF or WAV format audio file.

The audio output from cocoaPath can be sent to a sound card. It can also be written to an AIFF or WAV file. A propagation model, for example to simulate propagation conditions of high latitude flutter, is applied to the input signal, and passed on to the output section.

The propagation models are based on the seminal 1970 paper "Experimental Confirmation of an HF Channel Model" by Watterson, Juroshek and Bensema. Technical and implementation details of cocoaPath can be found in the page that is linked by the Technical tab button above.

Propagation models that are defined by the CCIR 520-2 Recommendation (1992) and the ITU-R F.1487 Recommendation (2000) are included in the set of built-in models in cocoaPath. A user can also create other propagation conditions that are based upon the Watterson parameters.


2 System Requirements

cocoaPath requires either Intel or PowerPC Macintosh computers that run Mac OS X 10.5 (Leopard) or newer.


3 User Interface

When cocoaPath is launched, you will see the main cocoaPath window shown in the figure below:

first

The cocoaPath window is separated into three primary sections, Input, Propagation Model and Output.


3.1 Input Interface

The figure below shows the input section in greater detail

Input

On the left of the input section is a segmented control with Pause, Play and Stop buttons to control an internal sound generator, an audio (AIFF or WAV) file, or an input sound card.

The Pause button only works with input sound files. If Play is pressed while the input section is paused, the file will resume playing from where it was paused. If Stop is pressed, play will stop, and the input file pointer will point to the beginning of the audio file. If Stop is pressed while the input is paused, the file pointer is placed at the beginning of the audio file.

With internal sound generators and sound card inputs, the Pause button behaves just like the Stop button.

An attenuation slider is immediately to the right of the Stop button. The attenuator is only active if the sound card input is selected. The slider is grayed out for other input types.

The Signal Level measures the peak level of the input signal every 32 ms. The red segment is lit if the signal is within 0.5 dB of full scale. The yellow segment is lit if the signal is within 1 dB of full scale. Each green segment represents 3 dB of signal level change.

When toggled, the Configuration Button opens and closes the input configuration panel. You can also close an opened configuration panel by using the red "close window" button at the top left of the window.


3.1.1 Input Configuration

The input configuration panel controls the source that is selected to provide the audio stream. When the Configuration button is pressed, you will see a window with the title "Input" as shown in the following figure:

iconfig

The upper row of tab buttons selects the type of input to use as the input to the simulator.

You can choose among certain internal signal generators, AIFF or WAV audio files or sound card devices. The above figure shows the panel's appearance when a built in signal generator is selected.

In the above figure, the inner tab view chooses the modulation mode of the signal generator. You can choose between a steady Carrier, a CW (Morse) signal, a PSK31 signal, or a 45.45 baud RTTY signal.

As seen above, you can enable up to two carriers for the steady carrier generator, and you can set the frequency of both carrier.

You will see the next figure when the CW signal generator is selected.

cfgcw

You can choose the CW frequency, and the Morse speed in words per minute. The text in the text view will be sent. If the Loop checkbox is set, the text will be repeated until the checkbox is cleared.

The PSK31 signal generator is shown below. Like the CW generator, the center frequency can be chosen, and the text can be repeated by setting the Loop checkbox. In addition, each "section" symbol ( § or Option-6 on a Macintosh keyboard) in the text will generate a short idle Varicode. Longer idle patterns can be generated by using a string of § characters. You can choose either BPSK31 or QPSK31 modulation.

pskg

The RTTY signal generator is shown below. You can "invert" (swap the Mark and Space tones) the RTTY signal by using a negative "shift" value.

configry




3.2 Output Interface

The figure below shows the output section in greater detail:


output


The width of the spectrogram can be chosen from 400 Hz down to 12.5 Hz. Since it is very narrow, it is crucial that you place the center frequency at or close to the input signal's frequency or frequencies. The left of the spectrogram is higher in frequency and the bottom of the spectrogram has the most recent slice of the spectrum.

The Playthrough checkbox enables the simulator's output to play on the sound card that is selected in the output configuration panel (see below). If you select the system sound output, you will be able to monitor the output of cocoaPath on the computer's speakers.

The Record to sound file checkbox turns on and off the recording of the same output to a sound file. This checkbox can be turn on before the input sound section is placed in Play mode; nothing will be recorded until Play is started. You can end a recording by either unselecting Record to sound file or stopping source in the input section.

When Auto Record is selected and input data is started, the Auto-recording window appears and there is a field to automatically stop the input stream after a set amount of time. In addition, if you have selected either a Generator or a sound file as input, and leave the output Playthrough unselected, the recording can be done at up to 8 times the real-time rate. (The actual speed up depends on the speed of the processor.)

autoWindow

When a recording ends, cocoaPath will display a custom file save dialog shown below:

saiff


The default name for the sound file is the name of the HF channel model. In addition to the usual file save dialog, you can choose between AIFF or WAV format. (WAV is a Windows format which the Mac OS can read and write.)

You can also select the sampling rate of the sound file. 11025 s/s is adequate for all bandwidths that cocoaPath uses, and will create the smallest sound file, but you can also choose 16000 or 44100 s/s if you need a rate to match the needs of other applications.

Finally, there is a checkbox to select if you want to write a single channel sound file or a stereo file. If you ask for a stereo file, the right channel will contain a time-aligned and noise-free reference signal that has no ionospheric disturbance. This provides a signal with very high signal to noise ratio that can be useful for automatic detection of bit errors in the test channel when testing modems.

When you select AIFF, cocoaPath will append the "aiff" extension to the file name. If you choose WAV, cocoaPath will append the "wav" extension to the file name.


3.2.1 Output Configuration

The Configuration button in the output section opens the output configuration panel. You can close the panel by using either the window's close button (the button at the top left corner of windows), or by clicking again on the Configuration button.

The output configuration panel allows you to select sound card and sound card parameters for the output play through. The output from the Watterson model can be sent to either the left or the right channel of the sound card.

You can also select between two variants of two-channel (stereo) output.

When you select Stereo I/Q, the in-phase component of the Watterson analytic model is sent to the left channel of the sound card, and the quadrature component of the model is sent to the right channel. This allows you to modulate the quadrature sampling exciter (QSE) of a software defined radio (SDR). In conjunction with a QSE, cocoaPath can be used to quantify the performance of built-in digital mode decoders in HF receivers.

When Stereo I/Q is selected, the quadrature component can be negated to reverse the sideband (whether the output spectrum is higher or lower than the local oscillator) of the QSE, as seen below:

iq

You can select stereo output where the Watterson model is sent to the left channel of the sound card, and a time-aligned and noise-free reference that has no ionospheric disturbance is sent to the right channel of the sound card, as seen below:

outset



3.3 Propagation Model Interface

The following figure shows the Propagation Model section of the cocoaPath user interface in greater detail:


modelp
Figure 3.3-1 User Interface for Propagation Model

The Model popup menu selects one of the built-in Propagation models. As mention in the Introduction, the propagation models are based on the Watterson paper, with the addition of an additive noise term that sets the signal-to-noise ratio of the model.

The power of the Additive White Gaussian Noise (AWGN) can be set to an arbitrary decibel value relative to the full scale value of an audio sample. The computations done within cocoaPath do not saturate. However, when you output the result to a sound file (or playing through to the computer's speakers), the signal will clip at the full scale value.

When an input signal arrives, the power is measured and displayed in the Input Power box together with signal-to-noise ratio (the ratio the input power and noise power). Because sound files have a resolution of 16 bits, setting the noise power to -96 dBFS will assure the output is completely noise free.

The Model menu is grouped into ITU and CCIR conditions, taken from Recommendation ITU-R F.1487 (Testing of HF Modems with Bandwidths of Up to About 12 kHz Using Ionospheric Channel Simulators) and Recommendation CCIR 520-2 (Use of High Frequency Ionospheric Channel Simulators).

models
Figure 3.3-2 Propagation Model Menu

Even though the ITU recommendations are newer than the CCIR ones, the CCIR conditions are included because the ITU recommendations does not include the "flat fading"condition which consists of Rayleigh Fading in the absence of multi-path.

When a CCIR condition overlaps an ITU condition, it is called out in the ITU menu. This can be seen in the figure above for the ITU Mid Latitudes Quiet Conditions, which is marked as having the same parameters as the CCIR Good Conditions.

As shown above, cocoaPath includes a built in "perfect" propagation model (lack of Doppler spread and multipath) that can be useful for evaluating modems using only additive white Gaussian noise.

You can view and change the parameters of the selected model by clicking on the Model Inspector button of Figure 3.3-1 above. The Model Inspector window (Figure 3.3-3) should appear.

inspect
Figure 3.3-3 Model Inspector

Each row in the table view of the Model Inspector represents a Watterson path (read the Technical section for more details).

Each path is connected to a delay line tap in the model. cocoaPath's time delay has a resolution of 0.0625 milliseconds and a maximum delay of 96 milliseconds. The Doppler frequency spread, the Doppler shift and attenuation determines the scattering function of a Watterson path. You can temporarily disable a path by clearing the Enabled cell of the path.

Although Watterson's models allow each path to take on a different attenuation and Doppler Shift, none of the ITU and CCIR conditions make use of these two parameters. Because of this, the fading depth of a path as defined by the ITU and CCIR documents can be unrealistically deep. cocoaPath implements both attenuation and Doppler Shift parameters, so you can use them to investigate more refined propagation models. For example, adding a path that has no relative delay and with no Doppler spread and attenuated to some low level will limit the output from fading below the level of this additional path.


3.4 Creating Custom Propagation Models

With the Model Inspector open, you can modify any of the parameters of that model by clicking on the table view cell and typing in new numbers. You can add or delete paths by using the small + and - buttons that can be seen at the bottom left of the Model Inspector window in Figure 3.3-3.

The new model parameters will remain there until you relaunch cocoaPath. When cocoaPath is relaunched, the original ITU or CCIR model will be restored.

You can create permanent custom models by editing one of the existing models, and then clicking on the Export button in the Model Inspector window.

The title of the model (the text field at the top of the Model Inspector) can be any text string. It is there for you to place some meaningful explanation of the model. Note that this title is not the name that appears in the model menu.

When you click on the Export button, cocoaPath will save the model to an XML format file. You can set the file name itself to anything you wish; cocoaPath will add a ".model" file extension when it creates the file. The filename you choose (without the extension) is the name that will appear in the Model Menu when you import the model.

Place your custom model inside the cocoaPath folder in the Application Support folder of your home directory's Library folder. You will need to create a new cocoaPath folder if it is the first time you are adding a custom model.

Each time cocoaPath is launched, it will look in this Application Support folder, searching for the cocoaPath folder. Within the cocoaPath folder, the program looks for files that have the ".model" file extension. If cocoaPath finds one or more files with that extension, they may then be imported.

Remember to relaunch cocoaPath each time you add a custom model to Application Support. You can directly edit XML files using the Dashcode application, the Property List Editor, or TextEdit.

The custom model(s) will show up in the Model menu below the built-in propagation models, as seen in Figure 3.4-1 below:

custom

Figure 3.4-1 Model Menu with Custom Models



3.4 Random Number Seeds

The random number generators that are used in the cocoaPath models and AWGN noise source come from separate routines, all of which execute the Wichmann-Hill algorithm. The random numbers are not really completely random but are generated from a set of linear congruence equations.

The linear congruences are initialized by an integer "seed." cocoaPath maintains a single based seed is used as a base to initialize the various random generators each time you start the model by pressing Play. Each generator is initialized with a different seed which are fixed offsets from this base seed. All generators are therefore independent, but of them will start from a known state.

This is especially useful when comparing different modems sequentially, since cocoaPath will send precisely the same signal to all modems.

If you prefer to use a different starting seed, you can change the base seed by selecting the Doppler Spread menu item in the Main Menu bar.

seed

If you enter 0 in the seed field, cocoaPath will use the current time as the seed -- which will cause the outcome to be completely random and will practically never repeat.