Programming Information for WiNRADiO G315 Series Receivers

The G315 receivers API is implemented as a single 32-bit library WRG315API.DLL. It provides functions for all communication with all types of G315 receivers. It can be used by any 32-bit application under Windows 98, ME, 2000, XP and Vista and by 64-bit applications under 64-bit Windows XP and Vista. On 64-bit Windows versions there is also support for 32-bit applications but restrictions may be required in multi-threaded applications due to possible race conditions between threads.

The API can be imagined as being built using two independent sets of functions. First there is a rather low-level set of functions, covering all hardware related functionality, including basic on-board DSP accessing. The second set of functions offer full demodulating features. In order to be able to use these higher-level functions the InitializeDemodulator function must be called first.

Open

Opens a radio device by its serial number to allow you to control the device using the other API functions.

C/C++ declaration

Delphi declaration

Parameters

ID

Radio device serial number that you would like to open. If NULL is specified, a demo receiver will be opened. The serial number is a null-terminated string.

Return Value

Returns a handle to the device that has to be used to call all the other API functions (hRadio). If zero is returned, the specified device doesn't exist or couldn't be opened.

Remarks

If you would like to have more than one application use the same device, you will have to close the device when you have finished using it to allow other applications to access the device. For Win32 applications, multiple threads can access the same device at any time.

See Also

G3GetRadioList

OpenRadioDevice

Opens a radio device by its index to allow you to control the device using the other API functions.

C/C++ declaration

Delphi declaration

Parameters

iDeviceNum

Radio device number that you would like to open from 1 to 255. If zero is specified, it will open the next available device.

Return Value

Returns a handle to a device that has to be used to call all the other API functions (hRadio). If zero is returned, no devices were available to open or the specified device doesn't exist.

Remarks

If you would like to have more than one application use the same device, you will have to close the device when you have finished using it to allow other applications to access the device. For Win32 applications, multiple threads can access the same device at any time.

CloseRadioDevice

Closes a radio device that was previously opened, and allows another program to access the radio device.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to the radio device to close, returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE, otherwise the return value is FALSE (invalid handle, or has already been closed).

GetRadioList

The GetRadioList function returns information about all G315 devices that can be opened.

C/C++ declaration

Parameters

lpRadioInfo

The buffer for an array of RADIO_INFO2 structures. It will contain a RADIO_INFO2 structure for each unalocated G315 device present in the system.

BufferSize

The size of the lpRadioInfo buffer. The function doesn't write all structures if the buffer is too small.

Infosize

Pointer to an integer value that will be written by GetRadioList with the size of the structure for each available receiver.

Return Value

The count of unallocated G315 devices present in the system. This value can be greater than the real number of RADIO_INFO2 structures written to the buffer if the buffer is too small.

See Also

Opening the device example

InitializeDemodulator

The DSP must be initialized before any signal processing, including signal strength measurement, can commence. When initializing the demodulator the full path to a valid calibration data file may be provided if signal strength measuremen must be calibrated. If not so, the passed pointer should be NULL.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

CalFilePath

Pointer to the file containing the calibration data for the receiver in use

Return Value

The returned value is TRUE if the demodulator could be initialized and FALSE if not.

Remarks

Once the demodulator is initialized, all handles to the receiver must be closed in order to allow a full re-initialization.

See Also

Demodulator initializing and using example

GetSignalStrengthdBm

The GetSignalStrengthdBm function returns the strength of the radio signal in dBm received by the radio device.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The aproximated value of the signal strength in dBm * 10 (i.e. the value is given in tenths of dBm). If the demodulator is properly initialized and a calibration file is provided, the resulting signal strength is calibrated.

See Also

InitializeDemodulator

GetRawSignalStrength

The GetRawSignalStrength function returns the "raw" signal strength value. This is made available for compatibility with applications which expect the signal strength value to be from 0 (min signal level) to 255 (max signal level). The formula for this is:

SignalStrength_RAW = 255*(SignalStrength_dBm + 1300)/1000

This means that -130dBm corresponds to 0 and -30dBm corresponds to 255 of "raw" value.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

RAW signal strength in the interval <0,255>.

GetLastSSdBm

The GetLastSSdBm function returns the last measured strength of the radio signal in dBm. Useful during block scanning.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The aproximated value of the signal strength in dBm * 10 (i.e. the value is given in tenths of dBm).

GetLastRawSS

The GetLastRawSS function returns last measured RAW signal strength value. Useful during block scanning.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

RAW signal strength <0,255>.

GetInternalRSSI

The GetInternalRSSI function returns a combination of the RSSI and AGC values read from the receiver hardware.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

AGC value in the upper 16 bits of the result and RSSI value in the lower 16 bits of the result.

SetFrequency

The SetFrequency function sets the frequency the device is to be tuned to.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

dwFreq

Specifies the frequency to tune to receiver to.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Remarks

The lower and upper limits are specified in the dwMinFreq and dwMaxFreq fields respectively in the RADIO_INFO structure that can be retrieved with the GetInfo or G3GetRadioList function.

See Also

GetFrequency

SetFreqAsync

The SetFreqAsync function starts the sequence of hardware commands that sets the frequency the device is to be tuned to. In order to insure the sequence has been executed and that the hardware is properly tuned, WaitFreqAsync function must be called.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

dwFreq

Specifies the frequency to tune to receiver to.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Remarks

The lower and upper limits are specified in the dwMinFreq and dwMaxFreq fields respectively in the RADIO_INFO structure that can be retrieved with the GetInfo or G3GetRadioList function.

See Also

WaitFreqAsync

WaitFreqAsync

The WaitFreqAsync function waits for the end of a receiver tunning started by a SetFreqAsync call.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

SetFreqAsync

SetIF2Frequency

The SetIF2Frequency function sets the center frequency of the last IF signal.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

iFreq

Specifies the IF2 frequency. It can be either positive or negative, negative values causing an IF2 spectrum inversion

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetIF2Frequency

SetAtten

The SetAtten function activates or deactivates the RF input attenuator. It is used to prevent overloading of the receiver with strong signals.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

fAtten

If TRUE, the RF attenuator is on, otherwise if FALSE, the RF attenuator is off (more sensitive).

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetAtten

SetRFAmp

The SetRFAmp function activates or deactivates the RF preamplifier. It is used to improve receiving weak signals.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

fRFAmp

If TRUE, the RF preamplifier is on (more sensitive), otherwise if FALSE, the RF preamplifier is off.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetRFAmp

SetPower

The SetPower function switches the device's power on or off. This function can be used to power down the receiver in portable applications to conserve battery power.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

fPower

If TRUE, the radio's power is on, otherwise if FALSE, the radio's power is off.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetPower

SetAGC

The SetAGC function sets the AGC value for given receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

iAGC

AGC value <0,3> - off, slow, medium or fast.

Return Value

If the function succeeds, the return value is TRUE, else the return value is FALSE.

See Also

GetAGC

SetIFGain

Sets IFGain value for the specified receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

iIFGain

IFGain value <0,100> to be set.

Return Value

If the function succeeds, the return value is TRUE, else the return value is FALSE.

See Also

GetIFGain

SetFMW

The SetFMW function switches the demodulator software input (either sound card or internal codec depending on the model) between narrow band IF output and the optional FMW module audio output.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

FMW

If TRUE the FMW module audio output is selected.

Return Value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

See Also

GetFMW

SetRefClock

Specifies the reference clock frequency and allows switching between internal and external references.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

RefClock

The frequency of the external reference clock. If 0 is specified the internal reference clock is used.

Return Value

If the function succeeds, the return value is TRUE, else the return value is FALSE.

See Also

GetRefClock

GetFrequency

The GetFrequency function retrieves the frequency the receiver is tuned to.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The current receiver frequency in Hz. If the handle is invalid, 0 is returned instead.

See Also

SetFrequency

IsSpectrumInverted

Checks if the receiver IF spectrum for narrow band demodulation is inverted.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE if the narrow band IF spectrum is inverted for the currently tuned frequency. Otherwise FALSE is returned.

GetIF2Frequency

The GetIF2Frequency function retrieves the current IF2 frequency.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The current IF2 frequency in Hz. If the handle is invalid, 0 is returned instead.

See Also

SetIF2Frequency

GetAtten

The GetAtten function returns the RF input attenuator setting.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

GetAtten returns TRUE if the RF attenuator is on, otherwise it returns FALSE if it is off.

See Also

SetAtten

GetRFAmp

The GetAtten function returns the RF input preamplifier setting.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

GetRFAmp returns TRUE if the RF preamplifier is on, otherwise it returns FALSE if it is off.

See Also

SetRFAmp

GetPower

The GetPower function returns whether the receiver's power is on or off.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

Returns TRUE if the receiver's power is on, otherwise it returns FALSE if it is off.

See Also

SetPower

GetAGC

The GetAGC function returns current AGC value of radio device.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The current AGC value if successful, otherwise -1 is returned.

See Also

SetAGC

GetIFGain

Retrieves the IFGain value of the receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is the IFGain value. Otherwise -1 is returned.

See Also

SetIFGain

GetFMW

The GetFMW function returns information about the demodulator software input source.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

Returns TRUE if the FMW audio output is the currently selected source.

See Also

SetFMW

GetLock

Retrieves the PLLs lock status.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

GetType

This argument is reserved for future extensions.

Return Value

If the function succeeds, the return value is a combination of the PLLs lock bits. Otherwise 0 is returned.

GetRefClock

Retrieves the current reference clock frequency.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is current reference clock frequency, else the return value is 0xFFFFFFFF.

See Also

SetRefClock

BlockScan

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Freqs

The array of frequencies to be scanned.

Count

The count of frequencies to be scanned.

StopSquelchRaw

The value of the RAW signal strength at which the scanning should stop.

FeedbackTime

The time interval in ms after which G3 API sends you scanned data.

WinHandle

The window handle to which the scanned data will arrive.

Msg

The constant for window mesage that will bring the scanned data.

Return Value

If the scan started, the return value is TRUE. Otherwise FALSE is returned.

Remarks

Scanned RAW signal strength values are written back to the Freqs buffer. Each frequency in the Freqs buffer is replaced by appropriate RAW value. Parts of this buffer are sent to the appplication after Feedback time interval expires. The block scanning automatically ends when scanned RAW signal strength value rises StopSquelchRaw parameter. The scanned RAW values are sent using window message Msg to the window procedure of the window handle WinHandle with buffer pointer as WParam and buffer length as LParam.

See Also

Block scanning example

StopBlockScan

Stops block scanning if it has been started.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

See Also

Block scanning example

PauseBlockScan

Pauses block scanning, if it has been started.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

See Also

Block scanning example

ResumeBlockScan

Resumes block scanning if it has been paused.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

See Also

Block scanning example

GetInfo

Retrieves the RADIO_INFO2 structure of the receiver.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

info

The pointer to an empty RADIO_INFO2 structure. It must have bLength member initialized to sizeof(RADIO_INFO2).

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

Remarks

For backward compatibility, depending on the value of the bLength field in the passed structure, also OLD_RADIO_INFO and RADIO_INFO structures are supported.

IsBusy

Checks the receiver whether it is ready to accept commands.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the receiver is currently busy TRUE is returned. Otherwise the function returns FALSE.

GetPath

Retrieves the system pathname of the receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Pathname

Pointer to the buffer that will be filled by the function with the device pathname.

size

The size of the destination buffer that must not be exceeded by the function.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

See Also

GetPath2

GetPath2

Retrieves the system pathname of the receiver.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is a pointer to the receiver pathname. Otherwise NULL is returned.

See Also

GetPath

IsDeviceConnected

Checks if the receiver is still connected to the computer. It is significant only for external receivers while the internal ones will always be reported as connected.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

IsUSVersion

Checks if the receiver is a special US version one.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

If the function succeeds, the return value is TRUE if the receiver is a special US version one. Otherwise FALSE is returned.

SetLEDFlashPattern

Sets the LED flashing pattern for the external receivers to the specified value.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Pattern

The pattern value as an 8-bit mask for 8 time slots; for each of those slots, a bit value of 1 corresponds to LED turned on and a bit value of 0 corresponds to LED turned off.

Return Value

If the function succeeds, the return value is TRUE. Otherwise FALSE is returned.

SetFreqPipelined

Function for queueing a frequency for pipelined scanning sequence.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

dwFreq

The frequency to be queued

IsFirst

Flag to be set to TRUE when the first frequency of the pipelined scanning sequence and FALSE for all other frequencies

Settling

AGC settling time in ms to be used when measuring the signal strength

Return Value

If the function succeeds, the return value is 0.

Remarks

A pipelined scanning sequence is built from calls of SetFreqPipelined and GetSSPipelined functions. The first function queues the frequencies to be scanned and the second one waits for ending the current step and returns the signal strength related readings. A pipelined sequence starts with two SetFreqPipelined calls, with the first and the second frequencies to be measured, and continues with alternating calls of GetSSPipelined and SetFreqPipelined. The signal strength reading corresponds to the frequency pipelined one steps before as the reading is immeditely followed, into the driver, by starting the tuning to the last pipelined frequency. This approach allows the application to use for other purposes the time normally spent waiting for the tuning and signal streangth reading to end.

Sea Also

Pipelined scanning example

GetSSPipelined

Function for reading the signal strength during pipelined scanning sequences.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

SS

Pointer to the signal strength variable to be written on success; if NULL the value is discarded

RawSS

Pointer to the raw signal strength variable to be written on success; if NULL the value is discarded

RSSI

Pointer to the RSSI variable to be written on success; if NULL the value is discarded

AGC

Pointer to the AGC loop gain variable to be written on success; if NULL the value is discarded

Return Value

If the function succeeds, the return value is 0.

Sea Also

SetFreqPipelined

dspOpen

This is the first function that should be called when using the DSP. It announces the API and the driver that a specific range of resources in the DSP is required by the application so no other application will be allowed to access the same resources until they are freed. It also registers a callback function to the API that will be used when interrupts are generated by the DSP.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Mask

One or more of the following constants specifying the DSP resources to be blocked for the application use:
WR_G315_DSP_1_1 - 0x00000001 - Lower halves of DSP program and data memories
WR_G315_DSP_1_2 - 0x00000002 - Upper halves of DSP program and data memories

CallbackFunc

Pointer to an application defined function that should be called by the API when a DSP interrupt occurs

CallbackTarget

Value to be passed to the application defined function as argument

Return Value

The function returns a handle to the reserved DSP resources or 0 in case of error. The call returns with success only if all required DSP resources could be allocated. The handle retuned by dspOpen must be used in all subsequent DSP related functions calls.

See Also

Simple DSP loopback example

dspClose

When the DSP resources are nolonger needed the API and the driver must be announced in order to allow other applications use them. That is done by calling dspClose. After it returns, the DSP handle is nolonger valid and DSP interrupts, even if previously enabled and not disabled through software, are nolonger dispatched for the closed handle. In order to allow maximum flexibility, the DSP is not automatically reset upon closing so it will continue running. This feature is very important when facilities like the “Mute audio on exit”, implemented in the standard G315i demodulator plug-in, are required.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

DSPHandle

DSP handle for which the resources can be freed for other applications; it must be a value previously returned by a dspOpen call.

Return Value

The function returns TRUE on successful closing and FALSE if there was an error.

See Also

Simple DSP loopback example

dspReset

Before loading the code into the DSP in order to boot, normally it should be reset, but there may be special situation in which such a behaviour is not desired. Depending on the current usage of the DSP resources, the driver may perform either a hardware or software reset. The initial DSP status after a software reset is unpredictable and thus any code used to boot it should do all the required initializations. Even with this small disadvantage, the software reset is very important when sharing the DSP between two applications.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

DSPHandle

DSP handle for which the resources can be freed for other applications; it must be a value previously returned by a dspOpen call.

Mask

One or more of the following constants specifying the DSP resources to be reset:
WR_G315_DSP_1_1 - 0x00000001 - Lower halves of DSP program and data memories
WR_G315_DSP_1_2 - 0x00000002 - Upper halves of DSP program and data memories

Return Value

The function returns TRUE on successful closing and FALSE if there was an error.

Remarks

If the Mask argument indicates the entire DSP (WR_G315_1_1|WR_G315_1_2) a hardware reset is issued. Otherwise a software reset of the code loaded into the specified DSP resources will be done.

See Also

Simple DSP loopback example

dspBoot

In order to make the DSP run, it must be booted. That requires two things: a special program to do all initializations and then continue with the actual processing and a way of loading that program into the DSP. dspBoot is the function that insures proper loading of a user specified program into the DSP resources associated to the opened handle. For correct booting the data passed to the function must have a very strict format.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

DSPHandle

DSP handle for which the resources can be freed for other applications; it must be a value previously returned by a dspOpen call.

Mask

One or more of the following constants specifying the DSP to boot:
WR_G315_DSP_1_1 - 0x00000001 - Lower halves of DSP program and data memories
WR_G315_DSP_1_2 - 0x00000002 - Upper halves of DSP program and data memories

Data

The data to be used to boot the specified DSP resources

Size

The size of the boot data in words.

Return Value

If the booting succeeds the return value is TRUE, else it is FALSE. The booting may fail from many reasons, including incorrect booting data.

Remarks

The boot data must be generated using VisualDSP++ tools with linker output set for IDMA booting. The output of the linker will have the extension .bnm and must be further processed with the IDMA2C tool presented later in this paper. The resulting file is a C/C++ source file that contains an array that should be passed directly to dspBoot after including it in the application source files. Any other data may cause undesired behaviour and may also crash the system.

See Also

Simple DSP loopback example

dspRead

This function reads data directly from the DSP memory and stores it in the specified application buffer. The position from which the read is done is application dependant and is given through Offset. This function accesses both the program and the data memories and the only way to differentiate between them is through the Offset value: program memory is located at 0x0000-0x3FFF and data memory is located at 0x4000-0x7FDF. For each program memory location there are two words that must be read from the DSP.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

DSPHandle

DSP handle for which the resources can be freed for other applications; it must be a value previously returned by a dspOpen call.

Mask

One or more of the following constants specifying the DSP to read from:
WR_G315_DSP_1_1 - 0x00000001 - Lower halves of DSP program and data memories
WR_G315_DSP_1_2 - 0x00000002 - Upper halves of DSP program and data memories

Offset

The DSP memory address from which the read should be started

lpData

Pointer to the buffer into which the read data should be stored

Size

The size of the read buffer in words

Return Value

The returned value is TRUE if the read succeeded and FALSE if not.

Remarks

Practically the application can read from a DSP memory location outside the resources associated to the specified DSP handle, but that is not the recommended usage except for only one situation – when two plug-ins use the the DSP simultaneously.

See Also

Simple DSP loopback example

dspWrite

This function writes data directly into the DSP memory from the specified application buffer. The position to which the write is done is application dependant and is given through Offset. This function accesses both the program and the data memories and the only way to differentiate between them is through the Offset value: program memory is located at 0x0000-0x3FFF and data memory is located at 0x4000-0x7FDF. For each program memory location there are two words that must be written to the DSP.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

DSPHandle

DSP handle for which the resources can be freed for other applications; it must be a value previously returned by a dspOpen call.

Mask

One or more of the following constants specifying the DSP to write to:
WR_G315_DSP_1_1 - 0x00000001 - Lower halves of DSP program and data memories
WR_G315_DSP_1_2 - 0x00000002 - Upper halves of DSP program and data memories

Offset

The DSP memory address to which the write should be started

lpData

Pointer to the buffer from which the write data should be read

Size

The size of the write buffer in words

Return Value

The returned value is TRUE if the write succeeded and FALSE if not.

Remarks

Practically the application can write to a DSP memory location outside the resources associated to the specified DSP handle, but that is not the recommended usage except for only one situation – when two plug-ins use the the DSP simultaneously.

See Also

Simple DSP loopback example

SetNotchFilter

Function for configuring the IF notch filter. The frequency is specified relatively to the IF frequency and is limited to the IF hardware filter bandwidth, meaning from -7500 to +7500.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Active

TRUE if the notch filter should be active and FALSE if not

Freq

The frequency offset of the notch filter relative to the center of the crystal IF bandwidth filter

BW

The bandwidth of the notch filter

Return Value

The return value is TRUE if the notch filter can be configured with the given parameters and FALSE if not.

See Also

GetNotchFilter
Demodulator initializing and using example

SetNoiseBlanker

Function for configuring the noise blanker. The treshold is given as percentage of the maximum acceptable input signal.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Active

TRUE if the noise blanker should be active and FALSE if not

Thres

Noise blanking threshold level given as percent of the whole signal range (0..100)

Return Value

The return value is TRUE if the noise blanker can be configured with the given parameters and FALSE if not.

See Also

GetNoiseBlanker
Demodulator initializing and using example

SetIFShift

Function for setting the IF shift. The specified value is added to the IF2 frequency and provides the actual receiving frequency. The resulting value must not exceed the IF hardware filter bandwidth (15kHz for G315), thus the accepted values are in the range -7500...+7500.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Shift

IF shift value relative to the IF crystal filter center

Return Value

The return value is TRUE if the IF shift can be configured with the given parameter and FALSE if not.

See Also

GetIFShift
Demodulator initializing and using example

SetIFBandwidth

Function for setting the IF bandwidth. Values in the 1Hz...15kHz range are accepted. Through this API call the filters that come after the I and Q multipliers are controlled.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

BW

The IF bandwidth value

Return Value

The return value is TRUE if the IF bandwidth can be configured with the given parameter and FALSE if not.

See Also

GetIFBandwidth
Demodulator initializing and using example

SetPassbandOffset

Function for setting the pass-band offset value. Normally it is 0. Accepted values are from -8kHz...+8kHz. It controls the amount that the spectrum is shifted before actual demodulation.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

PBO

The pass-band offset value to be set

Return Value

The return value is TRUE if the pass-band offset can be configured with the given parameter and FALSE if not.

See Also

GetPassbandOffset
Demodulator initializing and using example

SetSoftAGC

Function for setting the desired AGC behaviour. The AGC is active for as long as the reference level is below 0. The attack and decay times are automatically set to 1 if the values passed to the API are 0.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Data

Pointer to a SOFTAGC_DATA structure containing the AGC configuration values

Return Value

The return value is TRUE if the software AGC can be configured with the given parameters and FALSE if not.

Remarks

Reference level (iRefLevel in SOFTAGC_DATA) should be below -3 and it is given in dB. Normal value is -6...-8 for modes with carrier (AM, AMS, FM, CW) and -15 for modes with no carrier.

See Also

GetSoftAGC
Demodulator initializing and using example

SetMode

Function for selecting the desired demodulation mode. All demodulation modes available in the G315 demodulator can be selected here. The codes for the modes are the corresponding XRS codes - RADIOMODE_xxx.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Mode

The code for the demodulation mode:

CW 0
AM 1
FMN 2
LSB 4
USB 5
AMS 8
DSB 13
ISB 14

Return Value

The return value is TRUE if the demodulation mode can be set and FALSE if not.

See Also

GetMode
Demodulator initializing and using example

SetAudioBandwidth

Function for setting the final audio bandwidth. For linear modulation types it should be equal to IF bandwidth (LSB, USB) or half the IF bandwidth (AM, AMS, DSB, ISB). For exponential modulations (FM) it is transmission dependant. For CW there is a special condition as the audio bandwidth should be the minimum between half IF bandwidth and the CW tone frequency.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

BW

The audio bandwidth in Hz

Return Value

The return value is TRUE if the audio bandwidth can be set and FALSE if not.

See Also

GetAudioBandwidth
Demodulator initializing and using example

SetAudioGain

Function for setting the fixed audio gain. This value is used to provide a fixed audio amplification when the software AGC is disabled.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Gain

The fixed audio gain

Return Value

The return value is TRUE if the fixed audio gain can be set and FALSE if not.

See Also

GetAudioGain
Demodulator initializing and using example

SetVolume

Function for setting the audition volume. It can be any value between 0 and 31.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Volume

The audition volume

Return Value

The return value is TRUE if the audition volume can be set and FALSE if not.

See Also

GetVolume
Demodulator initializing and using example

SetFMAFSquelchLevel

Function for setting the AF squelch while demodulating FM transmissions. The level corresponds to the minimum noise level that will mute the audio output. By specifying a value of 0 the AF squelch is disabled.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Level

The AF squelch level

Return Value

The return value is TRUE if the FM AF squelch level can be set and FALSE if not.

See Also

GetFMAFSquelchLevel
Demodulator initializing and using example

SetISBAudioChannel

Function for specifying the audio channel that should be sent to the audio output when demodulating ISB transmissions. 0 stands for Left (LSB) and 1 for Right (USB).

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Channel

The channel that is to be sent to the audio output

Return Value

The return value is TRUE if the ISB audio channel can be selected and FALSE if not.

See Also

GetISBAudioChannel
Demodulator initializing and using example

SetCWTone

Function for setting the frequency of the audible tone when receving CW transmissions.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Freq

The CW tone frequency

Return Value

The return value is TRUE if the CW tone frequency can be set and FALSE if not.

See Also

GetCWTone
Demodulator initializing and using example

GetNotchFilter

Function for retrieving the IF notch filter settings.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Freq

Pointer to the location where the current central frequency of the notch filter should be stored

BW

Pointer to the location where the current bandwidth of the notch filter should be stored

Return Value

The return value is TRUE if the notch filter is active and FALSE if not.

See Also

SetNotchFilter
Demodulator initializing and using example

GetNoiseBlanker

Function for retrieving the noise blanker settings.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Thres

Pointer to the location where the current threshold level of the noise blanker should be stored

Return Value

The return value is TRUE if the noise blanker is active and FALSE if not.

See Also

SetNoiseBlanker
Demodulator initializing and using example

GetIFShift

Function for retrieving the IF shift value.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the IF shift value in Hz, relative to the center of the crystal IF filter.

See Also

SetIFShift
Demodulator initializing and using example

GetIFBandwidth

Function for retrieving the IF bandwidth value.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the IF bandwidth in Hz.

See Also

SetIFBandwidth
Demodulator initializing and using example

GetPassbandOffset

Function for retrieving the pass-band offset value.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the pass-band offset in Hz.

See Also

SetPassbandOffset
Demodulator initializing and using example

GetSoftAGC

Function for retrieving the software AGC parameters.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Data

Pointer to a SOFTAGC_DATA structure in which the AGC configuration should be stored

Return Value

The return value is TRUE if the software AGC configuration could be retrieved and FALSE if not.

See Also

SetSoftAGC
Demodulator initializing and using example

GetMode

Function for getting the current demodulation mode.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the code of the current demodulation mode.

See Also

SetMode
Demodulator initializing and using example

GetAudioBandwidth

Function for getting the current audio bandwidth.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current audio bandwidth in Hz.

See Also

SetAudioBandwidth
Demodulator initializing and using example

GetAudioGain

Function for getting the current fixed audio gain.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current fixed audio gain.

See Also

SetAudioGain
Demodulator initializing and using example

GetVolume

Function for getting the current audition volume.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current audition volume.

See Also

SetVolume
Demodulator initializing and using example

GetFMAFSquelchLevel

Function for getting the current FM AF squelch level.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current FM AF squelch level.

See Also

SetFMAFSquelchLevel
Demodulator initializing and using example

GetISBAudioChannel

Function for getting the currently selected ISB audio channel.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the currently selected ISB audio channel.

See Also

SetISBAudioChannel
Demodulator initializing and using example

GetCWTone

Function for getting the CW tone frequency.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current CW tone frequency.

See Also

SetCWTone
Demodulator initializing and using example

GetTuneError

Function for getting the tuning error after the demodulator has been initialized. The resulting value is valid only if the receiver is tuned to a transmissions. The returned value must be substracted from the frequency to which the receiver is currently tuned.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current tuning frequency error.

SeeAlso

Demodulator initializing and using example

GetFrequencyDeviation

Function for getting the frequency deviation (in Hz) of the currently received transmission.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the frequency deviation of the transmission currently demodulated.

SeeAlso

Demodulator initializing and using example

GetAMDepth

Function for getting the AM depth for the current transmission. The 0..1 range normal for this parameter is returned scaled to 0..1000.

C/C++ declaration

Delphi declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

Return Value

The return value is the current tuning frequency error.

SeeAlso

Demodulator initializing and using example

SetupStreams

Function for activating the IF and/or audio streams callback functions while the demodulator is active.

C/C++ declaration

Parameters

hRadio

Handle to a radio device that was returned by OpenRadioDevice or Open.

IFH

Application provided function to be called by the API when there is new data received through the IF stream from the receiver; if NULL IF streaming is nolonger sent to the application

IFT

Argument to be passed to the IFH application defined callback function

AudioH

Application provided function to be called by the API when there is new data received through the audio stream from the receiver; if NULL audio streaming is nolonger sent to the application

AudioT

Argument to be passed to the AudioH application defined callback function

Return Value

The return value is TRUE if the streams callback functions could be properly set and FALSE if not.

Remarks

For demodulators that provide more channels (like ISB), both channels are provided in the audio stream with alternating samples.

Both callback functions should like like this:

The arguments are the following ones:

The buffers sent to the application defined callback functions will always have the same size and will always contain the same number of samples of samples sets. In no case they will contain fractions of samples or samples sets.

SeeAlso

Demodulator initializing and using example