Trouble-shooting and Analysis

Calibration and Mount Control Problems

If you are just starting to use PHD2 or are connecting to new equipment for the first time, you may have trouble getting the guider calibration done.  This problem usually takes one of two forms, each requiring different responses:
  1. The star moves during calibration but it moves "too far" or "too little."  If you've used the new-profile wizard and have provided correct values for focal length, camera pixel-size, and mount guide speed setting, the "step-size" used in calibration should already be correct.  But if you've configured your profile by hand or have changed guide speed settings in the mount, you may need to adjust the 'calibration step-size' parameter in the 'Guiding' tab of Advanced Settings. The help content there describes how this parameter is used, and you should be able to resolve the problem quickly.  But if you've used the new profile wizard and are seeing problems with "too far" or "too little" guide star movement, the problem probably lies elsewhere.
  2. The star doesn't move enough during RA calibration, declination backlash clearing, or Dec calibration.  These problems are announced by alert messages at the top of the display window.  With longer focal lengths, small movements may even be the result of seeing deflections, and the mount isn't really moving at all.  Dealing with this sort of problem is described next.
In nearly all cases, the "no movement" problem is caused by failures in the hardware or, even more likely, problems in the cabling and connections.  The best tool for trouble-shooting this is the 'Manual Guide' option under the 'Tools' menu, as described in the Tools section of this help document.  Simply use the directional controls in the 'Manual Guide' window to send commands directly to the mount while watching a star in the image display window.  Use fairly large guide pulse amounts - at least several seconds - so you can clearly see if the mount is moving.  Try to move the mount in all four directions and verify the target star is moving by roughly equal amounts.  If the mount does not respond, you know you have either hardware or connectivity problems to resolve - nothing to do with PHD2.  If you're using a Shoestring device to connect to the mount, watch its indicator lights to see if the commands are reaching it.  Similarly, your ST-4 compatible guide camera may have indicator lights to show when guide commands are being received.  If you're using an ASCOM connection to the mount, be sure the COM port assignments are correct.  You can also use some of the ASCOM-supplied tools like POTH to be sure the ASCOM driver is communicating correctly with the mount.  It is best to use the latest version of the ASCOM driver for your mount because older versions of these drivers often had bugs associated with pulse-guiding.

Calibration Sanity-Checks and Alerts
It is also possible that the calibration process will complete but PHD2 will post a calibration alert message saying that some of the results are questionable.  This "sanity check" dialog will show an explanation of the issue and some details of the calibration results:



Starting with the 2.4.0 release, there are four things checked by PHD2:
With any of these alerts, the relevant data field will be highlighted based on the type of message.  You can choose to ignore the warning ('Accept calibration'), re-run the calibration ('Discard calibration'), or restore your last good calibration ('Restore old calibration').  With the third option, you can defer calibration until later and start guiding with your last good calibration data.  If you see repeated alerts on the same topic and are convinced there really isn't a problem, you can use the 'don't show' checkbox to block future alerts of that type.  But you should be aware that the sanity-checking used by PHD2 works well for a wide range of equipment, and most users don't see these calibration alerts at all.

Declination Backlash
By far the most common source of calibration problems is declination backlash, which is present to some degree in most geared mounts.  With many less-expensive mounts, however, the problem can be severe and can lead to poor calibration and guiding results.  Consider the following example of a calibration review dialog:



The first clue to the problem is found by comparing the number of steps required for calibration on the two axes - 10 for RA but 42 for Dec.  This shows the mount was not moving consistently in declination, probably because the backlash had not been effectively cleared.  This also explains the "wandering" behavior of the declination points (light green) when the guide commands were reversed from north to south. Finally, the computed declination rate is much smaller than the RA rate even though the guide speed settings on the two axes were identical.  In fact, this would have triggered a calibration alert dialog.  There are actually two problems to be addressed here.  First, the calibration result is poor and should be repeated in order to get a more accurate measure of the declination guide rate.  Second, the mount is likely to behave badly during direction reversals in declination even if the dec guide rate is correct.  The calibration can be improved by first manually moving the mount  north at guide speed for 10-20 seconds until consistent star movement is seen in the main window.  You can do this with the 'Manual Guide' tool or by using the hand-controller on your mount.  Once this is done, most of the declination backlash in your mount should have been overcome.  You can then repeat the calibration procedure and probably get a declination guiding rate that is more reasonable.  The underlying backlash problem generally requires some mechanical adjustment to the mount.  You can try using a backlash compensation setting, but this is not likely to work well if the backlash is large - more  than 2-3 seconds, for example.  If you can't correct the backlash or reduce it to manageable levels, you should consider choosing uni-directional guiding for declination. To do this, you determine which way the mount drifts due to polar alignment error, and tell PHD2 to guide only in the opposite direction (see  Uni-directional guiding). This is controlled by the 'Dec guide mode' control on the'Algorithms' tab of the Advanced Dialog.  For example, if the mount tends to drift north overall, restrict guide commands to south-only. This is not an ideal solution, obviously, but you can still use reasonably long exposures and achieve decent guiding results - and there are plenty of imagers out there who use this technique effectively.  If you have an unusual circumstance, such as a mount with no declination control at all, you can set the 'Dec guide mode' choice to 'Off'.  

Validating Basic Mount Control - the Star-Cross Test
If you are having repeated problems getting calibration to complete without alert messages, you should run a very simple test to see if the mount is responding to guide commands.  This test basically mimics what is done during calibration, but it is more direct and can give you a better feel for what's going on.  We'll call it the "star-cross" test.  The idea is to open the shutter on the main imaging camera, then send guide commands that should cause the stars in the field to trace out a distinctive cross pattern.  In other words, you want to get an image that looks something like this:



The angular orientation doesn't matter, that's just a function of how you have the guide camera rotated.  What is important is that the lines in the cross are perpendicular and have roughly equal lengths in each of the four directions relative to the starting point in the center.  If the image you get doesn't have this approximate appearance, guiding will either be impaired or perhaps impossible.  For example, consider the following poor result:



You can see the star has moved along only one axis  - only in right ascension in this example.  The declination guide commands sent to the mount did nothing at all.  Until this is fixed in the mount, you won't be able to guide in declination at all and will have to disable declination guiding to even complete a calibration.  There are  many other permutations of bad results, each suggesting a particular problem in the mount, the guide cable, or much less likely, the ASCOM driver for the mount.  You can safely assume it has nothing to do with PHD2.

Here are the steps for running the test:
  1. Set the mount guide speed to 1X sidereal.  Bring up the 'Manual Guide' tool in PHD2 and choose an initial pulse size - start with, say, 5 seconds.
  2. Start a 60 second exposure on the main camera.
  3. Send a 5-second pulse west, then two 5-second pulses east, then a final 5-second pulse west.  This should return the star to its approximate starting position.  You should wait about 5 seconds after sending each guide pulse to give the command time to complete before sending the next pulse.
  4. Now send a 5 second pulse north, then two 5-second pulses south, then a final 5-second pulse north.  This should again return the star to its starting position.
  5. Wait for the main camera image to download and see what you get.
You can use different pulse lengths if you want, perhaps using smaller values to confirm the mount will respond to them.  Just be sure the total exposure time on the main imaging camera is longer than the total  of guide durations plus a margin for error. On most mounts, the star will not return to its exact center because of some declination backlash - you can see that in the first example image.  But it should be fairly close or you'll need to look more carefully at how much declination backlash you have in the mount.  PHD2 also has a star-cross test tool, descibed here: Star-cross Tool.  You can use that to automatically perform the test steps described in 1-5 above.

One benefit to using this test is that it reduces things to the absolute basics: will the mount move as directed or not.  It has nothing to do with PHD2 guide settings because they aren't involved in the test.  You may find it helpful to use the test results to communicate with the mount manufacturer or other users who understand that specific mount and its typical  problems.

Measuring the Mount's Behavior
If you're having trouble getting decent guiding results, your first instinct will probably be to try making wild changes to the guiding parameters in the hope of finding a magic solution.  Thiis almost never works, and you're more likely to just make things worse.  If the default parameters from the new-profile-wizard aren't producing reasonable results, the fault is probably with the hardware and you'll need to determine the underlying cause.  Once you understand the cause, you can probably improve your guiding results even if no actual repairs can be made - but understanding the underlying problem is important.  To understand what the mount is doing, perform the following steps:

1. Use the new-profile-wizard to create a new equipment profile for the test, being sure the guide scope focal length and camera pixel size are correct.  Don't guess at them, look them up if you aren't sure.
2. Use an ASCOM connection to the mount if one is available.
3. Perform a fresh calibration near Dec=0 with the scope pointing at least 40 degrees above the horizon to minimize seeing effects.
4. Make sure there are no backlash compensation settings active in the mount, and set the mount guide speed to 0.5x - 1x sidereal.
5. Run the Guiding Assistant for 10-15 minutes and apply whatever recommendations it makes, particularly with respect to min-move values.  Let it measure your declination backlash.  You may need to use a large tracking region to avoid losing the guide star during this part of the process - just be sure there aren't multiple stars in the tracking rectangle.  The backlash test will move the star a long distance north, so choose a guide star that is nearer the southern edge of your camera frame to give yourself plenty of room.
6. Do not change any of the guide parameters beyond what is recommended by the Guiding Assistant.
7. Take a careful look at the results shown in the Guiding Assistant table.  Each entry in the table can tell you something useful about the mount's performance.  These results are also written to the guiding log, so they are available for later analysis.
8. If you got calibration alert messages in step 3, you should probably remedy those problems before proceeding.  Guiding with a bad calibration is not likely to produce good results.  Also, if your polar alignment error is 10 arc-min or more, you should improve on that and then repeat the above steps.
9. Let PHD2 guide for another 10-15 minutes, just letting it run so long as there aren't gross errors from wind or other "mistakes."  Do NOT change any of the guiding parameters while this is being done.

If you want to analyze the results yourself, use the PHDLogView tool and the tutorial on Analyzing PHD2 Guiding Results.  You should also consult the document on PHD2 Best Practices.  All of these references are available on the OpenPHDGuiding.org web site under the 'News' tab.  If you'd like some help understanding the results, post both the guiding and debug log files on the OpenPHD2 Google forum and we'll be glad to help you out.

Display Window Problems

New users often complain that the image displayed in the main window is extremely noisy or is almost all-white or all-black.  Assuming the camera is functioning and actually downloading images, the display issues are often caused by the absence of any usable stars in the frame.  For example, trying to test the camera indoors or in daylight will almost always create these conditions.  The appearance of the image display window in these situations provides no useful information and should be discounted.  PHD2 uses an automatic screen-stretching function that is intended to help you see real stars under a nightime sky.  When no stars are present, the display will be stretched to show the range of minimum-to-maximum brightness values of whatever is in the frame - which is often nothing at all.  This is usually what causes the noisy/all-white/all-black display results.  You may also encounter display problems if the guider is not well-focused.  Focusing the guider can be a tedious and frustrating experience but it's critical to getting good guiding results.  A good technique is to start with a bright but unsaturated star and try to reach focus with that.  Then move to successively fainter stars to fine-tune the focus position.  

Hot-pixel Problems

Even with some high-quality guide cameras, you may encounter problems where clumps of hot pixels are mistaken by PHD2 as guide stars.  This can be especially annoying if you're using automation tools and  the 'auto-select' guide star selection is mistakenly choosing hot pixels.  For many cameras, a simple dark frame will suffice for reducing or eliminating hot-pixel problems, and dark frames should always be used as a starting-point.  But for other cameras, you will need to build a bad-pixel map and update it as necessary when you see changes in the locations and sizes of defective pixels.  Camera sensors change over time and may react to changing temperatures, so bad-pixel map maintenance is a small task you should be able to perform.  Step-by-step instructions can be found in the Bad-pixel map chapter of this document.  These problems are different from transient hot pixels, which can be caused by cosmic ray strikes on the sensor.  Although cosmic ray hits can disrupt guiding, there's really nothing you can do about them.

Restoring a Working Baseline

Despite advice to the contrary, you may have made rapid, uninformed changes to your guiding parameters only to find the performance stayed the same or even got worse.  Before proceeding, you should restore the settings to their default values.  If you used the new-profile-wizard to build your profiles, the parameters will have been set based on the specifics of your configuration, and they are likely to be pretty close.  If you encounter significant guiding problems using those settings, you are probably having issues with the mount or other hardware. Blindly changing guiding parameters almost never solves these problems and quite often makes things worse.  You have several options for restoring the settings to their default values:
  1. On the 'Algorithm' tab of the Advanced Dialog, you can individually reset parameters by looking at the tool-tip for each field.  Hover your mouse cursor over the field and the default value will be displayed.  Note that this is not accurate for the min-move settings, which depend on your image scale.  This approach is best when you want to restore only a few settings.
  2. Click the 'reset' buttons on the 'Algorithm' tab for the selected RA and Dec guide algorithms.  This is the recommended approach for resetting all the guiding parameters.  The min-move settings will be reset to the values originally calculated by the new-profile-wizard.  If you subsequently adjusted those settings by running the Guiding Assistant, you should repeat that process.
  3. Run the new-profile-wizard, accessed by clicking on the 'Manage Profiles' button in the 'Connection' dialog.  Use the same camera and mount choices you already have and give the profile a new name.  If you want to re-use the dark library and bad-pixel map from the old profile, connect to the new profile and use the 'Darks' menu to import those files from the old profile.  Once you are satisfied with the new profile settings, you can delete the old one.

Camera Timeout and Download Problems

In some cases, you may experience problems where guider images aren't downloaded or displayed.  In extreme cases, this may even cause PHD2 or other camera-related applications to be non-responsive (i.e. to "hang").  Again, this is almost always due to hardware, camera driver, or connectivity issues, with one of the most common culprits being a faulty USB cable or device.  It is highly unlikely to be caused by an application like PHD2, so you should begin your investigation at the lower levels of the system. You can start by confirming that the guide camera is working - try using a short, direct cable from the camera to the computer and taking exposures with the native or test application that came with the camera.  If the camera is functional, you can start looking at USB hubs and cables, swapping them one at a time to see if you can isolate the problem.  It's worth remembering that we work in a hostile environment while doing our imaging, and many of the components we use are not designed for cold, outdoor conditions. So something that worked just last week or last month may no longer be reliable.

Starting with the 2.3 release, PHD2 uses a camera timeout property to protect against hang conditions.  This property is set in the Camera tab of Advanced Settings. and uses a default value of  15 seconds.  This means that PHD2 will wait up to 15 seconds after the completion of the exposure to receive the image from the camera.  This is a very generous amount of time and should work well for the majority of cameras.  However, some cameras are known to create problems by making large bandwith or power demands on the USB subsystem.  If you are getting timeouts of this sort and are convinced the camera is working properly, you can increase this timeout value.  You can even change it to a very high number - even 1000 seconds or more - so that timeout errors are never shown.  Doing so leaves you vulnerable to apparent hangs in the user interface and erratic guiding behavior, but it is a choice you can make for yourself.  A larger value for the timeout will not create extra delays during normal camera operations - once the image is downloaded from the camera, the timer is cancelled and guiding will proceed immediately.

Poor Guiding Performance

Once you've gotten everything running, you will probably get reasonably good guiding results almost immediately. You will have to decide what "good enough" means, and everyone's standard is likely to be different.  But if you find your imaging results are not acceptable because the stars are streaked or elongated, you'll need to take a systematic approach to correcting the problems.  It is often tempting to just start blindly adjusting the various guide parameters in an effort to make things better.  There is nothing wrong with adjusting the parameters - that's why they're there - but it should be done carefully based on an understanding of what they do.  The PHD2 default settings are carefully chosen to produce reasonable results for most amateur equipment and locations.  Optimal settings are entirely dependent on the image scale, seeing conditions, and behavior of your specific mount.  In other words, they are unique to your situation - there is no magic "red book" of correct guiding parameters, and settings you get from other users may be completely irrelevant to your situation.  If you got started by using the New-Profile wizard, the default settings will already be tuned somewhat to match your image scale.  By using the Guiding Assistant, you can get more specifics about your situation - how the seeing conditions look and how you might adjust the minimum-move settings to avoid chasing the seeing.  You can also use either the Guiding Assistant or the Manual Guiding tool to see how much backlash is present in your mount, something that can be important to understanding your declination guiding results.

Achieving the best possible guiding performance can be a complex task and not something that can be covered here. However, you can get help on the web from a variety of sources, with the document by Craig Stark being a very good place to start:  
http://www.cloudynights.com/page/articles/cat/fishing-for-photons/what-to-do-when-phd-guiding-isnt-push-here-dummy-r2677.

Alert Messages

PHD2 will sometimes display alert messages at the top of the main display window.  These generally show error or diagnostic information that warrant your attention.  During normal operation, you probably won't see any of these, but if you do, this section can help you decide what to do about them.

Dark-library and Bad-pixel Map Alerts

"Use a Dark Library or a Bad-pixel Map" - using a dark library or bad-pixel map reduces the likelihood that PHD2 will mistakenly identify hot pixels or some other image defect as a star.  If you choose to ignore this message, you'll be vulnerable to situations where PHD2 inadvertently switches from the guide star to a hot pixel and no longer guides correctly.

Format/geometry mismatches - dark frames and bad-pixel maps must match the format of the sensor in the camera being used.  If you've changed the camera in an existing profile, the existing dark/bpm files will not be usable and you'll see this alert message.  To avoid seeing the message, you should instead create a new profile when you change cameras. You'll still need to shoot new darks or bpms, but you can keep the old files for use with the original camera. In very unusual circumstances, you may see this message when either the driver or PHD2 code for handling the camera has changed. You might also see a format-incompatibility alert message if you have an old dark library that has somehow accumulated frames with different sensor formats.

In any of these cases, you should rebuild the dark library or bad-pixel map from scratch - more information can be found here:  Dark Frames and Bad-pixel Maps

ASCOM Alerts

When you first connect to a mount, camera, or other ASCOM-controlled device, you may see an alert message saying that a required capability is not supported by the driver.  One example would be lack of support for pulse-guiding by an ASCOM telescope/mount driver, something that can occur with outdated drivers.  In these situations, your only recourse is to update the ASCOM driver.  These drivers are generally available from the ASCOM web site or, in some cases, from the device manufacturer.  As a rule, the best practice is to use the latest versions of these drivers so you don't encounter problems that have already been identified and fixed.

You might also see other alert messages associated with the ASCOM driver for the mount:
1. "PulseGuide command to mount has failed - guiding is likely to be ineffective."  This is usually caused by a bug or timing sensitivity in the ASCOM mount driver, and there is generally no way to know if the guide command was executed properly or not.  If you rarely see the alert and your guiding results are acceptable, you can probably ignore it.  Despite the alert condition, PHD2 will continue to issue guide commands, so you don't need to take any immediate action.  If you see the alert frequently, you should send us your debug log so we can understand the details of the problem and possibly help you describe it to the author of the ASCOM driver.
2. "Guiding stopped: the scope started slewing."  This is pretty self-explanatory, but the determination that the scope was slewing is something reported to PHD2 by the ASCOM mount driver.  Whether it was actually slewing isn't known to PHD2.  Assuming you didn't mistakenly slew the scope with guiding active, there is probably a timing problem in the driver.  If you want to sidestep the problem temporarily, you can disable the logic to check for slewing - go into the 'Guiding' tab of the brain dialog, and un-check the box that says "Stop guiding when mount slews."  This will let you continue guiding, but the results might be suspect.  The debug log should provide the details needed to describe the problem to the author of the ASCOM driver.

Camera Timeout Alerts
Alert messages associated with camera timing/timeout problems are discussed above: Camera Timeouts

Calibration Alerts
A number of alerts may appear during the mount calibration process.  These are described here: Calibration Alerts

Maximum-Duration Limit Alerts
During normal guiding, you may see an alert message saying that your settings for maximum-duration limits in RA or Dec are preventing PHD2 from keeping the guide star locked.  If you've decreased these parameters from their default values, you should consider increasing them.  However, if the limits are well above one second, this alert probably indicates you've encountered a mechanical problem that needs to be corrected.  In the simplest cases, you may have suffered a cable snag, wind gust, mount bump, or other external event that caused the guide star to move by a large amount.  In such cases, you simply need to correct the problem if you can and proceed with guiding.  But in other cases, the alert may be triggered by a steadily growing guide star displacement that is not being corrected at all.  For example, if PHD2 can't move the mount correctly in either the north or south directions, the cumulative uncorrected error will eventually reach a point that triggers the alert.  These sorts of problems will require careful diagnosis and correction and simply increasing the maximum-duration limits will not help.

Log Analysis

Any sort of problem isolation or tuning will invariably require use of the PHD2 log files.  Both are formatted for straightforward interpretation by a human reader, and the guide log is constructed to enable easy import into other applications.  As mentioned in the 'Tools' section, applications such as PHDLogViewer or Excel can be used to visualize overall performance, compute performance statistics, and examine time periods when guiding was problematic.  With Excel or similar applications, simply specify that the guide log uses a comma as a column separator.

Guiding Log Contents

The contents of the guiding log will continue to evolve as new capabilities are added.  But the basic content is stable, and considerable care is taken to not "break" applications that parse it.  If you wish to analyze the log yourself, the following information will be helpful.  

The PHD2 guide log will contain zero or more sequences of calibration and zero or more sequences of guiding.  Each of these sections has a header that provides most of the information about the guiding algorithms being used and the internal parameters used by PHD2 for guiding.  At the start of either a calibration run or a guiding sequence, the last line of the header information defines a set of column headings.   The meanings of those columns are shown below:

 Calibration columns:

 Guiding columns:

All distance values are in units of pixels.  The header for the guiding section will show the image scale as it is known by PHD2, and that can be used to scale the pixel distance values into units of arc-seconds if desired.

Problem Reporting

If you encounter application problems that are specific to PHD2, you are encouraged to report them to the open-phd-guiding Google group: https://groups.google.com/forum/?fromgroups=#!forum/open-phd-guiding.  Obviously, the more information you can provide, the more likely we will be able to resolve the problem.  Using the following guidelines will help in that regard:
  1. Try to reproduce the problem - if we have a clear set of steps to follow, we are more likely to find a solution quickly.  If you can reproduce it, try to reduce things to the minimum number of steps.  Remember, we won't have your hardware or computer environment when we try to reproduce it ourselves.
  2. Try to be complete about describing your configuration - operating system, equipment types, PHD2 version, etc.
  3. Attach the PHD2 debug log from the session in which you encountered the problem.  You can find the debug log in the PHD2 folder in your Documents folder. If you can't reproduce the problem, try to estimate the time of day when you first saw it - this could help us find evidence in the debug log without having to sift through hundreds of lines of output.