pg2sdr.h

Go to the documentation of this file.

/*
 *  pg2sdr.h - PG2 host library, public API header
 *
 *  Copyright (c) 2026 FlightAware All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are
 *  met:
 *
 *  1. Redistributions of source code must retain the above copyright
 *  notice, this list of conditions and the following disclaimer.
 *
 *  2. Redistributions in binary form must reproduce the above copyright
 *  notice, this list of conditions and the following disclaimer in the
 *  documentation and/or other materials provided with the distribution.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 *  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef PG2SDR_H
#define PG2SDR_H
 
#include <libusb-1.0/libusb.h>
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
#include <stdbool.h>
#include <stdlib.h>
#include <endian.h>
#include <string.h>
#include <errno.h>
 
#if defined(__cplusplus)
extern "C" {
#endif
 
typedef struct pg2sdr__context pg2sdr_context;
 
typedef enum {
    PG2SDR_LOG_DEBUG, 
    PG2SDR_LOG_INFO,  
    PG2SDR_LOG_ERROR  
} pg2sdr_log_level;
 
typedef void (*pg2sdr_log_callback)(pg2sdr_context *context,
                                    pg2sdr_log_level level,
                                    const char *message);
 
 
 
#define PG2SDR_API_VERSION 0x01000100U
 
uint32_t pg2sdr_get_api_version(void);
 
/* if documenting the API, gloss over the macro API stuff */
#ifdef DOXYGEN
int pg2sdr_init(pg2sdr_context **ctx);
#else /* !DOXYGEN */
/* internal version of pg2sdr_init, checks that the runtime API version is at least min_api_version */
int pg2sdr__init_version(pg2sdr_context **ctx, uint32_t min_api_version);
#define pg2sdr_init(ctx) pg2sdr__init_version(ctx, PG2SDR_API_VERSION)
#endif
 
int pg2sdr_exit(pg2sdr_context *ctx);
 
int pg2sdr_set_log_callback(pg2sdr_context *ctx, pg2sdr_log_callback callback);
 
enum pg2sdr_error {
    PG2SDR_SUCCESS = 0,                    
    PG2SDR_ERROR_NOT_FOUND = -1,           
    PG2SDR_ERROR_DISCONNECTED = -2,        
    PG2SDR_ERROR_BAD_ARGUMENT = -3,        
    PG2SDR_ERROR_NO_MEMORY = -4,           
    PG2SDR_ERROR_NOT_IMPLEMENTED = -5,     
    PG2SDR_ERROR_FIRMWARE_MISMATCH = -6,   
    PG2SDR_ERROR_MULTIPLE_DEVICES = -7,    
    PG2SDR_ERROR_BUSY = -8,                
    PG2SDR_ERROR_BAD_STATE = -9,           
    PG2SDR_ERROR_TIMEOUT = -10,            
    PG2SDR_ERROR_CORRUPTION = -11,         
    PG2SDR_ERROR_ACCESS = -12,             
    PG2SDR_ERROR_LIBRARY_VERSION = -13,    
    PG2SDR_ERROR_TRANSFER_OTHER = -200,    
    PG2SDR_ERROR_TRANSFER_STALL = -201,    
    PG2SDR_ERROR_TRANSFER_OVERFLOW = -202, 
    PG2SDR_ERROR_TRANSFER_FORMAT = -203,   
    PG2SDR_ERROR_TUNER_DETECT = -300,      
    PG2SDR_ERROR_TUNER_PLL_LOCK = -301,    
    PG2SDR_ERROR_TUNER_PLL_RANGE = -302,   
    PG2SDR_ERROR_TUNER_I2C = -303,         
    PG2SDR_ERROR_ADC_RATE_RANGE = -304,    
    PG2SDR_ERROR_SYSTEM_MAX = -1000,       
    PG2SDR_ERROR_SYSTEM_MIN = -1999,       
    PG2SDR_ERROR_LIBUSB_MAX = -2000,       
    PG2SDR_ERROR_LIBUSB_MIN = -2999,       
};
 
const char *pg2sdr_strerror(int error);
 
const char *pg2sdr_strerror_r(int error, char *buf, size_t buflen);
 
typedef struct pg2sdr__device pg2sdr_device;
 
typedef enum {
    PG2SDR_MODE_LOWIF_REAL, 
    PG2SDR_MODE_BASEBAND    
} pg2sdr_conversion_mode_t;
 
typedef enum {
    PG2SDR_SIDEBAND_LOWER, 
    PG2SDR_SIDEBAND_UPPER  
} pg2sdr_sideband_mode_t;
 
typedef struct {
    const char *serial;        
    const char *ports;         
    libusb_device *lu_device;  
} pg2sdr_usb_device;
 
typedef struct {
    pg2sdr_conversion_mode_t mode;
 
    int16_t *samples;
 
    unsigned count;
 
    uint64_t timestamp;
} pg2sdr_sample_buffer;
 
typedef bool (*pg2sdr_stream_callback)(pg2sdr_device *dev, pg2sdr_sample_buffer *buffer, void *user_data);
 
/* Device discovery and open/close (device.c) */
 
ssize_t pg2sdr_discover_devices(pg2sdr_context *ctx,
                                const char *match_serial_prefix,
                                const char *match_ports,
                                pg2sdr_usb_device ***usb_device_list);
 
void pg2sdr_free_device_list(pg2sdr_usb_device **usb_device_list);
 
int pg2sdr_open_device(pg2sdr_context *ctx, pg2sdr_usb_device *usb_device, pg2sdr_device **device);
 
int pg2sdr_open_libusb_device(pg2sdr_context *ctx, libusb_device *lu_device, pg2sdr_device **device);
 
int pg2sdr_open_single_device(pg2sdr_context *ctx,
                              const char *serial_prefix,
                              const char *ports,
                              pg2sdr_device **device);
 
int pg2sdr_close_device(pg2sdr_device *dev);
 
const char *pg2sdr_get_serial(pg2sdr_device *dev);
 
const char *pg2sdr_get_ports(pg2sdr_device *dev);
 
uint32_t pg2sdr_get_firmware_version(pg2sdr_device *dev);
 
int pg2sdr_set_conversion_mode(pg2sdr_device *dev, pg2sdr_conversion_mode_t mode);
 
int pg2sdr_get_conversion_mode(pg2sdr_device *dev, pg2sdr_conversion_mode_t *mode);
 
int pg2sdr_set_buffer_size(pg2sdr_device *dev, size_t buffer_size);
 
int pg2sdr_get_buffer_size(pg2sdr_device *dev, size_t *buffer_size);
 
int pg2sdr_set_sample_rate(pg2sdr_device *dev, double rate);
 
int pg2sdr_get_sample_rate(pg2sdr_device *dev, double *requested, double *actual);
 
#define PG2SDR_DECIMATION_AUTO (-1)
 
int pg2sdr_set_decimation_mode(pg2sdr_device *dev, int decimation_mode);
 
int pg2sdr_get_decimation_mode(pg2sdr_device *dev, int *decimation_mode, unsigned *actual_decimation);
 
int pg2sdr_set_undersampling_mode(pg2sdr_device *dev, unsigned undersampling_mode);
 
int pg2sdr_get_undersampling_mode(pg2sdr_device *dev, unsigned *undersampling_mode);
 
int pg2sdr_set_adc_limit(pg2sdr_device *dev, double adc_limit);
 
int pg2sdr_get_adc_limit(pg2sdr_device *dev, double *adc_limit);
 
int pg2sdr_get_adc_rate(pg2sdr_device *dev, double *actual_adc_rate);
 
int pg2sdr_set_sideband(pg2sdr_device *dev, pg2sdr_sideband_mode_t mode);
 
int pg2sdr_get_sideband(pg2sdr_device *dev, pg2sdr_sideband_mode_t *mode);
 
int pg2sdr_set_frequency(pg2sdr_device *dev, double frequency);
 
int pg2sdr_get_frequency(pg2sdr_device *dev, double *requested, double *actual);
 
int pg2sdr_set_bandpass(pg2sdr_device *dev, double low, double high);
 
int pg2sdr_get_bandpass(pg2sdr_device *dev, double *req_low, double *req_high, double *actual_low, double *actual_high);
 
int pg2sdr_apply_changes(pg2sdr_device *dev);
 
int pg2sdr_set_lna_gain(pg2sdr_device *dev, unsigned gain);
 
int pg2sdr_set_mix_gain(pg2sdr_device *dev, unsigned gain);
 
int pg2sdr_set_vga_gain(pg2sdr_device *dev, unsigned gain);
 
int pg2sdr_get_stage_gains(pg2sdr_device *dev, unsigned *lna, unsigned *mix, unsigned *vga);
  
int pg2sdr_set_lna_gain_db(pg2sdr_device *dev, double gain_db);
 
int pg2sdr_set_mix_gain_db(pg2sdr_device *dev, double gain_db);
 
int pg2sdr_set_vga_gain_db(pg2sdr_device *dev, double gain_db);
 
int pg2sdr_get_stage_gains_db(pg2sdr_device *dev, double *lna_db, double *mix_db, double *vga_db);
 
int pg2sdr_set_total_gain_db(pg2sdr_device *dev, double gain_db);
 
int pg2sdr_get_total_gain_db(pg2sdr_device *dev, double *gain_db);
 
typedef struct {
    double gain_db;         
    unsigned lna_gain : 4;  
    unsigned mix_gain : 4;  
    unsigned vga_gain : 4;  
} pg2sdr_gain_table_t;
 
int pg2sdr_set_gain_tables(pg2sdr_device *dev,
                           const pg2sdr_gain_table_t *gain_table, size_t gain_table_size,
                           const double *lna_table,
                           const double *mix_table,
                           const double *vga_table);
 
int pg2sdr_get_gain_tables(pg2sdr_device *dev,
                           pg2sdr_gain_table_t **gain_table,
                           size_t *gain_table_size,
                           double *lna_table,
                           double *mix_table,
                           double *vga_table);
 
typedef struct {
    /* floats here to reduce the size of the (large) table */
 
    float lower_corner;      
    float upper_corner;      
    float ripple;            
    unsigned hpf_corner : 4; 
    unsigned lpf_narrow : 1; 
    unsigned lpf_coarse : 2; 
    unsigned lpf_fine : 4;   
    unsigned lpf_q : 1;      
} pg2sdr_bandpass_table_t;
 
 
int pg2sdr_set_bandpass_table(pg2sdr_device *dev,
                              const pg2sdr_bandpass_table_t *bandpass_table, size_t bandpass_table_size);
 
int pg2sdr_get_bandpass_table(pg2sdr_device *dev,
                              pg2sdr_bandpass_table_t **bandpass_table,
                              size_t *bandpass_table_size);
 
int pg2sdr_stream_data(pg2sdr_device *dev, pg2sdr_stream_callback callback, void *user_data);
 
int pg2sdr_stop_streaming(pg2sdr_device *dev);
 
void pg2sdr_release_buffer(pg2sdr_sample_buffer *buffer);
 
#if defined(__cplusplus)
}
#endif
 
 
#endif /* PG2SDR_H */