C:/NightlyBuild/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h

Go to the documentation of this file.

#ifndef DL_H
#define DL_H

#include <stddef.h>

#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
#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,        

        // 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 FilterType
    {
        Monochrome,                 
        Color,                      
        SparseColor,                
        InvalidFilterType = 0xff,   
    };

    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, 

        LastEndpointType,        
        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;

    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, 
            GSENSE2020 = 0x600, 

            P1300 = 0x400,      

            IMX428 = 0x500,     
            IMX428_7,           


            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,            

            SettingCount,           
            FirstSensorSetting = UseOverscan, 
            InvalidSensorSetting = 0xff 
        };

        enum CalibrationKey
        {
            EGain,

            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,                      
            Reserved1,                  
            Reserved2,                  
            AlumaCMOS,                  
            StarChaser,                 
            STC,                        
            AlumaAC2020,                
            StarChaserE,                
            Reserved8,                  

            InvalidCameraModel = 0xff,  
            Reserved4 = StarChaser,     
            Reserved5 = STC,
            Reserved3 = AlumaCMOS,
            Reserved6 = AlumaAC2020,
            Reserved7 = StarChaserE,
            StarChaserP3 = StarChaserE
        };

        enum Capability {
            eSupportsFan,                   
            eSupportsCooler,                
            eSupportsCoolerTemp,            
            eSupportsHeatSinkTemp,          
            eSupportsAdaptiveOptics,        
            eSupportsFilterWheel,           
            eSupportsGuidePort,             
            eSupportsWiFi,                  
            eSupportsDefogHeater,           
            eSupportsSensorGainOffset,      
            eSupportsInternalStacking,      
            eSupportsFastContinuousReadout, 
            eSupportsShutter,               
            eSupportsPrecisionCoolerPower,  
            eSupportsExtendedStartDownload, 
            eSupportsInputVoltage,          
            eSupportsOverscan,              
            eSupportsOnChipBinning,         
            eSupportsAdjustableGain,        
            eSupportsPeripheralInfo,        

            CameraCapabilityCount,          
            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;
    }

    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 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;
    };

    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