Document Apple II SSC setup

[pneubauer]

Setup on the Apple II needs better documentation. For example:

• The SSC must be in slot 2, but the release notes don't mention this.
• The SSC must have interrupts enabled (DIP switch on the card), but the release notes don't mention this.
• The SSC has DIP switches for various serial port settings. PLATOTerm doesn't use these settings, but the release notes don't mention this.
• Setup in an emulator requires multiple steps (see Does not connect on Apple II emulator. #13), and these steps need to be documented somewhere.

I'm happy to write this documentation. What's the preferred format (text, Markdown, HTML) and location (convention or organization or platform-specific documentation)?

[tschak909]

Markdown, and I will put it in the documentation when I cut a release.

Thanks. :)

Should I make the ability to change SSC slot? I've never seen anyone use it anywhere but slot 2, and the IIc/IIc+/Laser 128xxx machines all keep the serial port on slot 2.

Also worth mentioning, the terminal makes judicious use of RTS and CTS for flow control, so your WIFI modem should be cabled and use this, if possible.

[tschak909]

FWIW, I am literally developing all of these in emulation, and I release it when it works, so, thanks for filling in the much needed details on actual hardwre. I can't thank you, enough.

[pneubauer]

[Edited 14 June 2019 to correct notes about SW1-7 and SW2-7.]

That's an important comment about hardware flow control. For the benefit of others, here are few details on SSC setup:

• The Apple Super Serial Card (SSC) must be in slot 2.
• Interrupts Enabled: On the SSC, ensure that switch SW2-6 is CLOSED to enable interrupts.
• RS-232-C Signals: Ensure that switch SW2-7 is OPEN and SW1-7 is CLOSED to enable normal CTS and DCD signals. [Edited 14 June 2019]
• Enable hardware flow control on the modem. "AT&K3" will usually do this, but consult your modem's manual.

Without flow control working, PLATOTerm tends to hang or corrupt drawings.

[tschak909]

Am curious, what Apple II system are you using to test? In theory PLATOTERM should work even on a II+ with 48K of RAM, and this works in emulation (this is why the ESC ESC key combo was added, to act as a shift-lock.

[pneubauer]

I'm using an enhanced (platinum) Apple IIe. I don't have a II+, but I can test some other machines (unenhanced IIe, IIc, IIc+, IIgs).

[tschak909]

oo, if you do... then I actually have a DHGR build of PLATOTERM that Michael Sternberg has been working on... it increases the resolution considerably.
PLATOTERM-DHGR.zip

[michaelsternberg]

I was under the impression that on the SSC, while the DIP switches provide a default, settings can also be configured in software. For example, there's DIP switches to set the baud rate, stop bits, etc, but these can obviously changed by software. However, I'm not an expert and there may be some settings that can not be changed in software. I'll read through the Super Serial Card manual and review cc65's serial card functions.

Most of my testing has been done on a real IIc or IIc+ and things have tended to work or perhaps I've become accustomed to some idiosyncrasies. For example, I have a "change your password" reminder that appears upon login and I know I have to wait 25 seconds before I can progress beyond it.

If running the DHGR version, a monochrome monitor provides the best display. On a color monitor, inhibit the chroma signal by turning down the color.

To provide a network connection, I use a Serial-to-USB cable setup similar to ADT-Pro to connect the Apple II and a Linux computer. After the PLATOTerm title screen appears on the Apple II, on the Linux computer I run:
socat /dev/ttyUSB0,b1200,echo=0,raw tcp:irata.online:8005

[pneubauer]

Many of the SSC DIP switches provide default settings that software can (and often does) override. However, there are a few SSC DIP switches (mentioned in my previous comment) that software cannot override. Take a look at the schematic in your Super Serial Card manual (page 100). I looked at the PLATOTerm and cc65 serial code, and I don't see anything amiss.

The IIc/IIc+ don't have these DIP switches. See Figure 11-37 of the Apple IIc Tech Ref (2nd edition).

[pneubauer]

I don't think hardware flow control works on the IIc/IIc+. Per Figure 11-37 of the Apple IIc Tech Ref (2nd edition), the CTS signals are pulled low internally and not available on the external connector. Instead, the IIc/IIc+ support DTR/DSR handshaking controlled via the ACIA's RTS/DCD lines. The CC65 serial driver doesn't currently support this arrangement. Just in case this isn't complicated enough, http://adtpro.sourceforge.net/connectionsserial.html notes that many standard IIc serial cables disconnect the hardware handshaking lines entirely.

[tschak909]

Well, shit.

…

-Thom

On Mon, Jun 17, 2019 at 4:46 PM Peter Neubauer ***@***.***> wrote: I don't think hardware flow control works on the IIc/IIc+. Per Figure 11-37 of the Apple IIc Tech Ref (2nd edition), the CTS signals are pulled low internally and not available on the external connector. Instead, the IIc/IIc+ support DTR/DSR handshaking controlled via the ACIA's RTS/DCD lines. The CC65 serial driver doesn't currently support this arrangement. Just in case this isn't complicated enough, http://adtpro.sourceforge.net/connectionsserial.html notes that many standard IIc serial cables disconnect the hardware handshaking lines entirely. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#30?email_source=notifications&email_token=AAVBYZX2OOR2UBQNM5DQV6LP3AA2LA5CNFSM4HOXTG7KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODX4RKKQ#issuecomment-502863146>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAVBYZUZJ7SF522LHDTQUHLP3AA2LANCNFSM4HOXTG7A> .

[pneubauer]

Yep. OTOH, at least one person is using the software on a IIc, so I guess the buffer overruns are somewhat infrequent.

I think the "path forward" includes:

1. Modify the cc65 serial driver to detect the IIc/IIc+ and support the alternative handshaking signals.
2. Update documentation to recommend a cable with handshaking lines connected.
3. Collect stats on buffer usage. Maybe we can make the buffer large enough to minimize overruns. The PLATO protocol-level flow control still works, so maybe we can tune the thresholds to avoid overruns.
4. I know the PLATO protocol is stateful. Is there a way to reset/resynchronize the protocol state? In other words, if a buffer overrun does occur, can the software recover?

[tschak909]

Well, there are two things:

(1) I need to add support for switching between PLATO and TTY mode, if needed.

But once in PLATO mode, the way the PLATO protocol works is that typically there are primary modes (0, 1, 2, 3, and 4 for dot, line, alpha, and block erase respectively), and each of those can have various sub modes.

The protocol is designed as such that usually if there is a slip, there will be a slight glitch, that can cause display corruption until the next mode is set.

I know Mike Sternberg (16kram) has run this on a IIc+, am wondering if he just ran at 1200 baud and said #*%@ it? ;)

-Thom

[colinleroy]

Chiming in a few years later,

I don't think hardware flow control works on the IIc/IIc+. Per Figure 11-37 of the Apple IIc Tech Ref (2nd edition), the CTS signals are pulled low internally and not available on the external connector. Instead, the IIc/IIc+ support DTR/DSR handshaking controlled via the ACIA's RTS/DCD lines. The CC65 serial driver doesn't currently support this arrangement.

I think that's false. Experiencing with real hardware empirically shows that this works (data loss with a stupid RX/TX/Gnd cable, no data loss with a fully wired cable); verifying the code of cc65's serial driver does hardware flow control using RTS, flipping bit 3 of the command register to set RTS low or high (see https://github.com/cc65/cc65/blob/master/libsrc/apple2/ser/a2.ssc.s#L287)