SignalHawk™ Application Programming Interface Operations Manual This is a preliminary manual. Specifications, limits, and text are subject to change without notice. The information within this manual was as complete as possible at the time of printing. Bird Electronic Corporation is not liable for errors. ©Copyright 2010 by Bird Electronic Corporation Instruction Book Part Number 920-SH-API Rev.
Safety Precautions The following are general safety precautions that are not necessarily related to any specific part or procedure, and do not necessarily appear elsewhere in this publication. These precautions must be thoroughly understood and apply to all phases of operation and maintenance. WARNING Keep Away From Live Circuits Operating Personnel must at all times observe general safety precautions.
Safety Symbols WARNING Warning notes call attention to a procedure, which if not correctly performed, could result in personal injury. CAUTION Caution notes call attention to a procedure, which if not correctly performed, could result in damage to the instrument. Note: Calls attention to supplemental information.
Safety Statements USAGE ANY USE OF THIS INSTRUMENT IN A MANNER NOT SPECIFIED BY THE MANUFACTURER MAY IMPAIR THE INSTRUMENT’S SAFETY PROTECTION. USO EL USO DE ESTE INSTRUMENTO DE MANERA NO ESPECIFICADA POR EL FABRICANTE, PUEDE ANULAR LA PROTECCIÓN DE SEGURIDAD DEL INSTRUMENTO. BENUTZUNG WIRD DAS GERÄT AUF ANDERE WEISE VERWENDET ALS VOM HERSTELLER BESCHRIEBEN, KANN DIE GERÄTESICHERHEIT BEEINTRÄCHTIGT WERDEN.
SERVICE SERVICING INSTRUCTIONS ARE FOR USE BY SERVICE TRAINED PERSONNEL ONLY. TO AVOID DANGEROUS ELECTRIC SHOCK, DO NOT PERFORM ANY SERVICING UNLESS QUALIFIED TO DO SO. SERVICIO LAS INSTRUCCIONES DE SERVICIO SON PARA USO EXCLUSIVO DEL PERSONAL DE SERVICIO CAPACITADO. PARA EVITAR EL PELIGRO DE DESCARGAS ELÉCTRICAS, NO REALICE NINGÚN SERVICIO A MENOS QUE ESTÉ CAPACITADO PARA HACERIO. WARTUNG ANWEISUNGEN FÜR DIE WARTUNG DES GERÄTES GELTEN NUR FÜR GESCHULTES FACHPERSONAL.
About This Manual This manual covers the operating and maintenance instructions for the following models: SH-36S-PC Changes to this Manual We have made every effort to ensure this manual is accurate. If you discover any errors, or if you have suggestions for improving this manual, please send your comments to our Solon, Ohio factory. This manual may be periodically updated. When inquiring about updates to this manual refer to the part number and revision on the title page.
vi
Table of Contents Safety Precautions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i Safety Symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ii Safety Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Changes to this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
shDisconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 shGetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Returns . . . . . . . . . . . . . . . . . .
shSaGetDemodData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Returns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 shSaStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Arguments . . . . . . . . . . . . . . . . . . . . .
x
Chapter 1 Introduction This document describes an Application Programming Interface (API) for the Bird PC Hawk spectrum analyzer. The API is written in C and provides a C calling interface to a Windows DLL. The API for Windows has groups of functions distinguished by their prefixes as follows: z z sh... for general management and control functions. shSa... for functions specific to Spectrum Analyzer measurements. The general outline of the steps required to perform a sweep are as follows: 1. 2. 3. 4. 5.
Bird Technologies 2
Chapter 2 Reference General Types shConnection_t Structure This structure is used to represent a connection that has been established with a particular Signal Hawk RF Module. The API assigns the handle. User applications must use a valid shConnection_t object to communicate with specific PC Hawk devices. shConnection_t Structure Members Device A handle used by the API to reference a specific PC Hawk inside the API.
Bird Technologies shErrorData Structure Members ErrorCode Numeric code for the error. ErrorMessage[MAX_ERROR_ME S_SIZE] Short message of type TCHAR, describing the error. General Functions shInitialize This function initializes the API. This must be called before any other API function. DWORD shInitialize() Arguments None. Returns Returns an error code indicating the status of the operation: ERROR_SUCCESS SH_ERROR_INITIALIZE_USB_ LIBRARY_FAILED Others Initialization was successful.
Reference shConnectDefault This function establishes a connection with the first Signal Hawk RF Module found. int BIRD_SH_API shConnectDefault(shConnection_t* Connection); Arguments Connection Pointer to a structure of type shConnection_t to hold the context for the connection.
Bird Technologies Returns Returns an error code indicating the status of the operation: ERROR_SUCCESS SH_ERROR_DEVICE_ ALREADY_CONNECTED SH_ERROR_NO_DEVICE_ ATTACHED SH_ERROR_USB_LIBRARY_ NOT_INITIALIZED Other Operation was successful. The device is already connected. The driver did not find any devices. The USB driver library has not been initialized. Call shInitialize() to load and initialize the USB libraries before using other functions of the API.
Reference SH_ERROR_USB_SELECTED_ DEVICE_NOT_FOUND SH_ERROR_USB_LIBRARY_ NOT_INITIALIZED The driver did not find the requested device. The USB driver library has not been initialized. Call shInitialize() to load and initialize the USB libraries before using other functions of the API. SH_ERROR_USB_CONNECTION There was a problem with the USB _FAILED driver. Other Call shGetLastError() for information on the specific error. Remarks Call shGetDeviceList(…) to get a list of available PC Hawk devices.
Bird Technologies shGetLastError This function returns information about the most recent error encountered by the API. Use this function to get a text string description of the error. int BIRD_SH_API shGetLastError(shErrorData* Error); Arguments Error Pointer to a data structure of type shErrorData. Returns Returns an error code indicating the status of the operation: ERROR_SUCCESS Initialization was successful. SH_ERROR_INVALID_ ARGUMENT One or more of the arguments was not valid.
Reference Spectrum Analyzer Types shSaParameters_t Structure Contains structures used to configure the various measurements of the PC Hawk. MeasureId, SaConfigParameters, SaTriggerParameters are required for all measurements. The remaining structures are measurement specific and can be ignored if you are not using the measurements they apply to. Field Comments MeasureId Enumerated int of type shSaMeasureId indicating the type of measurement.
Bird Technologies shSaConfigParameters Structure CenterFrequency FrequencySpan VideoBandwidth ResolutionBandwidth DetectorMode PreampAttenuation Unsigned 64 bit variable (type Frequency) Specifies the center frequency in Hz Unsigned 64 bit variable (type Frequency) Specifies the frequency span in Hz Enumerated integer of type shSaBwSettings indicating the video bandwidth setting. Enumerated integer of type shSaBwSettings indicating the resolution bandwidth setting.
Reference shSaOccupiedBandwidthConfig Structure OccupiedBandwidthType Enumerated integer of type shSaOccupiedBWType indicating the method percent or dBc) used to set the power level for the measurement. OccupiedBandwidthLevel Specifies the power level used to calculate the occupied bandwidth. shSaChannelConfig Structure ChannelWidth Unsigned 64 bit variable (type Frequency) Specifies the channel width in Hz.
Bird Technologies shSaCountersConfig Structure CountersEnable[ SA_MAX_COUNTERS] CountersFrequency[ SA_MAX_COUNTERS] Array of type boolean. The array contains enable state for up to MAX_COUNTERS frequency counter measurements. Array of type Frequency (unsigned 64 bit integer). The array contains the reference frequency (in Hz) for as many as MAX_COUNTERS frequency counter measurements.
Reference TimeData[SA_MAX_DATA_SIZE] Array of type float containing Time Domain measurement data. SweepData[SA_MAX_DATA_SIZE] Array of type float containing the Spectrum Analyzer measurement data. OccupiedBandwidthData Structure of type shSaOccupied BandwidthData containing the Occupied Bandwidth measurement data. ChannelData Structure of type shSaChannelData containing the Channel Power measurement data.
Bird Technologies SaCountersId FreqData[SA_MAX_DATA_SIZE] SweepData[SA_MAX_DATA_SIZE] CountersData SaDemodSignalId None. See shSaDemodSignalData for information on demodulation data structures. SweepCount SweepCount is used to provide information about the data set when a timeout occurs while waiting for data. Under normal conditions, the API will always return complete measurements and SweepCount = 705.
Reference shSaAdjacentChannelData Structure ChannelPower Variable of type float indicating the channel power in dBm. AdjacentUpperPower Variable of type float indicating the upper adjacent channel power in dBm. AdjacentLowerPower Variable of type float indicating the lower adjacent channel power in dBm. AdjacentUpperRatio Variable of type float indicating the upper adjacent channel ratio. AdjacentLowerRatio Variable of type float indicating the lower adjacent channel ratio.
Bird Technologies shSaMeasureId Enumeration This enumeration specifies the type of measurement as follows: SaSpecAnId SaOccupiedBandwidthId SaChannelPowerId SaAdjacentChannelId SaZeroSpanId SaCountersId SaDemodSignalId shSaPreampAttenSettings Enumeration This enumeration specifies the settings for the attenuator & preamp as follows: PreampOnAtten00dB PreampOffAtten00dB PreampOffAtten10dB PreampOffAtten20dB PreampOffAtten30dB shSaBwSettings Enumeration This enumeration specifies the settings for Resolution
Reference shSaDetectorModes enumeration This enumeration specifies the mode for the detector as follows: DetectorAverage DetectorSample DetectorMin DetectorMax shSaTriggerEvents Enumeration This enumeration specifies the settings for the trigger event as follows: TriggerEventHigh, TriggerEventLow, TriggerEventRise, TriggerEventFall, TriggerEventAnyEdge shSaTriggerModes Enumeration This enumeration specifies the settings for the trigger modes as follows: TriggerModeFreeSingle, TriggerModeExtSingle, TriggerM
Bird Technologies Returns Returns an error code indicating the status of the operation: ERROR_SUCCESS SH_ERROR_INVALID_ ARGUMENT Other Initialization was successful. The pointer to shSaParameters_t is not valid. Call shGetLastError() for information on the specific error. Remarks The default values are given in the following table. Field MeasureId Comments shSaSpecAnId saConfigParameters CenterFrequency 1800000000 Hz (1.8 GHz) FrequencySpan 3600000000 Hz (3.
Reference ZeroSpan SweepTime 5000 ms (5 s) Counters CountersEnable[i] false CountersFrequency [i] 1800000000 Hz (1.8 GHz) DemodSignal ModulationType Wideband_FM_Modulation shSaGetData This function returns the results of a sweep. int BIRD_SH_API shSaGetData( shConnection_t* Connection, shSaData_t* Data, WORD Timeout ); Arguments Connection Data Timeout Pointer to a structure of type shConnection_t which specifies a connection previously established with shConnect(…) or shConnectDefault(…).
Bird Technologies Remarks shSaGetData() only returns data for the specified measurement. shSaData_t contains structures for all the measurement types, but most of them are ignored. See the remarks on shSaData_t for more detail. shSaGetData() does not return demodulation data. Use shSaGetDemodData() to get demodulation data. shSaGetDemodData This function returns the results of a demodulation measurement.
Reference shSaStart This function starts a measurement with the specified parameters. int BIRD_SH_API shSaStart( shConnection_t* Connection, shSaParameters_t* Parameters ); Arguments Connection Parameters Pointer to a structure of type shConnection_t which specifies a connection previously established with shConnect(…) or shConnectDefault(…). Pointer to a structure of type shSaParameters_t which specifies the parameters for the measurement to be made.
Bird Technologies shSaStop This function stops a sweep. int BIRD_SH_API shSaStop( shConnection_t* Connection, WORD Timeout ); Arguments Connection Timeout Pointer to a structure of type shConnection_t to hold the context for the connection. Timeout interval in milliseconds. Returns Returns an error code indicating the status of the operation: ERROR_SUCCESS SH_ERROR_INVALID_ ARGUMENT SH_ERROR_DEVICE_NOT_ CONNECTED SH_ERROR_SELECTED_ DEVICE_NOT_CONNECTED Others Initialization was successful.
Reference 33554437 SH_ERROR_USB_CONNECTION_FAILED SH Error, USB Connection Failed 33554438 SH_ERROR_BULK_READ_FAILED SH Error, USB Bulk Read Failed 33554439 SH_ERROR_BULK_WRITE_FAILED SH Error, USB Bulk Write Failed 33554440 SH_ERROR_CONNECT_FAILED SH Error, Failed to Connect 33554441 SH_ERROR_DISCONNECT_FAILED SH Error, Failed to Disconnect 33554442 SH_ERROR_DEVICE_NOT_CONNECTED SH Error, Device Not Connected 33554443 SH_ERROR_SELECTED_DEVICE_NOT_CONNECTED SH Error, Selected Device Not Connected 33554444
Bird Technologies 33554455 SH_ERROR_CENTER_FREQUENCY_INVALID SH Error, Center Frequency Invalid 33554456 SH_ERROR_FREQUENCY_SPAN_INVALID SH Error, Frequency Span Invalid 33554457 SH_ERROR_VIDEO_BANDWIDTH_INVALID SH Error, Video Bandwidth Out Invalid 33554458 SH_ERROR_RESOLUTION_BANDWIDTH_INVALID SH Error, Resolution Bandwidth Invalid 33554459 SH_ERROR_COUNTERS_FREQUENCY_INVALID SH Error, Counters Frequency Invalid Control Parameter Errors 33554460 SH_ERROR_TRIGGER_GATE_DELAY_INVALID SH Error, Trigger Gate
Reference Installation and Packaging Bird API package is installed at C:\Program Files\Bird Technologies Group\PC SignalHawk API. Compiler and Linker required files are: z z BirdSh.h (Compiler requirement) BirdShWinC.lib (Linker requirement) Copy these files to the appropriate user’s development directory. The BirdShWinC.dll is the runtime library required file. It can be copied either to the windows/Systems32 or to the appropriate local directory.
Bird Technologies 26
