THE ALPHA NIR SDK ----------------- INTRODUCTION The purpose of the Alpha NIR SDK is to provide assistance to Visual Basic programmers and Visual C++ programmers who wish to control the Indigo Systems Alpha NIR camera by using the serial port packet protocol described in the Alpha NIR ICD (Interface Control Document). Support for VB and VC++ programmers (and others) is provided in the form of a single control, written in Visual Basic, which exposes the parameters and functions of the Alpha NIR camera as properties and methods, respectively, of the control. The control is built in two ways: as a private control in the subdirectory 'AllSrcDemo', and as an ActiveX control in the subdirectory 'Ocx'. Here's a little background on the terms. A "private control", in this context, is Visual Basic source code which can be used by Visual Basic programmers only. An "ActiveX control", often referred to as an "OCX" because of its file extension, is a Windows DLL with a lot of special internal structure that the Microsoft software development tools understand. The 'AlphaNIR' control itself is written in Visual Basic, but the compiled and linked .ocx file is equally useful to Visual C++ programmers, and even to programmers using other Windows-based development environments not discussed in this document, e.g., LabView. ROADMAP The Alpha NIR SDK consists of this documentation file and the contents of four subdirectories: 'AllSrcDemo', 'Ocx', 'VBDemo', and 'VCDemo'. 1. AllSrcDemo. This subdirectory contains a Visual Basic project, 'AllSrcDemo.vbp', containing complete Visual Basic source code for the 'AlphaNIR' private control, as well as a Visual Basic demo program that exercises the control. To open the project, make sure that Visual Basic 6.0 is installed, then double-click the project file 'AllSrcDemo.vbp'. If your only interest is in creating Visual Basic programs which talk to the AlphaNIR, and you want the source code for the 'AlphaNIR' control to be part of your project, then you can safely ignore the contents of the other 3 subdirectories. 2. Ocx. This subdirectory contains the file 'AlphaNIRLib.ocx, which is the result of building the 'AlphaNIR' control as an ActiveX control. 3. VBDemo. This subdirectory contains a Visual Basic project, 'VBDemo.vbp', for building 'VBDemo.exe', a Visual Basic program which exercises the 'AlphaNIR' ActiveX control. (It's the same demo program as the one in the 'AllSrcDemo' subdirectory.) To open the project, make sure that Visual Basic 6.0 is installed, then double-click the project file 'VBDemo.vbp'. If you intend to use the 'AlphaNIR' control as an ActiveX control in your Visual Basic project, then this is the place for you. 4. VCDemo. This subdirectory contains a Visual C++/MFC project, 'VCDemo.dsw', for building 'VCDemo.exe', a Visual C++ program which uses the 'AlphaNIR' ActiveX control. To open the project, make sure that Visual C++ 6.0 is installed, then double-click the workspace file 'VCDemo.dsw'. Since the 'AlphaNIR' control is written in Visual Basic, Visual C++ programmers can't use it in source code form, so the only option is to use it as an ActiveX control. STEP-BY-STEP VISUAL BASIC TUTORIAL None of the source code described above is necessary to create a Visual Basic program (or a Visual C++ program) which controls the camera. All that is needed is Visual Basic itself (or Visual C++ or LabView or ?), and the OCX. The shortest Visual Basic program which does something useful with this SDK is 1 line of code: If AlphaNIR1.OpenComm(1) Then Text1 = AlphaNIR1.CaseTemp This program assumes that 'Form1' contains an instance 'AlphaNIR1' of the 'AlphaNIR' control and an instance 'Text1' of the 'TextBox' control. (See below.) It attempts to communicate with an Alpha NIR camera on Com1. If it succeeds in doing so, it then uses the Alpha NIR packet protocol to retrieve the current case temperature from the camera and it uses the TextBox control to display the result. Here are step-by-step instructions for creating this program using the OCX and Visual Basic 6.0: 1. Register the OCX, 'AlphaNIRLib.ocx', by copying it from the 'Ocx' subdirectory to your Windows System directory (in Windows NT, this is usually 'c:\winnt\system32') or the directory of your choice. Then go to a command prompt, log into the directory where you copied the OCX, and type the command regsvr32 AlphaNIRLib.ocx 2. Run Visual Basic. When the first screen comes up, elect to create a "Standard EXE". 3. Go to the "Project" menu, select "Components...", click the checkbox next to the 'AlphaNIR' control (look under "I" for "Indigo"), then click OK. Observe that the 'AlphaNIR' control has been added to your Visual Basic toolbox. Note: The Microsoft MSComm control, 'MSComm32.ocx', is usually installed with Visual Basic or Visual C++, and is required by the 'AlphaNIR' control, so make sure it's in the list of components too. (Look under "M" for "Microsoft".) If it's not there, then find it, and install and register it as you did the 'AlphaNIR' control itself. (You need not arrange for it to appear in the toolbox, though.) 4. Use the VB toolbox to put a 'TextBox' control and an 'AlphaNIR' control on 'Form1'. (They will receive default names of 'Text1' and 'AlphaNIR1', respectively.) 5. Double-click on 'Form1', if necessary, to bring up the code window for the form, and add the 1 line of source code above to the 'Form_Load' procedure. 6. Make sure you have a living Alpha NIR camera properly attached to Com1. 7. Run the program and behold the case temperature. THE DETAILS Note that use of the packet protocol to communicate with the camera is completely hidden inside the assignment statement and need never be seen by a programmer who only wants to access camera parameters. Any of the other camera parameters which can be read from the camera can be read in exactly the same way. Here is the complete list: Variable name Type ------------- ---- TECIsDisabled Boolean FPAIsDisabled Boolean PartNumber Long SerialNumber Long Version Long InstalledOptions Long FPAMode Long FPASkimmingEnable Boolean IntegrationCapacitor IntCapConstants: camCapLo camCapHi IntegrationMode IntModeConstants: camIntModeNormal camIntModeShort InvertEnable Boolean RevertEnable Boolean FPATemp Long CaseTemp Long Vdetcom Long LongIntMode LongIntModeConstants: camLongIntModeFPA camLongIntModeExtended camLongIntModeManual NormalIntTime Long ExtendedIntTime Long ShortIntTime Long Note that some of these parameters are stored in the bits of a single 2-byte parameter in the camera (referred to as FPA_MODE in the ICD, and returned in its entirety in the variable 'FPAMode'). The extraction of these parameters from FPA_MODE is also hidden from view inside the assignment statements. Modifying camera parameters which allow write access is equally easy. Again, use of the packet protocol is completely hidden inside an assignment statement, this time with the camera parameter on the left hand side of the equals sign. For example, AlphaNIR1.NormalIntTime = 10000 causes the value 10000 to be written into the camera's Normal Integration Timer. Here is the complete list of parameters that this SDK can write to the camera: Variable name Type ------------- ---- InitializationByte Long FPAMode Long FPASkimmingEnable Boolean IntegrationCapacitor IntCapConstants: camCapLo camCapHi IntegrationMode IntModeConstants: camIntModeNormal camIntModeShort InvertEnable Boolean RevertEnable Boolean Vdetcom Long LongIntMode LongIntModeConstants: camLongIntModeFPA camLongIntModeExtended camLongIntModeManual NormalIntTime Long ExtendedIntTime Long ShortIntTime Long TestOutput TextOutputConstants: camTestOutputNormal camTestOutputRamp1 camTestOutputRamp2 ExtSyncEnable Boolean Again, some of these parameters are stored in the bits of FPA_MODE, and, according to the ICD, a read-modify-write sequence is required to change the value of one of the parameters without affecting the others. This, too, is hidden in the assignment statement. The user of the SDK need not even be aware that it is happening. In addition to read and/or write access to camera parameters, the OCX also provides equally simple access to the following commands: OpenComm CloseComm Reset StartManualIntegration StopManualIntegration For example, here is a program which resets the camera attached to Com2, sets manual integration mode, then starts and stops integration as fast as the packet protocol will allow. (The theoretical minimum time is the time it takes to transmit 18 bytes at 57600 baud.) Private Sub Form_Load() If AlphaNIR1.OpenComm(2) Then AlphaNIR1.Reset AlphaNIR1.LongIntMode = camLongIntModeManual AlphaNIR1.IntegrationMode = camIntModeNormal AlphaNIR1.StartManualIntegration AlphaNIR1.StopManualIntegration AlphaNIR1.CloseComm End If End Sub THE TOOL KNOWS If you actually typed the code above into Visual Basic, then you probably noticed that Visual Basic knows the names of all the 'AlphaNIR' properties and methods, and it knows the special variable types and possible values used by the 'AlphaNIR' control. As you type the code, you are presented with lists of such items to pick from when Visual Basic sees that it might be helpful to you to do so. This can be enormously useful when dealing with a lengthy list of fully descriptive names which would otherwise have to be memorized or looked up by some independent means, and even then, would be misspelled from time to time. ERROR HANDLING The function 'AlphaNIR.OpenComm' opens the serial port, sets the port's communication parameters, sends a packet to the camera, and waits the required time for the required response. If anything at all goes wrong, then 'OpenComm' will report failure. Therefore, once 'OpenComm' reports success, it is highly likely that subsequent uses of the 'AlphaNIR' object will also be successful. Of course, it's always possible that the serial cable could become loose or dislodged or the power to the camera could be cut. If something like that happens, then attempts to write a value to the camera or to execute a camera command will silently fail. And attempts to read a value from the camera will return with all bits set to 1, which is usually a nonsense value. For example, the integrity of the connection to the camera can be tested at any time by just reading, say, the serial number. The connection is working if and only if the value is not -1 (all bits set). Here it is in Visual Basic code: If AlphaNIR1.SerialNumber = -1 Then ' Something is amiss. Else ' All is well. End If If the camera connection is working well and the camera is responding as expected, an attempt to write a value to the camera can still fail to modify the camera's stored value if the new value is not in the range of values permitted by the camera. When this happens, the 'AlphaNIR' object takes the view that it's really a success, not a failure, because, after all, the packet protocol worked perfectly and the camera is definitely holding up its end. The only indication that the data value was not written can be had by reading the value back (if permitted). The following Visual Basic code illustrates the point: AlphaNIR1.NormalIntTime = 50000 If AlphaNIR1.NormalIntTime = 50000 Then ' The timer was set. Else ' The timer was not set. End If USING THE SDK IN VISUAL C++ The 'AlphaNIR' ActiveX control, like any ActiveX control, can be used in a Visual C++ program, too. The procedure is completely standard, and is demonstrated in the 'VCDemo' subdirectory. Start by adding the control to your project. (The Visual C++ 6.0 commands go like this: "Project" menu, pick "Add To Project", "Components and Controls...", etc.). When you add the control to your project, Visual C++ creates a wrapper class for the control, greatly simplifying its use. As simple as it is, though, using the wrapper class in a Visual C++ program can't touch the blinding simplicity of the Visual Basic you-name-it-you-got-it syntax.