POTH Information

POTH started out to be just a Plain Old Telescope Hub. Along the way, it took on some additional features. An ASCOM Hub is a program that connects to a driver and allows multiple programs to connect to itself. Additional features for POTH include:

• dome control. ASCOM dome architecture allows middleware (like POTH) to behave as a telescope even though a dome is being transparently managed as well. POTH will optionally do this as needed. If dome “slaving” is not required, POTH is still a dome hub for concentrating access for multiple packages needing such.
• focuser control. POTH is a focuser control HUB as well.
• flexible user interface. POTH allows basic manual control and monitoring of state. The control “Handset” window is configurable to show only the devices that are being used.
• conversion of V1 drivers into V2 drivers. Many useful Telescope V2 features are now available to V1 driver users such as: SideOfPier, AtPark, and the Alt / Az motion commands. All required features of V2 are handled, although a few of the optional V2 features can not be simulated - see Telescope API notes below.
• simulation of features not in connected driver. Many optional features in V1 and V2 can be simulated by POTH to provide more robust driver support. Often this support is via settings in the setup dialog (optics as an example). Sometimes, features can be built out of existing commands (Alt / Az support is the best example). 
• quiet mode. Many applications polling a hub / driver can create a lot of Hardware I/O. Quiet mode allows POTH to use cached knowledge of the current state, thus drastically reducing I/O requirements. This is most useful when using CCD cameras elsewhere in the system that are sensitive to I/O blocking. Quiet mode is only for the telescope connection at this time. However, the dome and focuser get far less polling traffic.
• debug features. journaling, logging to a file, and capabilities monitoring for all ASCOM entry points.

Quick Links:

• Simple usage
• Setup dialog
• Using the handset controls
  • Telescope handset
  • Dome handset
  • Focuser handset
• Notes for GEM users
• Logging
• API notes
  • Telescope API notes
  • Dome API notes
  • Focuser API notes

Simple Usage

The POTH main window is called the “Handset” window. 1st time usage will require bringing up the setup dialog. Press [Setup].
 
The POTH setup dialog is used to select the drivers that POTH will control. By default, the telescope chooser is the only one visible. To use a dome or focuser, press the [Dome>>] and/or [Focus>>] buttons. The dome and focus areas will be revealed. The [Setup] buttons near each chooser will bring up the setup dialogs for the selected driver. The [Connect] buttons on the setup dialog are mostly for advanced usages. For simple usage, just use the relevant choosers, then press [OK] to dismiss this dialog and return to the Handset.
 
POTH can now be connected to via any other ASCOM clients, and will be fully functional. Or, you can use the [Connect] buttons on the Handset. This is useful for getting the devices up and running, unparked if desired, dome syncing started, or other such before other software is fired up.

Setup Dialog

The basic area of this dialog is used to specify the devices to be used. It also gives access to some POTH behavior:

• The motion controls checkbox adds controls to the Handset window.
• The Auto Track checkbox provides for V1 type behavior on connect. V1 drivers unparked and tracking is turned on automatically as part of connect.
• Hour Angle checkbox toggles the Handbox display from its default Right Ascension display, to and from an hour angle display. Also, at any time the RA/HA display line of the Handbox window can be clicked as a fast access toggle.

The advanced area is accessed by pressing the [Advanced >>] button. This area can be used to provide information to higher level software that the drivers are not supplying. This can happen when a driver is a simple implementation, or when an older version 1 telescope driver is being used.

The Capabilities area within the Advanced area is output only. It indicates the capabilities of the connected devices. The check boxes are used only to indicate capabilities of the Scope, Dome and Focuser. Checking or un-checking them has no influence on POTH behaviour.

Using the “Handset” Controls

Indicator LED's

An red "LED" in upper left of the main window is illuminated if a problem has been detected. This LED will not be reset until POTH is reloaded. If this happens often, then the Traffic window should be used to diagnose the root cause of the problem.

Telescope Handset

• Quiet Mode – toggles caching of state for the telescope driver so that intense pooling from some high level SW does not swamp the telescope.
• Track – toggles telescope tracking state.
• Park / Unpark – park and unpark the telescope.  When the scope is parked a green LED will be placed next to the park / unpark button.
• Flip – cause an immediate pier / meridian flip (only visible for connected GEM scopes)

Dome Handset

• Goto and Sync – the nearby text field can be used to enter an azimuth, then either of these buttons can be used to trigger the desired action.
• Slave Dome – toggles dome slaving calculations as per the entries in the advanced area of the setup dialog, and slews the dome as necessary.
• Open/Close Dome – triggers the shutter to open or close.
• Park – park the dome.

Focuser Handset

• Abs / Rel Move button – the nearby text field can be used to enter a position change, then this button can be used to trigger the desired action. If the focuser is relative, then the value will be added or subtracted (if negative). This field is in steps by default. However, if the setup dialog advanced area for focusers has had the “Manual moves are in microns” checkbox clicked, then this field will be interpreted as microns.
• Abs Move checkbox – for absolute focusers, this toggle changes the behavior of the [Move] button. In absolute mode the value entered will be an absolute position, otherwise it’s a relative motion request. Relative focusers are always relative.
• Temp Comp – toggles the drivers notion of temperature compensation. POTH does not at this time perform its own temperature compensation. If the focuser driver does not support temperature compensation, then this checkbox will be disabled.
• Zero – for relative focusers, this control will reset the current position, defining it to be “zero”. No focuser commands are generated. This is just for simplifying the usage of such focusers.
• In / Out – (Only visible when motion controls are enabled). Move the focuser incrementally the amount of the last incremental request. The incremental value is taken from the field above. If the field is in Absolute mode, then the last incremental value will be used. The sign of the number is ignored. The [In] and [Out] designation overrides.

Notes for GEM users

Current pier side is designated by a green LED effect near the [E] or [W] motion control buttons. This will show up only when GEM mount is connected, and motion controls are enabled.

Geometry parameters for GEMs located in domes are defined at the following link: http://www.astro.ufl.edu/~oliver/DomeSync/.  However be careful of the signs. The signs should be positive for East, North, and Up offsets as described in the POTH Setup Dialog.

Pier side status is best managed via telescope drivers that report that status. However if a given driver can not do so, then POTH endeavors to keep track itself. It is very important that POTH's notion of when the mount will flip is the same as the mount's notion. To this end, the POTH setup dialog has GEM Flip Delay fields. For example: if the mount is set to delay a West to East side flip to 1 hr past the meridian then GEM Flip Delay West should also be set to 1. East works the same way. If the scope is on the East side, and pier flip is needs to occur early by 30 min, GEM Flip Delay East should be set to -0.5. Automatic pier flip is never triggered by POTH. These fields are to model when the scope flips by virtue of the GOTO’s that are sent to the driver and mount. Also these fields are only used when the driver does not support the pier side tracking.

When a driver does not support the pier side behaviors, and POTH is using Flip Delays, it may be that the scope is manipulated manually to be on the “other” side of the pier from POTH’s notion. In this case Alt-LeftMouseButton on either [E] or [W] motion controls will cause POTH to change its notion of pier side.

If East and West pier side delays overlap (e.g. they are both set to 1), and the scope is in this overlap zone at connect time, then POTH can not make a good guess as to pier side. In this case both pier side LEDs will light up yellow. Alt-Click on the correct side motion control ([E] or [W]) will sync POTH with the real mount state. From then on POTH will stay in sync.

Logging

The traffic window can provide diagnostic output. It will show incoming ASCOM requests from higher level SW.  A log file is created in the directory which POTH.exe resides. By default this is “C:\Program Files\Common Files\ASCOM\Telescope”. the log file is named “POTH.log”. Each time POTH is run, it will copy POTH.log to POTH.bak and start a new POTH.log. Commands available from the Traffic window are:

• checkboxes – toggle interest in different types of commands.
• Disable / Enable – toggle the logging function. Commands will still be processed through to the drivers.
• Clear – clear the window and start the log file over from the beginning. This will not copy into POTH.bak.

Telescope API Notes

Whatever the connected driver supports is passed though of course. For partial implementations many of the API's are supported directly from POTH.

Required V2 features that are simulated for V1 and partial V2 drivers:

• AtHome - supported via command stream monitoring
• AtPark - supported via command stream monitoring
• CanMoveAxis - returns false
• CanSetDeclinationRate - returns false
• CanSetGuideRates - returns false
• CanSetRightAscensionRate - returns false
• CanSlewAltAz - often returns true (if other commands can simulate)
• CanSlewAltAzAsync - often returns true (if other commands can simulate)
• CanSyncAltAz - often returns true (if CanSync is true)
• DoesRefraction - supported via setup dialog
• EquatorialSystem - supported via setup dialog
• InterfaceVersion - returns 2
• AxisRates - returns empty collection

Optional V2 features that are simulated:

• ApertureArea - supported via setup dialog
• SideOfPier - supported via command stream monitoring and setup dialog limits
• DestinationSideOfPier - supported via setup dialog limits
• SlewToAltAz - supported via coordinate translations
• SlewToAltAzAsync - supported via coordinate translations
• SyncToAltAz - supported via coordinate translations

Optional V2 features that are not simulated (they just error out, which is allowed by the spec):

• GuideRateDeclination - out of luck for non-V2
• GuideRateRightAscension - out of luck for non-V2
• MoveAxis - out of luck for non-V2

Dome API Notes

POTH dome control supports the pass through of the full ASCOM dome API. Full hub support, journaling, and capabilities review (as mentioned above) are all supported.

In addition to the pass though of all dome calls, CanSlave always reports True, and the Slaved property can be set to True. This provides for programmatic control over slaving the Dome to a telescope. Any specific commands for the dome to slew will turn off slaving, and the slew will execute.

Focuser API Notes

As for dome control, focuser control passes through all focuser calls and acts as a focuser hub.