-
Notifications
You must be signed in to change notification settings - Fork 0
LWgreys/PJMO
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252" />
<TITLE>ASCOM Local Server Read-Me</TITLE>
<META NAME="GENERATOR" CONTENT="OpenOffice.org 3.2 (Win32)" />
<META NAME="CREATED" CONTENT="0;0" />
<META NAME="CHANGEDBY" CONTENT="Chris Rowland" />
<META NAME="CHANGED" CONTENT="20110422;10442800" />
<META NAME="CHANGEDBY" CONTENT="Chris Rowland" />
<STYLE TYPE="text/css">
<!--
@page {
margin: 2cm
}
ol, ul, p {
font-family: "Verdana", "Arial", "Helvetica", sans-serif;
font-weight: normal
}
TD P {
font-family: "Verdana", "Arial", "Helvetica", sans-serif;
font-weight: normal
}
H3 {
font-family: "Arial", "Helvetica", sans-serif
}
H2 {
font-family: "Arial", "Helvetica", sans-serif
}
H4 {
font-family: "Arial", "Helvetica", sans-serif
}
span.code {
color: #ff0000;
font-family: monospace;
font-size: large
}
PRE {
margin-left: 0.18cm;
margin-right: 0.18cm;
margin-top: 0.18cm;
margin-bottom: 0.18cm;
background: #ccffff
}
PRE.western {
font-weight: normal
}
PRE.cjk {
font-family: "NSimSun", monospace;
font-weight: normal
}
PRE.ctl {
font-weight: normal
}
EM.underline {
text-decoration: underline
}
-->
</STYLE>
</HEAD>
<BODY LANG="en-GB" DIR="LTR">
<H2>
ASCOM LocalServer Driver
</H2>
<H4>You have just created an ASCOM Local Server driver.</H4>
<P>
This project creates an ASCOM local server executable and a driver class that will support multiple clients. It can also be extended to serve multiple ASCOM devices such
as a Telescope and a Focuser or multiple devices of the same type such as two focusers.
</P>
<P STYLE="margin-left: 0.42cm; margin-right: 0.42cm; border: 1px solid #000000; padding: 0.21cm">
<STRONG>
<SPAN STYLE="background: #ffee88">NOTE:</SPAN>
</STRONG>
<SPAN STYLE="background: #ffee88">
Modern astronomical observatories often use multiple clients concurrently such as planetariums, session managers and device managers and typically these clients expect drivers to handle
concurrent access to ASCOM interface properties and methods. To be successful, your driver will therefore need to operate asynchronously e.g. by being able to respond to device
position properties while the device is moving.
<BR /><BR />
Device implementation complexity is closely related to ASCOM device interface complexity. In broadly increasing order of complexity the ASCOM interfaces are:
SafetyMonitor, ObservingConditions, FilterWheel, CoverCalibrator, Focuser, Rotator, Switch, Camera, Dome, Video and Telescope.
<BR /><BR />
In addition to responding to asynchronous client requests, you will need to reliably serialise communications with your hardware if it does not intrinsically
support concurrent operation. This means that you will need to be familiar with asynchronous programming techniques or be prepared to navigate a steep learning curve.
</SPAN>
</P>
<P>
You're probably anxious to get going, but if you are new to this it will help to read through the short <A HREF="#theory">Theory of Operation</A> and <A HREF="#disposal">Disposing of Resources</A> sections below.
</P>
<h3>Driver Architecture</h3>
<p>
The Telescope driver created by the local server project template comprises these main layers:
<ol>
<li style="margin-bottom:10px">
<b>TelescopeDriver\TelescopeDriver.cs</b> - An ASCOM COM driver that is served to clients by the local server. An instance of this class will be created every time
a client creates an instance of your Telescope driver. This class is mainly a presentation layer for the shared functionality that is contained in the Telescope\TelescopeHardware class
and should require little customisation.
</li>
<li style="margin-bottom:10px">
<b>TelescopeDriver\TelescopeHardware.cs</b> - An internal static class that is shared by all instances of your TelescopeDriver class. This is where you should locate capabilities that
will be shared by all instances of your Telescope driver. This static class will contain
most of the heavy lifting to map the ASCOM interface functions to the specific communications protocol and behavioural requirements of your Telescope hardware.
The main functionality is implemented in this shared class so that you have the opportunity to manage concurrent requests from multiple instances of your Telescope driver created
by one or more ASCOM client applications.
Ordinarily, the capabilities in this file would not be shared with other drivers that you may add to the local server at a later date.
</li>
<li style="margin-bottom:10px">
<b>SharedResources.cs</b> - This is where you should place resources that will be shared between the different drivers served by the local server. Typically communications functionality that is shared across multiple drivers
will go here. In the generated project, some basic serial port functionality is located here.
</li>
<li style="margin-bottom:10px">
<b>Local server operation support files</b> - The remaining files in the generated project support local server operation and do not need to be customised further.
Please do not change these files unless you are completely sure you know what you are doing!
</li>
</ol>
</p>
<h3>To complete your local server driver, please follow these steps in order:</h3>
<OL>
<LI style="margin-bottom:20px">
Review the local server's project properties:
<UL>
<LI>Review the Application tab and change the AssemblyName and default namespace if required, the recommended format is ASCOM.xxx.</LI>
<LI>Click the Assembly Information button and review and update the text if required.</LI>
<LI>Do not check the "Make assembly COM visible" checkbox; the local server will register the COM drivers dynamically at run-time, and checking this box interferes with the dynamic registration process.</LI>
<LI>
Change the assembly version number if required but do not use wild-card (*) numbering because it causes issues with COM registration.
It is not recommended that the assembly version number is changed on each release, use the file version number to identify different releases.
</LI>
<LI>Change the assembly file version if required, this can use wild-card numbering.</LI>
<LI>
Do not change the Platform Target on the Build tab from x86, this must remain as set for correct local server operation. The local server runs as a fully independent process rather than as a thread
within the client application and behind the scenes COM automatically translates between both 32bit and 64bit client processes and the 32bit local server process.
<br />
</LI>
</UL>
</LI>
<LI style="margin-bottom:20px">
Check and test the driver created from the template
<ul>
<li>Review the ProgID and ServedClassName fields above the Class name for suitability.</li>
<li>Compile the whole solution but don't run it.</li>
<li>Open a command prompt at the folder where the local server executable is located.</li>
<li>
Run the local server exe with the /regserver parameter (requires admin privilege), which will create the entry that appears in the ASCOM Chooser. This registration only needs to be done once on each PC.
Use the /unregserver parameter to unregister the server when no longer required. Never use REGASM on the local server executable, this way lies confusion and much time wasting!
</li>
<li>Close the command prompt</li>
<li>
Start an ASCOM client application or Conform or a Connection form in the Diagnostics tool and use the client to open a Chooser for the device type of your driver.
You will see your driver in the list, will be able to select it and open its Setup dialogue.
</li>
<li>
To support debugging, the driver will create three log files in a Documents\ASCOM\Logs yyyy-mm-dd folder.
<ol>
<li><b>ASCOM.PJMO.Driver.xxx</b> - One log per instance of the COM driver class. (Can be enabled / disabled through the Driver setup dialogue.)</li>
<li><b>ASCOM.PJMO.Hardware.xxx</b> - One log from the shared hardware class containing information from all instances of the COM driver. (Can be enabled / disabled through the Driver setup dialogue.)</li>
<li>
<b>ASCOM.PJMO.LocalServer.xxx</b> - One log for the local server executable itself. (After the driver is running stably, this log can be disabled if required
by editing the TL.Enabled statement near the top of the LocalServer.cs file.)
</li>
</ol>
</li>
<li>
At this point the basics are proved and its time to start making the driver do something! If you have issues in getting to this point, check the
logs in your Documents\ASCOM folder, which will help determine what has gone wrong. You are welcome to post at the ASCOM Developer forum listed below if you get stuck.
</li>
</ul>
</LI>
<LI style="margin-bottom:20px">
Implement the driver methods
<ul>
<li>The first implementation task is to fully implement the Connected property to establish communications to your device hardware.</li>
<li>
After this, it's a good idea to implement a straightforward property before moving on to more complex properties and finally to methods. This approach will
enable you to focus on the essential driver / application infrastructure initially before having to deal with more complex device functions.
</li>
</ul>
</LI>
</OL>
<h3>How to add further drivers if required</h3>
<p>
This method works when:
</p>
<ul>
<li>Adding a completely new served device type e.g. adding a FOCUSER device to a local server already hosting a TELESCOPE device.</li>
<li>Adding a second or further instance of an existing served device type e.g. adding a second FOCUSER to a local server already hosting a FOCUSER device.</li>
</ul>
<h4>Method</h4>
<ol>
<li>
Add a new "Local Server" project to the solution ensuring that:
<ul>
<li>It is configured as the device type that you require.</li>
<li>It's ASCOM DeviceId is different to all other drivers in the local server.</li>
<li>You rename the driver folder in the new project if it matches one already present in original project.</li>
</ul>
</li>
<li>
Within Visual Studio drag and drop the driver folder from the new project to the root of the original project.
</li>
<li>
Delete the new local server project added in step 1.
</li>
<li>Compile the project</li>
<li>Register the driver as described above with /regserver.</li>
<li>Verify that the driver is visible in an application Chooser dialogue.</li>
<li>Implement the new driver's methods.</li>
</ol>
<H3>Notes</H3>
<UL>
<LI>
<P STYLE="margin-bottom: 0cm">
if required, a serial port is already provided (see SharedResources.cs) as <FONT FACE="Lucida Console, Courier New, Courier, monospace">SharedResources.SharedSerial</FONT>.
If you don't need the serial port you can remove the public static SharedSerial property, the m_SharedSerial member in the private data region, and the line in main that initializes it.
</P>
</LI>
<LI>
<P>
You may want to add controls and/or status information to the main form frmMain of the local server. Please resist the temptation to turn the local server's main form into a graphical device control
panel. A better approach is to create a separate application that connects to the served driver(s).
</P>
</LI>
</UL>
<H3>
<A NAME="theory"></A>Theory of Operation
</H3>
<P>
The local server is an executable that can provide multiple instances of multiple drivers to multiple clients, and which supports two core capabilities:
</P>
<UL>
<LI>
<P STYLE="margin-bottom: 0cm">
Being a hub, which allows multiple clients to share a single device
</P>
</LI>
<LI>
<P>
Supporting hardware that contains multiple devices such as a telescope that has a built-in focuser, where both the telescope and focuser are controlled by the same connection.
</P>
</LI>
</UL>
<P>
A driver is an assembly which contains a class that <EM>implements</EM> one of the ASCOM standard driver interfaces and <EM>inherits</EM> the ReferenceCountedObjectBase class of the local server.
</P>
<P>
The fact that driver classes inherit from the local server's ReferenceCountedObjectBase class allows the local server to maintain a reference count on the driver class. If a client creates an
instance of a served driver, the local server automatically starts up and provides an instance of the class to the client. Once started the local server can provide additional instances of any of its served
driver classes. If the reference count of all served classes drops to zero as a result of clients releasing their instances, the local server will automatically exit.
</P>
<P>
The local server's registration services include not only basic COM class registration, but also the DCOM/AppID info needed to use the served classes from outbound connections from Software Bisque's TheSky. It
also registers the served classes for the ASCOM Chooser. The "friendly" name of each served driver that appears in the chooser comes from the driver's ServedClassName attribute.
The COM ProgID for each served driver is specified in the ProgId attribute for example, ASCOM.AlphaTech.Telescope, where AlphaTech is the local server name and Telescope is the ASCOM type of the driver.
</P>
<H3>
<A NAME="disposal"></A>Disposing of Resources
</H3>
<P>
If you create objects that consume significant memory or that use finite operating system resources such as file handles, synchronisation objects etc. you will want to release these back to the operating system
as soon as you know that clients have finished with them. This is where the Dispose methods on your driver, hardware class and the shared resources class come in.
</P>
<p>
The TelescopeDriver class is instanciable and supports the IDisposable pattern. This means that clients can inform your class that it is no longer needed, so that it can release its resources. It doesn't
matter if clients don't call the Dispose() method because the IDisposable interface implemented in the driver ensures that the runtime's garbage collector will call the driver instance's
Dispose() method and your resources will then be released.
</p>
<p>
Both the static TelescopeHardware and SharedResources classes are decorated with the <span class="code">[HardwareClass()]</span> attribute, which the local server will detect when it is about to close down.
The local server will then automatically call the Dispose() methods on these classes without requiring any action on your part.
</p>
<p>
If you create further static classes that need to be
disposed when the local server shuts down, just add a hardware class attribute line (<span class="code">[HardwareClass()]</span>)
immediately above your class definition line (<span class="code">internal static class YOURCLASSNAME</span>) and add a public Dispose() method to your class.
</p>
<p>
Please do not call the static class Dispose() methods from the TelescopeDriver.Dispose() method. The static class lifetimes are linked to the lifetime of the local server application and should be Disposed
only when it is clear that the local server is irretrievably closing down, as already implemented in the automatic disposal mechanism built into the local server.
</p>
<H3>ASCOM Initiative</H3>
<P>
The ASCOM Initiative consists of a group of astronomy software developers and instrument vendors whose goals are to promote the driver/client model and scripting automation.
</P>
<P>
See the <A HREF="https://ascom-standards.org/" TARGET="browser">ASCOM web site</A> for more information.
If you have questions, please post here: <A HREF="https://ascomtalk.groups.io/g/Developer/topics" TARGET="browser">ASCOM-Talk Developer Forum</A>.
</P>
</BODY>
</HTML>About
No description, website, or topics provided.
Resources
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published