GBT-MAC CONFIGURATION REFERENCE
================================

Version context
---------------
This reference describes the GBT-Mac configuration style used in the
current stable development branch, including:

- interactive PDP-8 terminal mode;
- BIN/RIM paper-tape upload;
- text upload to the Symbolic Editor;
- guided MACRO-8 assembly;
- capture of Symbolic Editor PUNCH output;
- up to 20 configurable operation slots.

The program is normally configured through a plain text file named
`gbt.conf`. The repository also contains `gbt.conf.example`, which is the
safe template to keep under version control. The user's local `gbt.conf`
should usually remain private and untracked, because it contains local
paths, serial-port names, and personal slot choices.


GENERAL DESCRIPTION
-------------------
GBT-Mac is a small terminal and paper-tape utility written to support the
use of a PDP-8, or a PDP-8-compatible machine such as OTTO, from a modern
macOS computer. It is not intended to be a general-purpose terminal
emulator. Its purpose is more specific: to reproduce, as faithfully as
possible, the practical functions once performed by a Teletype, a
paper-tape reader, and a paper-tape punch.

In normal terminal mode, GBT-Mac behaves like a simple serial terminal.
Characters typed on the Mac keyboard are sent to the PDP-8, and characters
received from the PDP-8 are displayed on the Mac screen. This is the mode
normally used with FOCAL, BASIC, ODT, the Symbolic Editor, or any program
expecting an interactive terminal. The terminal path usually operates in
7-bit ASCII, no parity, one stop bit.

The program also includes controlled file-transfer modes. A binary
paper-tape image, such as a RIM, BIN, MAINDEC, FOCAL, BASIC, or MACRO-8
tape, can be sent as an 8-bit stream. When the PDP-8 interface provides a
Reader Enable signal, GBT-Mac can use it as a pacing signal, sending each
byte only when the PDP-8 is ready. In the OTTO setup described here, this
signal is carried on CTS. This makes loading much more reliable than a
simple timed upload.

Text transfer is handled differently. When sending a source file to the
Symbolic Editor, the file is transmitted as ordinary 7-bit text, with
small delays between characters and a longer delay after each carriage
return. This imitates the behaviour of a human operator or a slow terminal
closely enough for the editor to keep up. Text files created on modern
systems may contain LF or CR/LF line endings; GBT-Mac can translate these
into the carriage returns expected by the PDP-8.

A special mode is provided for MACRO-8. This assembler has rather peculiar
paper-tape input requirements. A simple text upload is not sufficient:
MACRO-8 expects its source as a paper-tape stream with the high bit set. It
also performs its assembly in several passes and can produce either a
binary output tape or a listing. GBT-Mac therefore includes a guided
MACRO-8 workflow. It sends the source for the first pass, waits for the
operator when the PDP-8 stops, sends the source again while capturing the
generated binary tape, and can optionally perform the third pass to capture
the listing. The captured binary file can be given a synthetic leader,
while the listing is cleaned so that it becomes an ordinary text file usable
with modern editors.

GBT-Mac can also capture output produced by the PDP-8. This is useful, for
example, when the Symbolic Editor executes its PUNCH command. A practical
procedure is to issue the P command in the editor, let the PDP-8 stop,
select the capture slot in GBT-Mac, and then press CONT on the PDP-8. The
received characters are written to a file until the line becomes silent for
a configurable time, or until the user stops the capture manually.

In practice, GBT-Mac becomes a small software front panel for paper-tape
work. It does not try to hide the PDP-8 operating procedure: the user still
loads RIM, starts the Binary Loader, sets the switch register, presses ADDR
LOAD, CLEAR, CONT, or raises the required switches when the original
software expects it. What GBT-Mac does is remove the mechanical part of the
process. The paper tapes are files, the reader is paced by CTS, and the
punch can be captured directly into a modern text or binary file.

For the OTTO/PDP-8 configuration used here, the usual serial speed is 2400
baud. Interactive terminal and Symbolic Editor operations use 7N1. Binary
paper tapes and MACRO-8 assembly use 8N1. Reader Enable is normally
connected to CTS, with loose pacing rather than strict ON/OFF handshaking.


CONFIGURATION FILE FORMAT
-------------------------
The configuration file is a plain text file. It contains global parameters,
followed by optional local send/capture slots named [send1] to [send20].

Boolean parameters accept the following common forms:

    yes / no
    true / false
    on / off
    1 / 0

File paths may be absolute or relative. Relative paths are interpreted from
the directory where `gbt` is started. For example:

    file=./binaries/focal69.bin
    file=./sources/EXA1.ASM
    bin_file=./output/EXA1.BIN
    lst_file=./output/EXA1.LST

A typical configuration begins with global parameters:

    port=/dev/cu.PL2303G-USBtoUART1440
    baud=2400
    reader=none
    strict=no
    active_low=no
    byte_delay_ms=0
    char_delay_ms=5
    cr_delay_ms=100
    local_echo=no
    newline_to_cr=yes
    uppercase_tx=no
    uppercase_rx=no
    rx_hex=no
    append_log=no
    text_log_file=
    raw_log_file=
    bs_map=rubout
    del_map=rubout
    screen_color=green
    screen_bg=black
    command_prefix=ctrl-a
    macro8_source_mark_bit=yes


GLOBAL PARAMETERS
-----------------

port
    Values: serial device path
    Default: /dev/cu.usbserial-1430
    Serial port used by GBT-Mac. On macOS, the /dev/cu.* device is normally
    preferred over /dev/tty.*.

baud
    Values: integer
    Default: 2400
    Serial speed in baud. For the current PDP-8/OTTO setup, 2400 is normally
    used. 110 baud may also be possible with a suitable adapter and driver,
    but character format may require attention on a real ASR-33/KL8-E setup.

reader
    Values: none, cts, dsr, dcd, ri
    Default: none
    Selects which modem-control input is used as PDP-8 Reader Enable. For
    OTTO, cts is normally used for paper-tape input pacing.

strict
    Values: boolean
    Default: no
    If enabled, GBT waits not only for Reader Enable ON before each byte, but
    also for Reader Enable OFF after the byte. For OTTO, strict=no is usually
    better.

active_low
    Values: boolean
    Default: no
    Inverts the selected Reader Enable signal. Use only if the hardware
    interface asserts the control line low.

byte_delay_ms
    Values: integer
    Default: 0
    Delay after each byte during binary transfer. With CTS pacing this can
    usually be 0. With unpaced transfers, a small value may be useful.

char_delay_ms
    Values: integer
    Default: 5
    Delay after each normal character during text upload.

cr_delay_ms
    Values: integer
    Default: 100
    Delay after a carriage return during text upload. The Symbolic Editor
    often needs a longer delay after CR.

local_echo
    Values: boolean
    Default: no
    If enabled, characters typed locally are also echoed on the Mac terminal.

newline_to_cr
    Values: boolean
    Default: yes
    Converts text-file newlines to PDP-8 carriage returns. CR/LF pairs are
    sent as a single CR.

uppercase_tx
    Values: boolean
    Default: no
    Converts typed terminal characters and text uploads to uppercase before
    transmission. Raw binary transfers are not modified.

uppercase_rx
    Values: boolean
    Default: no
    Converts received display/log text to uppercase. Raw logging is not
    affected.

rx_hex
    Values: boolean
    Default: no
    Displays received bytes in hexadecimal form, useful for diagnostics.

append_log
    Values: boolean
    Default: no
    If enabled, text and raw logs are appended rather than overwritten.

text_log_file
    Values: file path
    Default: empty
    Optional text transcript file for received terminal output.

raw_log_file
    Values: file path
    Default: empty
    Optional raw received-byte log. This preserves the exact byte stream.

bs_map
    Values: rubout, backspace, left-arrow, none
    Default: rubout
    Defines what GBT sends when the Mac Backspace key is pressed.

del_map
    Values: rubout, backspace, left-arrow, none
    Default: rubout
    Defines what GBT sends when the Mac Delete key is pressed.

screen_color or color
    Values: mono, green, amber, cyan, white
    Default: green
    Foreground colour used by the local Mac terminal display. Nothing is sent
    to the PDP-8.

screen_bg, background, or bg
    Values: none, black, blue, green, amber, cyan, white
    Default: black
    Background colour used by the local Mac terminal display.

command_prefix or prefix
    Values: ctrl-a, ctrl-t, ctrl-g, ctrl-], esc, etc.
    Default: ctrl-a
    Local command prefix used by GBT inside terminal mode. The default is
    Ctrl-A, convenient on an Italian Mac keyboard.

macro8_source_mark_bit or source_mark_bit
    Values: boolean
    Default: yes
    Global default for MACRO-8 source transmission. When enabled, source
    characters are sent with bit 8 set, as required by MACRO-8 paper-tape
    input.


LOCAL SEND/CAPTURE SLOTS
------------------------
GBT-Mac supports up to twenty local operation slots, named [send1] through
[send20]. In terminal mode they are selected with the local command prefix:

    Ctrl-A 1..9     run slots 1..9
    Ctrl-A 0        run slot 10
    Ctrl-A a..j     run slots 11..20
    Ctrl-A s        ask for a slot number
    Ctrl-A ?        show the slot list
    Ctrl-A q        quit terminal mode
    Ctrl-A x        abort an active transfer or capture

A slot may contain display-only operational notes. These are shown only when
the slot is selected, not in the compact slot list:

    [send4]
    name=Assemble EXA1.ASM with MACRO-8
    #Switches: 7777
    #Start address: 0200
    #Notes: RIM destroyed by Binary Loader; reload RIM when needed

The equivalent key/value forms are also accepted:

    switches=7777
    start_address=0200
    notes=RIM destroyed


SLOT PARAMETERS
---------------

name
    Values: text
    Default: empty
    Human-readable name shown in the slot menu. It has no operational effect.

file
    Values: file path
    Default: empty
    Main input or output file for the slot. For mode=bin and mode=text, it is
    the file to send. For mode=capture, it may be the output file.

mode
    Values: text, bin, macro8_assemble, macro8, capture
    Default: empty
    Selects the slot operation. macro8 is accepted as a shorter alias for
    macro8_assemble.

data_bits
    Values: 7 or 8
    Default: mode-dependent
    Serial word length for the slot. Text and Symbolic Editor work normally
    use 7; binary paper tapes and MACRO-8 use 8.

reader
    Values: none, cts, dsr, dcd, ri
    Default: global default
    Per-slot Reader Enable source. Use cts for OTTO paper-tape pacing.

strict
    Values: boolean
    Default: no
    Per-slot strict Reader Enable handshake.

active_low
    Values: boolean
    Default: global default
    Per-slot inversion of the Reader Enable signal.

byte_delay_ms
    Values: integer
    Default: global default
    Per-slot delay after each binary byte.

char_delay_ms
    Values: integer
    Default: global default
    Per-slot delay after each text character or MACRO-8 source character.

cr_delay_ms
    Values: integer
    Default: global default
    Per-slot delay after carriage return.

newline_to_cr
    Values: boolean
    Default: yes
    For text uploads, converts LF or CR/LF text files to PDP-8 carriage
    returns.

uppercase_tx or uppercase
    Values: boolean
    Default: inherited global value
    Per-slot uppercase conversion for mode=text.

add_leader
    Values: boolean
    Default: no
    Adds a synthetic paper-tape leader before binary transmission, or before
    the captured MACRO-8 BIN file. The leader byte is octal 0200.

leader_len or leader_length
    Values: integer
    Default: 200
    Number of octal 0200 bytes used for the synthetic leader.

first_char_free
    Values: boolean
    Default: no; effective yes for MACRO-8
    Sends the first source character without waiting for Reader Enable. Used
    by the MACRO-8 workflow.

stop_at_dollar
    Values: boolean
    Default: no; effective yes for MACRO-8
    Stops source transmission after sending the $ end marker.

source_mark_bit, macro8_source_mark_bit, or mark_bit
    Values: boolean
    Default: global MACRO-8 default
    In MACRO-8 source transmission, forces bit 8 of each source character.

preserve_source, source_raw, or raw_source
    Values: boolean
    Default: yes
    In MACRO-8 mode, preserves the source tape byte stream rather than
    normalizing it as ordinary text.

free_leader, leader_free, or free_leader_runin
    Values: boolean
    Default: yes
    In MACRO-8 mode, sends the leading source-tape leader and the first real
    source character without waiting for Reader Enable. Pacing then resumes
    normally.

bin_file
    Values: file path
    Default: ASSEMBLED.BIN
    Output file for the binary produced during MACRO-8 pass 2.

lst_file, list_file, or listing_file
    Values: file path
    Default: ASSEMBLED.LST
    Output file for the listing produced during MACRO-8 pass 3.

listing or do_listing
    Values: boolean
    Default: yes
    Enables or disables the optional MACRO-8 listing pass.

capture_file
    Values: file path
    Default: empty
    Alternate output file for capture operations. In mode=capture, either
    file= or capture_file= may be used.

capture_mode
    Values: ascii7, raw8
    Default: based on data_bits
    Selects how received bytes are saved. ascii7 clears bit 8; raw8 preserves
    the byte exactly.

capture_stop
    Values: silence, manual
    Default: silence
    Selects how a capture is closed. silence closes after a quiet interval;
    manual waits for an abort/close key.

capture_silence_ms
    Values: integer
    Default: 3000
    Quiet interval, in milliseconds, used when capture_stop=silence.

strip_nul, strip_null, strip_nulls, remove_nul, or remove_nulls
    Values: boolean
    Default: no
    Removes NUL bytes from a saved capture file. Useful for Symbolic Editor
    PUNCH output where paper-tape leader/trailer may appear as NULs after
    7-bit conversion.

switches or sw
    Values: text
    Default: empty
    Display-only note for required switch-register contents.

start_address, start_addr, start, or address
    Values: text
    Default: empty
    Display-only note for the required PDP-8 start address.

notes, note, comment, or comments
    Values: text
    Default: empty
    Display-only operational note shown when the slot is selected.


SLOT MODES
----------

mode=text
~~~~~~~~~
Sends an ASCII text file in 7N1. This is the appropriate mode for feeding
the Symbolic Editor. It normally uses reader=none, newline_to_cr=yes, and
small character delays.

Example:

    [send2]
    name=Source to Symbolic Editor
    file=./sources/SOURCE.TXT
    mode=text
    data_bits=7
    reader=none
    uppercase_tx=yes
    newline_to_cr=yes
    char_delay_ms=5
    cr_delay_ms=100

mode=bin
~~~~~~~~
Sends a raw paper-tape image, normally in 8N1. It may be sent with timing
only, or paced by Reader Enable.

Example:

    [send3]
    name=FOCAL 69 BIN
    file=./binaries/focal69.bin
    mode=bin
    data_bits=8
    reader=cts
    strict=no
    byte_delay_ms=0
    add_leader=yes
    leader_len=200

mode=macro8_assemble
~~~~~~~~~~~~~~~~~~~~
Performs a guided MACRO-8 assembly. GBT sends the source for pass 1, waits
for the operator, sends it again for pass 2 while capturing the binary, and
optionally performs pass 3 while capturing the listing.

The source is sent in 8N1 with bit 8 marked, matching the working DOS GBT
behaviour. Source leader handling is deliberately special: leading
blank-tape bytes and the first real source character are sent without
waiting for Reader Enable; after that, CTS pacing is used.

Example:

    [send4]
    name=Assemble EXA1.ASM with MACRO-8
    #Switches: 7777
    #Start address: 0200
    #Notes: RIM destroyed by Binary Loader; reload RIM when needed
    file=./sources/EXA1.ASM
    mode=macro8_assemble
    reader=cts
    strict=no
    active_low=no
    byte_delay_ms=0
    first_char_free=yes
    stop_at_dollar=yes
    source_mark_bit=yes
    preserve_source=yes
    free_leader=yes
    uppercase_tx=no
    newline_to_cr=no
    char_delay_ms=5
    cr_delay_ms=100
    bin_file=./output/EXA1.BIN
    lst_file=./output/EXA1.LST
    listing=yes
    add_leader=yes
    leader_len=200
    capture_stop=silence
    capture_silence_ms=3000

mode=capture
~~~~~~~~~~~~
Records received serial output on demand. It is useful for saving the output
of the Symbolic Editor PUNCH command.

A practical procedure is:

    1. Give the P command in the Symbolic Editor and press CR.
    2. Let the PDP-8 stop.
    3. Start the capture slot in GBT-Mac.
    4. Press CONT on the PDP-8.
    5. GBT-Mac closes the capture after the configured silence interval.

Example:

    [send9]
    name=Capture Symbolic Editor PUNCH
    #Notes: Give P <CR>; when the editor halts, start this slot, then press CONT
    file=./sources/PUNCHED.TXT
    mode=capture
    data_bits=7
    capture_mode=ascii7
    capture_stop=silence
    capture_silence_ms=3000
    strip_nul=yes

For a binary capture, use for example:

    data_bits=8
    capture_mode=raw8
    strip_nul=no


COMMAND-LINE OPTIONS
--------------------
Most work is normally done through gbt.conf, but GBT-Mac also accepts
command-line options. Command-line options override values read from the
configuration file.

--help, -h
    Shows the built-in help text.

--config <file>
    Selects an alternate configuration file.

--write-config
    Writes the current configuration to the selected config file.

--port <device>
    Overrides the serial port.

--baud <rate>
    Overrides the baud rate.

--terminal
    Starts interactive terminal mode.

--list-ports
    Lists available serial ports.

--test-console
    Shows raw keyboard codes for local console diagnostics.

--test-modem
    Monitors modem-control inputs such as CTS, DSR, DCD, and RI.

--test-rtscts
    Toggles RTS and reads modem inputs; useful for checking RTS/CTS loopback.

--send-text <file>
    Sends a text file directly, without entering terminal mode.

--send-bin <file>
    Sends a binary paper-tape image directly, without entering terminal mode.

--reader <none|cts|dsr|dcd|ri>
    Selects the Reader Enable input for direct transfer.

--strict
    Enables strict Reader Enable ON/OFF handshaking.

--active-low
    Inverts the Reader Enable input.

--byte-delay <milliseconds>
    Sets the binary byte delay for direct transfers.

--add-leader
    Adds a synthetic octal 0200 leader before a direct binary transfer.

--leader-len <n>, --leader-length <n>
    Sets the number of bytes in the synthetic leader.

--char-delay <milliseconds>
    Sets the normal text character delay.

--cr-delay <milliseconds>
    Sets the carriage-return delay.

--log <file>
    Saves a 7-bit text transcript of received terminal output.

--raw-log <file>
    Saves raw received bytes.

--append-log
    Appends to existing log files instead of overwriting them.

--local-echo
    Enables local echo.

--no-newline-to-cr
    Disables automatic newline-to-carriage-return conversion.

--uppercase
    Enables uppercase conversion for transmitted terminal/text characters.

--uppercase-rx
    Enables uppercase conversion for displayed/logged received text.

--rx-hex
    Displays received bytes in hexadecimal form.

--bs-map <rubout|backspace|left-arrow|none>
    Overrides Backspace key mapping.

--del-map <rubout|backspace|left-arrow|none>
    Overrides Delete key mapping.

--color <mono|green|amber|cyan|white>
    Selects the local terminal foreground colour.

--background <value>, --bg <value>
    Selects the local terminal background colour. Typical values are none,
    black, blue, green, amber, cyan, and white.

--prefix <value>
    Overrides the local command prefix, for example ctrl-a, ctrl-t, ctrl-g,
    ctrl-], or esc.


COMMAND-LINE EXAMPLES
---------------------

Start terminal mode:

    ./build/gbt --terminal

List serial ports:

    ./build/gbt --list-ports

Monitor modem-control signals:

    ./build/gbt --test-modem

Send a text file to the Symbolic Editor:

    ./build/gbt --send-text ./sources/SOURCE.TXT --char-delay 5 --cr-delay 100 --uppercase

Send a BIN/RIM paper tape with CTS pacing and a synthetic leader:

    ./build/gbt --send-bin ./binaries/focal69.bin --reader cts --add-leader --leader-len 200


PRACTICAL OTTO/PDP-8 DEFAULTS
-----------------------------
For the OTTO/PDP-8 setup described here, the most useful practical defaults
are:

    baud=2400
    reader=cts
    strict=no
    active_low=no
    byte_delay_ms=0
    char_delay_ms=5
    cr_delay_ms=100
    command_prefix=ctrl-a

Terminal and Symbolic Editor text operations use 7N1. BIN/RIM paper tapes,
MACRO-8 assembly, and raw captures use 8N1 when the high bit is significant.


NOTES ON WINDOWS PORTABILITY
----------------------------
The current implementation described here runs on macOS. Most of the
program is written in portable C++, but the low-level serial and console
layers are platform-dependent. A Windows version should be possible by
replacing the POSIX/termios serial code with the corresponding Win32 serial
API. It should therefore be considered feasible, but not part of the current
macOS version unless actually implemented and tested.

