sm_api.h

Go to the documentation of this file.

// Copyright (c).2023, Signal Hound, Inc.
// For licensing information, please see the API license in the software_licenses folder
 
#ifndef SM_API_H
#define SM_API_H
 
#if defined(_WIN32) // Windows
    #ifdef SM_EXPORTS
        #define SM_API __declspec(dllexport)
    #else
        #define SM_API
    #endif
 
    // bare minimum stdint typedef support
    #if _MSC_VER < 1700 // For VS2010 or earlier
        typedef signed char        int8_t;
        typedef short              int16_t;
        typedef int                int32_t;
        typedef long long          int64_t;
        typedef unsigned char      uint8_t;
        typedef unsigned short     uint16_t;
        typedef unsigned int       uint32_t;
        typedef unsigned long long uint64_t;
    #else
        #include <stdint.h>
    #endif
 
    #define SM_DEPRECATED(comment) __declspec(deprecated(comment))
#else // Linux
    #include <stdint.h>
    #define SM_API __attribute__((visibility("default")))
 
    #if defined(__GNUC__)
        #define SM_DEPRECATED(comment) __attribute__((deprecated))
    #else
        #define SM_DEPRECATED(comment) comment
    #endif
#endif
 
#define SM_INVALID_HANDLE (-1)
 
#define SM_TRUE (1)
#define SM_FALSE (0)
 
#define SM_MAX_DEVICES (16)
 
#define SM_ADDR_ANY ("0.0.0.0")
#define SM_DEFAULT_ADDR ("192.168.2.10")
#define SM_DEFAULT_PORT (51665)
 
#define SM_AUTO_ATTEN (-1)
#define SM_MAX_ATTEN (6)
#define SM_MAX_REF_LEVEL (20.0)
 
#define SM_MAX_SWEEP_QUEUE_SZ (16)
 
#define SM200_MIN_FREQ (100.0e3)
#define SM200_MAX_FREQ (20.6e9)
#define SM435_MIN_FREQ (100.0e3)
#define SM435_MAX_FREQ (44.2e9)
#define SM435_MAX_FREQ_IF_OPT (40.8e9)
 
#define SM_MAX_IQ_DECIMATION (4096)
 
#define SM_PRESELECTOR_MAX_FREQ (645.0e6)
 
#define SM_FAST_SWEEP_MIN_RBW (30.0e3)
 
#define SM_REAL_TIME_MIN_SPAN (200.0e3)
#define SM_REAL_TIME_MAX_SPAN (160.0e6)
 
#define SM_MIN_SWEEP_TIME (1.0e-6)
#define SM_MAX_SWEEP_TIME (100.0)
 
#define SM_SPI_MAX_BYTES (4)
 
#define SM_GPIO_SWEEP_MAX_STEPS (64)
 
#define SM_GPIO_SWITCH_MAX_STEPS (64)
#define SM_GPIO_SWITCH_MIN_COUNT (2)
#define SM_GPIO_SWITCH_MAX_COUNT (4194303 - 1)
 
#define SM_TEMP_WARNING (95.0)
#define SM_TEMP_MAX (102.0)
 
#define SM_MAX_SEGMENTED_IQ_SEGMENTS (250)
#define SM_MAX_SEGMENTED_IQ_SAMPLES (520e6)
 
#define SM435_IF_OUTPUT_FREQ (1.5e9)
#define SM435_IF_OUTPUT_MIN_FREQ (24.0e9)
#define SM435_IF_OUTPUT_MAX_FREQ (43.5e9)
 
typedef enum SmStatus {
    // Internal use
    smCalErr = -1003,
    // Internal use
    smMeasErr = -1002,
    // Internal use
    smErrorIOErr = -1001,
 
    smInvalidCalibrationFileErr = -200,
    smInvalidCenterFreqErr = -101,
    smInvalidIQDecimationErr = -100,
 
    smJESDErr = -54,
    smNetworkErr = -53,
    smFx3RunErr = -52,
    smMaxDevicesConnectedErr = -51,
    smFPGABootErr = -50,
    smBootErr = -49,
 
    smGpsNotLockedErr = -16,
    smVersionMismatchErr = -14,
    smAllocationErr = -13,
 
    smSyncErr = -11,
    smInvalidSweepPosition = -10,
    smInvalidConfigurationErr = -8,
    smConnectionLostErr = -6,
    smInvalidParameterErr = -5,
    smNullPtrErr = -4,
    smInvalidDeviceErr = -3,
    smDeviceNotFoundErr = -2,
 
    smNoError = 0,
 
    smSettingClamped = 1,
    smAdcOverflow = 2,
    smUncalData = 3,
    smTempDriftWarning = 4,
    smSpanExceedsPreselector = 5,
    smTempHighWarning = 6,
    smCpuLimited = 7,
    smUpdateAPI = 8,
    smInvalidCalData = 9,
} SmStatus;
 
typedef enum SmDataType {
    smDataType32fc,
    smDataType16sc
} SmDataType;
 
typedef enum SmMode {
    smModeIdle = 0,
    smModeSweeping = 1,
    smModeRealTime = 2,
    smModeIQStreaming = 3,
    smModeIQSegmentedCapture = 5,
    smModeIQSweepList = 6,
    smModeAudio = 4,
 
    // Deprecated, use smModeIQStreaming
    smModeIQ = 3,
} SmMode;
 
typedef enum SmSweepSpeed {
    smSweepSpeedAuto = 0,
    smSweepSpeedNormal = 1,
    smSweepSpeedFast = 2
} SmSweepSpeed;
 
typedef enum SmIQStreamSampleRate {
    smIQStreamSampleRateNative = 0,
    smIQStreamSampleRateLTE = 1,
} SmIQStreamSampleRate;
 
typedef enum SmPowerState {
    smPowerStateOn = 0,
    smPowerStateStandby = 1
} SmPowerState;
 
typedef enum SmDetector {
    smDetectorAverage = 0,
    smDetectorMinMax = 1
} SmDetector;
 
typedef enum SmScale {
    smScaleLog = 0,
    smScaleLin = 1,
    smScaleFullScale = 2
} SmScale;
 
typedef enum SmVideoUnits {
    smVideoLog = 0,
    smVideoVoltage = 1,
    smVideoPower = 2,
    smVideoSample = 3
} SmVideoUnits;
 
typedef enum SmWindowType {
    smWindowFlatTop = 0,
    smWindowNutall = 2,
    smWindowBlackman = 3,
    smWindowHamming = 4,
    smWindowGaussian6dB = 5,
    smWindowRect = 6
} SmWindowType;
 
typedef enum SmTriggerType {
    smTriggerTypeImm = 0,
    smTriggerTypeVideo = 1,
    smTriggerTypeExt = 2,
    smTriggerTypeFMT = 3
} SmTriggerType;
 
typedef enum SmTriggerEdge {
    smTriggerEdgeRising = 0,
    smTriggerEdgeFalling = 1
} SmTriggerEdge;
 
typedef enum SmBool {
    smFalse = 0,
    smTrue = 1
} SmBool;
 
typedef enum SmGPIOState {
    smGPIOStateOutput = 0,
    smGPIOStateInput = 1
} SmGPIOState;
 
typedef enum SmReference {
    smReferenceUseInternal = 0,
    smReferenceUseExternal = 1
} SmReference;
 
typedef enum SmDeviceType {
    smDeviceTypeSM200A = 0,
    smDeviceTypeSM200B = 1,
    smDeviceTypeSM200C = 2,
    smDeviceTypeSM435B = 3,
    smDeviceTypeSM435C = 4
} SmDeviceType;
 
typedef enum SmAudioType {
    smAudioTypeAM = 0,
    smAudioTypeFM = 1,
    smAudioTypeUSB = 2,
    smAudioTypeLSB = 3,
    smAudioTypeCW = 4
} SmAudioType;
 
typedef enum SmGPSState {
    smGPSStateNotPresent = 0,
    smGPSStateLocked = 1,
    smGPSStateDisciplined = 2
} SmGPSState;
 
typedef struct SmGPIOStep {
    double freq;
    uint8_t mask;
} SmGPIOStep;
 
typedef struct SmDeviceDiagnostics {
    float voltage;
    float currentInput;
    float currentOCXO;
    float current58;
    float tempFPGAInternal;
    float tempFPGANear;
    float tempOCXO;
    float tempVCO;
    float tempRFBoardLO;
    float tempPowerSupply;
} SmDeviceDiagnostics;
 
#ifdef __cplusplus
extern "C" {
#endif
 
SM_API SmStatus smGetDeviceList(int *serials, int *deviceCount);
 
SM_API SmStatus smGetDeviceList2(int *serials, SmDeviceType *deviceTypes, int *deviceCount);
 
SM_API SmStatus smOpenDevice(int *device);
 
SM_API SmStatus smOpenDeviceBySerial(int *device, int serialNumber);
 
SM_API SmStatus smOpenNetworkedDevice(int *device,
                                      const char *hostAddr,
                                      const char *deviceAddr,
                                      uint16_t port);
 
SM_API SmStatus smCloseDevice(int device);
 
SM_API SmStatus smPreset(int device);
 
SM_API SmStatus smPresetSerial(int serialNumber);
 
SM_API SmStatus smNetworkedSpeedTest(int device, double durationSeconds, double *bytesPerSecond);
 
SM_API SmStatus smGetDeviceInfo(int device, SmDeviceType *deviceType, int *serialNumber);
 
SM_API SmStatus smGetFirmwareVersion(int device, int *major, int *minor, int *revision);
 
SM_API SmStatus smHasIFOutput(int device, SmBool *present);
 
SM_API SmStatus smGetDeviceDiagnostics(int device, float *voltage, float *current, float *temperature);
 
SM_API SmStatus smGetFullDeviceDiagnostics(int device, SmDeviceDiagnostics *diagnostics);
 
SM_API SmStatus smGetSFPDiagnostics(int device,
                                    float *temp,
                                    float *voltage,
                                    float *txPower,
                                    float *rxPower);
 
SM_API SmStatus smSetPowerState(int device, SmPowerState powerState);
 
SM_API SmStatus smGetPowerState(int device, SmPowerState *powerState);
 
SM_API SmStatus smSetAttenuator(int device, int atten);
 
SM_API SmStatus smGetAttenuator(int device, int *atten);
 
SM_API SmStatus smSetRefLevel(int device, double refLevel);
 
SM_API SmStatus smGetRefLevel(int device, double *refLevel);
 
SM_API SmStatus smSetPreselector(int device, SmBool enabled);
 
SM_API SmStatus smGetPreselector(int device, SmBool *enabled);
 
SM_API SmStatus smSetGPIOState(int device, SmGPIOState lowerState, SmGPIOState upperState);
 
SM_API SmStatus smGetGPIOState(int device, SmGPIOState *lowerState, SmGPIOState *upperState);
 
SM_API SmStatus smWriteGPIOImm(int device, uint8_t data);
 
SM_API SmStatus smReadGPIOImm(int device, uint8_t *data);
 
SM_API SmStatus smWriteSPI(int device, uint32_t data, int byteCount);
 
SM_API SmStatus smSetGPIOSweepDisabled(int device);
 
SM_API SmStatus smSetGPIOSweep(int device, SmGPIOStep *steps, int stepCount);
 
SM_API SmStatus smSetGPIOSwitchingDisabled(int device);
 
SM_API SmStatus smSetGPIOSwitching(int device, uint8_t *gpio, uint32_t *counts, int gpioSteps);
 
SM_API SmStatus smSetExternalReference(int device, SmBool enabled);
 
SM_API SmStatus smGetExternalReference(int device, SmBool *enabled);
 
SM_API SmStatus smSetReference(int device, SmReference reference);
 
SM_API SmStatus smGetReference(int device, SmReference *reference);
 
SM_API SmStatus smSetGPSTimebaseUpdate(int device, SmBool enabled);
 
SM_API SmStatus smGetGPSTimebaseUpdate(int device, SmBool *enabled);
 
SM_API SmStatus smGetGPSHoldoverInfo(int device, SmBool *usingGPSHoldover, uint64_t *lastHoldoverTime);
 
SM_API SmStatus smGetGPSState(int device, SmGPSState *GPSState);
 
SM_API SmStatus smSetSweepSpeed(int device, SmSweepSpeed sweepSpeed);
 
SM_API SmStatus smSetSweepCenterSpan(int device, double centerFreqHz, double spanHz);
 
SM_API SmStatus smSetSweepStartStop(int device, double startFreqHz, double stopFreqHz);
 
SM_API SmStatus smSetSweepCoupling(int device, double rbw, double vbw, double sweepTime);
 
SM_API SmStatus smSetSweepDetector(int device, SmDetector detector, SmVideoUnits videoUnits);
 
SM_API SmStatus smSetSweepScale(int device, SmScale scale);
 
SM_API SmStatus smSetSweepWindow(int device, SmWindowType window);
 
SM_API SmStatus smSetSweepSpurReject(int device, SmBool spurRejectEnabled);
 
SM_API SmStatus smSetRealTimeCenterSpan(int device, double centerFreqHz, double spanHz);
 
SM_API SmStatus smSetRealTimeRBW(int device, double rbw);
 
SM_API SmStatus smSetRealTimeDetector(int device, SmDetector detector);
 
SM_API SmStatus smSetRealTimeScale(int device, SmScale scale, double frameRef, double frameScale);
 
SM_API SmStatus smSetRealTimeWindow(int device, SmWindowType window);
 
SM_API SmStatus smSetIQBaseSampleRate(int device, SmIQStreamSampleRate sampleRate);
 
SM_API SmStatus smSetIQDataType(int device, SmDataType dataType);
 
SM_API SmStatus smSetIQCenterFreq(int device, double centerFreqHz);
 
SM_API SmStatus smGetIQCenterFreq(int device, double *centerFreqHz);
 
SM_API SmStatus smSetIQSampleRate(int device, int decimation);
 
SM_API SmStatus smSetIQBandwidth(int device, SmBool enableSoftwareFilter, double bandwidth);
 
SM_API SmStatus smSetIQExtTriggerEdge(int device, SmTriggerEdge edge);
 
SM_API SmStatus smSetIQTriggerSentinel(double sentinelValue);
 
SM_API SmStatus smSetIQQueueSize(int device, float ms);
 
SM_API SmStatus smSetIQSweepListDataType(int device, SmDataType dataType);
 
SM_API SmStatus smSetIQSweepListCorrected(int device, SmBool corrected);
 
SM_API SmStatus smSetIQSweepListSteps(int device, int steps);
 
SM_API SmStatus smGetIQSweepListSteps(int device, int *steps);
 
SM_API SmStatus smSetIQSweepListFreq(int device, int step, double freq);
 
SM_API SmStatus smSetIQSweepListRef(int device, int step, double level);
 
SM_API SmStatus smSetIQSweepListAtten(int device, int step, int atten);
 
SM_API SmStatus smSetIQSweepListSampleCount(int device, int step, uint32_t samples);
 
SM_API SmStatus smSetSegIQDataType(int device, SmDataType dataType);
 
SM_API SmStatus smSetSegIQCenterFreq(int device, double centerFreqHz);
 
SM_API SmStatus smSetSegIQVideoTrigger(int device, double triggerLevel, SmTriggerEdge triggerEdge);
 
SM_API SmStatus smSetSegIQExtTrigger(int device, SmTriggerEdge extTriggerEdge);
 
SM_API SmStatus smSetSegIQFMTParams(int device,
                                    int fftSize,
                                    const double *frequencies,
                                    const double *ampls,
                                    int count);
 
SM_API SmStatus smSetSegIQSegmentCount(int device, int segmentCount);
 
SM_API SmStatus smSetSegIQSegment(int device,
                                  int segment,
                                  SmTriggerType triggerType,
                                  int preTrigger,
                                  int captureSize,
                                  double timeoutSeconds);
 
SM_API SmStatus smSetAudioCenterFreq(int device, double centerFreqHz);
 
SM_API SmStatus smSetAudioType(int device, SmAudioType audioType);
 
SM_API SmStatus smSetAudioFilters(int device,
                                  double ifBandwidth,
                                  double audioLpf,
                                  double audioHpf);
 
SM_API SmStatus smSetAudioFMDeemphasis(int device, double deemphasis);
 
SM_API SmStatus smConfigure(int device, SmMode mode);
 
SM_API SmStatus smGetCurrentMode(int device, SmMode *mode);
 
SM_API SmStatus smAbort(int device);
 
SM_API SmStatus smGetSweepParameters(int device,
                                     double *actualRBW,
                                     double *actualVBW,
                                     double *actualStartFreq,
                                     double *binSize,
                                     int *sweepSize);
 
SM_API SmStatus smGetRealTimeParameters(int device,
                                        double *actualRBW,
                                        int *sweepSize,
                                        double *actualStartFreq,
                                        double *binSize,
                                        int *frameWidth,
                                        int *frameHeight,
                                        double *poi);
 
SM_API SmStatus smGetIQParameters(int device, double *sampleRate, double *bandwidth);
 
SM_API SmStatus smGetIQCorrection(int device, float *scale);
 
SM_API SmStatus smIQSweepListGetCorrections(int device, float *corrections);
 
SM_API SmStatus smSegIQGetMaxCaptures(int device, int *maxCaptures);
 
SM_API SmStatus smGetSweep(int device, float *sweepMin, float *sweepMax, int64_t *nsSinceEpoch);
 
SM_API SmStatus smSetSweepGPIO(int device, int pos, uint8_t data);
 
SM_API SmStatus smStartSweep(int device, int pos);
 
SM_API SmStatus smFinishSweep(int device, int pos, float *sweepMin, float *sweepMax, int64_t *nsSinceEpoch);
 
SM_API SmStatus smGetRealTimeFrame(int device,
                                   float *colorFrame,
                                   float *alphaFrame,
                                   float *sweepMin,
                                   float *sweepMax,
                                   int *frameCount,
                                   int64_t *nsSinceEpoch);
 
SM_API SmStatus smGetIQ(int device,
                        void *iqBuf,
                        int iqBufSize,
                        double *triggers,
                        int triggerBufSize,
                        int64_t *nsSinceEpoch,
                        SmBool purge,
                        int *sampleLoss,
                        int *samplesRemaining);
 
SM_API SmStatus smIQSweepListGetSweep(int device, void *dst, int64_t *timestamps);
 
SM_API SmStatus smIQSweepListStartSweep(int device, int pos, void *dst, int64_t *timestamps);
 
SM_API SmStatus smIQSweepListFinishSweep(int device, int pos);
 
SM_API SmStatus smSegIQCaptureStart(int device, int capture);
 
SM_API SmStatus smSegIQCaptureWait(int device, int capture);
 
SM_API SmStatus smSegIQCaptureWaitAsync(int device, int capture, SmBool *completed);
 
SM_API SmStatus smSegIQCaptureTimeout(int device, int capture, int segment, SmBool *timedOut);
 
SM_API SmStatus smSegIQCaptureTime(int device, int capture, int segment, int64_t *nsSinceEpoch);
 
SM_API SmStatus smSegIQCaptureRead(int device, int capture, int segment, void *iq, int offset, int len);
 
SM_API SmStatus smSegIQCaptureFinish(int device, int capture);
 
SM_API SmStatus smSegIQCaptureFull(int device,
                                   int capture,
                                   void *iq,
                                   int offset,
                                   int len,
                                   int64_t *nsSinceEpoch,
                                   SmBool *timedOut);
 
SM_API SmStatus smSegIQLTEResample(float *input,
                                   int inputLen,
                                   float *output,
                                   int *outputLen,
                                   bool clearDelayLine);
 
SM_API SmStatus smSetIQFullBandAtten(int device, int atten);
 
SM_API SmStatus smSetIQFullBandCorrected(int device, SmBool corrected);
 
SM_API SmStatus smSetIQFullBandSamples(int device, int samples);
 
SM_API SmStatus smSetIQFullBandTriggerType(int device, SmTriggerType triggerType);
 
SM_API SmStatus smSetIQFullBandVideoTrigger(int device, double triggerLevel);
 
SM_API SmStatus smSetIQFullBandTriggerTimeout(int device, double triggerTimeout);
 
SM_API SmStatus smGetIQFullBand(int device, float *iq, int freq);
 
SM_API SmStatus smGetIQFullBandSweep(int device, float *iq, int startIndex, int stepSize, int steps);
 
SM_API SmStatus smGetAudio(int device, float *audio);
 
SM_API SmStatus smGetGPSInfo(int device,
                             SmBool refresh,
                             SmBool *updated,
                             int64_t *secSinceEpoch,
                             double *latitude,
                             double *longitude,
                             double *altitude,
                             char *nmea,
                             int *nmeaLen);
 
SM_API SmStatus smWriteToGPS(int device, const uint8_t *mem, int len);
 
SM_API SmStatus smSetFanThreshold(int device, int temp);
 
SM_API SmStatus smGetFanThreshold(int device, int *temp);
 
SM_API SmStatus smSetIFOutput(int device, double frequency);
 
SM_API SmStatus smGetCalDate(int device, uint64_t *lastCalDate);
 
SM_API SmStatus smBroadcastNetworkConfig(const char *hostAddr,
                                         const char *deviceAddr,
                                         uint16_t port,
                                         SmBool nonVolatile);
 
SM_API SmStatus smNetworkConfigGetDeviceList(int *serials, int *deviceCount);
 
SM_API SmStatus smNetworkConfigOpenDevice(int *device, int serialNumber);
 
SM_API SmStatus smNetworkConfigCloseDevice(int device);
 
SM_API SmStatus smNetworkConfigGetMAC(int device, char *mac);
 
SM_API SmStatus smNetworkConfigSetIP(int device, const char *addr, SmBool nonVolatile);
 
SM_API SmStatus smNetworkConfigGetIP(int device, char *addr);
 
SM_API SmStatus smNetworkConfigSetPort(int device, int port, SmBool nonVolatile);
 
SM_API SmStatus smNetworkConfigGetPort(int device, int *port);
 
SM_API const char* smGetAPIVersion();
 
SM_API const char* smGetErrorString(SmStatus status);
 
SM_DEPRECATED("smSetIQUSBQueueSize has been deprecated, use smSetIQQueueSize")
SM_API SmStatus smSetIQUSBQueueSize(int device, float ms);
 
#ifdef __cplusplus
} // Extern "C"
#endif
 
// Deprecated macros
#define SM200A_AUTO_ATTEN (SM_AUTO_ATTEN)
#define SM200A_MAX_ATTEN (SM_MAX_ATTEN)
#define SM200A_MAX_REF_LEVEL (SM_MAX_REF_LEVEL)
#define SM200A_MAX_SWEEP_QUEUE_SZ (SM_MAX_SWEEP_QUEUE_SZ)
#define SM200A_MIN_FREQ (SM200_MIN_FREQ)
#define SM200A_MAX_FREQ (SM200_MAX_FREQ)
#define SM200A_MAX_IQ_DECIMATION (SM_MAX_IQ_DECIMATION)
#define SM200A_PRESELECTOR_MAX_FREQ (SM_PRESELECTOR_MAX_FREQ)
#define SM200A_FAST_SWEEP_MIN_RBW (SM_FAST_SWEEP_MIN_RBW)
#define SM200A_RTSA_MIN_SPAN (SM_REAL_TIME_MIN_SPAN)
#define SM200A_RTSA_MAX_SPAN (SM_REAL_TIME_MAX_SPAN)
#define SM200A_MIN_SWEEP_TIME (SM_MIN_SWEEP_TIME)
#define SM200A_MAX_SWEEP_TIME (SM_MAX_SWEEP_TIME)
#define SM200A_SPI_MAX_BYTES (SM_SPI_MAX_BYTES)
#define SM200A_GPIO_SWEEP_MAX_STEPS (SM_GPIO_SWEEP_MAX_STEPS)
#define SM200A_GPIO_SWITCH_MAX_STEPS (SM_GPIO_SWITCH_MAX_STEPS)
#define SM200A_GPIO_SWITCH_MIN_COUNT (SM_GPIO_SWITCH_MIN_COUNT)
#define SM200A_GPIO_SWITCH_MAX_COUNT (SM_GPIO_SWITCH_MAX_COUNT)
#define SM200A_TEMP_WARNING (SM_TEMP_WARNING)
#define SM200A_TEMP_MAX (SM_TEMP_MAX)
#define SM200B_MAX_SEGMENTED_IQ_SEGMENTS (SM_MAX_SEGMENTED_IQ_SEGMENTS)
#define SM200B_MAX_SEGMENTED_IQ_SAMPLES (SM_MAX_SEGMENTED_IQ_SAMPLES)
#define SM200_ADDR_ANY (SM_ADDR_ANY)
#define SM200_DEFAULT_ADDR (SM_DEFAULT_ADDR)
#define SM200_DEFAULT_PORT (SM_DEFAULT_PORT)
 
#endif // SM_API_H