All rights reserved. This manual and the programs referred to herein are copyrighted works of the PsiStack Development Group (hereafter referred to as the authors).
The information in this document is subject to change without notice.
PsiStack is a trademark of the authors. Psion and the Psion logo are registered trademarks, and Psion, Psion Series 3a, 3c, Siena and PsiMail Internet are trademarks of Psion PLC. HyperTerminal Private Edition 2.0 is a trademark of Hilgraeve. UNIX is a trademark of AT&T. Windows is a trademark of Microsoft Corporation. MacOS is a trademark of Apple Computer. OS/2 is a trademark of IBM. Java is a trademark of Sun Microsystems. All other trademarks are acknowledged.
This product includes software developed by the University of California, Berkeley and its contributors, and also by the Linux development community.
The PsiStack software is distributed under the terms of the GNU General Public License, version 2, a copy of which is included in this package as 'COPYING.TXT'. Simply, that licence allows you to do almost anything you like with the software. Use it, copy it, give it to friends, modify it. However, support will only be given to unmodified versions of the software, and any modifications must include the authors' copyright.
Should you find PsiStack useful, and use it regularly, please consider the amount of work that went into its production, the production of its documentation, the testing involved, etc. The authors are not asking for any payment for this work, but a donation to charity would be most welcome.
This software would not exist without the efforts, encouragement and support of the PsiStack Development Group, who are (mostly):
The team would also like to thank:
Many others were involved in the making of this product: thank you, all!
Matt Gumbley
To do this, you will require:
We'll go into these requirements in a little more detail…
1.1 You'll need a Psion
You will need at least 70 kilobytes of free memory
to run PsiStack and 40 kilobytes of disk space on the internal
RAM drive M: (These are really rough figures based on current
builds of the package).
1.2 You may need a Modem
If you want to use PsiStack to connect to the Internet using a dial-up account with an Internet Service Provider (ISP), you'll need a modem. PsiStack was tested using the several modems and ISPs. A list of the modems, ISPs and scripts used to connect to them is given in "Appendix B: Modems, ISPs and Scripts provided", on page 39
Most modems can be accommodated using the dial-up scripting language, discussed in "Dial-up Scripting Language" on page 18.
If the modem supports the Hayes command set (AT commands), then you should have little problem with the supplied scripts. Details are given later about creating your own dial-up script for Hayes-compatible, and other modems. With the manual for your modem, and a little experimentation, you should be able to connect to your ISP and initiate connections.
If you are connecting your Psion to the Internet using a direct connection, say, from your Psion to a computer running UNIX, you don't need a modem, and you may not need a dial-up script.
If you are connecting two Psions together, you don't need a modem
or dial-up script. If you're connecting 3cs or Sienas, you can
use the infra-red link.
1.3 You may need a modem cable or other connection cable
1.3.1 3a owners
You will need the 3LINK cable, which is available
from your usual Psion dealer. This is sometimes referred to as
the "soap-on-a-rope". This is a complex piece of hardware
- you won't be able to build your own.
You will also need the null-modem adapter, as described below.
1.3.2 3c and Siena owners
You will need the serial cable, available in the PsiWin package, or on its own. This is available from your usual Psion dealer. There are alternative supplies for these cables, and you can always build your own. [insert details]
You will need a null-modem adapter (or build a cable with one already built in).
The standard serial cable (or "soap-on-a-rope") will
be referred to as "the link cable" in the discussion
that follows.
1.4 You may also need a null-modem adaptor
The link cable connects your Psion to a computer. In RS-232 terminology, both these devices are instances of Data circuit-Terminating Equipment, or DTEs. A modem is an instance of Data Communication Equipment, or a DCE. The link cable therefore is designed to connect two DTEs together. To connect a DTE to a DCE - i.e. to connect your Psion to your modem - you need a converter which converts DTE signals to DCE signals. This is known as a null-modem or zero-modem converter or adapter. These are available from all reputable computer stores, or you can make your own...
Signal Psion Cable Modem Signal Signal(Source: Psion Cable Adapter: MODEM, Part No: 1602-0016-01)
Abbr. DB9 DB25 Abbr. Name
FG CASE ----------+-- CASE FG Frame Ground
+-- 1 FG Frame Ground
TD 3 ------------- 3 RD Receive Data
RD 2 ------------- 2 TD Transmit Data
RTS 7 ------------- 5 CTS Clear To Send
CTS 8 ------------- 4 RTS Request To Send
DSR 6 ------------- 20 DTR Data Terminal Ready
DTR 4 ------------- 6 DSR Data Set Ready
SG 5 ------------- 7 SG Signal Ground
RI 9 ------------- 8 DCD Data Carrier Detect
DCD 1 nc
Note:
This information was kindly provided by Jochen Siegenthaler. See
his web page at:
http://ourworld.compuserve.com/homepages/Jochen_Siegenthaler/pmifaq.htm
for details on null-modem adapters to connect from any Psion to
any modem connector.
1.5 You'll need an account with an ISP
To connect to the Internet, your Psion must be able
to communicate with a computer which is already connected to the
Internet. You may be fortunate in having such a computer already.
If not, you will have to arrange access with an Internet Service
Provider (ISP). It is beyond the scope of this owner's manual
to list or recommend ISPs - check the computer magazines for them:
there are plenty to choose from!
When choosing an ISP, you should ask the following questions:
Do you support SLIP, CSLIP or PPP connections?
Can you give me details of the modem settings that I must use? Which standards do your modems support? I.e. V.34, MNP5, LAP-M, etc. What is the chat sequence I should use to connect to your system?
What is the static Internet Protocol (IP) address of my machine, when connected - or do you support dynamic addressing? If so, how is the IP address of my machine communicated to me in the chat sequence? What is my subnet mask? What is the IP address of the gateway? Of the Domain Name Service (DNS) servers?
For the application programs you will use with your Internet connection,
you will need to know the addresses of the Simple Mail Transfer
Protocol (SMTP) server, Post Office Protocol (POP3) server and
the Network News Transfer Protocol (NNTP) server. This manual
does not cover the setting up of applications for email and news.
1.6 And you'll need some spare time
Setting up PsiStack for the first time can take a
while. If you're connecting to one of the ISPs we've tested PsiStack
with, using a modem we've tested, you should be online quickly.
See "Appendix B: Modems, ISPs and Scripts provided"
on page 39.
If your modem is Hayes-compatible, you're half-way there. If your ISP uses a simple chat sequence, you're the other half-way there.
There is a lot of bizzare terminology surrounding the Internet, most of which can be safely ignored once you're up and surfing. There is a comprehensive glossary of relevant terms in "Appendix C: Glossary of terms" on page 40.You will also find it helpful to familiarise yourself with some basic internetworking concepts, discussed in "Appendix F: Introduction to Internetworking" on page 43.
There are several stages involved in setting up PsiStack. There's no point trying to run before you can walk, so start with the simplest parts first, and progress gradually through this section until you're finally surfing.
The stages are:
Note: we'll change to using Jochen's Setup.opo for this when the file formats have stabilised, and the easy-setup program is done… MJG
PsiStack stores its configuration files in the \APP\PSISTACK\ directory, and any dial-up connection scripts in the \PSISTACK\ directory of the internal drive. The programs themselves are located in \APP\PSISTACK\. In the current release, these locations are not changeable - for instance, you cannot store any of the components on a removable solid-state disk (SSD).
Using PsiWin, create the following directories on the Psion's internal drive, if they do not already exist:
You will find the PsiStack application files in the Install directory of the release medium. This directory holds all the PsiStack files, in their correct locations. The files you copy should be copied to the same place on your Psion. For example, \psistack\install\app\psistack\gs18.app should be copied to M:\app\psistack\gs18.app.
Copy the PSISTACK.DBF configuration file into the \APP\PSISTACK directory, if supplied by your vendor or ISP. Some ISPs will automatically configure parts of PsiStack for you, and this file contains that configuration. You'll still need to create the \APP\PSISTACK directory though, even if this file is not contained on your floppy.
Copy any appropriate .SCP dial-up script file(s) into the \PSISTACK directory. The default scripts are PSISTACK.SCP, MYSCRIPT.SCP and IRDA.SCP, so you should copy these at least. Your ISP may only supply one script, say DEMON.SCP. If this is the case, copy that file into \PSISTACK.
From the Psion's System Screen, press Psion-I, and install the
PsiStack programs - there is a PSISTACK.GRP group file to help with this.
2.2 Cabling up
Assuming you are connecting to the Internet via a
modem:
Assuming you're connecting to another computer (say, a Linux or Windows PC):
When PsiStack starts, it is inactive. A full discussion of how to use it is covered later, but to get your cabling quickly verified:
At the top of this dialogue box, you'll see the interface's current state, which is down. After pressing enter, providing no error messages have been shown, the interface should now be in the terminal state.
In terminal state, any key-presses are sent to the modem, and anything the modem sends back is displayed on screen. You can use this as a simple "dumb terminal" to connect to your modem and dial remote computers.
Check your modem manual to find any Hayes commands which show the current modem configuration. For example, on a Hayes Accura 288 V.34 + FAX modem, the command AT&V shows the current configuration. It sends quite a lot of information to the Psion, and so can be used to see if the handshaking is set correctly. Try a few commands. ATI, or ATI0, ATI1, ATI2 etc. usually display some diagnostic messages on most modems.
You may need to reset your modem before use: ATZ
You may need to turn on the text messages and command echo: ATE1Q0V1
To aid the capture of data from your modem, and/or remote system, you might find it useful to display the control characters which may be sent. These are characters such as carriage-return, line-feed, tab, etc. To 'expand' these characters, thus showing their hexadecimal representation, use the 'Show control chars : Expanded' option, under Tools/Logging.
Bear in mind that the carriage return key is ASCII 0x0D, and line-feed is 0x0A.
When the interface is working, and sending/receiving data correctly, bring the interface down, by changing its state from the menu.
For more information on the different views, and the states an
interface can be in, see "The PsiStack views and interface states"
on page 17, and "Appendix F: Introduction to Internetworking"
on page 42.
2.4 Dialling your ISP and capturing the chat sequence
To capture the chat sequence using PsiStack you can
either use a pencil and paper (my preferred method) or the capture
command, in the scripting language. See page 25 for details.
A sample chat sequence is shown on page 36.
2.5 Automating the chat sequence with a dial-up script
Having to type modem commands and log in manually
every time you feel the need to surf can be a real drag, man.
The process can be automated using PsiStack's dial-up scripting
language The full details of this are given on page 18. Refer
there if you need to customise the script you're using.
If your ISP supplied a script, then use that, otherwise, you can customise the default PSISTACK.SCP file you installed in the \PSISTACK directory, or write your own from scratch, using the Script Editor. For a full worked example, see page 36.
To select which script you want to use to control the state of each interface, select "Script" from the desired "I/F" menu:
If you're not using a modem, for instance, if you're connecting directly to another computer which speaks TCP/IP, or if you're connecting two Psions together via the infra-red device, you can say "No" to the "Use script?" prompt. All the other script settings are then ignored.
If you do need to use a script to connect to your ISP, then say "Yes" to "Use script?", and select the script file you want to use.
Set the "Debug level" to "None", unless you
want to see the script in action, in which case, select "Trace".
2.6 Setting up PsiStack for network operations
The dial-up script you just selected will dial your
ISP and set up the network connection, but which phone number
should it dial? You could always embed the phone number inside
the script, as well as any user name and password, but there's
an easier way.
2.6.1 Changing the ISP details
Select "ISP" from the "I/F" menu,
and you'll get a dialogue box like this:
It's fairly self-explanatory: put in the name of your ISP, and
up to three numbers for their modems. You don't have to fill all
three numbers if they only have one. Set your user name, and a
password, of up to eight characters (which won't be displayed
as you type). Your ISP will usually give you your user name and
password.
2.6.1.1 A note on security
Your password is not shown on screen, but it is stored,
unencrypted, in the PsiStack configuration file. If someone got
hold of your Psion (heaven forbid!) they could get your password
from there, if they know how to interpret the file. As a small
security measure, you can leave the password field blank. When
the appropriate point is reached in the script (when the $password
variable is read), you will be prompted for the password.
2.6.2 Changing the data-link protocol settings
Your ISP's host computer will talk to your Psion
using either the SLIP, CSLIP (compressed SLIP) or PPP protocols.
Select which of these is to be used by use of the "Protocols"
option on the "I/F" menu:
2.6.3 Changing the IP addresses of your Psion and the remote systems
If you're unfamiliar with IP addresses, please read
"Appendix F: Introduction to Internetworking" on page
42. Each interface on your Psion must have a unique IP address,
and you'll need to tell PsiStack the IP addresses of the default
gateway, DNS (domain name service) servers, and the subnetwork
mask. Your ISP will supply this information.
Change this information using the "IP Addrs" option on the "I/F" menu:
Each address is given as a dotted quad. If any of these is not known, use the IP address 0.0.0.0.
The serial port settings may be changed from the "I/F" menu's "Port" option. The dialogue box looks like this:
You may select one of three serial devices: TTY:A, TTY:B and TTY:I. These correspond to the first and second serial ports on a 3a, although on a 3c, only TTY:A is brought out on the PsiWin cable. TTY:I is the infra-red (IrDA) device on a Siena or 3c.
The baud rate is the speed at which data is transferred through the serial port. Usually, the higher the better. PsiStack can use any common baud rate between 300 and 115200 baud, although the higher speeds are only available on the more modern Psion's, such as the 3c/Siena, and the highest baud rate, 115200 baud is only available on IrDA devices. For a 28800 baud modem, set the port baud rate to 38400 baud on a 3c/Siena, or 19200 on a 3a, since this is the highest rate available on that system.
The number of data bits may be set to 5, 6, 7 or 8. For TCP/IP data, you must select 8 data bits, although 7 is sometimes necessary whilst running a dial-up script to establish the connection.
Parity may be set to Ignore, None, Even or Odd. Most connections are set up using no parity, although you may need even parity when running a dial-up script to establish the connection.
The number of stop bits may be set to 1 or 2: 1 is used almost universally.
Handshaking may be set to Ignore, RTS/CTS or XON/XOFF. For most modems, with a full serial cable, such as the PsiWin cable / null-modem adapter, use RTS/CTS, also known as hardware handshaking. For a three-wire cable, use XON/XOFF, also known as software handshaking. Don't ignore handshaking, unless you're using really low baud rates, or else, you'll lose data.
The other two options on the serial port settings allow you to ignore certain RS-232 signals. If these signals are not ignored, they must be present when the interface is brought up. Some of them (notably DCD) are only raised during a conversation with a modem.
The DTR (data terminal ready) signal is raised by a DTE (data-circuit terminating equipment) device when it is active, and DSR (data set ready) is raised by a DCE (data communications equipment) device when it is active. In short, modems give a DSR, and terminals and computers give a DTR. Modems need to see DTR before they talk, and computers need to see DSR before they talk. With a modem, PsiWin cable, and null-modem adaptor, the Psion (a DCE, oddly) won't see the modem's DSR, so you can ignore DTR/DSR. Use this option whenever you connect your Psion to your PC.
When a modem dials another modem, and establishes a communications path, it raises its DCD (data carrier detect) signal. Usually, this signal is not asserted before the detection of the remote modem's carrier. If this signal is not ignored, DCD must be present when the port is opened. This is unusual for dial-up connections, unless you've permanently strapped DCD high. So, ignore DCD here, and when the connection is established (when the modem returns CONNECT for example), use the detectcarrier command in your script. Then, if the modem drops carrier, the interface will be brought down cleanly.
In a dial-up script, some of the port settings can also be set using the baudrate, databits, stopbits, parity and handshaking commands. See "Dial-up Scripting Language" on page 18 for more details on these commands.
At any time the stack is active, network interfaces can be in one of four possible states:
Down: the interface has no serial device open, and keystrokes received when its view is active are consigned to the bit bucket.
Terminal: the interface has a serial device open, and any data received on this device is echoed to its console screen. When in the terminal state, and the interface's console screen is the active view, keystrokes are sent to the serial device. This can be used to manually initiate connections to your ISP.
Script: rather than nurse the interface through the tedious business of setting up a connection, PsiStack has a powerful built-in scripting language so you can automate the process. Life's just too short to do it manually all the time… In the script state, the interface processes the script, to bring the interface to a state where frames of the correct data link protocol are being transferred (i.e. you've got the remote end sending SLIP or PPP frames). If for some reason, the remote end can't be made to talk in the correct protocol, the interface changes to the down state. If the remote end is coaxed into talking the correct protocol, the interface changes to the up state. (up and down are the two keywords in the scripting language which tell the stack whether to enter the up or down state, when the script terminates.)
Up: A conversation is taking place between the stack and the remote host, in the data link protocol you chose in the interface protocols dialog. This state may be entered by a script up command or, if there is no script associated with the interface, directly from the down state. To terminate the connection, change state using the state option on the interface's menu. (That's the only way of terminating connections when they're up).
Scripts are given the .SCP extension, and are stored in the \PSISTACK directory on the Psion's internal drive. They are edited using the Script Editor, or Word. They are simple ASCII text files.
Scripts are processed by part of the PsiStack software known as the Script Interpreter. When a script is started, the interpreter works through each line of the script sequentially, until the script ends, or until a goto, truegoto, falsegoto, term, up, or down command is reached. The interpreter can also stop your script if there is something wrong with it, for instance, if you attempt a mathematical expression which is too complex, or if a label or variable is malformed.
PsiScript is a little like an early BASIC, a little like Forth.
Suitably perverse and arcane for most hackers…
5.1 Line contents
Each line of the script can either hold:
| A comment, which starts with a hash sign | e.g. # This is a comment |
| A label, which starts with a colon | e.g. :connected |
| A blank line | e.g. |
| A command (shown in this guide in bold) | e.g. send ATDT\n |
Comments may only appear on lines of their own: they must not occur at the end of commands, e.g. "echo You are now connected # so let's change to SLIP mode" is wrong.
Lines may start with spaces, so you can indent the actual commands and labels while keeping the comments flush against the left-hand side. This makes scripts a little easier to read. (You can indent comments too, should the urge take you.)
There must only be one command per line.
5.2 Labels
You can have as many labels as you like. Labels indicate
places in the script which may be jumped to using a goto, truegoto
or falsegoto command. Labels begin with a colon, followed
by the label name (with no space in between). Label names must
contain only alphanumeric characters, i.e. the digits 0..9, the
letters z..z and A..Z. A label must be less than 32 characters
in length. e.g.
| :loop | :dialmyISP | :0898 | are valid |
| loop: | my:loop | :$money$ | are not valid |
| \a | alert (bell) | \\ | backslash (\) |
| \b | backspace | \f | form feed |
| \n | new line | \r | carriage return |
| \t | horizontal tab | \v | vertical tab |
| \xhh | hexadecimal number | \* | break |
When writing text to the screen using the echo command, you will need to end your text with \r\n to cause the next line to appear at the left-hand edge of the screen, underneath the previous line.
When receiving text from a Hayes modem, the responses may end
in \r not \r\n. When sending text, you may need to end it in \r
5.5 Mathematical expressions in Reverse Polish Notation
Simple maths may be done on numbers and variables,
and values compared to yield boolean TRUE or FALSE values. Mathematical
expressions are specified in postfix notation, sometimes referred
to as Reverse Polish Notation, after the Hungarian scientist who
invented it, Lucasiewicz. Consider the expression 5 * 3 + 2. Is
the answer 17 or 25? The knowledgeable mathematicians amongst
us will immediately answer 17, since multiplication takes precedence
over addition. However, making a computer language which understands
precedence rules just gives me more work to do, and so I've taken
the easy option, and used RPN, which makes things much easier
for me, but slightly odd for you (if you've never used RPN before).
In RPN, the operations (multiplication and addition, in the example
above) come "at the end of the number", not "between
them". Examples will clarify this.
The above calculation in RPN would be expressed by 5 3 * 2 +, which is read from left to right as "take 5, then 3, multiply them, and take that result and 2, and add them".
Bracketed expressions are simple, too. Simply work out the brackets first, as you normally do: (15 / 3) + (7 * 23) is expressed by 15 3 / 7 23 * +
Given a variable $count, initialise it to 1, print it, and increase count. Repeat the print in a loop until count is 10, then drop out of the loop:
set $count 1 :loopStart echo Count is $count \r\n set $count $count 1 + eval $count 10 = falsegoto loopStart # end of loopWhen you use a number or the contents of a variable, it is placed onto what is known as an evaluation stack. Think of this as a pile of pieces of paper, empty at first. When you use a number, it is written onto a piece of paper. The next number is written onto another piece of paper, and placed on top of the first. The next number is handled likewise. Given the RPN statement 1 2 3, the 1 is written on the first piece of paper, the 2 on the second, and placed on top of the 1, and the 3 is written on a third piece of paper, and placed on top of the 2 and 1.
When you use an arithmetic operator, such as +, it takes the first two numbers off the stack of papers, adds them together, and writes the result on a new piece of paper, which is placed on top of the stack. So, the RPN statement 1 2 3 + + is interpreted as:
| RPN | What happens | Stack contents, Bottom to Top |
| 1: | Place 1 on the stack. | 1 |
| 2: | Place 2 on top of 1. | 1 2 |
| 3: | Place 3 on top of 2 and 1. | 1 2 3 |
| +: | Add the top two numbers. | 1 5 |
| +: | Add the top two numbers. | 6 |
Note: the evaluation stack can hold up to 32 16-bit unsigned integers. If your expression is wrong - or you're not keeping track of how much you've pushed onto the stack - you can fill the stack. If this happens, your script terminates, and will automatically perform the down command. A message will be printed on the console to warn you of this condition: a stack overflow.
Note: if a command requires a given number of numbers on the stack,
and can't find that many, your script terminates, and will automatically
perform the down command. A message will be printed on
the console to warn you of this condition: a stack underflow.
5.6 Arithmetic and boolean operators
As you can see from the above, the notion of a stack
is central to RPN. The notation before operator after is
used in this summary to show the stack contents before and after
a given operation. All arithmetic and boolean operations must
be done using a set or eval command.
5.6.1 Addition
num1 num2 + (num1 + num2)
e.g. eval 57 2 + removes 57 and 2, and places 59 on the
top of the stack.
5.6.2 Subtraction
num1 num2 - (num1 - num2)
e.g. eval 57 2 - removes 57 and 2, and places 55 on the
top of the stack.
5.6.3 Division
num1 num2 / (num1 / num2)
e.g. set $x 45 9 / removes 45 and 9, and places 5 in variable $x.
A message will be displayed if num2 is zero, and down will
be performed.
5.6.4 Multiplication
num1 num2 * (num1 * num2)
e.g. eval 50 2 * removes 50 and 2, and places 100 on the
top of the stack.
5.6.5 Modulus
num1 num2 % (num1 % num2)
e.g. set $x 46 9 % removes 46 and 9, and places 1 in variable $x
A message will be displayed if num2 is zero, and down will
be performed.
5.6.6 Testing for equality
num1 num2 = (num1=num2 ?)
e.g. eval 28 7 = removes 28 and 7, compares them to see if they are equal, and places the boolean value FALSE on the top of the stack. FALSE is the same as the number zero.
e.g. eval 50 2 * 100 = multiplies 50 and 2, leaving 100
on the top of the stack. 100 is then pushed on the stack, and
the top two numbers (100 and 100) are removed and tested for equality.
The boolean value TRUE is placed on top of the stack. TRUE is
the same as the number one, although when comparisons are made,
any non-zero number is interpreted as TRUE.
5.6.7 Testing for inequality
There is no specific operator which tests for inequality.
However, the ! operator can be used to negate the boolean value
on top of the stack, and there are two conditional goto
commands, truegoto and falsegoto, which branch depending
on whether TRUE or FALSE is on top of the stack.
e.g. eval 28 7 = ! removes 28 and 7, tests for equality, which places FALSE on the stack. ! removes the top value (FALSE), and replaces it with its boolean opposite, TRUE.
e.g. set $stillInLoop $count 10 = ! tests the contents of the $count variable and 10 for equality, negates this, and places the boolean result in the variable $stillInLoop.
e.g. eval $count 10 =
falsegoto loopStart Compares $count to 10, and if they
are not equal, jumps to the loopStart label.
5.6.8 Testing for ordering
num1 num2 < (num1 < num2?)
num1 num2 <= (num1 <= num2?)
num1 num2 > (num1 > num2?)
num1 num2 >= (num1 >= num2?)
As above, but testing for ordering instead of equality.
e.g. eval 34 5 < yields FALSE, eval 34 5 >
yields TRUE, eval 34 34 <= yields TRUE, eval 34
34 <= ! yields FALSE, and so on…
5.6.9 Logical operators
You want boolean and, or, xor? Sorry, if you desperately
need them, mail me, and I'll add them. I can't see a need for
them in a language like this…
5.7 Command reference
We now discuss each script command in turn. In the
description of the commands, the following notation is used:
TEXT is the text characters from the position in the line where the text starts, to the end of line. Character constants may be used, and so may variables, although if any text is to follow the contents of a variable, the variable must be followed by a space, to separate it from the following text. TEXT must come at the end of any command. Please note the size of variables and the size of the TEXT expansion buffer when expanding TEXT. See Variables on page 20.
RPN is a mathematical expression in reverse polish notation, and as such, can only contain numbers, variables and operators. The expression does not have to leave the stack in the same state as it found it, e.g. eval 1 2 3 is perfectly valid, and will leave these three numbers on the stack, with 3 on top.
e.g. To dial a phone number on a Hayes-compatible modem, using tone dialling, and the phone number stored in the $phone variable, use the command:
send ATDT$phone \r
5.7.1 baudrate TEXT
Sets the baud rate of the serial port, which must be one of the following values:
300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
(italicised speeds are only possible on Siena and Series 3c machines. Siena IrDA links have a maximum speed of 19200 baud, and 3c IrDA links can go up to 115200. 3c RS-232 links can only go up to 57600 baud.)
If the rate is not in the above list, the script will terminate with a message and will perform down. See databits, stopbits, handshaking.
Note: this rate is the DTE rate, i.e. the speed of the link between modem and the Psion. The DCE rate, i.e. the speed of the link between the two modems can be different, depending on how you configure them in the rest of the script. For example, the DTE rate could be set to 38400 baud, and the DCE rate at 28000 baud. Always try to set the DTE rate higher than the DCE rate.
e.g. baudrate 19200
5.7.2 beep
Emits a short beep from the Psion's speaker.
5.7.3 capture filename
Turns capture on. Sent and received data is stored
in the file indicated. Use the capture command on its own
to turn capturing off.
5.7.4 clear variable
Removes the variable from the script interpreter's
memory.
5.7.5 compare variable TEXT
The variable is compared exactly against TEXT, as
a string. A boolean result is placed on top of the stack.
Note: this is not the same as eval variable TEXT = (which wouldn't work, since TEXT must come at the end of a command. If this did work, then the = would be part of the TEXT…)
e.g. A little trivial…
setstring $myString Hello World!\n
compare $myString Hello World!\n
truegoto myLabel
# never gets to here!
:myLabel
echo Yes, they're the same.
5.7.6 databits TEXT
Sets the number of data bits sent and received by
the serial port. TEXT must be either 7 or 8, and if it doesn't,
the script will terminate, with a message, and will perform down.
See baudrate, handshaking, parity, stopbits.
To connect to some ISPs, you may need to change to 7E1 temporarily while the connection is established, then change to 8N1 before switching to SLIP/PPP mode. If you're having trouble doing anything other than pinging, then try this!
e.g. # Establish connection with a 7E1 link
databits 7
parity even
…
# Connected! Switch to 8N1
databits 8
parity none
echo Switching to SLIP \r\n
up
5.7.7 detectcarrier Y / N
Enables or disables detection of the DCD signal.
See "Serial port settings in detail" on page 16 for
more details.
5.7.8 detectdevice Y / N
Enables or disables detection of the DTR/DSR signal.
See "Serial port settings in detail" on page 16 for
more details.
5.7.9 discard
As serial data comes in, it is stored in the variable
$waitstring. The wait command allows you to sleep for a
certain number of seconds, and compare $waitstring against some
TEXT, placing a boolean value on the stack if the comparison succeeds
or fails. $waitstring is built up, as data comes in. However,
you might not always want to build it up until some predefined
time. You may want to discard serial input, until later.
This command sets the script input state to discard.
discard is not the same as flush. flush merely
resets the $waitstring variable, whereas discard causes
all serial input data to be ignored. See discarduntil,
wait, doze, dozeuntil, flush.
e.g. A little contrived…
# Get modem configuration, but throw it away
discard
send AT&V\n
# The configuration goes into the bit bucket…
# Now call my ISP, and wait for CONNECT. wait cancels discard, so
# $waitstring gets built up with the input data
send ATDT$phone \n
wait 10 CONNECT
# $waitstring might contain CONNECT 19200\n but the wait will
# match the first 7 letters of CONNECT correctly, placing TRUE on
# the stack.
5.7.10 discarduntil char
Incoming data is discarded until the char is seen,
after which, any further input data is stored in $waitstring as
usual. Used to throw away data you don't need.
e.g. (See the example in the appendix).. the modem and remote end sometimes send all the following text, without waiting to be 'woken up' by pressing return:
\r\n
CARRIER 9600\r\n
\r\n
PROTOCOL: ALT\r\n
\r\n
CONNECT 9600\r\n
\r\n
Annex Command Line Interpreter * Copyright 1991 Xylogics, Inc.\r\n
\r\n
Checking authorization, Please wait...\r\n
login:
Receiving all this data at once may overflow $waitstring.
(In this case, if you did a flush before sending the modem
dial command, all this data would fit in 255 characters, and so
wouldn't cause a problem. Your script may not be so fortunate.)
There are several approaches to handling this much data. Knowing
the exact contents of the data, you could use 'discarduntil
w' which would discard until it saw the 'w' of 'wait…\r\n'
on the penultimate line. Knowing roughly how long it takes to
send the above, you could 'discard' and 'sleep 3',
and hope the data has finished sending. Of course, with that approach,
you would probably miss the 'login:', but you could send a return
with 'echo \r' to get another login prompt. You could use
a series of 'dozeuntil \n' commands, followed by flushes…
5.7.11 down
The script is terminated, and the network interface
is said to be down. Use down whenever a connection
cannot be established. See up.
e.g. Didn't get a CONNECT string, so fail the connection
wait 5 CONNECT
truegoto connected
echo Nope, didn't connect\r\n
down
:connected
echo We're connected\r\n
up
5.7.12 doze
Pauses the script until the remote end sends some
data. The data is stored in $waitstring, and so can be compared
using a wait. Useful when waiting for your modem to dial,
in the case where the dial and handshake can take some time. See
wait, flush, discard, dozeuntil.
5.7.13 dozeuntil char
Pauses the script until the remote end sends the
char. Incoming data is built up in $waitstring while the script
dozes. Useful for waiting for the end of prompts.
e.g. waiting for a login: prompt…
# send dial commands, handle CONNECT etc. The login prompt ends in a colon.
dozeuntil :
send $username \r
e.g. retrieving dynamically-assigned IP addresses…
# When I send SLIP\r, the remote end will say "Switching to SLIP.\r\n
# Annex address is 123.1.2.55. Your address is 123.1.2.39.\r\n"
# Get ready to throw away the first line with the discarduntil \n
discarduntil \n
send SLIP\n
# We've seen the \n on the end of the first line, now wait for the end of the second line.
dozeuntil \n
splitip 2 $IPaddress
up
5.7.14 drop
Removes the top number from the evaluation stack.
Often useful after a wait in which you didn't really want
to test the result of the comparison.
5.7.15 dump
Dumps a list of all variables and what they contain
to the console window. This data is also captured to the capture
file, if you have used the capture filename command, but
it is not sent to the remote computer.
5.7.16 echo TEXT
Displays TEXT on the interface's console screen.
See note under "Character constants" on page 20.
e.g. echo Dialing your ISP on $phone \r\n
5.7.17 eval RPN
The RPN expression is evaluated. The numeric result
is placed on the evaluation stack. The expression may contain
numbers, operators, and variables.
This command is often used to do simple maths, and
to perform comparisons. See the above sections on RPN, and operators.
5.7.18 falsegoto label
The top value on the stack is removed. If it is FALSE
- i.e. zero - then the script continues at the line following
the label. If it is TRUE, the script continues with the next command.
If label doesn't exist, the script terminates with a message on
the console, and will automatically perform the down command.
e.g. Go backwards from 5 to 0, printing the counter as we go
set $count 5
:loopStart
echo Count is $count \r\n
set $count $count 1 -
eval $count 0 =
falsegoto loopStart
echo End of loop\r\n
5.7.19 flush
Resets the $waitstring variable. Any subsequent input
data will be stored at the start of $waitstring. Also use this
after a wait for a timeout with no compare string. (You
should really be using sleep for that though).
5.7.20 goto label
Unconditionally jump to label. If label doesn't exist,
the script terminates with a message on the console, and will
automatically perform the down command.
e.g.
# Not a terribly useful example, and don't try this at home, kids!
:infinite
goto infinite
5.7.21 handshaking TEXT
Sets the handshaking mode on the serial port. TEXT
must be either:
rtscts
xonxoff
ignore
If it isn't, the script will terminate with a message, and perform
down. See databits, stopbits and baudrate.
5.7.22 isempty variable
Pushes boolean TRUE or FALSE onto the stack. TRUE
if variable is clear, i.e. has no data stored in it. FALSE otherwise.
Useful after a nextphone command, to detect if the user
actually has stored a next phone number. See example script.
5.7.23 nextphone
You may have up to three phone numbers associated
with an ISP, corresponding to three possible remote modems. These
numbers are stored in the variables $phone1, $phone2 and $phone3.
When the script starts, the $phoneNumber variable will be set
to 1, and this indicates which one of $phone1,2,3 are returned
when the $phone variable is used. The nextphone command
increments $phoneNumber (setting it back to 1 when it increments
past 3).
5.7.24 parity TEXT
Sets the line parity to either even, odd, none or
ignore. See databits, handshaking, stopbits.
5.7.25 send TEXT
TEXT is sent out through the serial port, using the
current port settings. No carriage return or new-line characters
are added; if needed, they must be supplied by using character
constants. TEXT may contain variables: they are replaced by their
contents.
e.g. if the variable $phone contains the phone number string "01234 128828" (without the double quotes), then the command
send ATDT$phone \n
will send the string ATDT01234 128828\n to the serial port. See
note regarding modems and "Character constants" on page
20.
5.7.26 set variable RPN
Evaluates the RPN expression, and takes the resulting
value off the top of the stack, and places it in the variable.
See eval. The variable is created if it does not already
exist.
e.g. set $roughCircleArea 3 $radius $radius * *
5.7.27 setstring variable TEXT
Stores the TEXT in the variable. See compare.
The variable is created if it does not already exist.
e.g. setstring $text well, here's a piece of text
echo $text
5.7.28 sleep RPN
Causes the script to sleep for so many seconds. Any
received serial data is discarded. Upon waking up, the input state
is set to buildup. See discard, wait, doze.
5.7.29 splitip fieldno destinationvariable
Finds the fieldno'th dotted quad IP address of $waitstring,
and stores it in destinationvariable. Fields in $waitstring are
delimited by white space.
e.g. setstring $waitstring My IP Address is 192.147.123.234 honest!
splitip 1 $IPaddress
If the IP address does not parse correctly, the script will terminate,
a message will be output on the console, and the down command
will be performed.
5.7.30 stopbits TEXT
Sets the number of stop bits on the serial port.
TEXT must be 1 or 2, and the script will terminate with an error
message and will perform down if it doesn't. See databits,
baudrate, handshaking.
5.7.31 term
Sets the interface into term mode, and ends the script.
5.7.32 truegoto label
The top value on the stack is removed. If it is TRUE
- i.e. non-zero - then the script continues at the line following
the label. If it is FALSE, the script continues with the next
command. If label doesn't exist, the script terminates with a
message on the console, and will automatically perform the down
command.
e.g. Go backwards from 5 to 0, printing the counter as we go
set $count 5
:loopStart
echo Count is $count \r\n
set $count $count 1 -
eval $count 0 = !
truegoto loopStart
echo End of loop\r\n
5.7.33 up
The connection has been established correctly, and
the network interface is said to be up. The remote computer
should be communicating using the expected data-link protocol
(i.e. SLIP, CSLIP or PPP) before a up command is done.
e.g. # We've got the IP addresses of the gateway and my host in $gateway and $ipaddr
# So we switch to SLIP mode, and we're away
echo Switching to SLIP mode\r\n
echo Network interface is now up. Have a nice day.\r\n
up
5.7.34 wait timeout TEXT
As serial input data arrives, it is built up into
the $waitstring variable. (If you are not in discard mode).
The wait command will cause the script to sleep for timeout
seconds. The timeout can be either a number, or a variable, which
is interpreted numerically. When it wakes up after timeout
seconds, the characters of the TEXT are subset-compared against
the $waitstring variable. If there is a match (the TEXT has been
received anywhere in $waitstring within the specified time), the
boolean value TRUE is pushed onto the evaluation stack. If the
match fails (TEXT is not found inside $waitstring at the timeout),
the boolean value FALSE is placed there. $waitstring is not reset
by the wait command - you should use flush beforehand
if you want to reset $waitstring. After a wait, further
comparisons may be made using the compare or wait
commands, and $waitstring can be scanned using the splitip
command. If the duration of the wait is not known, you
can use the doze command beforehand.
See discard - wait places the script input state to buildup, thereby cancelling any discard command. If you can't remember whether you're discarding, wait 0 with no TEXT will return immediately, and set the script input state to buildup. Wait followed by a positive value and no TEXT causes the script to sleep, and FALSE to be placed on the stack (You should probably be using sleep for that though).
Note that wait always causes a pause if timeout is positive - if TEXT is received before the timeout, wait does not terminate and place TRUE on the stack. The timeout period is always observed.
e.g. after dialling using the send ATDT$phone \n command, the script waits five seconds for CONNECT, and, if received, jumps to another part of the script.
flush
send ATDT$phone \n
wait 5 CONNECT
truegoto connected
echo Connection failed\r\n
down
:connected
echo Connected\n
up
e.g. after dialling, the script detects CONNECT or BUSY and acts
accordingly.
flush
send ATDT$phone \n
wait 5 CONNECT
truegoto connected
compare $waitstring BUSY
truegoto linebusy
echo Connection failed\r\n
down
:connected
echo Connected\r\n
up
:linebusy
echo The line is busy - please try again later\r\n
down
e.g. it is not easily determined how long to wait for a CONNECT when dialling out, and your modem returns BUSY if the line is engaged. The following script will send the dial command, wait for the modem to report either way, and act accordingly:
flush
send ATDT$phone \r
doze
wait 1 CONNECT
truegoto connect
# could use compare $waitstring BUSY but wait does a
# subset compare, whereas compare does an exact
# compare…
wait 0 BUSY
truegoto busy
echo Unknown modem response\r\n
down
:busy
echo Line was engaged\r\n
down
:connect
echo Connected!!!\r\n
beep
up
See sleep, discard, flush, doze.
5.8 Variable reference
Before executing a script, certain variables are
initialised for you, and have a special meaning to the interface
you are connecting on, the ISP for that interface, or the protocol
settings for that interface. Some variables have special meanings
or functions within the script interpreter. The context of each
variable is given in the summaries which follow as I/F,
ISP, SI, PR. Some variables are read-only
and are marked as RO. Any attempt to store data in them
will terminate the script with a message, and the command down
will be performed. Variables marked RW and (I/F
or ISP) are stored back in the interface or ISP configuration
if (and only if) the script ends with up.
5.8.1 $IPDNS1, $IPDNS2
(I/F, RW, dotted quad)
Whatever IP address has been configured for this interface's primary
and secondary Domain Name Service (DNS) servers. When using dynamic
allocation, you'd store an address here before doing an up
command.
5.8.2 $IPgateway1, $IPgateway2, $IPgateway3, $Ipgateway4
(I/F, RW, dotted quad)
Whatever gateway IP addresses have been configured for this interface.
When using dynamic allocation, you'd store an address here before
doing an up command.
5.8.3 $IPaddress
(I/F, RW, dotted quad)
Whatever IP address has been configured for this interface. When
using dynamic allocation, you'd store an address here before doing
an up command.
5.8.4 $IPnetmask
(I/F, RW, dotted quad)
Whatever subnetwork mask has been configured for this interface.
When using dynamic allocation, you'd store an address here before
doing an up command. (Was called $subnetMask in 0.02)
5.8.5 $password
(ISP, RO, string)
The password you entered in the ISP dialog. Security Note: If
you don't want your password storing for posterity, you can leave
this field blank in the dialog. Whenever $password is referenced,
it is checked to see if it contains anything. If it's blank, a
dialog will pop up asking you to enter your password. This
password is not subsequently stored in the ISP details. It
is merely held while the script is being processed. You can press
return to leave a blank password, but then you'll still get prompted
for a password every time $password is referenced. For security
reasons, you should always have a password!
5.8.6 $phone
(SI, RO, string, initially set to $phone1)
$phone is the current phone number. See nextphone.
5.8.7 $phone1, $phone2, $phone3
(ISP, RO, string)
The bank of three phone number. See nextphone.
5.8.8 $phoneNumber
(SI, RO, numeric, initially set to 1)
Which phone number from the bank of three is returned when you
use $phone. See nextphone.
5.8.9 $username
(ISP, RO, string)
The user name you entered in the ISP dialog.
5.8.10 $waitstring
(SI, RO, alphanumeric)
Any data received on the interface's serial port is appended to
this variable, when the script input state is buildup. If the
state is discard (as set by the discard command), incoming
data is thrown away. See discard, wait, doze.
ATZ\r OK\r\n ATDT123456\r (several seconds later…) \r\n CARRIER 9600\r\n \r\n PROTOCOL: ALT\r\n \r\n CONNECT 9600\r\n \r\r\r (have to press return a few times) Annex Command Line Interpreter * Copyright 1991 Xylogics, Inc.\r\n \r\n Checking authorization, Please wait...\r\n login: username\r\r\n Password: password\r\r\n \r\n Permission granted\r\n PAD1>SLIP\r\r\n Switching to SLIP.\r\n Annex address is 123.1.2.55. Your address is 123.1.2.39.\r\n
# Xylogics Annex script. MJG 31/07/97 echo Resetting & Initialising modem...\r\n send ATZ\r sleep 2 send ATE0L1M1Q0V1\r sleep 1 :dial echo Dialling $phone \r\n flush send ATDT$phone \r doze wait 1 CONNECT # If we connect, go to the "connected" label truegoto connected # OK, we didn't connect... what happened? wait 0 BUSY truegoto busy # Nope, something weird happened. echo Could not connect. Modem returned "$waitstring "\r\n down :busy echo $phone is busy. Trying next number...\r\n nextphone isempty $phone falsegoto dial echo No more phone numbers to try\r\n down :connected echo Connected to $phone - logging in...\r\n # I need to send a few returns to wake the remote end up. I'll # get a login: prompt when it's awake. If I've sent 8 returns, # give up, 'cos something's wrong. set $return 1 :wakeyWakey wait 1 ogin: truegoto sendLogin flush send \r set $return $return 1 + eval $return 8 = falsegoto wakeyWakey echo Remote end didn't wake up.\r\n down :sendLogin #flush echo Sending user name "$username ".\r\n send $username \r\n # And now we get password:... set $return 1 :pwdpromptwait wait 1 assword truegoto sendPassword echo Waiting for Annex to ask for your password.\r\n set $return $return 1 + eval $return 8 = falsegoto pwdpromptwait echo Annex isn't asking after 8 seconds. Giving up.\r\n down :sendPassword echo Sending password "$password ".\r\n send $password \r\n # And now we get PAD1>... wait 2 PAD1> truegoto setProtocol echo Remote end didn't give a prompt.\r\n down :setProtocol echo Got prompt. Asking for SLIP.\r\n flush send SLIP\r # And now we get # "Switching to SLIP.\r\n # Annex address is 123.1.2.55. Your address is 123.1.2.39.\r\n" # Ignore the first address, but get the second IP address (dotted quads) # into the interface address variables. set $return 1 :waitaddr wait 1 Your address is truegoto fin set $return $return 1 + eval $return 8 = falsegoto waitaddr echo Annex isn't giving the IP address after 8 seconds. Giving up.\r\n down :fin splitip 2 $IPaddress echo Connected successfully. IP address is $IPaddress \r\n beep up
| Script | Provided by | Modem | ISP |
| Demon.SCP | Matt Gumbley | Hayes Accura 288 V.34+FAX | Demon Internet |
| IRDA.SCP | Matt Gumbley | Direct connection via IrDA device | None |
| Annex.SCP
See Appendix A | Matt Gumbley | Hayes Accura 288 V.34+FAX | A Xylogics Annex PAD |
| Win95\
PsiModem.SCP | Matt Gumbley | Direct connection to Win95 via fake Hayes Accura 288 V.34+FAX modem. | None |
| Win95\
PsiNull.SCP | Matt Gumbley | Direct connection to Win95 via TAPI Null-modem driver | None |
(I'll add some sensible ones later!!)
:-) A standard smiley, used to indicate humour. Voltaire didn't need it, neither did William Gibson. I suspect you don't, really.
Dotted Quad A unique numeric identifier for a network interface, a 32-bit number, which is split into four bytes or octets, each one being separated by a dot. E.g. 192.82.242.81
ICMP Internet Control Message Protocol. A standard for reporting errors in transmission over the Internet.
Interface A connection point to the Internet. PsiStack has two interfaces, one is a "local" interface, used by the stack itself; the other is for use when you connect to the Internet.
IP Internet Protocol. A best-effort data packet delivery mechanism for sending datagrams to machines on an internet.
Liberation Freedom from suffering, delusions, self-grasping ignorance, and your desktop computer.
Nuke To destroy, demolish, obliterate, wipe out, munge, hash into little bits, waste, screw up, or make FUBAR, by means of atomic weapons, or with a computer.
RTFM Read The Fine Manual. An exhortation to read these words before reporting problems….
TAPI Tremendously Awkward Protocol Infuriator, or, Telephony Applications Programming Interface. The software on Win95 which gets in the way when you try to connect PsiStack to it directly. TAPI doesn't understand direct connections, and expects to have to chat with a modem before it will allow a connection. So, since with Win95, everything you do will be faster and more fun, you have to download a third-party driver, install it, add a null modem device, configure dial-up networking, add a dial-up networking connection script, and a PsiStack dial-up script. Then test it, debug it, and so on. And they say Windows will take over the world. Please, spare me this torture.
TCP Transmission Control Protocol. Provides a reliable data connection between applications over an internet.
UDP User Datagram Protocol. Provides a best-effort data
packet delivery service between applications over an internet.
There are also the RFC's - Requests For Comments - these are mostly very technical documents, although there are a few which give general information on TCP/IP and the Internet. All RFC's can be downloaded using FTP from ds.internic.net, so point your web browser at ftp://ds.internic.net. FYI stands for "For Your Information".
And for those of you desperate to look "under the hood" and see how this technology works:
There are two other volumes in the Comer series, but they deal with the technicalities of writing a TCP/IP stack like PsiStack, and writing Internet programs. Only buy them if you're a real propeller-head, like me.
If you want to develop Internet applications using PsiStack, you might want to read:
psion-tcpip@listserv.inet.alsutton.com
Should you want to listen to our discussions about the product, you can subscribe to this mailing list by sending an email to the mailing list server:
majordomo@listserv.inet.alsutton.com
With a single line in the body of the message. (The subject header is ignored):
subscribe psion-tcpip (developer's list) or
subscribe psion-tcpip-announce (announcements list)
To obtain a help file for the majordomo server, send a message to the above, with the content:
help
General questions about the stack should be posted to the UseNet newsgroup comp.sys.psion.comm, where we'll try to answer as soon as we can. In particular, this is a good place to ask about scripts for your ISP.
Always check this owner's guide thoroughly before posting. We may just reply with "RTFM, page 27"
The latest version of the PsiStack software is available from our FTP server:
ftp://ftp.inet.alsutton.com/pub/psion-tcpip/
PsiStack has two interfaces. These can be
thought of as potential connection points to an internet.
We'll need to make some subtle distinctions here:
11.1 Some subtle distinctions
There are five classes of IP address: A, B, C, D, E and F. Every IP address is a member of one and only one of these classes. Exactly which class the address is a member of is determined by the first digit.
You'll need to understand a little about binary numbers to understand this diagram. If maths makes your eyes glaze over, don't worry. Just skip to the next section. The essential fact you should take from this section is that each interface has an IP address which uniquely identifies it.
| Class A | |||||||||
| Class B | |||||||||
| Class C | |||||||||
| Class D | |||||||||
| Class E | |||||||||
The splitting of IP addresses up into these different classes is a way of managing the number of hosts allowed on each network. From the diagram, you can see that the size of a Class A netid is smaller than that of a Class B netid. Similarly, a Class A hostid is larger than that of a Class B hostid. This means that you can have fewer Class A networks (unique netid's) than Class B networks, but you can have more hosts (unique hostid's) on a Class A network than you can have on a Class B network. And similarly for Class B vs. Class C. Class D and E addresses are special, and we won't go into what they're for…
Class A addresses, which are used for the handful of networks that have more than 216 (i.e. 65,536) hosts, devote 7 bits to the netid, and 24 bits to the hostid.
Class B addresses, which are used for intermediate size networks that have between 28 (i.e. 256) and 216 hosts, allocate 14 bits to the netid, and 16 bits to the hostid.
Class C addresses, which have less then 28 hosts, allocate
21 bits to the netid and only 8 bits to the hostid.
11.4 Static vs. Dynamic IP addresses
Each interface you use will have to be given a unique
IP address. If your computer is not connected to the Internet,
you can choose any old Class A, B or C IP addresses for your interfaces.
However, so as to prevent conflicts between your computer and
others, when hooked up to the Internet, you must use pre-allocated
IP addresses for your interfaces. There are two ways of allocating
IP addresses to interfaces: static and dynamic addressing.
Static addressing is easy: Your ISP will give you an IP address for your interface, which is fixed for that interface for all time. No-one else on the Internet will be using that IP address. ISPs are allocated batches of IP addresses by their superiors, and they are only given a limited amount, since, as you can see from the above table, unique hostid's on given networks are scarce.
Due to the incredible growth in Internet usage, ISPs have been forced to be more frugal in their allocation of IP addresses. Most of them have adopted dynamic addressing, where you are given an IP address from the ISP's address pool when you connect to them. This IP address is not being used by anyone else for the duration of your connection, but can be re-used by the next caller.
In the case of static addressing, you simply configure your interface with the IP address given to you by your ISP. It never changes. In the case of dynamic address, the IP address given to you must be communicated to stack when you connect. This is a job for dial-up scripting.
To conclude: PsiStack has two interfaces, each of which must be
given a unique IP address. These addresses may be allocated statically
or dynamically.
11.5 Why PsiStack is called a "stack"
At this point, it's worth understanding a little
more of how information gets around a TCP/IP network. This is
a little technical, so if you find yourself nodding off, skip
to the next section.
As an Internet User, you just want to get the job done, whether you're connecting to a mainframe computer as if you were sitting at one of its terminals, transferring data files or programs to remote computers, sending or receiving email, or surfing the World-Wide-Web. You're not really bothered about data-link layer protocol interactions, IP fragmentation and reassembly, selecting the correct TCP segment size and avoiding the strangely named "silly window syndrome", or wondering whether Karn's exponential backoff algorithm really is preventing packet storms on your PPP link. However, I feel that a little knowledge of these areas may help you understand how PsiStack works, and who knows, it may ignite the spark in you which sets you on the road to becoming a real propeller-head! It may even help you in troubleshooting… who knows…
As the above slightly whimsical paragraph may have indicated to you, there's a lot of things happening "under the hood" of stack - yes, there really is something called "silly window syndrome"!
PsiStack is called a "stack" for good reason: it consists of layers of complexity all stacked up on top of each other, like this:
In more detail, you can see the individual protocols in this "stack". At the top of this diagram are the applications, and at the bottom are the electromagnetic signals between computers:
So, to get a reliable connection from an application on your Psion (say, a telnet client) to an application on a remote computer (say, the telnet server on a UNIX computer), data has to flow from the top of the stack to the bottom, out through the cable, over the network, to the remote computer, which will presumably send you some information back. This information trickles back through your cable, up through the stack, and into the application.
And of course, if something goes wrong anywhere in that path between your host and the remote host, you'll cuss and swear and start to hate computers.
Fortunately, most of the leg work has been done for you by the
authors of PsiStack, but you still have to do some setting up.
In particular, you need to set up the IP addresses, select a data-link
protocol (SLIP or PPP), configure the RS-232 or IrDA link, and
finally, when all that's done, start communications by bringing
your interface up.
"ROFTL!!" - MJG
There is no simple method for connecting PsiStack to a Windows 95 PC. Several kludges are required, but it is possible. It is not possible to set up a SLIP, CSLIP or PPP connection directly over a serial port, as it is with UNIX or other systems. The only way is by using Dial-Up Networking (DUN) (even though you're using a direct cable connection, not a modem), and when you do, the Telephony Application Programming Interface (TAPI) gets in the way.
There are two ways to set up the direct connection using TAPI devices:
This is easier than you might think. TAPI normally sends several strings of modem initialisation commands, to which your modem replies 'OK'. It will then send a command to dial your ISP, usually of the form ATDT123456 where 123456 is your ISP phone number. The two modems chat for a second or two, then your modem tells TAPI that it has connected by sending the response CONNECT 28800 (or something similar). I use a Hayes Accura 288 V.34 + FAX modem, which is set to use numeric responses, rather than the text ones I've used above for illustration.
The PsiStack script which imitates my modem is quite simple, and may be found in the Win95 directory, file PsiModem.SCP:
echo Start dial-up networking on Win95\r\n
:waitloop
wait 0 ATDT0\r
truegoto dial
send 0\r
goto waitloop
:dial
echo Responding to dial\r\n
send 15\r
echo Connected to Win95!\r\n
beep
up
The first half of the script waits for TAPI to send the dial instruction.
When you set up the connection on Win95, set the 'phone number'
to a single zero. The script waits for the dial command ATDT0\r
and responds with the numeric OK response (0\r) to any other modem
initialisation command. When the dial command is sensed, the script
jumps to the :dial label, and sends the 15\r response, indicating
CONNECT 28800. PsiStack then brings up the interface.
12.1.1 Automation with Win95 Dial-Up Scripting, and installing SLIP/CSLIP
When TAPI sees the 15\r response, it will bring up
a terminal window to ask you if you need to type any extra commands
to the remote side. You don't, and you can press the 'Continue'
button. Or, you can install the Win95 Dial-Up Script DUNNull.SCP,
found in the Win95 directory, which brings Win95's interface up
immediately without prompting. You will need to install the Win95
Dial-Up Scripting tool from your Win95 CD-ROM first (it is integrated
with DUN on Win95 OSR2, but not on the first release of Win95).
To do this, insert your CD-ROM, go to Control Panel, Add/Remove
Programs, select the Windows Setup tab up top. Press Have Disk…,
and type the path D:\admin\apptools\dscript assuming your CD-ROM
is drive D. Press OK. Check the SLIP and Scripting for Dial-Up
Networking box, then press Install. (This also installs the SLIP
and CSLIP drivers on Win95).
Several configuration settings are discussed in the next section, so read that too, even though you're using the fake modem approach.
NB: Dial-up Networking 1.2 has recently been released. PsiStack
has not been extensively tested with that - there may be easier
ways of achieving these results.
12.2 Using a Null-Modem TAPI device
DUN is usually used with a modem, and Microsoft didn't
supply a Null-Modem TAPI driver with Windows 95. Fortunately one
has been developed, and is available as part of the PsiStack archive,
and from the home page of Kevin Wells, URL:
http://www.vt.edu:10021/K/kewells/net/scripts.html
Using this simplifies matters a little, but not much.
In the PsiStack Win95 directory, you'll find a file called mdmcisco.inf which is the Null-Modem driver. To install this, bring up the Control Panel, and select Modems. Click the 'Add' button. On the next dialog box, check the box marked 'Don't detect my modem; I will select it from a list', then click 'Next>'. Click 'Have Disk', and browse to the location of the mdmcisco.inf file. Select 'Generic NULL Modem', and then 'Next>'. Windows 95 will then install the driver. Configure it as necessary, ensuring the speed matches that of your Psion (57600 for the Series 3c, 19200 for the Series 3a).
If you are using SLIP to connect to your Psion, you will need to install the SLIP driver, details are given above.
To set up DUN to use the Null-Modem driver to connect to PsiStack, select 'Dial-Up Networking' under 'My Computer', and then 'Make New Connection'. Enter a suitable name for the connection, and select the 'Generic NULL Modem' as the modem (configure this as necessary). You'll need a phone number, so just enter zero as the number, and leave the area code blank.
Right-click on the newly-created connection, select Properties, and then select the Server Types tab.
For 'Type of Dial-Up Server', select 'SLIP: Unix Connection', and uncheck ALL other boxes, EXCEPT TCP/IP. Click the 'TCP/IP Settings' button.
Enter the IP address, and uncheck 'Use IP header compression'. 'Use default gateway on remote network' should be checked. Don't worry about the name server addresses.
On PsiStack, use the PsiNull.SCP script. Use the PsiWin cable
to connect the two computers. Start the Win95 side first, before
bringing PsiStack's interface up.
12.3 Conclusion
TAPI is braindead. (Well, it is a Microsoft
"standard", after all!) Take a look at the Connecting
to Linux section to see how it should be done on a real
Operating System.
With all this in place, and configured correctly, you should be
able to connect to your Win95 PC with no problems. Mail me (matt@gumbley.demon.co.uk)
if you run into problems.
You do not need a script on PsiStack since Linux will start sending SLIP-encapsulated IP data immediately, without anything awkward like TAPI in the way.