If you don't want the PiDP-8/I GPIO thread to run while your script
runs, pass True here instead, since this is the "skip GPIO" flag,
and its default is therefore False.  We do that from programs like
`os8-run` and `os8-cp` because we want them to run everywhere, even on
an RPi while another simulator is running; we also don't want the front
panel switches to affect these programs' operations.  If your program
never runs on an RPi, passing True here might make it run a bit faster,
since it doesn't try to start the useless GPIO thread, feed it data,
or pull data is is expected to provide back into the simulator.


## Logging

The next step is to tell the `s` object where to send its logging
output:

................................................................................
This shows one of the most-used methods, `simh.send_cmd`, which sends a
line of text along with a carriage return to the spawned child program,
which again is `pidp8i-sim`.


## Driving SIMH and OS/8

After the simulator starts up, we want to wait for an OS/8 `.` prompt
and then send the first OS/8 command to start our demo. We use the
`simh.os8_send_cmd` method for that:

    s.os8_send_cmd ('\\.', "R TECO")

This method differs from `send_cmd` in a couple of key ways.

................................................................................

(See the commentary for `simh._kbd_delay` if you want to know how that
delay value was calculated.)

The bulk of `teco-pi-demo` consists of more calls to `simh.os8_send_cmd`
and `simh.send_cmd`. Read the script if you want more examples.

**IMPORTANT:** The `\\.` syntax for specifying the OS/8 `.` command
prompt is tricky. If you pass just `'.'` here instead, Python's
[regular expression][re] matching engine will interpret it to mean
that it should match *any* character as the prompt, almost certainly
breaking your script's state machine, since it is likely to cause the
call to return too early. If you instead pass `'\.'`, Python's string
parser will take the backslash as escaping the period and again pass
just a single period character to the regex engine, giving the same
................................................................................

You can usually avoid the need for that delay by waiting for an OS/8
command prompt before escaping to SIMH, since that is a reliable
indicator that OS/8 is in such an interruptible state.

You don't see these anomalies when using OS/8 interactively because
humans aren't fast enough to type commands at OS/8 fast enough to cause
the problem.  That is doubtless why there this bug still exists in OS/8
in 2017.


### Re-Entering

If your use of OS/8 is such that all required state is saved to disk
before re-entering OS/8, you can call the `simh.os8_restart` method to
................................................................................

[ssc]: https://tangentsoft.com/pidp8i/file/lib/simh.py
[dsc]: https://tangentsoft.com/pidp8i/file/lib/pidp8i/dirs.py


## <a id="license" name="credits"></a>Credits and License

Written by and copyright © 2017 by Warren Young. Licensed under the
terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

If you don't want the PiDP-8/I GPIO thread to run while your script
runs, pass True here instead, since this is the "skip GPIO" flag,
and its default is therefore False.  We do that from programs like
`os8-run` and `os8-cp` because we want them to run everywhere, even on
an RPi while another simulator is running; we also don't want the front
panel switches to affect these programs' operations.  If your program
never runs on an RPi, passing True here will usuall make it run faster,
since the GPIO thread saps computer resources and so shouldn’t be
started if it isn’t needed.


## Logging

The next step is to tell the `s` object where to send its logging
output:

................................................................................
This shows one of the most-used methods, `simh.send_cmd`, which sends a
line of text along with a carriage return to the spawned child program,
which again is `pidp8i-sim`.


## Driving SIMH and OS/8

After the simulator starts up, we want to wait for an OS/8 “`.`” prompt
and then send the first OS/8 command to start our demo. We use the
`simh.os8_send_cmd` method for that:

    s.os8_send_cmd ('\\.', "R TECO")

This method differs from `send_cmd` in a couple of key ways.

................................................................................

(See the commentary for `simh._kbd_delay` if you want to know how that
delay value was calculated.)

The bulk of `teco-pi-demo` consists of more calls to `simh.os8_send_cmd`
and `simh.send_cmd`. Read the script if you want more examples.

**IMPORTANT:** The “`\\.`” syntax for specifying the OS/8 `.` command
prompt is tricky. If you pass just `'.'` here instead, Python's
[regular expression][re] matching engine will interpret it to mean
that it should match *any* character as the prompt, almost certainly
breaking your script's state machine, since it is likely to cause the
call to return too early. If you instead pass `'\.'`, Python's string
parser will take the backslash as escaping the period and again pass
just a single period character to the regex engine, giving the same
................................................................................

You can usually avoid the need for that delay by waiting for an OS/8
command prompt before escaping to SIMH, since that is a reliable
indicator that OS/8 is in such an interruptible state.

You don't see these anomalies when using OS/8 interactively because
humans aren't fast enough to type commands at OS/8 fast enough to cause
the problem.  That is doubtless why this bug still exists in OS/8
in 2017.


### Re-Entering

If your use of OS/8 is such that all required state is saved to disk
before re-entering OS/8, you can call the `simh.os8_restart` method to
................................................................................

[ssc]: https://tangentsoft.com/pidp8i/file/lib/simh.py
[dsc]: https://tangentsoft.com/pidp8i/file/lib/pidp8i/dirs.py


## <a id="license" name="credits"></a>Credits and License

Written by and copyright © 2017-2019 by Warren Young. Licensed under the
terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md