Understanding ASCOM Driver Registration

Tags: ASCOM, astronomy, software-engineering, development

This is a question that comes up occasionally on the ASCOM-Talk group, especially from developers using non-dotNet languages such as Delphi and C++. Assuming you have your driver written and working, to correctly register the driver and have it show up in the ASCOM Chooser, you need two do two things:

  1. Register your driver as a COM component so that it can be loaded based on its COM ProgID
  2. Create your driver’s profile in the ASCOM Profile Store

There exists a multitude of ways to achieve these two requirements, but the details of exactly what needs to be done are somewhat tricky to uncover, so that is where I am focusing my attention in this article.

The registration process is somewhat simplified for .NET developers during development, with Visual Studio automating the COM registration and the driver itself (assuming it is based on one of the standard templates) performing the ASCOM Profile registration as a side effect of COM registration. While this is very convenient, it arguably obscures the underlying process and this is sometimes confusing for new developers because it is not immediately obvious what’s being done on their behalf. The ASCOM automated approach also only works for 32-bit systems, which is fine for development but can be more problematic when the driver is ‘in the wild’.

In deployment, the ASCOM Developer Tools has a setup generator that produces a setup script for Inno Setup, a free open-source setup utility. Most driver developers use this successfully and that may be as far as you need to go when producing your own setup package.

For those curious about what’s actually happening, or who prefer to use tools other than those described, here are the underlying requirements for registration as we have interpreted and implemented them at .

COM Registration

This requires a number of registry keys to be created in standard locations in the registry. You can get an indication of what keys are required by using the Visual Studio Developer Command Line, and entering the following command:

regasm YourdDriver.dll /regfile

This produces a file called YourDriver.reg (registry export format) that contains the required registry keys. It’ll look something like this:

1 REGEDIT4 2 3 [HKEY_CLASSES_ROOT\ASCOM.AWR.Telescope] 4 @="ASCOM.AWR.Telescope" 5 6 [HKEY_CLASSES_ROOT\ASCOM.AWR.Telescope\CLSID] 7 @="{624A7575-D3E9-46FE-A56D-38C8B9823D40}" 8 9 [HKEY_CLASSES_ROOT\CLSID\{624A7575-D3E9-46FE-A56D-38C8B9823D40}] 10 @="ASCOM.AWR.Telescope" 11 12 [HKEY_CLASSES_ROOT\CLSID\{624A7575-D3E9-46FE-A56D-38C8B9823D40}\InprocServer32] 13 @="mscoree.dll" 14 "ThreadingModel"="Both" 15 "Class"="ASCOM.AWR.Telescope" 16 "Assembly"="TiGra.Astronomy.AWRDriveSystem, Version=6.1.0.0, Culture=neutral, PublicKeyToken=null" 17 "RuntimeVersion"="v2.0.50727" 18 19 [HKEY_CLASSES_ROOT\CLSID\{624A7575-D3E9-46FE-A56D-38C8B9823D40}\InprocServer32\6.1.0.0] 20 "Class"="ASCOM.AWR.Telescope" 21 "Assembly"="TiGra.Astronomy.AWRDriveSystem, Version=6.1.0.0, Culture=neutral, PublicKeyToken=null" 22 "RuntimeVersion"="v2.0.50727" 23 24 [HKEY_CLASSES_ROOT\CLSID\{624A7575-D3E9-46FE-A56D-38C8B9823D40}\ProgId] 25 @="ASCOM.AWR.Telescope" 26 27 [HKEY_CLASSES_ROOT\CLSID\{624A7575-D3E9-46FE-A56D-38C8B9823D40}\Implemented Categories\{62C8FE65-4EBB-45E7-B440-6E39B2CDBF29}] 28

IMPORTANT: Do not copy this file verbatim and do not double-click it. This is a real example from a working driver and you need to change most of the values to suit your own driver. We will discuss the meaning of these values now.

In line 3, the driver’s ProgID is being created. In this example, the ProgID is ASCOM.AWR.Telescope, and the default value for the key is identical to the key name. This is how ASCOM (and client applications) find your driver. The client application typically obtains the driver’s ProgID from the ASCOM Chooser and can then either load the driver directly, or use one of the helper classes in ASCOM.DriverAccess to load it indirectly.

On line 6, a CLSID subkey is created with a default value that is a GUID (globally unique identifier). This GUID is the ClsID (Class ID) of your driver and tells COM where to find the rest of your driver’s details. If you are writing a driver in .NET, then these two values come from your code, in attributes that decorate your driver’s class. As a minimum, you will probably have something like similar to this:

1 namespace ASCOM.AWR 2 // ReSharper restore CheckNamespace 3 { 4 /// <summary> 5 /// ASCOM Telescope V3 driver for AWR Drive System. 6 /// </summary> 7 [ProgId(CDeviceId)] 8 [Guid("624A7575-D3E9-46fe-A56D-38C8B9823D40")] 9 [ComVisible(true)] 10 [ClassInterface(ClassInterfaceType.None)] 11 public class Telescope : ITelescopeV3 12 { 13 /// <summary> 14 /// The ASCOM DeviceID and COM ProgID of this driver. 15 /// </summary> 16 internal const string CDeviceId = "ASCOM.AWR.Telescope"; 17 18 // etc... 19 }

In the registry, the ProgID entry will appear like this:

image

The remainder of the driver’s COM registration, the segment from line 9 or the .reg file to the end of the file, must exist in up to two locations, as follows:

HKEY_CLASSES_ROOT\CLSID\{your-driver’s-guid} On 32-bit and 64-bit systems
HKEY_CLASSES_ROOT\Wow6432Node\CLSID\{your-driver’s-guid} On 64-bit systems only

 

IMPORTANT: On 64-bit systems, the entire ClsID block must be created twice, in the locations shown above, with each being an exact copy of the other. That is, the part of the .reg file beginning on line 9 to the end of the file must be created in the registry twice.

That takes care of the COM registration. If you have done this correctly, then you should be able to open up Windows PowerShell, and load your driver as a COM object by entering the following commands:

image

Obviously, replace ASCOM.AWR.Telescope with your own driver’s COM ProgID. If this works, then your COM registration is probably correct.

ASCOM Profile Registration

In order for your driver to show up in the ASCOM Chooser you must create a Device Profile for your driver. For .NET developers, that is simply done by code similar to the following:

1 using (var profile = new ASCOM.Utilities.Profile()) 2 { 3 profile.DeviceType = "Telescope"; 4 if (!profile.IsRegistered("ASCOM.AWR.Telescope")) 5 { 6 profile.Register("ASCOM.AWR.Telescope", "AWR Microstep Drive System"); 7 } 8 }

 

If you are not using .NET, then you have to work a bit harder. You will either have to make an installer and call the .NET components from that, or you could do it with a PowerShell script, like this:

1 $driverId = "ASCOM.AWR.Telescope" 2 $driverDescription = "AWR Microstep Drive System" 3 $profile = New-Object ASCOM.Utilities.Profile 4 $profile.DeviceType = "Telescope" 5 if (-Not $profile.IsRegistered($driverId)) 6 { 7 $profile.Register($driverId, $driverDescription) 8 } 9

Once again, we have used real world sample data, you will have to adapt this for your own driver’s details.

Putting It All Together

This PowerShell script will show the ASCOM Chooser where you should see your driver and be able to choose it. Then it will load the driver as a COM object, based on the ProgID (sometimes also called the Driver ID) that was returned by the Chooser. We just write out the driver name to prove that the object is alive, but you could set the Connected property or do anything you like at this point.

1 [System.Reflection.Assembly]::LoadWithPartialName('ASCOM.DriverAccess') 2 $driverId = [ASCOM.DriverAccess.Telescope]::Choose("") 3 $driver = New-Object -ComObject $driverId 4 Write-Host "Successfully loaded driver:" $driver.Name

Deployment

As already mentioned, the ASCOM Developer Tools package includes a tool for generating Inno Setup scripts; most driver developers find that adequate. Here at Tigra Astronomy, we prefer to do all of our setup using WiX (Windows Installer XML) which is Microsoft’s free, open-source installer toolset. It has a nice Visual Studio integration and uses a declarative approach based on XML files. We are not necessarily advocating this approach over the tools supplied with the ASCOM Platform, but if you are already using WiX or for some reason don’t want to use the Inno tools, then we have developed a NuGet package that will help you get going with WiX. A detailed explanation is beyond the scope of this article, please contact us directly if you would like assistance or further information or refer to the project home page.

No Comments

Add a Comment

Let Us Help You

Find us on Facebook