C:/Users/arobi/Perforce/nightly/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h

Go to the documentation of this file.

#ifndef DL_H
#define DL_H
 
#include <stddef.h>
#include <cstdint>
 
#define DL_STRUCTALIGN 4
 
// Windows DLL Exports
#if defined(_WIN32) || defined(_WIN64)
    // Dynamic Linking
#   ifndef DL_STATICLIB
#       ifdef DL_EXPORTS
#           define DL_API extern "C" __declspec(dllexport)
#       else
#           define DL_API extern "C" __declspec(dllimport)
#       endif
 
#       define MYCDECL __cdecl
 
    // Static Linking
#   else
#       define DL_API
#       define MYCDECL
#   endif
 
#else 
 
// Define macros for Non-Windows systems
 
#define DL_API extern "C"
#define DL_GUI_API
#define MYCDECL
 
#endif
 
namespace dl
{
    enum EStatusCode
    {
        Success = 0,                
 
        // client specific errors ...
        ClientError = 0x01,         
        InvalidSoh = ClientError,   
        InvalidHeaderType,          
        InvalidBodyType,            
        InvalidFooterType,          
        InvalidSensorId,            
        InvalidMessageLength,       
        InvalidParameter,           
        UnsupportedBodyType,        
        BadChecksum,                
 
        // device specific errors ... 
        DeviceError = 0x80,                 
        DeviceBusy,                         
        ExposureInProgress = DeviceBusy,    
        ReadoutInProgress = DeviceBusy,     
        ImageNotAvailable,                  
        FeatureNotSupported,                
 
        // Book keeping
        InvalidStatus = 0xff 
    };
 
    enum EPulseGuideDirection
    {
        North = 0,  
        South = 1,  
        East = 2,   
        West = 3,   
    };
    
    enum EFilterType
    {
        Monochrome,                 
        Color,                      
        SparseColor,                
        InvalidFilterType = 0xff,   
    };
    using FilterType = EFilterType; // Kept for compatibility purposes [[deprecated]]
 
    enum EFrameType
    {
        Progressive,                
        Interline,                  
        BayerInterline,             
        RollingShutter,             
        GlobalShutter,              
        InvalidFrameType = 0xff,    
    };
 
    enum EShutterStatus
    {
        ShutterClosed = 0,  
        ShutterOpen,        
        ShutterClosing,     
        ShutterOpening,     
        ShutterRolling,     
        ShutterExercising,  
        ShutterError,       
 
        ShutterUninitialized = 0xFF 
    };
 
    enum ENetworkMode
    {
        AdHoc = 0,  
        Open = 1,   
        WEP = 2,    
        WPA = 3,    
        WPA2 = 4,   
        InvalidNetworkMode = 0xff   
    };
 
    enum EEndpointType {
        Net = 1, 
        USB = 2, 
        USB3 = 3, 
        RAW = 4, 
 
        EndpointTypeCount,                          
        LastEndpointType = EndpointTypeCount - 1,   
        FirstEndpointType = Net,                    
        InvalidEndpoint = 0xff,                     
    };
 
    namespace ErrorFlags {
 
        namespace TEC {
            static const int ThermistorErrorFlagMask = 0x00000003;      //<! Mask for thermistor error flags. \see ICamera::Status::flag
            static const int SensorThermistorErrorFlag = 0x00000001;    //<! Error flag for sensor thermistor. \see ICamera::Status::flag
            static const int HeatSinkThermistorErrorFlag = 0x00000002;  //<! Error flag for heatsink thermistor. \see ICamera::Status::flag
        }
        
        namespace AO {
            static const unsigned char statusMask = 0x0f;       
            static const unsigned char busy = 0x01;             
            static const unsigned char badCalibration = 0x02;   
            static const unsigned char reserved = 0x04;         
            static const unsigned char badCommand = 0x08;       
        }
    }
 
    namespace PulseGuideStatus
    {
        static const unsigned char c_xBusy = 0x01; 
        static const unsigned char c_yBusy = 0x02; 
    }
 
#   pragma pack(push, DL_STRUCTALIGN)
    struct TImageMetadata
    {
        unsigned int width;     
        unsigned int height;    
        unsigned int offsetX;   
        unsigned int offsetY;   
        unsigned int binX;      
        unsigned int binY;      
        float eGain;            
        float exposureDuration; 
    };
 
    struct TExposureOptions
    {
        float duration;             
        unsigned int readoutMode;   
        char binX;                  
        char binY;                  
        bool isLightFrame;          
        bool useRBIPreflash;        
        bool useExtTrigger;         
    };
 
    struct TSubframe
    {
        int top;    
        int left;   
        int width;  
        int height; 
        int binX;   
        int binY;   
    };
 
 
    struct TNetworkSettings
    {
        unsigned int ssidLength;        
        unsigned int passphraseLength;  
        ENetworkMode mode;              
        char ssid[32];                  
        char passphrase[64];            
        bool isUsaCanadaMode;           
        bool isPassphraseHex;           
    };
 
    struct TConnectionDetails
    {
        unsigned int serialNumber;  
        EEndpointType endpointType; 
        size_t index;               
 
        TConnectionDetails() : serialNumber(0), endpointType(InvalidEndpoint), index(0) {} 
    };
#   pragma pack(pop)
 
    class IImage
    {
    public:
        virtual unsigned short *    getBufferData() const = 0;
 
        virtual unsigned int        getBufferLength() const = 0;
 
        virtual TImageMetadata      getMetadata() const = 0;
    };
 
    typedef IImage* IImagePtr; 
    
    // TODO : Add documentation
    struct TLayerMetadata
    {
        unsigned int    width;
        unsigned int    height;
        unsigned int    binX;
        unsigned int    binY;
        float           eGain;
        unsigned int    darkCol;
        float           exposureDuration;
        unsigned int    exposureDelay;
        unsigned int    exposureWindow;
    };
    
    // TODO : Add documentation
    class IImageExt
    {
    public:
        virtual size_t getLayerCount() const = 0;
        virtual TLayerMetadata getLayerMetadata(unsigned int layer) const = 0;
        virtual void getExpMidpoint(char * pBuffer, size_t & lng) const = 0;
    };
    
    typedef IImageExt* IImageExtPtr;
    
    namespace V2 {
        
        class IImage : public IImageExt
        {
        public:
 
            class IMetadataKey {
            public:
                enum class Type {
                    UNKNOWN = 0,    
                    INT,            
                    FLOAT,          
                    DOUBLE,         
                    STRING,         
                    BOOL,           
                };
 
                virtual unsigned int id() const = 0;
                virtual const char* key() const = 0;
                virtual Type type() const = 0;
                
                // Methods to retrieve the value of the metadata key in various formats
                virtual const char* value() const = 0;
 
                virtual int asInt() const = 0;
 
                virtual float asFloat() const = 0;
 
                virtual double asDouble() const = 0;
 
                virtual const char* asString() const = 0;
                
                virtual bool asBool() const = 0;
 
            };
 
            virtual bool hasMetadataKeys() const = 0;
 
            virtual size_t getMetadataKeyCount() const = 0;
            
            virtual IMetadataKey* getMetadataKey(size_t index) const = 0;
            
            virtual IMetadataKey* getMetadataKey(const char* key) const = 0;
        };
 
        typedef IImage* IMetadataKeyPtr; 
        typedef IImage* IImagePtr; 
 
    }
 
 
    class IPromise
    {
    public:
 
        enum Status
        {
            Idle,      
            Executing, 
            Complete,  
            Error,     
 
            InvalidFuture = 0xff    
        };
 
        virtual void   getLastError(char * buffer, size_t& bufferSize) const = 0;
 
        virtual EStatusCode getAPIStatusCode() const = 0;
        
        virtual Status getStatus() const = 0;
 
        virtual Status wait() = 0;
 
        virtual void   release() = 0;
    };
 
    typedef IPromise* IPromisePtr; 
 
 
    class ITEC 
    {
    public:
        virtual bool  getEnabled() const = 0;
 
        virtual float getSetpoint() const = 0;
 
        virtual float getCoolerPower() const = 0;
    
        virtual float getSensorThermopileTemperature() const = 0;
        
        virtual float getHeatSinkThermopileTemperature() const = 0;
 
        virtual IPromisePtr setState(bool enable, float setpoint) = 0;
    };
 
    typedef ITEC* ITECPtr; 
 
 
    class IAO {
    public:
        
        enum Status {
            Idle,   
            Busy,   
            Error,  
            InvalidAOStatus = 0xff, 
        };
 
        enum Model
        {
            UnknownAOModel = 0,    
            AO8,                   
            AOX,                   
            InvalidAOModel = 0xff, 
        };
 
        virtual IPromisePtr initialize() = 0;
 
        virtual IPromisePtr queryStatus() = 0;
 
        virtual IPromisePtr setPosition(short tip, short tilt) = 0;
 
        virtual IAO::Status getStatus() const = 0;
 
        virtual void getPosition(short &tip, short &tilt) const = 0;
 
        virtual void getLimits(size_t &tipMin, size_t &tipMax, size_t &tiltMin, size_t &tiltMax) const = 0;
 
        virtual Model getModel() const = 0;
    };
 
    typedef IAO* IAOPtr; 
 
    class IFW {
    public:
        enum Model
        {
            UnknownFWModel = 0, 
 
            CFW2,           
            CFW5,           
            CFW8,           
            CFWL,           
            CFW402,         
            CFW6A,          
            CFW10,          
            CFW10_SERIAL,   
            CFW9,           
            CFWL8,          
            CFWL8G,         
            CFW1603,        
            FW5_STX,        
            FW5_8300,       
            FW8_8300,       
            FW7_STX,        
            FW8_STT,        
            FW5_STF_DETENT, 
            Internal,       
 
            // New AFW line where model number represents number of slots (submodels include filter diameter & shape)
            AFW16,  
            AFW15,  
            AFW14,  
            AFW13,  
            AFW12,  
            AFW11,  
            AFW10,  
            AFW9,   
            AFW8,   
            AFW7,   
            AFW6,   
            AFW5,   
            AFW4,   
            AFW3,   
            AFW2,   
 
            // ^^ new models here ^^
 
            InvalidFWModel = 0xFF, 
        };
 
        enum Status {
            FWIdle,  
            FWBusy,  
            FWError, 
 
            InvalidFWStatus = 0xff, 
        };
 
 
        virtual IPromisePtr initialize() = 0;
 
        virtual IPromisePtr queryStatus() = 0;
 
        virtual int getPosition() const = 0;
        
        virtual IFW::Status getStatus() const = 0;
        
        virtual IFW::Model getModel() const = 0;
        
        virtual unsigned int getSlots() const = 0;
        
        virtual IPromisePtr setPosition(int position) = 0;
    };
 
    typedef IFW* IFWPtr; 
 
    class IFWExtended : public IFW
    {
    public:
        virtual unsigned int getChildCount() const = 0;
        virtual IFW::Model getChildModel(unsigned int) const = 0;
        virtual unsigned int getChildSlots(unsigned int) const = 0;
 
        virtual const char* getModelName(unsigned int) const = 0;
    };
    typedef IFWExtended* IFWExtendedPtr;
 
    class ISensor {
    public:
 
        enum Model {
            RESERVED1 = 0x00,   
            RESERVED2 = 0x01,   
            ICX694 = 0x02,      
            ICX814 = 0x03,      
            CCD4710 = 0x04,     
            CCD7700 = 0x05,     
            RESERVED3 = 0x06,   
            RESERVED4 = 0x07,   
            RESERVED5 = 0x09,   
            RESERVED6 = 0x08,   
            KAF3200 = 0x0a,     
            KAF8300 = 0x0b,     
 
            RESERVED7 = 0x10,   
            RESERVED8 = 0x11,   
 
            RESERVEDB1 = 0x100, 
            
            RESERVEDC1 = 0x200, 
 
            GSENSE4040 = 0x300, 
            GSENSE4040BSI,      
 
            GSENSE2020 = 0x600, 
 
            P1300 = 0x400,      
 
            IMX428 = 0x500,     
            IMX428_7,           
 
            IMX290 = 0x800,     
 
            IMX455 = 0x900,     
            IMX461 = 0x901,     
 
            InvalidSensorModel = 0xFF, 
        };
 
        enum Status
        {
 
            Idle,            
            Trigger,         
            PreShutter,      
            DoShutterOpen,   
            Starting,        
            Exposing,        
            DoShutterClose,  
            Reading,         
            ReadyToDownload, 
            HomingShutter,   
 
            InvalidSensorState = 0xFF, 
        };
 
        enum Setting
        {
            UseOverscan,            
            RBIPreflashDuration,    
            RBIPreflashFlushCount,  
            UseWindowHeater,        
            FanSpeed,               
            ToggleIRLEDs,           
            UseOnChipBinning,       
            UseExtTrigger,          
            AutoFanMode,            
            ShutterPolarity,        
            EnableStatusLED,        
            PartialExposureLength,  
            UseFWAsShutter,         
            AnalogGain0,            
            AnalogGain1,            
            ContinuousExposure,     
 
            SettingCount,           
            
            // Software-only settings (not reflected in hardware)
            SoftwareBinMode = 0x10000000,       
            
            SoftwareSettingCount,
 
            FirstSensorSetting = UseOverscan, 
            FirstSoftwareSetting = SoftwareBinMode,
            
            InvalidSensorSetting = 0xff 
        };
 
        enum class SoftwareBinningMode : int
        {
            SumAndClip,
            Average,
 
            Count,
            First = SumAndClip,
            Default = SumAndClip
        };
 
        enum CalibrationKey
        {
            EGain,
            DriftStabilization,
 
            CalibrationCount,           
            FirstCalibrationKey = EGain,
            InvalidCalibrationKey = 0xff
        };
 
#       pragma pack(push, DL_STRUCTALIGN)
        struct Info
        {
            unsigned int   id;                          
            ISensor::Model model;                       
            unsigned int   pixelsX;                     
            unsigned int   pixelsY;                     
            unsigned int   numberOfChannelsAvailable;   
            FilterType     filterType;                  
            EFrameType     frameType;                   
            float          pixelSizeX;                  
            float          pixelSizeY;                  
            int            minCoolerSetpoint;           
            int            maxCoolerSetpoint;           
            unsigned int   maxBinX;                     
            unsigned int   maxBinY;                     
            float          minExposureDuration;         
            float          exposurePrecision;           
            bool           hasRBIPreflash;              
            unsigned char  flag;                        
        };
 
        struct Calibration
        {
            unsigned int substrateVoltage; 
            unsigned int channelsInUse;    
            unsigned int adcGains[4];      
            int          adcOffsets[4];    
            float        eGain;            
        };
 
        struct Settings
        {
            struct RBIPreflashSettings
            {
                int duration; 
                int flushes;  
            } rbiPreflash;    
 
            int  fanSpeed;              
            bool useOverscan;           
            bool useWindowHeater;       
            bool enableIRLEDs;          
            bool useOnChipBinning;      
            bool useExtTrigger;         
            bool autoFanSpeed;          
            int  shutterPolarity;       
            bool enableStatusLED;       
            int  partialExposureLength; 
            int  useFWAsShutter;        
        };
#       pragma pack(pop)
 
        virtual const unsigned int      getSensorId() const = 0;
 
        virtual ISensor::Info           getInfo() const = 0;
 
        virtual ISensor::Calibration    getCalibration() const = 0;
        
        virtual ISensor::Settings       getSettings() const = 0;
        
        virtual int                     getSetting(ISensor::Setting key) const = 0;
 
        virtual TSubframe               getSubframe() const = 0;
        
        virtual IImagePtr getImage() const = 0;
 
        virtual IPromisePtr queryInfo() = 0;
 
        virtual IPromisePtr querySetting(ISensor::Setting setting) = 0;
 
        virtual IPromisePtr queryCalibration() = 0;
        
        virtual IPromisePtr queryCalibration(ISensor::CalibrationKey key, int subkey) = 0;
 
        virtual unsigned int getCalibration(ISensor::CalibrationKey key, int subkey) = 0;
 
        virtual IPromisePtr querySubframe() = 0;
 
        virtual IPromisePtr setSetting(ISensor::Setting key, int value) = 0;
        
        virtual IPromisePtr setSubframe(const TSubframe & value) = 0;
 
        virtual IPromisePtr startExposure(const TExposureOptions & params) = 0;
 
        virtual IPromisePtr DebugStartExposure(unsigned int id, const char* exposureType, const TExposureOptions& params) = 0;
 
        virtual IPromisePtr startDownload() = 0;
 
        virtual IPromisePtr abortExposure() = 0;
 
 
        virtual void getReadoutModes(char * buf, size_t& lng) const = 0;
 
        enum AdjustableGainMode {
            eAdjustableADCGain0,
            eAdjustableADCGain1,
 
            eAdjustableADCGainCount,
            eAdjustableADCGainFirst = eAdjustableADCGain0,
 
            eAdjustableGainAC4040HiGain = eAdjustableADCGain0,
            eAdjustableGainAC4040LoGain = eAdjustableADCGain1
        };
 
        virtual void getAdjustableGains(AdjustableGainMode mode, int* pGainEntries, unsigned int& gainEntryCount) const = 0;
 
        virtual unsigned int getAdjustableGainCount(AdjustableGainMode mode) const = 0;
 
        virtual unsigned int getDefaultAdjustableGain(AdjustableGainMode mode) const = 0;
    };
 
    typedef ISensor* ISensorPtr; 
 
    class ICamera
    {
    public: 
        enum State {
            Uninitialized,  //<! Uninitialized Camera is uninitialized.
            Initializing,   //<! Initializing Camera is in process of initializing.
            Ready,          //<! Ready Camera is ready for operation.
            Error           //<! Error Camera has had an error.
        };
 
        enum Model {
            Aluma,                      
            AlumaPro,                   
            Reserved2,                  
            AlumaCMOS,                  
            StarChaser,                 
            STC,                        
            AlumaAC2020,                
            StarChaserE,                
            StarChaserC,                
            AlumaAC455,
            Reserved9,
            AlumaAC461,
 
            InvalidCameraModel = 0xff,  
            Reserved4 = StarChaser,     
            Reserved5 = STC,
            Reserved3 = AlumaCMOS,
            Reserved6 = AlumaAC2020,
            Reserved7 = StarChaserE,
            Reserved8 = StarChaserC,
            Reserved1 = AlumaPro,
            Reserved10 = AlumaAC461,
            StarChaserP3 = StarChaserE,
            StarChaser4 = StarChaserC,  
        };
 
        enum Capability {
            eSupportsFan,                   
            eSupportsCooler,                
            eSupportsCoolerTemp,            
            eSupportsHeatSinkTemp,          
            eSupportsAdaptiveOptics,        
            eSupportsFilterWheel,           
            eSupportsGuidePort,             
            eSupportsWiFi,                  
            eSupportsDefogHeater,           
            eSupportsSensorGainOffset,      
            eSupportsInternalStacking,      
            eSupportsFastContinuousReadout, 
            eSupportsShutter,               
            eSupportsPrecisionCoolerPower,  
            eSupportsExtendedStartDownload, 
            eSupportsInputVoltage,          
            eSupportsOverscan,              
            eSupportsOnChipBinning,         
            eSupportsAdjustableGain,        
            eSupportsPeripheralInfo,        
            eSupportsFibreXferProtocol,     
            eSupportsMetadataKeys,          
 
            CameraCapabilityCount,          
 
            eSupportsSoftwareBinMode = 0x10000000,
 
            SoftwareCapabilityCount,
            FirstSoftwareCapability = eSupportsSoftwareBinMode,
 
            InvalidCameraCapability = 0xff  
        };
 
#   pragma pack(push, DL_STRUCTALIGN)
        struct Status
        {
            ISensor::Status mainSensorState;        
            ISensor::Status extSensorState;         
            float           sensorTemperature;      
            float           coolerPower;            
            float           heatSinkTemperature;    
            float           inputVoltage;           
            unsigned int    pulseGuideStatus;       
            unsigned int    flag;                   
            EShutterStatus  shutterStatus;          
 
            Status() 
                : mainSensorState(ISensor::InvalidSensorState), extSensorState(ISensor::InvalidSensorState), 
                  sensorTemperature(0), coolerPower(0), heatSinkTemperature(0), inputVoltage(0), 
                  pulseGuideStatus(0), flag(0), shutterStatus(ShutterUninitialized) {} //<! Default constructor.
        };
 
        struct Info
        {
            ICamera::Model  model;                  
            unsigned int    serialNumber;           
            unsigned int    firmwareRevision;       
            unsigned int    wifiFirmwareRevision;   
            unsigned char   numberOfSensors;        
 
            Info() : model(InvalidCameraModel), serialNumber(0), firmwareRevision(0), wifiFirmwareRevision(0), numberOfSensors(0) {}  
        };
#       pragma pack(pop)
 
        virtual ~ICamera() = 0;
        
        // Query functions ping the camera for updated values.
        
        virtual bool initialize() = 0;
 
        
 
        virtual IPromisePtr     queryInfo() = 0;
 
        virtual IPromisePtr     queryStatus() = 0;
 
        virtual IPromisePtr     queryNetworkSettings() = 0;
 
 
        virtual IPromisePtr     queryCapability(ICamera::Capability key) = 0;
 
        // Commands
 
        virtual IPromisePtr     pulseGuide(EPulseGuideDirection direction, unsigned int duration, bool abort) = 0;
 
        // Set functions
 
        virtual IPromisePtr     setNetworkSettings(const TNetworkSettings& cfg) = 0;
        
        // Get functions return buffered values obtained using query functions.
 
        virtual ICamera::Info      getInfo()  const = 0;
 
        virtual void               getSerial(char * buffer, size_t & buffer_length) const = 0;
 
        virtual EEndpointType      getConnectionType() const = 0;
 
        virtual void getConnectionInfo(char * buffer, size_t &buffer_length) const = 0;
 
        virtual ICamera::Status getStatus() const = 0;
 
 
        virtual bool getCapability(ICamera::Capability key) const = 0;
 
        virtual TNetworkSettings  getNetworkSettings() const = 0;
 
 
        // Get Device Interfaces
 
        virtual ISensorPtr      getSensor(unsigned int id) const = 0;
        
        virtual ITECPtr         getTEC() const = 0;
 
        virtual IAOPtr          getAO() const = 0;
 
        virtual IFWPtr          getFW() const = 0;
    };
 
    namespace V1
    {
        typedef dl::ICamera ICamera;
        typedef dl::ICamera* ICameraPtr;
    }
 
    namespace V2
    {
        class IConnectionManager
        {
        public:
            virtual bool getConnection() const = 0;
            virtual void setConnection(bool enable) = 0;    
        };
        typedef IConnectionManager* IConnectionManagerPtr;
 
 
        class IFirmwareManager
        {
        public: 
            virtual IPromisePtr upload(const char* firmwarePath) = 0;
 
            virtual const char* getFPGAWorkerStatus() const = 0;
        };
    }
 
    typedef ICamera* ICameraPtr; 
    
    class IGateway
    {
    public:
 
        virtual ~IGateway() = 0;
        
        virtual TConnectionDetails getCameraConnectionDetails(unsigned int serial) const = 0;
        
        virtual ICameraPtr  getCamera(TConnectionDetails details) const = 0;
 
        virtual void        queryUSBCameras() = 0;
        
        virtual size_t      getUSBCameraCount() const = 0;
        
        virtual ICameraPtr  getUSBCamera(unsigned int id) const = 0;
        
        virtual void queryNetCameras() = 0;
 
        virtual void queryNetCamera(const char * ip, size_t port) = 0;
        
//      virtual void queryNetCamera(const char* ip, size_t port, const char* nic_ip) = 0;
 
 
        virtual size_t getNetCameraCount() const = 0;
 
        virtual ICameraPtr getNetCamera(unsigned int id) const = 0;
        
        virtual ICameraPtr  getNetCamera(const char * ip, unsigned int port) const = 0;
 
 
        virtual size_t getCommProtocolVersion() const = 0;
 
        virtual void initFitsDebugSettings() = 0;
 
        virtual void initNetworkConfig(const char* filePath) = 0;
    };
 
    typedef IGateway* IGatewayPtr; 
 
    class IDebugControl
    {
    public:
        enum Setting {
            Enable, 
 
            Count,
            Last = Enable,
            First = Enable
        };
 
        virtual void setDebugSetting(IDebugControl::Setting setting, int val) = 0;
 
        virtual int  getDebugSetting(IDebugControl::Setting setting) const = 0;
        
        virtual bool hasDebugSetting(IDebugControl::Setting setting) const = 0;
    };
    
    DL_API IGatewayPtr MYCDECL getGateway();
 
    DL_API void        MYCDECL deleteGateway(IGatewayPtr);
 
#if defined(_WIN32) || defined(_WIN64)
    typedef IGatewayPtr(MYCDECL * f_GetGateway)();          
    typedef void(MYCDECL * f_DeleteGateway)(IGatewayPtr);   
#endif
 
}
#endif