PT Filterwheel Controller Commands

Introduction
Command Interface
Commands
Changes
History

Introduction

The PT Filterwheel Controller controls the shutter, filter wheel and flat field lamp. It runs on a ZWorld JackRabbit BL1810 single board computer, and the code is written in Dynamic C.

Command Interface

The command port is an RS-232 port running at 9600 baud with no flow control. Hardware flow control is available and should probably be used (requires a minor bit of code). It does not appear that ^S/^Q flow control is available.
Commands are not case sensitive
Commands may begin with an optional "fwb" prefix (a deprecated holdover from the original controller); again case doesn't matter. If MOP is reprogrammed to eliminate the fwb then we may make it forbidden.
Commands are acknowledged as follows:
- If the command succeeds, the command verb (excluding the arguments, if any) is echoed followed by any return data (separated by one or more spaces).
- If the command fails, the entire command (including arguments, if any) is echoed surrounded by question marks and followed by an error message.
All exposure times are input and output as integer numbers of tenth seconds (e.g. 51 means 5.1 seconds).
The command argument processing is a bit crude; extra characters are ignored, even if they are part of a number (so 45.9 is treated as 45, 4a is treated as 4 and a is treated as 0; for those familiar with C, the function atoi is used).

Commands

Basic Commands
rebootAck	Acknowledge controller reboot. Until this command is sent, all other commands are rejected (following a reboot). This is a no-op once reboot has been acknowledged.
reset	Resets the controller to a known state, including closing the shutter (aborting a timed exposure, if any), moving the filter wheel to the next known position if the position is unknown (i.e. if there is was an error last time the filter wheel was moved), and turning off the flat field lamp.
Shutter Commands
startExposure timeTenthSec	Starts an exposure, where exposuretime is in integer tenth seconds. The allowed range is [1, 20,000]. Prohibited while the shutter is open, the filter wheel is moving or the filter wheel position is unknown. As a deprecated feature, if you omit timeTenthSec then the default exposure time is used (see setExposureTime).
remainingTime	Returns the remaining exposure time for the current exposure in integer tenth seconds. Returns 0 if no exposure. Returns -1 if the shutter is open for an untimed exposure.
closeShutter	Closes the shutter, aborting a timed exposure, if any. Returns the exposure time (in tenths of a second) if a timed exposure was occurring. Returns 0 if the shutter was already closed. Returns -1 if an untimed exposure was in progress.
interruptExposure	Identical to closeShutter.
openShutter	Kills the current timed exposure, if any, then opens the shutter for an untimed exposure.
queryShutter	Returns the state of the shutter: "open" or "closed".
The following shutter commands are deprecated:
setExposureTime timeTenthSec	Sets the default exposure time in integer tenth seconds. Returns the actual time that has been set. The use of default exposure time is deprecated.
getExposureTime	Returns the default exposure time in integer tenth seconds. The use of default exposure time is deprecated.
Filter Wheel Commands
setFilter desPos	Moves the filter wheel to the desired position 1-6. Returns the same information as getFilter. Prohibited during a timed exposure. Note: most of the motion happens in the background. However, if the current position is unknown (i.e. if the last move failed) then the filter wheel is first moved to the next known position in the foreground (which can take several seconds) before the command returns.
getFilter	Returns currPos desPos status: currPos is the current filterwheel position: `1-6`, or `NaN` if unknown. desPos is the desired filterhweel position: `1-6` if specified, `0` if "go to next known position", or `NaN` if some internal error has occurred. state is one of: `OK` if the last move finished successfully. remTime the estimated remaining time to move as an decimal number of seconds. This number is only valid to within a few seconds; the decimal point is included solely to make it obvious it is not a filter position. `error:` error message if the previous move failed.
Miscellaneous Commands
setFFLamp desState	Controls the flat field lamp; desState is one of `on` or `off`. Returns the state. Prohibited during a timed exposure.
getFFLamp	Returns the state of the flat field lamp; one of `on` or `off`.
getDigIO	Returns the value of digital I/O and other boolean info in hex with a leading 0x; for example: 0x13e. The bits are as follows (where 0 is the low order bit): 0-2: filter wheel switch input; valid filter positions are 1-6; warning: incorrect positions are possible for brief periods during transitions between filters (due to not using a gray code) 3-5: not used, always 1 6: flat field lamp output; 1=on 7: shutter output; 1=open 8: shutter wheel motor output; 1=on; warning: this is maintained by software; ill-behaved code can toggle the filter wheel motor and not toggle this bit 9: filter wheel background task; 1=running

Changes

On 2003-03-28 the PT filterwheel controller underwent a major overhaul. The changes are as follows:

Overall Changes:

Commands may be lowercase and the initial "fwb" is optional. Note that the echoed command verb is identical to that entered.
Errors are reported.
invalid exposure times are rejected. Formerly they were truncated to the range [1, 3600].
At startup and reset the filter is moved to the next known position, not to a specific filter.

Changed Commands:

fwbStartExposure takes an optional exposure time (if omitted the default is used) and returns the exposure time used.
fwbSetExposureTime and fwbGetExposureTime are deprecated; please specify the time with fwbStartExposure instead.
fwbRemainingTime returns -1 if the shutter is open for an untimed exposure.
fwbGetFilter (renamed from fwbReadFilter) now works (!) and the output format has changed.
fwbSetFilter prints out additional information (the same info as fwbGetFilter). It may also take up to one filter change time before it returns if the current position is unknown.

New Commands:

fwbSetFFLamp turns the flat field lamp on or off
fwbGetFFLamp returns the flat field lamp status
fwbGetDigIO returns the state of the digital I/O.

Deleted Commands:

fwbWriteWord: replaced by fwbGet/SetFFLamp
fwbReadFilter: rnamed to fwbGetFilter; this is more standard notation and MOP wasn't using it anyway since it didn't do anything.
fwbSetupShutter: use interruptExposure or closeShutter, instead; three commands to do the same job is a bit much and MOP wasn't using it.
fwbEnableFilter: it wasn't being used and there was no obvious use for it nor any way to disable the filter wheel.
fwbAuxOn
fwbAuxOff
fwbReadByte
fwbReadWord

History

2003-03-28 ROwen and JBrinkmann: major overhaul (see Changes section)