pcr_api.h

Go to the documentation of this file.

// Copyright (c).2025, Signal Hound, Inc.
// For licensing information, please see the API license in the software_licenses folder
 
#ifndef PCR_API_H
#define PCR_API_H
 
#if defined(_WIN32) // Windows
    #ifdef PCR_EXPORTS
        #define PCR_API __declspec(dllexport)
    #else
        #define PCR_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 PCR_DEPRECATED(comment) __declspec(deprecated(comment))
#else // Linux
    #include <stdint.h>
    #define PCR_API __attribute__((visibility("default")))
 
    #if defined(__GNUC__)
        #define PCR_DEPRECATED(comment) __attribute__((deprecated))
    #else
        #define PCR_DEPRECATED(comment) comment
    #endif
#endif
 
#define PCR_MAX_DEVICES (4)
 
#define PCR_DEFAULT_HOST_ADDR ("192.168.2.2")
#define PCR_DEFAULT_DEVICE_ADDR ("192.168.2.10")
#define PCR_DEFAULT_PORT (51665)
#define PCR_DEFAULT_STREAM_PORT (4991)
 
#define PCR_SWEEP_CHANNEL_DISABLED (-1)
 
#define PCR_AUTO_ATTEN (-1)
#define PCR_MAX_ATTEN (6)
 
#define PCR_MIN_FREQ (100.0e3)
#define PCR_MAX_FREQ (20.0e9)
#define PCR_SWEEP_MIN_SPAN (100.0)
#define PCR_SWEEP_MIN_RBW (100.0)
#define PCR_SWEEP_MAX_RBW (10.0e6)
#define PCR_MIN_SWEEP_TIME (1.0e-6)
#define PCR_MAX_SWEEP_TIME (1.0)
 
#define PCR_MIN_REF_LVL (-130.0)
#define PCR_MAX_REF_LVL (20.0)
 
#define PCR_STREAM_SR (50.0e6)
#define PCR_STREAM_MIN_DECIMATION (1)
#define PCR_STREAM_MAX_DECIMATION (256)
#define PCR_STREAM_MIN_BW (20.0e3)
#define PCR_STREAM_MAX_BW (40.0e6)
 
#define PCR_MIN_CNTX_INTERVAL (3)
#define PCR_MAX_CNTX_INTERVAL (4095)
 
#define PCR_VSG_MIN_LEVEL (-80.0)
#define PCR_VSG_MAX_LEVEL (10.0)
#define PCR_VSG_MAX_BUF_LEN (4096)
 
#define PCR_MIN_FAN_SETPOINT (5.0)
#define PCR_MAX_FAN_SETPOINT (60.0)
 
#define PCR_MIN_CHANNEL_DELAY (-25.0e-9)
#define PCR_MAX_CHANNEL_DELAY (25.0e-9)
 
typedef enum PCRBool {
    PCRBoolFalse = 0,
    PCRBoolTrue = 1
} PCRBool;
 
typedef enum PCRDataType {
    PCRDataType16sc = 0,
    PCRDataType32fc = 1
} PCRDataType;
 
typedef enum PCRReference {
    PCRReferenceInternal = 0,
    PCRReferenceExternal = 1
} PCRReference;
 
typedef enum PCRGPSState {
    PCRGPSStateNotPresent = 0,
    PCRGPSStateLocked = 1,
    PCRGPSStateDisciplined = 2
} PCRGPSState;
 
typedef enum PCREndianness {
    PCREndiannessBig = 0,
    PCREndiannessLittle = 1
} PCREndianness;
 
typedef enum PCRSweepDetector {
    PCRSweepDetectorAvg = 0,
    PCRSweepDetectorMin = 1,
    PCRSweepDetectorMax = 2
} PCRSweepDetector;
 
typedef enum PCRSweepVideoUnits {
    PCRSweepVideoUnitsLog = 0,
    PCRSweepVideoUnitsVoltage = 1,
    PCRSweepVideoUnitsPower = 2,
    PCRSweepVideoUnitsSample = 3
} PCRSweepVideoUnits;
 
typedef enum PCRSweepScale {
    PCRSweepScaleLog = 0,
    PCRSweepScaleLin = 1,
    PCRSweepScaleFullScale = 2
} PCRSweepScale;
 
typedef enum PCRSweepWindow {
    PCRSweepWindowFlattop = 0,
    PCRSweepWindowNutall = 1,
    PCRSweepWindowGaussian6dB = 2
} PCRSweepWindow;
 
typedef enum PCRTriggerEdge {
    PCRTriggerEdgeRising = 0,
    PCRTriggerEdgeFalling = 1
} PCRTriggerEdge;
 
typedef enum PCRStreamMode {
    PCRStreamModeLocal = 0,
    PCRStreamModeVRT = 1
} PCRStreamMode;
 
typedef enum PCRStatus {
    PCRStatusSweepNotActiveErr = -14,
    PCRStatusSweepActiveErr = -13,
    PCRStatusADCErr = -12,
    PCRStatusPairedErr = -11,
    PCRStatusSyncErr = -10,
    PCRStatusIOErr = -9,
    PCRStatusInvalidParameterErr = -8,
    PCRStatusInvalidConfigurationErr = -7,
    PCRStatusMemoryErr = -6,
    PCRStatusMaxDevicesConnectedErr = -5,
    PCRStatusInvalidDeviceErr = -4,
    PCRStatusNullPtrErr = -3,
    PCRStatusDeviceConnectionLostErr = -2,
    PCRStatusDeviceNotFoundErr = -1,
 
    PCRStatusNoError = 0,
 
    PCRStatusSettingClamped = 1,
    PCRStatusADCOverflow = 2,
    PCRStatusUncalData = 3,
    PCRStatusTempDriftWarning = 4,
    PCRStatusBufferOverflow = 5,
    PCRStatusInvalidCalData = 6
 
} PCRStatus;
 
typedef struct PCRDeviceDiagnostics {
    float voltage;
    float currentInput;
    float currentOCXO;
    float current58;
    float tempFPGA;
    float tempMB;
    float tempRFBoard1;
    float tempRFBoard2;
    float sfpTemp;
    float sfpTxPower;
    float sfpRxPower;
} PCRDeviceDiagnostics;
 
#ifdef __cplusplus
extern "C" {
#endif
 
PCR_API PCRStatus pcrConnectDevice(int *handle,
                                   const char *hostAddr,
                                   const char *deviceAddr,
                                   uint16_t port);
 
PCR_API PCRStatus pcrPairDevice(int handle, 
                                const char *hostAddr,
                                const char *deviceAddr, 
                                uint16_t port);
 
PCR_API PCRStatus pcrCloseDevice(int handle);
 
PCR_API PCRStatus pcrGetSerialNumber(int handle, int *serialNumber);
 
PCR_API PCRStatus pcrGetFirmwareVersion(int handle, int *major, int *minor, int *revision);
 
PCR_API PCRStatus pcrGetCalDate(int handle, uint32_t *lastCalDate);
 
PCR_API PCRStatus pcrGetDeviceDiagnostics(int handle, float *voltage, float *current, float *temperature);
 
PCR_API PCRStatus pcrGetFullDeviceDiagnostics(int handle, PCRDeviceDiagnostics *diagnostics);
 
PCR_API PCRStatus pcrSetLowPowerState(int handle);
 
PCR_API PCRStatus pcrSetReference(int handle, PCRReference reference);
 
PCR_API PCRStatus pcrGetReference(int handle, PCRReference *reference);
 
PCR_API PCRStatus pcrSetGPSTimebaseUpdate(int handle, PCRBool enabled);
 
PCR_API PCRStatus pcrGetGPSTimebaseUpdate(int handle, PCRBool *enabled);
 
PCR_API PCRStatus pcrGetGPSHoldoverInfo(int handle, PCRBool *usingGPSHoldover, uint64_t *lastHoldoverTime);
 
PCR_API PCRStatus pcrGetGPSState(int handle, PCRGPSState *state);
 
PCR_API PCRStatus pcrGetGPSInfo(int handle, PCRBool refresh, PCRBool *updated, int64_t *secSinceEpoch,
    double *latitude, double *longitude, double *altitude);
 
PCR_API PCRStatus pcrWriteMessageToGPS(int handle, uint32_t key, uint64_t value, int valueSizeBytes);
 
PCR_API PCRStatus pcrSetFanEnabled(int handle, PCRBool enabled);
 
PCR_API PCRStatus pcrGetFanEnabled(int handle, PCRBool *enabled);
 
PCR_API PCRStatus pcrSetFanSetPoint(int handle, float setPoint);
 
PCR_API PCRStatus pcrGetFanSetPoint(int handle, float *setPoint);
 
PCR_API PCRStatus pcrGetChannelCount(int handle, int *channelCount);
 
PCR_API PCRStatus pcrSetChannelConfig(int handle, const int *enabled, int sweepChannel);
 
PCR_API PCRStatus pcrGetChannelConfig(int handle, int *enabled, int *sweepChannel);
 
PCR_API PCRStatus pcrSetChannelShared(int handle, int channel, PCRBool useSharedLO);
 
PCR_API PCRStatus pcrUpdateChannelShared(int handle, int channel, PCRBool useSharedLO, int64_t *timeStamp);
 
PCR_API PCRStatus pcrGetChannelShared(int handle, int channel, PCRBool *useSharedLO);
 
PCR_API PCRStatus pcrSetChannelFreq(int handle, int channel, double freqHz);
 
PCR_API PCRStatus pcrUpdateChannelFreq(int handle, int channel, double freqHz, int64_t *timeStamp);
 
PCR_API PCRStatus pcrGetChannelFreq(int handle, int channel, double *freqHz);
 
PCR_API PCRStatus pcrSetChannelPhaseOffset(int handle, int channel, double phaseOffset);
 
PCR_API PCRStatus pcrGetChannelPhaseOffset(int handle, int channel, double *phaseOffset);
 
PCR_API PCRStatus pcrSetChannelDelay(int handle, int channel, double delay);
 
PCR_API PCRStatus pcrGetChannelDelay(int handle, int channel, double *delay);
 
PCR_API PCRStatus pcrSetSharedFreq(int handle, double freqHz);
 
PCR_API PCRStatus pcrUpdateSharedFreq(int handle, double freqHz, int64_t *timeStamp);
 
PCR_API PCRStatus pcrGetSharedFreq(int handle, double *freqHz);
 
PCR_API PCRStatus pcrSetStreamDataType(int handle, PCRDataType dataType);
 
PCR_API PCRStatus pcrSetStreamFullScale(int handle, PCRBool fullScale);
 
PCR_API PCRStatus pcrSetStreamRefLevel(int handle, double refLevel);
 
PCR_API PCRStatus pcrSetStreamAtten(int handle, int atten);
 
PCR_API PCRStatus pcrSetStreamSampleRate(int handle, int decimation);
 
PCR_API PCRStatus pcrSetStreamBandwidth(int handle, double bandwidth);
 
PCR_API PCRStatus pcrSetStreamTriggerEdge(int handle, PCRTriggerEdge edge);
 
PCR_API PCRStatus pcrSetStreamMode(int handle, PCRStreamMode mode);
 
PCR_API PCRStatus pcrSetStreamLocalAddr(
    int handle,
    int deviceIndex,
    uint16_t port);
 
PCR_API PCRStatus pcrSetStreamVrtAddr(
    int handle,
    int channel, 
    const char *dstAddr, 
    uint16_t dstPort, 
    uint64_t dstMACAddr);
 
PCR_API PCRStatus pcrSetStreamVrtChannelID(int handle, int channel, int streamID);
 
PCR_API PCRStatus pcrSetStreamVrtCntxInterval(int handle, PCRBool enabled, int interval);
 
PCR_API PCRStatus pcrSetStreamVrtEndianness(int handle, PCREndianness endianness);
 
PCR_API PCRStatus pcrSetSweepRefLevel(int handle, double refLevel);
 
PCR_API PCRStatus pcrSetSweepAtten(int handle, int atten);
 
PCR_API PCRStatus pcrSetSweepCenterSpan(int handle, double centerHz, double spanHz);
 
PCR_API PCRStatus pcrSetSweepStartStop(int handle, double startHz, double stopHz);
 
PCR_API PCRStatus pcrSetSweepCoupling(int handle, double rbw, double vbw, double sweepTime);
 
PCR_API PCRStatus pcrSetSweepDetector(int handle, PCRSweepDetector detector, PCRSweepVideoUnits videoUnits);
 
PCR_API PCRStatus pcrSetSweepScale(int handle, PCRSweepScale scale);
 
PCR_API PCRStatus pcrSetSweepWindow(int handle, PCRSweepWindow window);
 
PCR_API PCRStatus pcrSetVSGEnabled(int handle, PCRBool enabled);
 
PCR_API PCRStatus pcrSetVSGLevel(int handle, double level);
 
PCR_API PCRStatus pcrSetVSGPattern(int handle, void *iq, int len, PCRDataType dataType);
 
PCR_API PCRStatus pcrInitiate(int handle);
 
PCR_API PCRStatus pcrAbort(int handle);
 
PCR_API PCRStatus pcrStreamParameters(int handle, int *channelCount, double *sampleRate, double *bandwidth);
 
PCR_API PCRStatus pcrStreamCorrection(int handle, int channel, float *correction);
 
PCR_API PCRStatus pcrStreamRecv(int handle,
                                void **buffers,
                                int samples,
                                int64_t *nsSinceEpoch,
                                PCRBool purge,
                                int *sampleLoss,
                                int *samplesRemaining,
                                double *triggers,
                                int triggerBufSize);
 
PCR_API PCRStatus pcrStreamRecvFlat(int handle,
                                void* buffer,
                                int samples,
                                int64_t* nsSinceEpoch,
                                PCRBool purge,
                                int* sampleLoss,
                                int* samplesRemaining,
                                double* triggers,
                                int triggerBufSize);
 
PCR_API PCRStatus pcrSweepGetParameters(int handle,
                                        double *actualRBW,
                                        double *actualVBW,
                                        double *actualStartFreq,
                                        double *binSize,
                                        int *sweepSize);
 
PCR_API PCRStatus pcrGetSweep(int handle, float *sweep);
 
PCR_API PCRStatus pcrSweepStart(int handle);
 
PCR_API PCRStatus pcrSweepFinish(int handle, float *sweep);
 
PCR_API PCRStatus pcrNetworkConfigGetDeviceList(int *serials, int *deviceCount);
 
PCR_API PCRStatus pcrNetworkConfigOpenDevice(int *handle, int serialNumber);
 
PCR_API PCRStatus pcrNetworkConfigCloseDevice(int handle);
 
PCR_API PCRStatus pcrNetworkConfigGetMAC(int handle, char *mac);
 
PCR_API PCRStatus pcrNetworkConfigSetIP(int handle, const char *addr, PCRBool nonVolatile);
 
PCR_API PCRStatus pcrNetworkConfigGetIP(int handle, char *addr);
 
PCR_API PCRStatus pcrNetworkConfigSetPort(int handle, int port, PCRBool nonVolatile);
 
PCR_API PCRStatus pcrNetworkConfigGetPort(int handle, int *port);
 
PCR_API PCRStatus pcrSetPPSSource(int handle, PCRBool useExternalPPS);
 
PCR_API PCRStatus pcrSetTime(int handle, uint32_t epochTimeSec);
 
 
PCR_API const char* pcrGetAPIVersion();
 
PCR_API const char* pcrGetErrorString(PCRStatus status);
 
#ifdef __cplusplus
} // Extern "C"
#endif
 
#endif // PCR_API_H