ZWO-Gcam Software Documentation

The Observatories of the Carnegie Institution for Science (Carnegie Observatories), Pasadena, CA

Christoph C. Birk (birk AT carnegiescience DOT edu)


Location of this document: http://instrumentation.obs.carnegiescience.edu/Software/ZWO/zwogcam.html


  • News
  • Screen Shots and Software Documentation

  • HowTo setup the RaspberryPi and NUC
  • Zwo-Server


    News

    v0.423 (2024-05-10)
  • Introduced the new image mode "-m5" (2520x2520) for use as the MagE slitviewer.
  • Please note that the parameter of the "-m" switch has changed:
    -m2: 1000x1000
    -m3: 1512x1512
    -m4: 2000x2000
    -m5: 2520x2520
    This also affects the mode keyword for the .ini files. In particular:
    pfs.ini: "mode 1" --> "mode 2" (1000x1000 geometry)
    mike.ini: "mode 5" --> "mode 3" (1512x1512 geometry)
    Download zwogcam-0423.tar.gz
    v0.422 (2024-04-08)
  • Change the cursor from an arrow to a crosshair when on the image.
  • Download zwogcam-0422.tar.gz
    v0.421 (2024-03-12)
  • Fixed a bug that would drive the guide star out of the box in 'gm5'.
  • Download zwogcam-0421.tar.gz
    v0.420 (2024-03-12)
  • Lower the minimum 'apa' update time to 2 seconds.
  • Download zwogcam-0420.tar.gz
    v0.419 (2024-03-11)
  • Fixed a bug in the 'position angle' calculation in 'gm5'.
  • Display the host name (zwoserver) in the title bar of the GUI.
  • I tested some failure modes of the ZWO system:
  • Device Event GUI error fix requires
    rPi unplug ethernet cable no response from 'host' restart GUI
    rPi unplug USB cable no data restart GUI
    ZWO unplug power no data reboot rPi / restart GUI
    v0.418 (2024-03-08)
  • Introduced guider mode 'gm5'.
  • Place cursor4 on the object on the slit and cursor5 (box) on a star in the field of view. Pressing F3 (or F5) will start guiding on the field star. The GUI will read the paralactic angle from the TCSIS and rotate the position of the guide box (and magnifier) around the object on the slit accordingly.
    Note: Cursor4 and Cursor5 cannot be moved while 'gm5' is active.
  • Introduced the (temporary) command "parity {-1,1} ". It defaults to +1 and allows to reverse the angular tracking motion of the guide box in 'gm5'.
  • Note: This is not the same as the "parity" parameter in the .ini file and will be removed from the GUI once 'gm5' is tested and verified.
  • Verify that the TCSIS did receive the telescope corrections from the guider.
  • If there is a communication issue, the GUI prints an error message, then closes the TCP/IP connection and tries to re-open it.
  • Added the "sn" (guider sensitivity) parameter to the .ini file.
  • v0.415 (2024-02-20)
  • Introduced the "-f" switch that loads a configuration file. Example: pfs.ini, mike.ini.
  • I plan to remove the "PFS" mode (-mp switch) in the next version to avoid hardcoded configuration parameters for each instrument.
  • Updated the graph labels according to the guider mode ('gm').
  • Determine a scale-factor from the left/right flux ratio to scale the left+right flux estimate in 'gm4'.
  • Print the "mx" value in red if it is above 15000.
  • v0.410 (2024-01-30)
  • Updated some defaults (PFS mode: -mp): px 53, bx 41, pct 60, bkg 24, span 5000, gain lo
  • v0.409 (2024-01-30)
  • Experimental guide mode "gm4".
  • Derive 'dx' from the slope of the calculated ratio 'rx'.
    v0.408 (2024-01-29)
  • Experimental guide mode "gm4".
  • Derive 'dx' from a 1-dim gauss fit:
    Please note that this requires an appropritate slit width estimate ('sw' command, default: 6 [pixels]).
    The GUI is sending corrections every frame if the error exceeds 0.05" (before multiplying by 'sens' and 'fudge').
  • New command 'sw' that defines the assumed slit width for the 'gm4' mode.
  • Fixed a bug in the "bx" box update.
  • v0.407 (2024-01-25)
  • Experimental guide mode "gm4".
  • 'dy' is derived from a 1-dim gauss fit, while 'dx' is calculated as in "gm3".
    v0.403 (2024-01-12)
  • Removed the option to run multiple guiders in one GUI.
  • Overhauled the layout to reduce the GUI footprint on the screen.
  • Removed the "-s" (sendHost) switch. Always uses the TCSIS host.
  • Removed the "-mz" (ZWO) option, since it is the default.
  • New options with only 500x500 image on the GUI:
  • "-m1": 1000x1000, "-m5": 1512x1512, "-m2": 2000x2000
  • New vertical layout ("-v" switch).
  • v0.355 (2023-12-21)
  • Use the (dimenionless) ratios 'dx' and 'dy' as a criterion whether to send a correction to the telescope and guider probes.
  • Require [abs(dx) .gt. 0.1] AND [abs(dy) .gt. 0.05]
  • Plot 'dx' and 'dy' on the 'tc' and 'fw' plots (temporary feature).
  • The '-mp' (PFS) mode automatically applies the switch '-o -10,85'
  • v0.354 (2023-12-20)
  • Added a second (optional) parameter for the "gm" command. That parameter may be 't' or 'p' and is only relevant in 'gm3' mode.
  • In 'gm3' mode, limit sending corrections and graph updates to once every 5 seconds or every 'av+1' frames, whatever is longer.
  • v0.353 (2023-12-19)
  • Use the parity parameter when calculating telescope offsets (flip X: dx=-dx).
  • v0.352 (2023-12-18)
  • Fixed a bug in the east calculation for the (Az,El) "L".
  • Added the partity parameter for the compass "L". It may be set using the '-i' switch, but is imlicitly set to '-1' in the '-mp' (PFS) mode.
  • The '-mp' (PFS) mode automatically sets these switches:
    -a -128 -e -1 -r 0 -i -1
    v0.350 (2023-12-17)
  • Added a new switch '-o' to adjust the center of the window on the array:
  • -o dx,dy: adds dx,dy pixels to the center coordinates.
    In a future version I plan to add the proper offset (TBD) when using the PFS slitview mode (-mp).
  • Added an experimental guider mode (gm3) for use with a slitviewer.
  • It creates 4 sums: pixels above, below, left or right of the cross hair. Then it sends a corrections to the TCS of 0.1" multiplied by the 'sn' (sensitivity) parameter (defaults to 0.5); ie. a 0.05" correction.
    v0.347 (2023-12-08)
  • The EDS-801 message is sent every 'av' frames or 1 second, but never faster than 'tf'.
  • Send EDS-82i messages (format: 82%d; %.1f %.1f ).
  • All cursors are sent at startup; thereafter only when a cursor position changes.
    Please note the spaces before and after the cursor coordinates.
    v0.345 (2023-11-21)
  • PFS mode: the switch '-mp' uses a smaller FOV (1200x1200).
  • This required a change to the mask filename convention to include the geometry:
    Rename the existing mask(s), eg. "zwoSERIALNUMBER.mask" to "zwoSERIALNUMBER_1800.mask".
    Then you will need to create a new bad pixel mask when in PFS mode that will be named "zwoSERIALNUMBER_1200.mask".
    v0.344 (2023-10-31)
  • Send guider corrections (and EDS 801 messages) only every 'av' frame.
  • Keep open EDS connection during guiding (do not close the socket after each message).
  • v0.343 (2023-09-13)
  • Layout change: Move the "av" box next to "tf".
  • Re-use the exposure time countdown box to display the send countdown.
  • Re-use the frameCounter box to display the last frame number sent.
  • v0.342 (2023-09-06)
  • Append '\n' [LF] to the EDS messages (was '\r' [CR]).
  • Report the error message "connection to TCS failed" when "F9/F10" fails to connect to the TCS.
  • v0.341 (2023-09-01)
  • Reduced the wait for an EDS response from 2 seconds to 50 milli-seconds.
  • Updated the format of the 801 EDS message (moved the guider-flag to touch the FWHM).
  • Close connection (hangup) between messages. [v0341b]
  • Append '\r' [CR] to the messages. [v0341c]
  • Bug-fix. [v0341d]
  • v0.340 (2023-09-01)
  • Wait for a response from the EDS.
  • v0.339 (2023-08-31)
  • Terminate the string sent to the EDS with a '\0' byte (was '\r').
  • v0.338 (2023-08-31)
  • Do not wait for a response from the EDS.
  • v0.337 (2023-08-25)
  • Made the FWHM sanity check less restrictive. It interfered with measuring the very small pinholes.
  • v0.336 (2023-08-18)
  • Added the '801' EDS message to the TCSIS.
  • Most keyboard commands should work over the TCP/IP interface.
  • v0.332 (2023-08-01)
  • Renamed various instances of 'zwoguider' to 'zwogcam'
  • Added a basic TCP/IP interface.
  • Currently there are only three commands, "version", "fone" and "fthr".
    v0.331 (2023-07-28)
  • Swapped F9/F10 functionality.
  • Set 'send=0' when using 'F3' for the first time in 'fm2' mode.
  • Renamed the binary to 'gcamzwo'.
  • v0.330 (2023-07-20)
  • Implemented the fm command (F1,F3 overlay).
  • F9: send 'gpsha#' to the TCSIS, where '#' is the value of '-g gnum'.
  • F10: send 'gpfld#' to the TCSIS, where '#' is the value of '-g gnum'.
  • v0.328 (2023-07-18)
  • Added the following FITS keywords (requested from the TCSIS)
  • RA      = ' 12:49:52.0'                                                         
    DEC     = '-29:05:00.0'                                                         
    EQUINOX =           2023.54000                                                  
    ST      = '12:50:33'                                                            
    HA      = '00:00:42'                                                            
    ZD      =               0.1529                                                  
    AIRMASS =                1.000                                                  
    TELFOCUS=                  0.0                                                  
    ROTANGLE=                  0.0                                                  
    ROTATORE=                -90.2                                                  
    GUIDERX1=               13.000                                                  
    GUIDERY1=               14.000                                                  
    GUIDERX2=               15.000                                                  
    GUIDERY2=               16.000                                                  
    TELGUIDE= '10'                                                                  
    
    v0.326 (2023-06-27)
  • Improved the fitting routine for faint objects.
  • Fixed the "gm" command (guider mode).
  • The 'gm' parameter is the guider number by default.
    It is used in the "gpaer#" command in "mm2" mode.
    v0.323 (2023-04-28)
  • Implemented hot pixel masking (mask {on,off,#}).
  • Added "sm" (display smoothing) and "gain" value boxes below the "span" box.
  • Changed the color of the cursors from black to light grey and the thickness from 2 pixels to 1.
  • Automatially set the gain to "high" (300 50) at startup of the GUI.
  • v0.317 (2023-01-20)
  • Fixed time related FITS records when sending frames.
  • Added keywords to FITS header
  • CAMERA = {1,2,3} // $(-g #)
    FRAME = 123 // sequential send frame number
    ROTATORN = {1..5} // rotator port number
    v0.316 (2023-01-19)
  • Added keywords to FITS header
  • MASK = 1 // fixed
    CA = "-a" + 180 // (0..360)
    SH = 'sh #' // value from command
  • Send FITS files to SH-host (was 'gcam' format).
  • v0.315 (2023-01-17)
  • Allow 'elsign' to be zero (elsign = {+1,-1,0}).
  • Set the TCS port to 5810+rotatorPort (-p switch)
  • If the rotatorPort is '0' (default) the TCS port will be 5801.
  • Changed some defaults:
  • -r: 'rosign' = -1
    -e: 'elsign' = 0
  • Take care of some more compiler warnings.
  • v0.314 (2023-01-10)
  • Fixed some compiler warnings on Povilas' Ubuntu machine.
  • Warnings (eg. -Wunused-result, sprintf_check).
    System call open(,O_CREAT,) requires the permissions as the 3rd parameter.
    v0.313 (2022-09-09)
  • Added cooler power percentage next to the temperature on the GUI.
  • Default to 'TEC=off' at startup (no temperature control).
  • Default to 'mm1' at startup (mouseMode=1: move box).
  • Display the "GuiderCamera" number {1,2,3} ('-g' switch) on the GUI. This parameter is used for:
    Defines the IP-port number at the sendHost (5699+g)
    Defines the prefix for the FITS files, eg. gdr1_NNNN.fits ('write' command).
    Sets the default guider mode ('gm').
  • Implement the 'gm' command ('guider mode' {1=PR,2=SH,3=SV}).
  • In 'mm-2' (mm2) mouse mode this is the probe parameter of the 'gpaer' command.
    Eg. 'gm3' moves both probes (slitviewer mode).
  • Added the '-s' switch to preset the SH-image SendHost.
  • Use a separate 'sendFrame' number when sending images to the SendHost.
  • Added the '-p' switch to define the 'rotator port'.
    This will define which guider-stage to send "F9/F10" commands to (TBD).
    This number has currently no other significance.
  • v0.312 (2022-08-24)
  • Write the serial number of the ASI-294 camera to the FITS header, eg.
  • INSTRUME='ZWO_ASI294MM_PRO         / 1f3a0e0301010900  
    Note: This version requires zwoserver v0031 or newer.
    v0.311 (2022-08-09)
  • Allow multiple instances (removed the lock-file).
  • Added command line switches to modify the 'PA' calculation (camera angle).
  • -a: constant angle [default=-120]
    -e: elevation sign { +1 , -1 } [default=-1]
    -r: rotator sign { +1 , -1 , 0 } [default=0]
    PA = angle + elsign*ELEVATION + rosign*ROTATORE
    v0.310 (2022-07-11)
  • Added the "aeg" command to the guider loop.
  • Horizontal/vertical layout selectable via the '-v' switch.
  • Removed the "legacy" pixel option.
  • v0.309 (2021-10-21)
  • Optics tests at SBS before shipping the Magellan guider prototype.
  • v0.300 (2021-03-12)
  • Forked from the andorguider code.

  • Screen Shots and Software Documenation

  • Startup
  • GUI Elements
  • Keyboard Commands
  • TCP/IP Interface


    Starting the GUI

    Startup the ZwoGcam GUI:
    ./gcamzwo -t2 -h raspberrypi

    "-m" mode:
    -m2: 1000x1000, 2x2 binned (500x500 GUI image)
    -m3: 1512x1512, 2x2 binned (504x504 GUI image)
    -m4: 2000x2000, 2x2 binned (500x500 GUI image)
    -m5: 2520x2520, 2x2 binned (504x504 GUI image)
    -mh: high resolution: 2048x2048, 1x1 binned (512x512 GUI image)
    -mf: full field: 2400x2400, 2x2 binned (600x600 GUI image)
    default: 1800x1800, 2x2 binned (600x600 GUI image)

    "-f" file
    load configuration from ASCII file containing one 'keyword value' pair per line; e.g. pfs.ini:
    host lab-pi-01: RaspberryPi host name ("-h")
    port 1: rotator port ("-p")
    mode 2: image geometry mode: 1000x1000 ("-m")
    gnum 3: guider number ("-g")
    gmode 4: guider mode ('gm')
    gmpar t: guider mode parameter ('gm')
    angle -128: "-a"
    elsign -1: "-e"
    rosign 0: "-r"
    parity -1: "-i"
    offx -10: "-o"
    offy 85: "-o"
    px 53: pixel scale [milli-arcsec] ('px')
    lmag: lupe magnification ('lmag')
    pct 60: percent scaling ('pct)
    bkg 24: background scaling ('bkg')
    span 5000: imacs scaling ('span')
    bx 41: guide box size ('bx')
    gain lo: amplifier gain ('gain')
    sw 6: slit width, used for fit in 'gm4' ('sw')
    sn 0.7: guider control loop sensitivity ('sn')

    "-h" host:
    hostname (IP number) of the zwoserver computer (RaspberryPi)

    "-t" telescope:
    -t2: Clay (host=mag2tcs, port=5801 or 5810+rotatorPort)
    -t1: Baade (host=mag1tcs, port=5801)
    -t0: no telescope [default]

    "-g" # {1,2,3}:
    guider (camera) number

    "-o" dx,dy :
    Window offset on the CMOS array.

    "-p" #
    rotator port. If set it will be used to calculate the TCS port (5810+rotatorPort).

    "-a" angle {-360..+360} : [default=-120]
    constant angle in the camera angle formula 'PA = angle +elsign*ELEVATION +rosign*ROTATORE'

    "-e" elsign { -1 , +1 , 0 }: [default=-1]
    elevation sign in the camera angle formula 'PA = angle +elsign*ELEVATION +rosign*ROTATORE'

    "-r" rosign { -1 , +1 , 0 }: [default=0]
    rotator sign in the camera angle formula 'PA = angle +elsign*ELEVATION +rosign*ROTATORE'

    "-i" parity { -1 , +1 }: [default=+1]
    Parity for the compass "L" display.

    "-v": vertical layout


    GUI Elements

    tf: exposure time, current time, frame number
    av: number of frames averaged
    send: seconds until next send; number of the last frame sent
    FpS: frames per second (acquisition, display, guiding)
    The maximum display frame rate may be throttled for better keyboard response time via the 'dt' command (default=5 Hz)
    Temp: CCD temperature [deg.Celsius] and cooler power [percent].


    Keyboard Commands

    F1
    stop guiding/calculating
    F2
    start calculating the guide corrections
    F3
    start guiding (send corrections to TCS)
    F4
    move the guide-box to the centeroid and then start calculating
    F5
    move the guide-box to the centeroid and the start guiding
    F9
    send 'gpfld#' to the TCSIS, where '#' is the value of '-g gnum'.
    F10
    send 'gpsha#' to the TCSIS, where '#' is the value of '-g gnum'.

    tf #
    set the exposure time to '#' seconds {0.01..30}
    av #
    Average '#' frames (for display and guiding, 0=off)
    dt #
    Throttle the display update frame rate to '#' Hz (default=5)

    apa [#]
    toggle auto-get position angle ('pa') from the TCSIS
    '#' is the optional update period in seconds (default=30)
    pa
    set the position angle manually
    mm #
    set mouse mode {1,2,-2,3}
    left click: move 1/10 of the distance (requires "Control" key)
    left click while holding down the right mouse button: move the full distance (requires "Control" key)
    1: move guider box to the mouse position
    2: move guider probe to the mouse position (not available for SV)
    -2: move the SH- and PR-probes and the telescope to the mouse position
    3: move the telescope to the mouse position

    gm #
    guider mode (paramter in 'gpaer' command when using mm-2 or mm2).

    sh #
    Shack-Hartman (mask) mode ('flag' in the header when sending data on port 5700).

    xys c x y
    set cursor 'c' to coordinate 'x,y'
    xyr c x y
    move cursor 'c' by 'x,y' pixels

    send [#]
    send the guider images to the 'SendHost' (Menu: GuiderX--SendHost) via TCP/IP every '#' seconds; '0' means 'off'.
    Without parameter the GUI will send one file.
    write [#]
    writes the next '#' images to disk as FITS files (default=1)

    tec {#,off}
    #: Turn on the temperature control at setpoint # [Celsius].
    off: Turn off the temperature control.

    gain {#,# #,lo,med,hi}
    #: set the gain {0..570} and leave the offset as is.
    # #: set the gain {0..570} and offset {0..80}.
    lo: sets the gain/offset to '0 10'.
    med: sets the gain/offset to '150 21'.
    hi: sets the gain/offset to '300 50'.

    sm #
    Smooth the displayed image using the box-car (4,2,1, weights) algorithm, running '#' iterations ('0' turns off the smoothing). Please note, this does not affect the guiding.

    sw #
    Set the slit width for the "gm4" fit (default=6 [pixels]).

    fm #
    Function mode: determines the action for the F1 and F3 keys
    fm1:
    F1: stop guiding
    F3: start guiding
    fm2:
    F1: save 'tf(F3)', 'av', 'send' parameters; then restore 'tf(F1)', av=0, send=0
    F3: save 'tf(F1)'; then restore 'tf(F3)', 'av' and 'send' paramters

    mask {on, off, #}
    "on": turn on hot pixel masking
    "off": turn off hot pixel masking
    "#": create a mask using cutoff of #-sigma above the average
    Please use the following procedure for creating a new mask:
    The mask will be stored in the home directory as a file named "zwoSERIALNUMBER_gggg.mask" and automatically loaded at startup of the zwogcam ('gggg' is the geometry).

    curcol {dark,light}
    dark: black cursor color
    light: light grey cursor color [default]
    magpix
    Toggle printing the value at the magnifier center pixel
    lmag {1,2,4}
    Set the magnification for the magnifier (lupe) window.

    exit
    Close the GUI immediately (without a confirmation dialog box).


    TCP/IP Interface

    The GUI is listening on port 52200+gnum.
    Each command must be terminated by a [LF] (ASCII=10, 0x0a, '\n') character. The response string will also be terminated by a [LF]. All communications are initiated by the client (your program).
    An easy way to test the interface is the 'nc' (netcat) utility. It can be run like a terminal emulator (^D terminates the connection) or be used in scripts:

    xterm> nc localhost 52201
    version
    0.332
    ^D
    xterm>

    Note: Most commands should work with the TCP/IP interface.

    fone
    equivalent of "F1" on the keyboard.
    returns "OK".
    fthr
    equivalent of "F3" on the keyboard.
    returns "OK".
    version
    returns "0.322"


    2021-11-09, Christoph C. Birk, Carnegie Observatories