Astroart drivers SDK 7 (software development kit)

This document explains how to create camera drivers for Astroart 7.0/6.0/5.0
Version 1.40.

1.1) Introduction

1.2) Requirements

2.1) Let's start

2.2) Exported functions

3.1) History

Introduction

A driver is an external module (DLL) that is called by the CCD User Interface of Astroart to command a specific video camera.

Requirements

Since Astroart plug-ins are standard DLLs, any compiler can be used for this purpose. This SDK contains some examples in C and Pascal: although almost every programming language allows creation of DLLs, this is often an uncommon task for most programmers; we recommend to take a look at the specific documentation of your compiler.

Let's start

This document provide complete documentation for programmers of C and Pascal. The fastest way to start is to take a look and compile the demos included in this archive.
Astroart looks for drivers when it starts; for every driver correctly recognized there will be a new item in the "CCD Check combo box". There is no need to "install" driver, every DLL placed in the Astroart directory will be checked and installed if its name is compatible with the following convention:

D_*.DLL , where "*" means a sequence of characters.

Example of valid plug-in names: D_VIDEO.CCD , D_WEBCAM.DLL ..

This means that installing drivers in Astroart is very easy for final users: simply copy them into the installation directory. Software authors may implement this automatically in a installation wizard.

Exported functions

A DLL (dynamic link library) is a collection of functions which are exported to applications which use that DLL. The calling convention is always WINAPI (= STDCALL) this is the standard for Windows. All parameters are 32 bit long.
Astroart needs the functions from a valid plug-in:

Example of C declaration:

 
int WINAPI d_Initialize(HWND whandle)

int WINAPI d_Finalize()

int WINAPI d_SetupCCD(int silent)

int WINAPI d_GetOK()

int WINAPI d_Subframe(int x, int y, int w, int h, int binmode)

int WINAPI d_MoveFrame(int param)

int WINAPI d_GetWidth(int param)

int WINAPI d_GetHeight(int param)	

int WINAPI d_BinningCount()

char* WINAPI d_BinningName(int n)

char* WINAPI d_GetName()

char* WINAPI d_GetInfo()

int WINAPI d_GetTemperature()

int WINAPI d_StartExposure(int expo, int openshutter)

int WINAPI d_IsExposing()

int WINAPI d_StartDownload()

int WINAPI d_ReadImage(unsigned short* pbuffer)

int WINAPI d_EndDownload(unsigned short* pbuffer)

int WINAPI d_InterruptExposure()

int WINAPI d_IsColor()

int WINAPI d_Telescope(int command, int msec)   [optional !]

int WINAPI d_FilterWheel(int command, int param)   [optional !]

int WINAPI d_SetTemperature(int milliCelsius, int coolerPerc)   [optional !]

int WINAPI d_CameraMode(int mode)   [optional !]

The exported functions are the layer between Astroart and the hardware device, a programmer must implement them to perform the operations explained below:


NAME

PARAMS TYPE - COMMENT

RETURNS

d_Initialize

(HWND whandle)

This function is called on startup, a driver should allocate here the memory and the resources it needs, without checking the hardware. "whandle" is the handle of the window of the CCD User Interface.

0,1

d_Finalize

()

This function is called when Astroart closes. The driver should free the resources it allocated.

1

d_SetupCCD

(int silent)

Here the driver should check the hardware. If silent = 0 then the driver can display a dialog window with the parameters of the hardware. If silent = 1 it should use the default settings or the saved ones. This function must return always "1", the result of the CCD check must be stored into a variable which will be returned by then function below (d_GetOK).

1

d_GetOK

()

This function is called many times after "d_Setup CCD", it must return "1" if the hardware was detected and powered on correctly, "0" if not.

0,1

d_Subframe

(int x, int y, int w, int h, int binmode)

Sets the parameters of the image. Binmode is a number defined by the function "d_BinningName" below; x,y,w,h,are the coordinates of the subframe, expressed in percentage*1000 (0..100000). For a full frame x=0, y=0, w=100000, h=100000. This function could be ignored at all, this subframe is only a hint by Astroart. The driver is free to choose the size of the image and how to round/trunc the operations to calculate it.

0,1

d_GetWidth / d_GetHeight

(int param)

These are the most important functions. The driver should return the width and height of the image it wants to pass to Astroart. "param" is a parameter which can be ignored in this release. These functions are usually called after "d_Subframe" and before "d_ReadImage".

int

d_MoveFrame

(int param)

This function is called by the focus window of Astroart to move the subframe by one pixel. A simple driver could ignore it. "param": 1=UP, 2=DOWN, 3=LEFT, 4=RIGHT.

1

d_BinningCount

()

The driver must return how many binning modes it supports.

1..8

d_BinningName

(int n)

The driver must return a pointer to a string which describes the binning mode. For example: "1 X 1 interlaced". The parameter "n" can vary from 0 to d_BinningCount-1.

char*

d_GetName

()

The driver must return a pointer to a string which describes the driver. Example: "CCD Camera XYZ - Control panel".

char*

d_GetInfo

()

The driver must return a pointer to a string which describes the temperature and/or other info about the status of the camera.
Example: "T = -15°"

char*

d_GetTemperature

()

This function must return the temperature of the CCD in degrees * 1000.

int

d_StartExposure

(int expo, int openshutter)

Starts an exposure. "expo" is the exposure time in milliseconds, "openshutter" can be "1" or "0" to select a dark or light exposure. If the camera is not ready this function must return "0".

0,1

d_IsExposing

()

This function must return "1" if an exposure is in progress, "0" otherwise.

0,1

d_StartDownload

()

This function is called when d_IsExposing goes to "0" after an exposure. It can be ignored by most drivers.

1

d_ReadImage

(unsigned short* pbuffer)

This function must write into the memory pointed by "pbuffer" the image acquired. The size of this image must be the same returned by d_GetWidth and d_GetHeight above. The data must be written as 16 bit unsigned numbers. If the image has colors then this function will be called three times: GREEN plane, RED plane, BLUE plane.

1

d_EndDownload

(unsigned short* pbuffer)

This function is called after d_ReadImage, usually it can be ignored.

1

d_InterruptExposure

()

This function is called to interrupt the current exposure, which in any case will be downloaded.

1

d_IsColor

()

This function must return "1" for a color device and "0" for black and white.

0,1

d_Telescope [Optional]

(int command, int msec)

This function controls the optional relays of your CCD camera, to command a telescope for autoguide. "command" is a constant between 0 and 11 which can be defined by the following C enum:
{te_present, te_name, te_initialize, te_finalize, te_n, te_s, te_e, te_w, te_ne, te_nw, te_se, te_sw}.
"msec" is the time in milliseconds to activate the relay(s). If msec is less than 0 then the function should return immediately leaving the relay active. If msec is zero then the relay should be deactivated immediately.

0,1

d_FilterWheel [Optional]

(int command, int param)

This function controls the optional filter wheel integrated in your CCD camera. "command" is a constant between 0 and 5 which can be defined by the following C enum:
{fw_present,fw_name,fw_initialize,fw_finalize,fw_setpos,fw_getpos}.
"param" is the parameter related to the command. See the demo drivers for more information. This command is supported since the CCD Interface 4.01.

0,1

d_SetTemperature [Optional]

(int milliCelsius, int coolerPerc)

Sets the temperature setpoint of the camera.
The temperature is expressed in celsius x 1000, for example -18500 means -18.5 celsius. It's also possible to set the power of the cooler, in the range 0 - 100. "0" means cooler off.

0,1

d_SetMode [Optional]

(int mode)

Suggests the camera mode (0 if primary, 1 if secondary).
In mode zero the camera will be used as main camera for imaging. In mode one the camera will be used for autoguide or sky watch. A driver may change its behaviour depending the mode.

0,1

History

 2018/07/14 Compatible with Astroart 7; version 1.40
2013/12/28 Added d_SetTemperature and d_CameraMode; version 1.30
2008/01/02 Added d_FilterWheel; version 1.20
2007/04/16 Added d_Telescope; version 1.10
2004/03/03 The first release; version 1.00