ANSI-BBS2 Sepecifcation for Server to Client Communications and Saved ANSI-BBS2 Files

The ANSI-BBS2 Specification

This specification is designed to be a formal standard for new terminals intended to work with existing ANSI-BBS systems and provide usefull features which exist in the ECMA-48 standard or common implementations (ie: xterm, Linux console).

The goals of this specification are to be compatible with existing ANSI-BBS applications as much as possible, be compatible with the ECMA-48 as much as feasible without breaking ANSI-BBS compatability, provide a standard method for detecting these features, and provide a standard method for detecting new optional features.

ANSI-BBS terminal chariteristics:

End of line behaviour (wrapping) (Subject to discussion)

End of line wrapping will be controlled by the

As soon as a character is written to the last position on a line, an ANSI-BBS2 terminal will move to the beginning of the next line, scrolling all text up on the screen if this was the last line. No special handling of control characters at this point should occur. This means that directly writing to the last column of the last line will always cause a scroll.

Attributes

This document will often speak of attributes. An attribute is a complete combination of four different factors which effect visual presentation of a character. These factors are:

Please feel free to comment on this item.

Control characters:

While control characters have well defined meanings intended for terminals, BBS tradition has used these to display IBMs "low ascii" glyphs. Because of this historical usage, we must therefore support this if we intend to be compatible with a larger number of door games. In the standards, these are referred to as the C0 control function set.

List of all control characters by ASCII value

Please feel free to comment on this item.

Two-byte control functions

Two-byte control function format

Known as the "7-bit C1 control function set" for '@' to '_' and the "Independant control functions" for '`' to '~' in standards, these are two-byte combinations which do not take any parameters. The first byte is always an ESC (0x1b) character. The second byte is from the range '@' (0x40) to '~' (0x7e) inclusive.

Unhandled functions

If a legal function which the terminal does not support is encountered, that function should be silently ignored.

Illegal functions

An illegal function is defined as any ESC character followed by any character which is not in the range of '@' (0x40) to '~' (0x7e) inclusive.

When an illegal function is encountered, the terminal should attempt to make this known to the user in some manner. Commonly all or part of the function itself is displayed

Defined Control Functions (in alphabetical order by the second byte)

Please feel free to comment on this item.

Control Sequences:

Control Sequence Format

Control sequences make up the bulk of the ANSI-BBS spec. And contain four distinct parts which are, in order:

Control Sequence Introducer (CSI)
The two-character CSI consists of the ESC character (0x1b) followed by the '[' character (0x5b)
Parameter Bytes (PBs)
Parameter bytes consist of zero of more of the characters from '0' (0x30) to '?' (0x3f)
Intermediate Bytes (IBs)
Intermediate bytes consist of zero or more of the charaters from ' ' (0x20) to '/' (0x2f)
Final Byte (FB)
The final byte consists of one of the characters from '@' (0x40) to '~' (0x7e)

All control sequences begin with a CSI, are followed by a series of zero or more PBs which are followed by zero or more IBs and terminated with a FB. The IBs and the FB together make a string which defines the Control Function CF.

Parameter Byte Formats

If a parameter byte string consists of only characters from '0' to ';' inclusive ("0123456789:;") then it is interpreted as a list of semi-colon (';') separated numeric values. The meaning of a colon in a value must be defined by the control function. If it is not so defined, anything between a colon and the end of that sub-parameter is ignored (ie: up to the next semi-colon, IB, or FB).

If a parameter byte string begins with one of the chrarcters from '<' to '?' inclusive ("<=>?") then it is part of an extension which will be defined in another document.

If a parameter byte string begins with one of the characters from '0' to ';' inclusive ("01234567890:;") but contains one of the characters from '<' to '?' ("<=>?"), it is deemed to be an illegal sequence and should be handled accordingly.

Unhandled sequences

If a legal sequence which the terminal does not support is encountered, that sequence should be silently ignored. If one item in a parameter list is not handled, only that single unhandled parameter should be ignored. All other parameters from the list should be handled.

Illegal sequences

An illegal sequence is defined as:

  1. A sequence which begins with a CSI but has any IB character before any PB character.
  2. A sequence which begins with a CSI and contains a character which is not a legal PB, IB, or FB
  3. A sequence which begins with a CSI, is followed by a PB from the set of charaters from '0' to ';' inclusive, and contains a PB from the set of characters from '<' to '?' inclusive.

When an illegal sequence is encountered, the terminal should attempt to make this known to the user in some manner. Commonly all or part of the sequence itself is displayed, however, the effects on the local screen and terminal state are not defined by this standard.

Defined Control Sequences (in alphabetical order by FB)

Please feel free to comment on this item.

Sending characters from the client

Normal ASCII Characters

Any normal character entered at the keyboard is sent to the remote system as-is. Specifically, this includes the characters from ' ' (0x20) to '~' (0x7e) inclusive.

Control Characters

Control characters are the characters from NUL (0x00) to US (0x1f) inclusive and DEL (0x7f). Control characters except for the NUL (0x00) character entered by the user regardless if they are entered by a special key (such as TAB) or by a control-key sequence (such as CTRL-I) are to be sent unmodified to the remote system except when they are required by the underlying communication method to be handled in a special manner. This includes the Xon/Xoff (0x11 and 0x13) characters used for flow control for some serial connections and normal RLogin connections. NUL handling is not defined by this specification. The client may transmit it unmodified, may silently ignore it, or may perform some other action.

Special handling of the ESC key

Probably the most commonly asked question when people are working on doors is the ability to bind an action to the ESC key. Because excended characters all begin with an ESC key, a complex timeout system must be used which will always result in issues. It would be nice therefore to implement some method of communicating a user-pressed ESC to the server without requiring this. This concept however would break backwards compatability. Adding additional state is unsatisfactory for this since the state would likely to be maintained into a door which does not support ANSI-BBS2. At th is point, I favour using the ESC NULL pair to indicate this as it allows normal processing of ESC + next char and the NULL *should* be ignored. However, DoorWay mode expresses this as NULL ESC... so possibly using the DoorWay mode is a "better" idea.

Extended ASCII Characters Subject to discussion

Client handling of extended ASCII characteres entered by the user is not defined in the specification

DISCUSSION:
In general, it is believed that extended ASCII chars should be treated as normal ASCII characters for the purpose of this specification since many languages have code pages which require this range to be useable. The lack of a standard method to agree on current code-page however makes this a tough call as it cannot be readily determined which character is intended.

Extended keystrokes

Most systems have a large number of extended keystrokes available. These keystrokes require a special sequence to be sent to the remote system. Since some of these keystrokes will be required for control of the terminal program itself, these will be split into three groups:

  1. Required keystrokes whuch MUST be sent to the remote when entered by the user.
  2. Suggested keystrokes which are discouraged from being used by the client and, if they are not so used should be sent to the remote.
  3. Optional keystrokes which may or may not be implemented by the client in any way.

All extended keystrokes sent to the server will begin with the Control Sequence Introducer (CSI) and have one or more additional characters sent. The two-character CSI consists of the ESC character (0x1b) followed by the '[' character (0x5b).

Required Extended Keystrokes

The following extended keystrokes MUST be sent to the remote system when entered by the user

KeystrokeSequence to sendNotes
Left ArrowCSID
Right ArrowCSIC
Up ArrowCSIA
Down ArrowCSIB

Suggested Extended Keystrokes

The following keystrokes are discouraged from being used by the client and, if they are not so used should be sent to the remote.

KeystrokeSequence to sendNotes
F1ESC (0x1b) 'O' 'P'
F2ESC (0x1b) 'O' 'Q'
F3ESC (0x1b) 'O' 'R'
F4ESC (0x1b) 'O' 'S'
F5ESC (0x1b) 'O' 't'
F6CSI17~
F7CSI18~
F8CSI19~
F9CSI20~
F10CSI21~
F11CSI23~
F12CSI24~
InsertCSI@
DeleteDEL (0x7f)
HomeCSIH
EndCSIK
Page UpCSIV
Page DownCSIU

Optional Extended Keystrokes

These keystrokes are low-priority ones which should send these sequences if they send anything at all

Currently, no optional extended keystrokes are defined

Please feel free to comment on this item.

References

This is a list of the source documentation for existing specifications and implementations.

Please feel free to comment on this item.