Documented the Shutter Position Inference option in the ReadMe.md file

ReadMe.md

@@ -13,7 +13,7 @@
 
 In 2006, Tigra Astronomy was commissioned buy Technical Innovations to produce an ASCOM driver for their observatory automation product known as Digital DomeWorks. The project served well for 12 years but here we are in 2018 and it was looking a bit tired. In the intervening years, the ASCOM LocalServer (hub) pattern was created; we created our Reactive Communications for ASCOM library; and we learned a lot about the art of software development based on experience of producing more than 10 commercial ASCOM drivers for telescopes, domes, focusers, rotators, switches and weather safety systems.
 
-But we started to experience problems with the old driver and we wre not happy with the robustness in operation nor the code quality. We decided it was time for a new start. So we have produced the 2018 Reboot version, sporting the following features:
+But we started to experience problems with the old driver and we were not happy with the robustness in operation nor the code quality. We decided it was time for a new start. So we have produced the 2018 Reboot version, sporting the following features:
 
 - ASCOM LocalServer/Hub that accepts multiple client connections.
 - ASCOM Dome driver, implementing the IDomeV2 interface.
@@ -26,6 +26,7 @@ But we started to experience problems with the old driver and we wre not happy w
 - Reliable shutter state upon connection. If the shutter position is unknown when
    the driver connects, then it can optionally be forced to close to establish a
    known starting state.
+- Shutter Position Inference - more reliable shutter state reporting.
 - Hardware simulator built in. To test the driver without hardware, simply check
    the "use simulator" option in the setup dialog.
 - New graphical user interface shows the current state of the hardware.
@@ -43,7 +44,7 @@ But we started to experience problems with the old driver and we wre not happy w
   that the driver is thread-safe for use in multi-threaded applications
   such as SGP.
 
-## Simulator ##
+## Hardware Simulator ##
 
 The driver now incorporates the hardware simulator that we developed to assist with our unit testing. The simulator can work in `real time` or `quick time`. In `real time` mode the simulator tries to be as realistic as possible, simulating the timing characteristics of the Digital DomeWorks hardware. In `quick time` mode, everything is done as fast as possible.
 
@@ -55,6 +56,40 @@ The simulator can come in very handy if you need to test software without being
 
 Previous versions had some clunky command line utilities and _Custom Actions_ for controlling the user output pins. These pins are typically used with the _Remote Power Module_. Now, we provide an ASCOM Switch driver making this much easier and more discoverable and usable by applications. And, because the new driver is a LocalServer Hub, both drivers can be in use by multiple clients simultaneously and everything will work.
 
+## Shutter Position Inference ##
+
+We experienced issues with Digital Domeworks reporting the shutter position as 'indeterminate' after closing, even though the shutter was fully closed and everything
+worked perfectly in terms of the mechanics. We have not been able to determine the source
+of this issue, which was causing ACP Expert Scheduler to abandon the imaging session and
+go into "Operator Intervention Required" state. Game over; wasted clear skies.
+
+Digital Domeworks actually has no shutter position sensor. The limit switches activated by the shutter are wired into the Shutter Relay Box, which controls power to the shutter motor, but these signals are not available to the main microprocessor in the control box. This is why the shutter position is always 'Indeterminate' when the unit is powered up even if the shutter is fully open or closed. This lack of direct positional feedback means that Digital
+Domeworks must _infer_ the shutter position based on the last shutter command and the length of time the shutter moved for. If you tell the shutter to open and it moves for 5 seconds, then Digital Domeworks assumes it is open (and vice versa for closed). Movement
+is detected by measuring the current drawn by the shutter motor. When the current draw exceeds a threshold, then the motor is assumed to be energised and the shutter is assumed
+to be moving. When the current draw drops below the threshold for several seconds, it is
+assumed that the shutter has reached the limit of travel and stopped moving.
+
+It occurred to us that we could use a very similar heuristic within the ASCOM driver
+and ignore the problematic detection built into the firmware. We have all of the
+information available to us to do this because Digital Domeworks tells us when a shutter
+movement has started, which direction it is in and then reports current measurements once
+per second while the movement proceeds.
+
+So that's exactly what we have done. We introduced a driver option, titled
+_Ignore shutter sensor and infer shutter position_. When this option is disabled
+(the default) then we use the shutter position reported by Digital Domeworks. When the
+option is enabled, we use our own custom heuristic to infer the shutter position.
+Our initial testing has indicated that our heuristic works at least as well as the one in
+the firmware and eliminates some of the phantom shutter errors that we were observing.
+
+This option is experimental and potentially unsafe, because we are overriding the status
+reported by the firmware. We do not recommend that you use this option unless you are
+seeing the 'phantom errors' and want to try our workaround and you have carefully
+considered the implications. If you do enable this option, you will be warned that you
+are enabling a potentially unsafe configuration. Note that this option will not fix
+mechanical or electrical issues. If in doubt, leave the option at the default setting
+of Disabled.
+
 ## Obtaining and Installing the Driver ##
 
 The driver may be downloaded from: https://bitbucket.org/tigra-astronomy/ta.digitaldomeworks/downloads/