sp_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 SP_API_H
#define SP_API_H
 
#if defined(_WIN32) // Windows
    #ifdef SP_EXPORTS
        #define SP_API __declspec(dllexport)
    #else
        #define SP_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 SP_DEPRECATED(comment) __declspec(deprecated(comment))
#else // Linux
    #include <stdint.h>
    #define SP_API __attribute__((visibility("default")))
 
    #if defined(__GNUC__)
        #define SP_DEPRECATED(comment) __attribute__((deprecated))
    #else
        #define SP_DEPRECATED(comment) comment
    #endif
#endif
 
#define SP_TRUE (1)
#define SP_FALSE (0)
 
#define SP_MAX_DEVICES (9)
 
#define SP_MAX_REF_LEVEL (20.0)
#define SP_AUTO_ATTEN (-1)
#define SP_MAX_ATTEN (6)
 
#define SP_MIN_FREQ (9.0e3)
#define SP_MAX_FREQ (15.0e9)
#define SP_MAX_RBW (10.0e6)
#define SP_MIN_SWEEP_TIME (1.0e-6)
#define SP_MAX_SWEEP_TIME (100.0)
 
#define SP_REAL_TIME_MIN_SPAN (200.0e3)
#define SP_REAL_TIME_MAX_SPAN (40.0e6)
#define SP_REAL_TIME_MIN_RBW (2.0e3)
#define SP_REAL_TIME_MAX_RBW (1.0e6)
 
#define SP_MAX_IQ_DECIMATION (8192)
 
#define SP_MAX_IQ_SWEEP_STEPS (1000)
 
#define SP_MIN_FAN_SET_POINT (0.0)
#define SP_MAX_FAN_SET_POINT (60.0)
 
#define SP_MAX_SWEEP_QUEUE_SZ (16)
 
typedef enum SpStatus {
    spInternalFlashErr = -101,
    spInternalFileIOErr = -100,
 
    spGPSErr = -12,
    spAllocationErr = -11,
    spMaxDevicesConnectedErr = -10,
    spInvalidConfigurationErr = -9,
    spSweepAlreadyActiveErr = -8,
    spBootErr = -7,
    spFramingErr = -6,
    spConnectionLostErr = -5,
    spInvalidDeviceErr = -4,
    spNullPtrErr = -3,
    spInvalidParameterErr = -2,
    spDeviceNotFoundErr = -1,
 
    spNoError = 0,
 
    spSettingClamped = 1,
    spTempDrift = 2,
    spADCOverflow = 3,
    spUncalData = 4,
    spCPULimited = 5,
    spInvalidCalData = 6
} SpStatus;
 
typedef enum SpBool {
    spFalse = 0,
    spTrue = 1
} SpBool;
 
typedef enum SpPowerState {
    spPowerStateOn = 0,
    spPowerStateStandby = 1
} SpPowerState;
 
typedef enum SpMode {
    spModeIdle = 0,
    spModeSweeping = 1,
    spModeRealTime = 2,
    spModeIQStreaming = 3,
    spModeIQSweepList = 4,
    spModeAudio = 5,
} SpMode;
 
typedef enum SpDetector {
    spDetectorAverage = 0,
    spDetectorMinMax = 1
} SpDetector;
 
typedef enum SpScale {
    spScaleLog = 0,
    spScaleLin = 1,
    spScaleFullScale = 2
} SpScale;
 
typedef enum SpVideoUnits {
    spVideoLog = 0,
    spVideoVoltage = 1,
    spVideoPower = 2,
    spVideoSample = 3
} SpVideoUnits;
 
typedef enum SpWindowType {
    spWindowFlatTop = 0,
    spWindowNutall = 1,
    spWindowBlackman = 2,
    spWindowHamming = 3,
    spWindowGaussian6dB = 4,
    spWindowRect = 5
} SpWindowType;
 
typedef enum SpDataType {
    spDataType32fc = 0,
    spDataType16sc = 1
} SpDataType;
 
typedef enum SpTriggerEdge {
    spTriggerEdgeRising = 0,
    spTriggerEdgeFalling = 1
} SpTriggerEdge;
 
typedef enum SpGPSState {
    spGPSStateNotPresent = 0,
    spGPSStateLocked = 1,
    spGPSStateDisciplined = 2
} SpGPSState;
 
typedef enum SpReference {
    spReferenceUseInternal = 0,
    spReferenceUseExternal = 1
} SpReference;
 
typedef enum SpGPIOFunction {
    SpGPIOFunctionTrigIn = 0,
    SpGPIOFunctionPPSOut = 1,
    SpGPIOFunctionLogicOutLow = 2,
    SpGPIOFunctionLogicOutHigh = 3,
    SpGPIOFunctionUARTDirect = 4,
    SpGPIOFunctionUARTSweep = 5,
    SpGPIOFunctionUARTDoppler = 6
} SpGPIOFunction;
 
typedef enum SpAudioType {
    spAudioTypeAM = 0,
    spAudioTypeFM = 1,
    spAudioTypeUSB = 2,
    spAudioTypeLSB = 3,
    spAudioTypeCW = 4
} SpAudioType;
 
typedef enum SpGPSPlatformModel {
    SpGPSPlatformModelPortable = 0,
     SpGPSPlatformModelStationary = 2,
     SpGPSPlatformModelPedestrian = 3,
     SpGPSPlatformModelAutomotive = 4,
     SpGPSPlatformModelAtSea = 5,
     SpGPSPlatformModelAirborne_1g = 6,
     SpGPSPlatformModelAirborne_2g = 7
} SpGPSPlatformModel;
 
#ifdef __cplusplus
extern "C" {
#endif
 
SP_API SpStatus spGetDeviceList(int *serials, int *deviceCount);
 
SP_API SpStatus spOpenDevice(int *device);
 
SP_API SpStatus spOpenDeviceBySerial(int *device, int serialNumber);
 
SP_API SpStatus spCloseDevice(int device);
 
SP_API SpStatus spPresetDevice(int device);
 
SP_API SpStatus spSetPowerState(int device, SpPowerState powerState);
 
SP_API SpStatus spGetPowerState(int device, SpPowerState *powerState);
 
SP_API SpStatus spGetSerialNumber(int device, int *serialNumber);
 
SP_API SpStatus spGetFirmwareVersion(int device, int *major, int *minor, int *revision);
 
SP_API SpStatus spGetDeviceDiagnostics(int device, float *voltage, float *current, float *temperature);
 
SP_API SpStatus spGetCalDate(int device, uint32_t *lastCalDate);
 
SP_API SpStatus spSetReference(int device, SpReference reference);
 
SP_API SpStatus spGetReference(int device, SpReference *reference);
 
SP_API SpStatus spSetGPIOPort(int device, SpGPIOFunction func);
 
SP_API SpStatus spGetGPIOPort(int device, SpGPIOFunction *func);
 
SP_API SpStatus spSetUARTBaudRate(int device, float rate);
 
SP_API SpStatus spGetUARTBaudRate(int device, float *rate);
 
SP_API SpStatus spWriteUARTDirect(int device, uint8_t data);
 
SP_API SpStatus spSetGPSTimebaseUpdate(int device, SpBool enabled);
 
SP_API SpStatus spGetGPSTimebaseUpdate(int device, SpBool *enabled);
 
SP_API SpStatus spGetGPSHoldoverInfo(int device, SpBool *usingGPSHoldover, uint32_t *lastHoldoverTime);
 
SP_API SpStatus spGetGPSState(int device, SpGPSState *GPSState);
 
SP_API SpStatus spSetRefLevel(int device, double refLevel);
 
SP_API SpStatus spGetRefLevel(int device, double *refLevel);
 
SP_API SpStatus spSetAttenuator(int device, int atten);
 
SP_API SpStatus spGetAttenuator(int device, int *atten);
 
SP_API SpStatus spSetSweepCenterSpan(int device, double centerFreqHz, double spanHz);
 
SP_API SpStatus spSetSweepStartStop(int device, double startFreqHz, double stopFreqHz);
 
SP_API SpStatus spSetSweepCoupling(int device, double rbw, double vbw, double sweepTime);
 
SP_API SpStatus spSetSweepDetector(int device, SpDetector detector, SpVideoUnits videoUnits);
 
SP_API SpStatus spSetSweepScale(int device, SpScale scale);
 
SP_API SpStatus spSetSweepWindow(int device, SpWindowType window);
 
SP_API SpStatus spSetSweepGPIOSwitching(int device, double *freqs, uint8_t *data, int count);
 
SP_API SpStatus spSetSweepGPIOSwitchingDisabled(int device);
 
SP_API SpStatus spSetRealTimeCenterSpan(int device, double centerFreqHz, double spanHz);
 
SP_API SpStatus spSetRealTimeRBW(int device, double rbw);
 
SP_API SpStatus spSetRealTimeDetector(int device, SpDetector detector);
 
SP_API SpStatus spSetRealTimeScale(int device, SpScale scale, double frameRef, double frameScale);
 
SP_API SpStatus spSetRealTimeWindow(int device, SpWindowType window);
 
SP_API SpStatus spSetIQDataType(int device, SpDataType dataType);
 
SP_API SpStatus spSetIQCenterFreq(int device, double centerFreqHz);
 
SP_API SpStatus spGetIQCenterFreq(int device, double *centerFreqHz);
 
SP_API SpStatus spSetIQSampleRate(int device, int decimation);
 
SP_API SpStatus spSetIQSoftwareFilter(int device, SpBool enabled);
 
SP_API SpStatus spSetIQBandwidth(int device, double bandwidth);
 
SP_API SpStatus spSetIQExtTriggerEdge(int device, SpTriggerEdge edge);
 
SP_API SpStatus spSetIQTriggerSentinel(double sentinelValue);
 
SP_API SpStatus spSetIQQueueSize(int device, int units);
 
SP_API SpStatus spSetIQSweepListDataType(int device, SpDataType dataType);
 
SP_API SpStatus spSetIQSweepListCorrected(int device, SpBool corrected);
 
SP_API SpStatus spSetIQSweepListSteps(int device, int steps);
 
SP_API SpStatus spGetIQSweepListSteps(int device, int *steps);
 
SP_API SpStatus spSetIQSweepListFreq(int device, int step, double freq);
 
SP_API SpStatus spSetIQSweepListRef(int device, int step, double level);
 
SP_API SpStatus spSetIQSweepListAtten(int device, int step, int atten);
 
SP_API SpStatus spSetIQSweepListSampleCount(int device, int step, uint32_t samples);
 
SP_API SpStatus spSetAudioCenterFreq(int device, double centerFreqHz);
 
SP_API SpStatus spSetAudioType(int device, SpAudioType audioType);
 
SP_API SpStatus spSetAudioFilters(int device,
    double ifBandwidth,
    double audioLpf,
    double audioHpf);
 
SP_API SpStatus spSetAudioFMDeemphasis(int device, double deemphasis);
 
SP_API SpStatus spConfigure(int device, SpMode mode);
 
SP_API SpStatus spGetCurrentMode(int device, SpMode *mode);
 
SP_API SpStatus spAbort(int device);
 
SP_API SpStatus spGetSweepParameters(int device, double *actualRBW, double *actualVBW,
                                     double *actualStartFreq, double *binSize, int *sweepSize);
 
SP_API SpStatus spGetRealTimeParameters(int device, double *actualRBW, int *sweepSize, double *actualStartFreq,
                                        double *binSize, int *frameWidth, int *frameHeight, double *poi);
 
SP_API SpStatus spGetIQParameters(int device, double *sampleRate, double *bandwidth);
 
 
SP_API SpStatus spGetIQCorrection(int device, float *scale);
 
SP_API SpStatus spIQSweepListGetCorrections(int device, float *corrections);
 
SP_API SpStatus spGetSweep(int device, float *sweepMin, float *sweepMax, int64_t *nsSinceEpoch);
 
SP_API SpStatus spGetRealTimeFrame(int device, float *colorFrame, float *alphaFrame, float *sweepMin,
                                   float *sweepMax, int *frameCount, int64_t *nsSinceEpoch);
 
SP_API SpStatus spGetIQ(int device, void *iqBuf, int iqBufSize, double *triggers, int triggerBufSize,
                        int64_t *nsSinceEpoch, SpBool purge, int *sampleLoss, int *samplesRemaining);
 
SP_API SpStatus spIQSweepListGetSweep(int device, void *dst, int64_t *timestamps);
 
SP_API SpStatus spIQSweepListStartSweep(int device, int pos, void *dst, int64_t *timestamps);
 
SP_API SpStatus spIQSweepListFinishSweep(int device, int pos);
 
SP_API SpStatus spGetAudio(int device, float *audio);
 
SP_API SpStatus spGetGPSInfo(int device, SpBool refresh, SpBool *updated, int64_t *secSinceEpoch,
                             double *latitude, double *longitude, double *altitude, char *nmea, int *nmeaLen);
 
SP_API SpStatus spWriteToGPS(int device, const uint8_t *mem, int len);
 
 
SP_API SpStatus spSetGPSPlatformModel(int device, SpGPSPlatformModel platformModel);
 
SP_API SpStatus spSetFanSetPoint(int device, float setPoint);
 
SP_API SpStatus spGetFanSettings(int device, float *setPoint, float *voltage);
 
SP_API const char* spGetErrorString(SpStatus status);
 
SP_API const char* spGetAPIVersion();
 
#ifdef __cplusplus
} // extern "C"
#endif
 
#endif // #ifndef SP_API_H