SP API
sp_api.h
Go to the documentation of this file.
1// Copyright (c).2023, Signal Hound, Inc.
2// For licensing information, please see the API license in the software_licenses folder
3
13#ifndef SP_API_H
14#define SP_API_H
15
16#if defined(_WIN32) // Windows
17 #ifdef SP_EXPORTS
18 #define SP_API __declspec(dllexport)
19 #else
20 #define SP_API
21 #endif
22
23 // bare minimum stdint typedef support
24 #if _MSC_VER < 1700 // For VS2010 or earlier
25 typedef signed char int8_t;
26 typedef short int16_t;
27 typedef int int32_t;
28 typedef long long int64_t;
29 typedef unsigned char uint8_t;
30 typedef unsigned short uint16_t;
31 typedef unsigned int uint32_t;
32 typedef unsigned long long uint64_t;
33 #else
34 #include <stdint.h>
35 #endif
36
37 #define SP_DEPRECATED(comment) __declspec(deprecated(comment))
38#else // Linux
39 #include <stdint.h>
40 #define SP_API __attribute__((visibility("default")))
41
42 #if defined(__GNUC__)
43 #define SP_DEPRECATED(comment) __attribute__((deprecated))
44 #else
45 #define SP_DEPRECATED(comment) comment
46 #endif
47#endif
48
50#define SP_TRUE (1)
52#define SP_FALSE (0)
53
55#define SP_MAX_DEVICES (9)
56
58#define SP_MAX_REF_LEVEL (20.0)
60#define SP_AUTO_ATTEN (-1)
62#define SP_MAX_ATTEN (6)
63
65#define SP_MIN_FREQ (9.0e3)
67#define SP_MAX_FREQ (15.0e9)
68
70#define SP_MIN_SWEEP_TIME (1.0e-6)
72#define SP_MAX_SWEEP_TIME (100.0)
73
75#define SP_REAL_TIME_MIN_SPAN (200.0e3)
77#define SP_REAL_TIME_MAX_SPAN (40.0e6)
79#define SP_REAL_TIME_MIN_RBW (2.0e3)
81#define SP_REAL_TIME_MAX_RBW (1.0e6)
82
84#define SP_MAX_IQ_DECIMATION (8192)
85
87#define SP_MAX_IQ_SWEEP_STEPS (1000)
88
90#define SP_MIN_FAN_SET_POINT (0.0)
92#define SP_MAX_FAN_SET_POINT (60.0)
93
99#define SP_MAX_SWEEP_QUEUE_SZ (16)
100
104typedef enum SpStatus {
109
111 spGPSErr = -12,
156
159
182
187typedef enum SpBool {
191 spTrue = 1
193
197typedef enum SpPowerState {
203
207typedef enum SpMode {
220} SpMode;
221
225typedef enum SpDetector {
231
235typedef enum SpScale {
243
247typedef enum SpVideoUnits {
255 spVideoSample = 3
257
261typedef enum SpWindowType {
273 spWindowRect = 5
275
281typedef enum SpDataType {
287
291typedef enum SpTriggerEdge {
297
301typedef enum SpGPSState {
309
313typedef enum SpReference {
319
323typedef enum SpGPIOFunction {
343
347typedef enum SpAudioType {
357 spAudioTypeCW = 4
359
363typedef enum SpGPSPlatformModel {
401
402#ifdef __cplusplus
403extern "C" {
404#endif
405
427SP_API SpStatus spGetDeviceList(int *serials, int *deviceCount);
428
442SP_API SpStatus spOpenDevice(int *device);
443
456SP_API SpStatus spOpenDeviceBySerial(int *device, int serialNumber);
457
470SP_API SpStatus spCloseDevice(int device);
471
483SP_API SpStatus spPresetDevice(int device);
484
495SP_API SpStatus spSetPowerState(int device, SpPowerState powerState);
496
506SP_API SpStatus spGetPowerState(int device, SpPowerState *powerState);
507
517SP_API SpStatus spGetSerialNumber(int device, int *serialNumber);
518
533SP_API SpStatus spGetFirmwareVersion(int device, int *major, int *minor, int *revision);
534
551SP_API SpStatus spGetDeviceDiagnostics(int device, float *voltage, float *current, float *temperature);
552
563SP_API SpStatus spGetCalDate(int device, uint32_t *lastCalDate);
564
578SP_API SpStatus spSetReference(int device, SpReference reference);
579
589SP_API SpStatus spGetReference(int device, SpReference *reference);
590
601SP_API SpStatus spSetGPIOPort(int device, SpGPIOFunction func);
602
612SP_API SpStatus spGetGPIOPort(int device, SpGPIOFunction *func);
613
626SP_API SpStatus spSetUARTBaudRate(int device, float rate);
627
637SP_API SpStatus spGetUARTBaudRate(int device, float *rate);
638
650SP_API SpStatus spWriteUARTDirect(int device, uint8_t data);
651
664SP_API SpStatus spSetGPSTimebaseUpdate(int device, SpBool enabled);
665
676SP_API SpStatus spGetGPSTimebaseUpdate(int device, SpBool *enabled);
677
695SP_API SpStatus spGetGPSHoldoverInfo(int device, SpBool *usingGPSHoldover, uint32_t *lastHoldoverTime);
696
708SP_API SpStatus spGetGPSState(int device, SpGPSState *GPSState);
709
723SP_API SpStatus spSetRefLevel(int device, double refLevel);
724
734SP_API SpStatus spGetRefLevel(int device, double *refLevel);
735
750SP_API SpStatus spSetAttenuator(int device, int atten);
751
762SP_API SpStatus spGetAttenuator(int device, int *atten);
763
775SP_API SpStatus spSetSweepCenterSpan(int device, double centerFreqHz, double spanHz);
776
788SP_API SpStatus spSetSweepStartStop(int device, double startFreqHz, double stopFreqHz);
789
805SP_API SpStatus spSetSweepCoupling(int device, double rbw, double vbw, double sweepTime);
806
818SP_API SpStatus spSetSweepDetector(int device, SpDetector detector, SpVideoUnits videoUnits);
819
829SP_API SpStatus spSetSweepScale(int device, SpScale scale);
830
840SP_API SpStatus spSetSweepWindow(int device, SpWindowType window);
841
860SP_API SpStatus spSetSweepGPIOSwitching(int device, double *freqs, uint8_t *data, int count);
861
872
884SP_API SpStatus spSetRealTimeCenterSpan(int device, double centerFreqHz, double spanHz);
885
895SP_API SpStatus spSetRealTimeRBW(int device, double rbw);
896
906SP_API SpStatus spSetRealTimeDetector(int device, SpDetector detector);
907
923SP_API SpStatus spSetRealTimeScale(int device, SpScale scale, double frameRef, double frameScale);
924
934SP_API SpStatus spSetRealTimeWindow(int device, SpWindowType window);
935
945SP_API SpStatus spSetIQDataType(int device, SpDataType dataType);
946
956SP_API SpStatus spSetIQCenterFreq(int device, double centerFreqHz);
957
967SP_API SpStatus spGetIQCenterFreq(int device, double *centerFreqHz);
968
979SP_API SpStatus spSetIQSampleRate(int device, int decimation);
980
990SP_API SpStatus spSetIQSoftwareFilter(int device, SpBool enabled);
991
1002SP_API SpStatus spSetIQBandwidth(int device, double bandwidth);
1003
1014
1025SP_API SpStatus spSetIQTriggerSentinel(double sentinelValue);
1026
1046SP_API SpStatus spSetIQQueueSize(int device, int units);
1047
1057SP_API SpStatus spSetIQSweepListDataType(int device, SpDataType dataType);
1058
1071SP_API SpStatus spSetIQSweepListCorrected(int device, SpBool corrected);
1072
1082SP_API SpStatus spSetIQSweepListSteps(int device, int steps);
1083
1093SP_API SpStatus spGetIQSweepListSteps(int device, int *steps);
1094
1109SP_API SpStatus spSetIQSweepListFreq(int device, int step, double freq);
1110
1125SP_API SpStatus spSetIQSweepListRef(int device, int step, double level);
1126
1143SP_API SpStatus spSetIQSweepListAtten(int device, int step, int atten);
1144
1161SP_API SpStatus spSetIQSweepListSampleCount(int device, int step, uint32_t samples);
1162
1172SP_API SpStatus spSetAudioCenterFreq(int device, double centerFreqHz);
1173
1183SP_API SpStatus spSetAudioType(int device, SpAudioType audioType);
1184
1198SP_API SpStatus spSetAudioFilters(int device,
1199 double ifBandwidth,
1200 double audioLpf,
1201 double audioHpf);
1202
1212SP_API SpStatus spSetAudioFMDeemphasis(int device, double deemphasis);
1213
1228SP_API SpStatus spConfigure(int device, SpMode mode);
1229
1239SP_API SpStatus spGetCurrentMode(int device, SpMode *mode);
1240
1250SP_API SpStatus spAbort(int device);
1251
1274SP_API SpStatus spGetSweepParameters(int device, double *actualRBW, double *actualVBW,
1275 double *actualStartFreq, double *binSize, int *sweepSize);
1276
1303SP_API SpStatus spGetRealTimeParameters(int device, double *actualRBW, int *sweepSize, double *actualStartFreq,
1304 double *binSize, int *frameWidth, int *frameHeight, double *poi);
1305
1318SP_API SpStatus spGetIQParameters(int device, double *sampleRate, double *bandwidth);
1319
1320
1333SP_API SpStatus spGetIQCorrection(int device, float *scale);
1334
1350SP_API SpStatus spIQSweepListGetCorrections(int device, float *corrections);
1351
1366SP_API SpStatus spGetSweep(int device, float *sweepMin, float *sweepMax, int64_t *nsSinceEpoch);
1367
1394SP_API SpStatus spGetRealTimeFrame(int device, float *colorFrame, float *alphaFrame, float *sweepMin,
1395 float *sweepMax, int *frameCount, int64_t *nsSinceEpoch);
1396
1436SP_API SpStatus spGetIQ(int device, void *iqBuf, int iqBufSize, double *triggers, int triggerBufSize,
1437 int64_t *nsSinceEpoch, SpBool purge, int *sampleLoss, int *samplesRemaining);
1438
1463SP_API SpStatus spIQSweepListGetSweep(int device, void *dst, int64_t *timestamps);
1464
1490SP_API SpStatus spIQSweepListStartSweep(int device, int pos, void *dst, int64_t *timestamps);
1491
1502SP_API SpStatus spIQSweepListFinishSweep(int device, int pos);
1503
1519SP_API SpStatus spGetAudio(int device, float *audio);
1520
1562SP_API SpStatus spGetGPSInfo(int device, SpBool refresh, SpBool *updated, int64_t *secSinceEpoch,
1563 double *latitude, double *longitude, double *altitude, char *nmea, int *nmeaLen);
1564
1578SP_API SpStatus spWriteToGPS(int device, const uint8_t *mem, int len);
1579
1580
1602SP_API SpStatus spSetGPSPlatformModel(int device, SpGPSPlatformModel platformModel);
1603
1618SP_API SpStatus spSetFanSetPoint(int device, float setPoint);
1619
1631SP_API SpStatus spGetFanSettings(int device, float *setPoint, float *voltage);
1632
1641SP_API const char* spGetErrorString(SpStatus status);
1642
1658SP_API const char* spGetAPIVersion();
1659
1660#ifdef __cplusplus
1661} // extern "C"
1662#endif
1663
1664#endif // #ifndef SP_API_H
SpTriggerEdge
Definition: sp_api.h:291
@ spTriggerEdgeFalling
Definition: sp_api.h:295
@ spTriggerEdgeRising
Definition: sp_api.h:293
SP_API SpStatus spWriteToGPS(int device, const uint8_t *mem, int len)
SpReference
Definition: sp_api.h:313
@ spReferenceUseExternal
Definition: sp_api.h:317
@ spReferenceUseInternal
Definition: sp_api.h:315
SP_API SpStatus spIQSweepListStartSweep(int device, int pos, void *dst, int64_t *timestamps)
SpStatus
Definition: sp_api.h:104
@ spInternalFlashErr
Definition: sp_api.h:106
@ spDeviceNotFoundErr
Definition: sp_api.h:155
@ spFramingErr
Definition: sp_api.h:138
@ spTempDrift
Definition: sp_api.h:167
@ spInternalFileIOErr
Definition: sp_api.h:108
@ spMaxDevicesConnectedErr
Definition: sp_api.h:117
@ spUncalData
Definition: sp_api.h:171
@ spADCOverflow
Definition: sp_api.h:169
@ spBootErr
Definition: sp_api.h:133
@ spNoError
Definition: sp_api.h:158
@ spGPSErr
Definition: sp_api.h:111
@ spConnectionLostErr
Definition: sp_api.h:144
@ spNullPtrErr
Definition: sp_api.h:148
@ spSettingClamped
Definition: sp_api.h:161
@ spInvalidDeviceErr
Definition: sp_api.h:146
@ spInvalidCalData
Definition: sp_api.h:180
@ spAllocationErr
Definition: sp_api.h:115
@ spSweepAlreadyActiveErr
Definition: sp_api.h:131
@ spCPULimited
Definition: sp_api.h:173
@ spInvalidConfigurationErr
Definition: sp_api.h:124
@ spInvalidParameterErr
Definition: sp_api.h:150
SP_API SpStatus spGetCalDate(int device, uint32_t *lastCalDate)
SP_API SpStatus spSetRealTimeCenterSpan(int device, double centerFreqHz, double spanHz)
SP_API SpStatus spSetRealTimeScale(int device, SpScale scale, double frameRef, double frameScale)
SP_API SpStatus spSetIQQueueSize(int device, int units)
SP_API SpStatus spSetIQSoftwareFilter(int device, SpBool enabled)
SP_API SpStatus spCloseDevice(int device)
SpDataType
Definition: sp_api.h:281
@ spDataType16sc
Definition: sp_api.h:285
@ spDataType32fc
Definition: sp_api.h:283
SpMode
Definition: sp_api.h:207
@ spModeRealTime
Definition: sp_api.h:213
@ spModeAudio
Definition: sp_api.h:219
@ spModeIdle
Definition: sp_api.h:209
@ spModeIQStreaming
Definition: sp_api.h:215
@ spModeIQSweepList
Definition: sp_api.h:217
@ spModeSweeping
Definition: sp_api.h:211
SP_API SpStatus spSetSweepWindow(int device, SpWindowType window)
SpPowerState
Definition: sp_api.h:197
@ spPowerStateStandby
Definition: sp_api.h:201
@ spPowerStateOn
Definition: sp_api.h:199
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 spSetGPSTimebaseUpdate(int device, SpBool enabled)
SP_API SpStatus spWriteUARTDirect(int device, uint8_t data)
SP_API SpStatus spSetSweepScale(int device, SpScale scale)
SP_API SpStatus spSetIQSweepListSampleCount(int device, int step, uint32_t samples)
SpGPSPlatformModel
Definition: sp_api.h:363
@ SpGPSPlatformModelPedestrian
Definition: sp_api.h:379
@ SpGPSPlatformModelAutomotive
Definition: sp_api.h:384
@ SpGPSPlatformModelAtSea
Definition: sp_api.h:389
@ SpGPSPlatformModelAirborne_2g
Definition: sp_api.h:399
@ SpGPSPlatformModelStationary
Definition: sp_api.h:374
@ SpGPSPlatformModelAirborne_1g
Definition: sp_api.h:394
@ SpGPSPlatformModelPortable
Definition: sp_api.h:368
SP_API SpStatus spSetReference(int device, SpReference reference)
SP_API SpStatus spSetIQSampleRate(int device, int decimation)
SP_API SpStatus spIQSweepListFinishSweep(int device, int pos)
SP_API SpStatus spSetFanSetPoint(int device, float setPoint)
SP_API const char * spGetErrorString(SpStatus status)
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 spSetIQExtTriggerEdge(int device, SpTriggerEdge edge)
SP_API SpStatus spGetReference(int device, SpReference *reference)
SP_API SpStatus spGetGPSState(int device, SpGPSState *GPSState)
SP_API SpStatus spSetIQTriggerSentinel(double sentinelValue)
SP_API SpStatus spSetAudioCenterFreq(int device, double centerFreqHz)
SpGPIOFunction
Definition: sp_api.h:323
@ SpGPIOFunctionUARTSweep
Definition: sp_api.h:339
@ SpGPIOFunctionLogicOutLow
Definition: sp_api.h:333
@ SpGPIOFunctionUARTDirect
Definition: sp_api.h:337
@ SpGPIOFunctionLogicOutHigh
Definition: sp_api.h:335
@ SpGPIOFunctionUARTDoppler
Definition: sp_api.h:341
@ SpGPIOFunctionTrigIn
Definition: sp_api.h:329
@ SpGPIOFunctionPPSOut
Definition: sp_api.h:331
SP_API SpStatus spAbort(int device)
SP_API SpStatus spOpenDevice(int *device)
SP_API SpStatus spSetAudioFilters(int device, double ifBandwidth, double audioLpf, double audioHpf)
SP_API SpStatus spSetRefLevel(int device, double refLevel)
SP_API SpStatus spSetSweepCenterSpan(int device, double centerFreqHz, double spanHz)
SP_API SpStatus spGetDeviceList(int *serials, int *deviceCount)
SP_API SpStatus spGetRealTimeParameters(int device, double *actualRBW, int *sweepSize, double *actualStartFreq, double *binSize, int *frameWidth, int *frameHeight, double *poi)
SP_API SpStatus spIQSweepListGetSweep(int device, void *dst, int64_t *timestamps)
SP_API SpStatus spGetFanSettings(int device, float *setPoint, float *voltage)
SP_API SpStatus spGetFirmwareVersion(int device, int *major, int *minor, int *revision)
SpWindowType
Definition: sp_api.h:261
@ spWindowBlackman
Definition: sp_api.h:267
@ spWindowRect
Definition: sp_api.h:273
@ spWindowHamming
Definition: sp_api.h:269
@ spWindowFlatTop
Definition: sp_api.h:263
@ spWindowNutall
Definition: sp_api.h:265
@ spWindowGaussian6dB
Definition: sp_api.h:271
SP_API SpStatus spGetGPSHoldoverInfo(int device, SpBool *usingGPSHoldover, uint32_t *lastHoldoverTime)
SP_API SpStatus spSetSweepDetector(int device, SpDetector detector, SpVideoUnits videoUnits)
SP_API SpStatus spSetIQDataType(int device, SpDataType dataType)
SP_API SpStatus spSetRealTimeRBW(int device, double rbw)
SP_API SpStatus spGetUARTBaudRate(int device, float *rate)
SpDetector
Definition: sp_api.h:225
@ spDetectorMinMax
Definition: sp_api.h:229
@ spDetectorAverage
Definition: sp_api.h:227
SpAudioType
Definition: sp_api.h:347
@ spAudioTypeFM
Definition: sp_api.h:351
@ spAudioTypeLSB
Definition: sp_api.h:355
@ spAudioTypeCW
Definition: sp_api.h:357
@ spAudioTypeUSB
Definition: sp_api.h:353
@ spAudioTypeAM
Definition: sp_api.h:349
SP_API SpStatus spGetIQCenterFreq(int device, double *centerFreqHz)
SP_API SpStatus spGetCurrentMode(int device, SpMode *mode)
SP_API SpStatus spOpenDeviceBySerial(int *device, int serialNumber)
SP_API SpStatus spSetIQSweepListSteps(int device, int steps)
SP_API SpStatus spSetIQSweepListRef(int device, int step, double level)
SP_API SpStatus spGetSweep(int device, float *sweepMin, float *sweepMax, int64_t *nsSinceEpoch)
SP_API const char * spGetAPIVersion()
SP_API SpStatus spSetAudioFMDeemphasis(int device, double deemphasis)
SP_API SpStatus spGetIQSweepListSteps(int device, int *steps)
SP_API SpStatus spGetIQParameters(int device, double *sampleRate, double *bandwidth)
SP_API SpStatus spSetSweepGPIOSwitchingDisabled(int device)
SP_API SpStatus spGetRefLevel(int device, double *refLevel)
SP_API SpStatus spSetUARTBaudRate(int device, float rate)
SP_API SpStatus spSetIQBandwidth(int device, double bandwidth)
SP_API SpStatus spSetAudioType(int device, SpAudioType audioType)
SP_API SpStatus spGetSerialNumber(int device, int *serialNumber)
SP_API SpStatus spSetIQSweepListAtten(int device, int step, int atten)
SP_API SpStatus spSetIQSweepListCorrected(int device, SpBool corrected)
SP_API SpStatus spConfigure(int device, SpMode mode)
SpScale
Definition: sp_api.h:235
@ spScaleFullScale
Definition: sp_api.h:241
@ spScaleLin
Definition: sp_api.h:239
@ spScaleLog
Definition: sp_api.h:237
SP_API SpStatus spSetPowerState(int device, SpPowerState powerState)
SpGPSState
Definition: sp_api.h:301
@ spGPSStateLocked
Definition: sp_api.h:305
@ spGPSStateDisciplined
Definition: sp_api.h:307
@ spGPSStateNotPresent
Definition: sp_api.h:303
SP_API SpStatus spSetIQCenterFreq(int device, double centerFreqHz)
SP_API SpStatus spGetAttenuator(int device, int *atten)
SP_API SpStatus spGetSweepParameters(int device, double *actualRBW, double *actualVBW, double *actualStartFreq, double *binSize, int *sweepSize)
SpVideoUnits
Definition: sp_api.h:247
@ spVideoPower
Definition: sp_api.h:253
@ spVideoLog
Definition: sp_api.h:249
@ spVideoSample
Definition: sp_api.h:255
@ spVideoVoltage
Definition: sp_api.h:251
SP_API SpStatus spSetRealTimeDetector(int device, SpDetector detector)
SP_API SpStatus spGetRealTimeFrame(int device, float *colorFrame, float *alphaFrame, float *sweepMin, float *sweepMax, int *frameCount, int64_t *nsSinceEpoch)
SP_API SpStatus spSetIQSweepListDataType(int device, SpDataType dataType)
SP_API SpStatus spSetSweepCoupling(int device, double rbw, double vbw, double sweepTime)
SP_API SpStatus spSetIQSweepListFreq(int device, int step, double freq)
SP_API SpStatus spSetSweepStartStop(int device, double startFreqHz, double stopFreqHz)
SP_API SpStatus spIQSweepListGetCorrections(int device, float *corrections)
SP_API SpStatus spGetPowerState(int device, SpPowerState *powerState)
SpBool
Definition: sp_api.h:187
@ spTrue
Definition: sp_api.h:191
@ spFalse
Definition: sp_api.h:189
SP_API SpStatus spSetAttenuator(int device, int atten)
SP_API SpStatus spGetDeviceDiagnostics(int device, float *voltage, float *current, float *temperature)
SP_API SpStatus spGetAudio(int device, float *audio)
SP_API SpStatus spGetGPSTimebaseUpdate(int device, SpBool *enabled)
SP_API SpStatus spSetRealTimeWindow(int device, SpWindowType window)
SP_API SpStatus spSetSweepGPIOSwitching(int device, double *freqs, uint8_t *data, int count)
SP_API SpStatus spSetGPSPlatformModel(int device, SpGPSPlatformModel platformModel)
SP_API SpStatus spGetGPIOPort(int device, SpGPIOFunction *func)
SP_API SpStatus spPresetDevice(int device)
SP_API SpStatus spSetGPIOPort(int device, SpGPIOFunction func)
SP_API SpStatus spGetIQCorrection(int device, float *scale)