Whistle InterJet front panel -- control map
===========================================

The panel is a serial terminal on com1 (NetBSD's com1, 0x2f8; the BIOS and
DOS call this port COM2) at 57600 8N1.  20 characters by 8 rows of text.
The keypad sends plain 7-bit ASCII back down the same wire -- one wire, so
anything you echo back is a COMMAND, not an echo.

Sources, and why the column matters
-----------------------------------
  sheet     Archie Cobbs' cheat sheet, as published on this site
  log       minicom experiments on real hardware
  BIOS      the machine's own firmware, dumped and disassembled; it speaks
            this protocol at every power-on
  paneld    Whistle's own panel daemon, from a recovered WhistleWare 3.0.3
            disk, disassembled
  hw        measured on a live panel

  Every code with two independent sources works.  The only code the cheat
  sheet gives alone (^F / ^G) is the only one that does nothing.


TEXT CODES
----------
  ^L   0x0c   clear the screen                     sheet + log     works
  ^H   0x08   back one column, non-destructive     sheet + log     works
  ^I   0x09   horizontal tab, 8-column stops       sheet + log     works
  ^J   0x0a   down one row                         log             CR+LF works
  CR   0x0d   carriage return, NO linefeed         log             works

  ^O   0x0f   INVERTED TEXT ON   (sets, not toggles)   hw + BIOS   works
  ^N   0x0e   INVERTED TEXT OFF                        hw + BIOS   works

       The published cheat sheet gives ^F and ^G for these.  They have NO
       EFFECT.  Note also that the polarity is the opposite of ECMA-35's
       SO/SI, so a reader who assumes the standard gets it backwards.

       INVERSION SURVIVES A REBOOT.  Only ^N or a power cycle clears it.
       Anything you write must send ^N when it opens the port, or a crash
       leaves the panel inverted permanently.

  0x1e, 0x1f are NOT control codes.  Each prints a glyph.


CODES THAT TAKE AN ARGUMENT
---------------------------
  Each of these consumes the bytes that follow.  Send one blind and it
  swallows whatever text comes next, and can leave the firmware waiting.

  ^A   0x01  <col>            set X, 0 to 127      sheet + paneld
  ^B   0x02  <page>           set Y page, 0 to 7   sheet+log+paneld
  ^C   0x03  <n> <n bytes>    write n bitmap bytes sheet+log+paneld
  ^D   0x04  <mask>           front-panel LEDs     log + paneld

       ^A and ^B DO position text as well as graphics: the vendor's own
       factory test paints four rows with ^B <row> / ^A <4 + 6*col> and
       emits no CR or LF at all.


ESCAPE SEQUENCES -- READ THIS BEFORE SENDING ANY
------------------------------------------------
  ESC W   1b 57   ARMS A HARDWARE WATCHDOG.  The machine RESETS after ten
                  seconds of serial silence.  Never send this, and never
                  write a tool that sweeps escape sequences at this panel.
                  There is no version of that experiment worth running.

  ESC X   1b 58   POWER OFF -- one bit away from ESC W.  What it does
                  depends on the mains:
                    mains present  the panel acks, then a power CYCLE
                    mains absent   immediate power off, and it stays off

  ESC C   1b 43   Unknown.  The BIOS emits it once, right after the POST
                  counter stops backspacing.  Never sent by this project.


GRAPHICS GEOMETRY
-----------------
  It is a 128 x 64 pixel graphics LCD, not a character display.

  Framebuffer      1024 bytes = 128 columns x 8 pages
  Byte index       x + (y >> 3) * 128
  Bit in the byte  1 << (y & 7)   -- BIT 0 IS THE TOP PIXEL OF THE PAGE
  Page 0           the TOP eight pixel rows
  Character cell   6 x 8; LcdTextPosn(col,row) puts the pen at
                   x = col * 6 + 4, y = row * 8 + 7

  So there are exactly EIGHT text rows and none of them is short.

  Clip your own drawing.  The firmware "goes nutty" if you draw off the
  screen, in the original author's words.  X: 0-127.  Y: 0-7 in PAGES, not
  pixels.  For ^C n, require x + n <= 128.

  Getting the bit order wrong produces a display that is plausibly wrong
  rather than obviously wrong, which is why it is stated here: bit 0 is the
  top.


KEYPAD
------
  Plain 7-bit ASCII.  No scan codes, no escape sequences, no modifiers.

  Enter          0x0d
  X (Cancel)     0x09   -- DELETE on a non-empty field; Cancel only on an
                           empty one.  That is the vendor's design.
  Backspace      0x08   -- for a terminal plugged in instead of the keypad
  *              0x2a
  #              0x23
  softkey 1  ^   0x5e
  softkey 2  v   0x76   (lower-case vee)
  softkey 3  <   0x3c
  softkey 4  >   0x3e

  2-5-8 is a FORCED POWER DOWN.  It signals nothing -- no modem-control
  line moves -- so the operating system gets no warning at all.  Sync first.


TWO TRAPS WHEN WRITING CODE FOR THIS PORT
-----------------------------------------
  1. The port must already be OPEN when stty runs.  A first open resets
     termios to B9600, so "stty -f /dev/dty01 ..." against a closed port
     configures nothing that outlives the command.  Hold the descriptor and
     point stty at it.

  2. isig must be OFF.  The keypad shares this line, so a stray 0x03 from
     the panel would SIGINT whatever is reading it.

  There is NO READBACK.  The keypad is the only return path and it reports
  keystrokes, not screen contents, so nothing can self-test this panel.  A
  probe must WRITE FIRST and ASK SECOND, or the operator answers about the
  previous state.


WHAT THIS IS EVIDENCE OF
------------------------
  paneld and the BIOS are evidence of what Whistle's SOFTWARE SENT.  The
  AT89C2051 firmware on the panel in front of you has never been dumped.
  The two are very likely the same -- a cheat sheet and two binaries
  agreeing independently is a strong pair -- but the gap is real.