EXE Drivers and TheSky™ V6 (only)

PLEASE NOTE: THIS APPLIES ONLY TO TheSky 6 AND NOT TO TheSky X.
Since TheSky 6 is still in use (as of late 2013), you should still probably pay attention to this.

Background

If your driver is a "local server" executable (EXE), and you wish to have it usable from TheSky 6 (for example, via the TeleAPI adapter plugin), you'll have to do provide some registry info to activate it for Microsoft Distributed COM (DCOM). TheSky uses DCOM. As a result, any outgoing COM connections from TheSky are subject to an additional layer of security in the Windows OS. Since an EXE driver is external to TheSky, this means your EXE driver needs to be known to DCOM and it's security level must be set to allow connections.

If you write your LocalServer (EXE) driver in C#.NET or VB.NET, and use the templates included with the Developer Components, this is all handled for you. You need not read any further!

If you use the InnoSetup tools provided with the Developer Components, this is all handled for you. You need not read any further!

Microsoft's theory on DCOM permissions is (was) that an end user would use the DCOM Config tool to set activation and security for component objects. This tool is, to say the least, user-hostile. Thus, in order for your EXE driver to be user-usable from TheSky, you'll have to create the DCOM activation and security info in the registry as part of your driver's installation process. Don't put this into the driver's code, make it a part of the installer for your driver.

Click for full size imageIf you don't already have the free Microsoft OLEView tool (it is included with most Microsoft development platforms, as well as the Platform SDK), get it from the Microsoft Download Center, search for "OLEView". You'll need this to determine the class ID for your driver, and it's essential to validate your registry changes, as well as for inspecting your driver's class structure and type library (definitions of its properties and methods). Browse around with it in the Automation Objects tree, and try to find an EXE based component server with an AppID section. Beware, if you expand the tree below a particular object, the OS will try to activate an instance. If this happens (the node will become bold), right click and select Release Instance. You're inly interested in the stuff that appears in the right pane when you select an object in the left (tree) pane.

This image shows the registry info for the ASCOM Telescope Simulator, an EXE driver. Click on it for a full size image.

Finding the driver CLSID

Make sure your driver is already registered for COM.

The first step is to determine your driver's class ID (CLSID). OleView makes this easy. You know the description of your driver, "ASCOM Telescope Driver for MammaJamma 6000" or whatever. Locate it in the OleView tree under Automation Objects (or .NET Category if you developed it in .NET). Click on the node (don't expand it!) and some info will appear in the right pane. Not everything that appears in the above image will be there (yet).

The main thing to note is at the top, CLSID = and the line underneath with a GUID followed by your driver's descriptive name. That GUID (for example {575A8E82-B2A4-4C95-8CAE-ACF25ED65869}) is your driver's CLSID. While you're at it, verify the ProgID (for example ScopeSim.Telescope) and the executable path (for example, C:\Program Files\Common Files\ASCOM\Telescope\ScopeSim.exe"). Make sure it's really your driver.

Adding AppID info

Click for full size image

The COM registration info for your driver is located in HKCR\CLSID\{CLSID}. This is what the top section in the OleView display shows. Start RegEdit and navigate there. Verify that you see the same subkeys and data items as you see in OleView.

You now need to add a new data value which is the link from the CLSID area to the AppID area that you will create in the next step. Create a new string (REG_SZ) value under CLSID, at the same level as the unnamed (default) value that is your driver's descriptive name. See the diagram to the right, click on it to see the full size image. The name of the string is AppID, and the value is your driver's CLSID.

Click for full size image

Now, in RegEdit, move to HKCR\AppId and create a new key whose name is your driver's CLSID, for example HKCR\APPID\{575A8E82-B2A4-4C95-8CAE-ACF25ED65869}. See the diagram to the right, click it to see the full size image. Next change the (default) value to the descriptive name of your driver. Now create a new string (REG-SZ) value named AppId and make the value your driver's CLSID. Finally, and this is the magic entry, create a new DWORD (REG_DWORD) value AuthenticationLevel and set it to 0x00000001 (1). This is what enables TheSky to make outgoing connections to your driver.

After doing all of this, you should go back to OleView, refresh it if needed, and check to see that the info it shows looks like that in the first image above.

Testing

Make sure your driver is already registered for ASCOM/Chooser.

Now it's time to test outgoing connections from TheSky to your driver. We'll use a Telescope driver used via the ASCOM adapter TeleAPI plugin. Start up TheSky, in Telescope Setup select Telescope API, then click Settings... This should display the ASCOM Telescope Chooser. If needed, click Properties... in the Chooser to configure your driver, close the driver's setup dialog and click OK in the Chooser, then Close in TheSky's Telescope window.

Now for the magic moment. In TheSky, Telescope menu, Link, Establish. If all went well, your Telescope driver should load and start accepting commands from TheSky!