0.0 Introduction and History They say necessity is the mother of invention, and this piece of code is no exception. Several months ago, after reflecting on the success of YAZI, George and I started talking about how we would like to use our Newtons. The bottom line seemed to be that we wanted to be able to use them as "wee little computers" that we could take with us anywhere. Since we spend most of our time playing on Un*x boxes, it seems natural to use VT100 as our standard interface to the various tools we use. Unfortunately, we were underwhelmed (if that's a word) with the available products. The biggest problem is that they were far too slow -- they would timeout before we could login! The other problem was that the other products just cost too much. So, instead, we spent several months writing our own! We designed PT100 for ourselves: to provide basic VT100 support in a small, fast, inexpensive product. Non-critical features have been excluded. If you feel something important is missing, please drop us a line so we can discuss the new feature. As you read through the following documentation, realize that we originally designed this product for ourselves, to solve problems we were having, and have more recently begun to support various options other folks may want. If something critical to your application is missing, please drop us a line so we can discuss how to remedy the oversight. 1.0 About PT100 PT100 is a VT100 emulator for the Newton, capable of Modem, Direct Serial and Telnet sessions. VT100 emulation is the most common text-based interface on the Internet, as well as the standard used by BBSes, corporate systems, various email mechanisms and many online services. In addition, it is useful for many types of straight serial connectivity. PT100 is the only VT100 emulator on the Newton capable of providing Telnet capability with Newton Internet Enabler (NIE). PT100 requires Newton OS 2.X and supports and takes advantage of many of the advanced features of the eMate 300 and the MP2000. . For telnet access, an MP130, MP2000 or an eMate 300 is recommended. PT100 ©1997 Scrawl. All Rights Reserved. PT100 was written by George Madrid and Sanjay Vakil. 2.0 Setup a Session To set up a session, click on the info button and select Edit Sessions. If you have not already created a session, a blank one will appear for you to edit. You can change the session that your are editing by clicking on the Session popup. The routing button (envelope) allows you to copy the current session, delete it, or create a new blank session. Once you have selected the session to edit, you will need to name it, and select the Type (Modem, Direct Serial or Telnet). If you wish, you can enter your username and password to have them available for quick input. The password will be encrypted on the Newton and will be decrypted before it is sent. If you are paranoid, don't enter a password at all. A password can easily be entered manually. Based on the type of session you selected, additional options will appear, specific to the type of session. See the next sections on additional information that might be necessary. 2.1 Setting up a Modem Session For a Modem Session, you will need to enter a phone number and the various modem parameters. If these are not correctly set, you may not be able to connect. However, incorrect parameters should not damage your Newton or your modem, so you may want to experiment to get the correct values. Reasonable values for this parameters are as follows: Speed: the fastest rate that you modem can handle (if necessary, the modem will slow down to the speed of the service automatically) Flow Control: Hardware Error Correction: Selected Data Bits / Parity / Stop Bits: Common triplets are 8N1 and 7E1 If you are unsure about the correct parameters, try contacting the service you intend to connect with to determine their suggested parameters, or experiment. 2.2 Setting up a Direct Serial Session For a Direct Serial Session, you will need to set a number of serial parameters. If these are not correctly set, you may receive garbled output, if any at all. However, incorrect parameters should not damage your Newton or the other device, so you may to experiment to get the correct values. Reasonable values for this parameters are as follows: Speed: Read the manual for the device with which you are connecting. Or, if you built it yourself, you should know (: Flow Control: Hardware if you are using a full RS232 connection, software if you only have a 2 or 3 wire connection. Data Bits / Parity / Stop Bits: Common triplets are 8N1 and 7E1 If you are unsure about the correct parameters, try consulting the manual of the device with which you intend to connect. In addition, you can explicitly select the serial port that you wish to use. On current Newtons, this can involve selecting between the external serial port and the PC card slot(s). This can be very useful if you need to connect directly to PC card devices, such as oddball cellular modems. Astute users will note that "IR Port" appears on the list. We make no guarantees about what this will do. We'd love to know if you get it to do something useful! 2.3 Setting up a Telnet Session For a Telnet Session, you will need to select a machine name to telnet to, and a port number. You should enter the full machine name, including the domain, for example "sanj-o-matic.mit.edu". An IP address (for example 127.0.0.0) associated with the machine name is looked up by the Newton. If you know the machineŐs IP address, you can enter it instead of the name. A port number is a numeric identifier of the specific TCP/IP port to which you wish to connect. The standard port number for telnet is 23, though if you want to do cool things like getting to finger (79), smtp (25), or web (80) port, you can select that instead. The other setup options for Telnet Sessions (phone numbers, ISP, etc.) are controlled by the Newton Internet Enabler (NIE). Consult your NIE documentation and setup program for additional information. 2.4 Session Setup Tips A new session created by using Blank Session will default to a standard set of options. If you have already created a working session tailored to your specific modem, Newton and service combination, it may be faster to simply use Duplicate Session to create a new session. You only need to update the options that are different, such as the username and password. If you have differing users of the same Newton, you can create a different session for each user. Make sure you name each session in a way that makes it apparent which user's session it is. 3.0 Connect to a Service To connect to a service, tap on Connect on the status line. A slip will appear, from which you can select a session. If you need to edit the calling slip to use a calling card or attach a prefix before dialing, click the Assist button. Once you have selected the session you wish to connect to, press Connect on the slip. The progress of the connection status will appear on the slip. If you are connecting with a Telnet Session, clicking Connect will pop up the NIE slip box, in which you can select your service provider and associated phone number. Click the Connect button on the NIE slip to initiate the call. 4.0 Disconnect from a Service To disconnect from a service, tap Hangup in the Action Button. A slip will appear, showing the connection being broken, and will prompt you when the Newton is available to connect once more. Exiting PT100 will also disconnect. Note that you will have to disconnect before your Newton will turn off. 5.0 Inputing Data There are several ways to input data in PT100. The easiest (and default) manner is to write words onto the input line. For control codes and difficult-to-write characters, you can use an onscreen or hardware keyboard. Finally, you can choose to have no onscreen input area at all. To switch between the different modes, press the Keyboard icon on the status bar. 5.1 Using the Input Line To use the input line, simply write what you wish to send, and press Send. The popup diamond allows quick access to an editable set of common words. The word you select will be appended to the input line. This list also allows you to easily send your username and password. The size of the input line can be changed in the Prefs, available from the info button. 5.2 Editing the Popup List To edit the list of words, click on the diamond and select Edit List. A slip will appear to allow you to edit individual words. To add a new entry, write it on the input line and press Add. To examine the list, click on Available Words. To delete an entry, select it with Available Words and then press Delete. 5.3 Using the Onscreen Keyboard To use the onscreen keyboard, select Keyboard from the Keyboard button on the status line. Simply type on the keyboard as you normally would. The alt key will prefix an ESC to a keystroke for Un*x users. The QuickPicker is available (and very useful) when using the onscreen keyboard. 5.4 Using the Hardware Keyboard A hardware keyboard can be used in two ways with PT100. It can be used either to type into the input line (buffered), or to directly send characters (unbuffered). For buffered input, simply select the input line and type away. For unbuffered input, select Keyboard or None from the Keyboard button on the status line and type normally. The alt key will prefix an ESC to a keystroke for Un*x users, and an ESC on its own can be created with CTRL-[. 5.5 Using the QuickPicker On the status line, there is a popup diamond that allows access to common words used with the input line. Selecting an entry from this list sends it directly to the session, without having to press Send. The last few lines of the QuickPicker work differently than the editable ones. After the dotted line will be the most recently sent string, either selected with the QuickPicker, or sent with the Input Line. The next two entries will send your username or password. Be wary -- sending a password at the wrong time will blast it to the screen. The QuickPicker is particularly handy if you have the input area minimized to allow full-screen viewing. 5.6 Sending Returns with the Send Button After you write something on the input line, you can choose to have it sent with a carriage return appended or without . To toggle between these two modes, press the Return arrow next to Send. When it is lit a carriage return will be sent with both the QuickPicker and the input line. 5.7 Input Tips Since it is quick and easy to change the words in the QuickPicker, it makes sense to modify it regularly to make it useful from session to session. If you use a command regularly, write it into the input line, press Edit Sessions and then Add. In a few short taps you've added a new entry to the QuickPicker. For many users, having quick access to a space character is useful. Adding this to the QuickPicker looks odd (it's an empty line!), but can save you from pulling up the keyboard regularly. 5.8 Advanced Input: Parsing Text input can be parsed to allow control characters to be sent without using the keyboard. A circumflex indicates that a control character should be sent, so that ^g will send the Bell, and ^[ will send ESC. This can be very useful for sending control codes when you don't have keyboard connected. Text input that contains material inside double-quotes will ignore anything outside the quotes. This can be very useful, as it allows you to label commands that contain fancy control information: save: "^x^s" load: "^x^f" To circumvent these behaviors, use a backslash to escape the character: - to send a ", type \" - to send a ^, type \^ - to send a \, type \\ To turn on this parsing, select "Parse Output" in the preferences. This will also place an extra segment in the "Send Button", which allows quick toggling of this feature. 5.9 Advanced Input: Send Break To send a "Break", tap on Send Break in the Action Button. The duration of the Break signal can be selected in Preferences. 6.0 Move Around the Screen In many cases, the Newton screen (especially in portrait orientation) is too small to fit all the text on the screen at one time. PT100 overcomes this problem by showing a portion and allowing you to move the text to see offscreen information. To move text you can either use the onscreen compass (if it is visible) or you can click on the text and "drag" it around. Using the compass moves the screen in set increments: eight characters or one line at a time. If you grow tired of moving around the screen, you can try switching to a smaller font, or rotating the screen. 7.0 Change the Font or Screen Size To change the currently displayed font, select Prefs from the info button. You can select from any of the installed monospaced fonts and sizes. Note that certain ill-formed monospaced fonts may not display information correctly in bold. The Minico font that came with PT100 is specially designed to allow accurate output. While easier on the eyes, larger fonts may require you to move the screen around to see all the information. You can also select the number of input lines available, screen width and screen height. Changing the width and height may cause odd wrapping if you select less than the standard 80x24. If you have the ability to tell the computer on the other end that you have changed the screen size, do so before resizing the PT100 screen. 8.0 Save Output To save output is to use the Copy to Notes entry in the info button. This will copy the current screen to a new unfiled note in the Notepad preserving the font, but not attributes such as inverse, bold and underline. If you are scrolled back, the page that you see will be stored. 9.0 Tweak Performance Comms Update determines how fast a non-terminated line will display. The lower you set this, the faster the Newton looks for incomplete lines. A value that is too low may slow your Newton down. Screen Update determines how quickly the Newton will refresh the screen with new information. Too low a value may slow your Newton down as it refreshes too often. 10.0 About PT100Ős Cripple PT100 is crippled shareware. Unregistered versions of PT100 will only be allowed five minutes of connection time per session. After a warning at the four-minute mark, the application will hang up at the five-minute mark. You may redial and start another session. If you intend to use an unregistered version of PT100 in a critical situation, please be sure to save your work. Better yet, if you're using it for critical work, pay for it. 11.0 Register PT100 To register PT100, send $25 to: Sarah Buta c/o Scrawl 86 Norfolk St., Apt. 4 Cambridge, MA 02139-2652 Be sure to include the spelling of your name as it appears on your Newton. You will receive a registration string by email. If you do not have email, send a SASE. Alternately, you can use Kagi with Flash SheridanŐs Register. 12.0 Register PT100 via WWW Kagi You can Register PT100 directly over the WWW by using Kagi. For more information about Kagi, visit: You can register PT100 directly over the Web at: 13.0 Contact Scrawl You can visit Scrawl at: or send email to: 14.0 Frequently Asked Questions Q: Will you support 1.X Newtons? A: It is unlikely that PT100 will ever support 1.X machines. Many of the tools used to get maximum performance out of the system are 2.0-specific. You might try looking at at some of the other emulators available for the Newton. Q: What about support for VT220, Tek and other emulators? A: At the moment PT100 is highly focused on speedy and accurate VT100 emulation, because it is the largest common denominator for text interfaces. If another interface becomes necessary and has a large enough market, it will be considered. Q: My modem is not directly Newton supported and needs special setup strings. Can I use PT100 on it? A: You can certainly use it as a serial device by entering your own setup strings. Fundamentally, however, you should use a supported modem for your Newton. It will make you life much easier. Q: What about login scripts? A: Support for creating login scripts is on the list of features for upcoming releases. Please write to us if this is a key feature for your use of PT100. Q: Odd things are happening when I use certain programs. How complete is the VT100 emulation? A: As mentioned earlier, PT100 was designed as tool for personal use. As such, we have implemented VT100 emulation elements as we require them, and have the ability to test them. If certain elements are missing, it may be because those elements were not used by the programs we used to test it. If a particular emulation problem is repeatable, and shows up in a program which you use, please write to us, and we'll look into updating the emulation. We hope, at some future date, to have complete VT100 emulation in PT100, but expect the vast majority of people can use it comfortably in the interim. Q: Can I scroll back and see stuff that went off the top of the screen? A: Yep. Turn the Scroll Back to some number greater than zero. Then use the up and down arrows (not the compass) to scroll back. Q: What about support for the MP2000 and the eMate 300? A: PT100 has been casually tested on both these machines, and it works flawlessly. On the MP2000, the application runs about 8x faster; on the eMate about 3x faster. Q: I need a specific vertical market application that will use a textual front end. Are you guys interested in extra work? A: Contact us, we just might be! Q: How about multiple simultaneous telnet sessions? A: Jeepers! You want it all! In good time we hope to have this capability, but for right now, chill out and enjoy what PT100 does do! 15.0 Trouble Shooting Problem: PT100 doesn't work! Solution: Does too! Seriously, check to make sure that all your cables are plugged in, and your PC card modem is installed, and locked into the card slot. Check that your modem is plugged into the phone line and that the line is working. Problem: PT100 still doesn't work! Solution: Does anything on the Newton work with your modem? If, when you insert the PC card, the Newton doesn't acknowledge that you did so, you're out of luck. If the Newton recognizes that a communications card has been inserted, try to dial a number with the Calls applicaton or try to send a fax. If this fails, you do not have the correct Modem Setup for your modem. Check the Apple web pages for the list of supported modems and links to Modem Setup files. Alternately, you can try to roll your own Modem Setup by using ModemMod from DMP Systems . Be sure to pay the shareware fee if you find it useful. Problem: My modem doesn't work! Solution: Certain older modems, notably the Compaq 24/96 modem, provide only marginal Newton support. Checking the Marginal Modem box will let PT100 work in many situations, though not all. For example, 7 Data Bits will not work with this option enabled We strongly discourage the use of this option. Buy a new modem. Problem: I'm not getting VT100 emulation. Solution: Make sure that you have have told the server the terminal type that you are using, i.e. VT100. Problem: PT100 connects for a few seconds, then disconnects, sometimes with a "I/O Buffer Overflow" error. Solution: Check to make sure your Modem Setup is correct. Also verify that you have some sort of flow control (either software or hardware enabled) Problem: I get garbage after I connect. Solution: Try turning on error correction. New, high speed modems are pushing the limits of current analogue phone lines, leading to noisy connection. Error correction can help a great deal. Next, make sure that you have the modem or serial parameters set correctly. Problem: Telnet doesn't work on my MP120. Solution: As with all NIE related software, using Telnet on an MP120 is tricky at best. Try freezing, or erasing everything you can. Try resetting or rebooting your Newton. We're working very hard to get this working (since we only own MP120s) but it's difficult. Don't hold your breath. Enjoy great shell access instead! Problem: I can't see all of the text on the screen. Solution: Try scrolling around with the compass, setting a smaller font size, or minimizing the input area by selecting None from the Keyboard button. You can also make the input line smaller. Problem: There don't seem to be any bold characters in the 9 point Minico font. Solution: There aren't. With only 3 pixels to work in, a bold 9 point font would be unreadable. If you need to see bold, look at the text in 10 point. Problem: My registration string wasn't accepted. Solution: Please recheck it and try again. Make sure that Os and 0s, ls, 1s and Is are not begin confused. Verify that the name you sent us is the same one in the "Owner Info" on your Newton. If you have multiple owner cards, try sending us your Newton Serial Code (which appears in the About Box). Problem: Weird characters like "[5;c" sometimes appear on my screen. Solution: Congratulations! You've found an oddball VT100 code. Please send us mail detailing how you caused this problem and win our undying gratitude, as well as a witty reply. The exact text of the garbage would be useful as well. Problem: When I dial into a BBS, I don't get nice line drawings, but a bunch of lowercase letters. Solution: The font set required by ANSI compliant BBSes is not yet completely supported in Minico. We're working with the designer of Minico (Michael Peay) to complete the set in all of the used font sizes. Problem: My hardware keyboard isn't working. Solution: Your keyboard needs to be plugged into your Newton on powerup in order to be recognized. Try turning your Newton on and off. In some cases, selecting Input Line, and then None from the Keyboard button may solve problems.