FSC-0006 YOOHOO and YOOHOO/2U2 The matrix handshake used by Opus-Cbcs LEGAL STUFF ------------------------------------------------------------------------------ The protocol, documentation, and sample routines are by Wynn Wagner III. They are released to the public domain for any use whatsoever as long as you don't modify any transmitted structure. If you choose to use the method or the sample routines, you do so entirely at your own risk. It is possible that the routines will cause physical damage to your equipment, an invasion of fire ants, the plague, or an extended visit from in-laws. If any of that stuff (or anything else) happens, you accept the consequences totally. CREDITS ------------------------------------------------------------------------------ The state charts in this document were done by Vince Perriello (141/491). The ZModem protocol was designed by Chuck Forsberg. The Sealink protocol is copyrighted by System Enhancment Associates. Rick Huebner designed and implemented the WaZOO file request method. UPFRONT ------------------------------------------------------------------------------ YOOHOO and YOOHOO/2U2 are the initial handshakes for the WaZOO protocol. They are designed to let two system establish a common ground for a session while making sure that non-WaZOO software doesn't get upset by material it can't understand. Most of the time, the systems will be negotiating an e-mail session, but that isn't any kind of restriction. The mechanism could also be used to establish some kind of high-speed user interface session. YOOHOO is nothing more than a session-level negotiation. It does not suggest the kind of session being negotiated, and there is space in the initial packet for expansion into as-yet-unthought-of kinds of sessions. The YOOHOO procedure begins as a single byte (0xF1). If the system on the other end doesn't reply to that byte, no further YOOHOO or WaZOO transmissions are attempted. To a non-WaZOO netmail system, the YOOHOO byte will simply seem like a byte of debris. The calling system initiates the YOOHOO by sending the attention character. If the receiving system seems interested, the calling system sends a 128 byte packet containing such information as system and sysop names as well as a "capability mask." A 16-bit CRC protects the integrity of the 128-byte packet. In response, the receiving system prepares a 128 byte packet to send back. This is the YOOHOO/2U2 procedure. FEATURES ------------------------------------------------------------------------------ The features of YOOHOO and YOOHOO/2U2 include * non-interference with systems that don't understand the handshake * relatively foolproof method for identifying a remote system and establishing a common ground for transmission * built-in room to expand the capabilities of WaZOO without having to resort to a kludge USAGE ------------------------------------------------------------------------------ A calling system simply uses a routine like `sendYOOHOO()' instead of its normal TSYNC sending method. This sample routine will take care of both the TSYNC and the YOOHOO handshakes. A receiving system can call a routine like `getYOOHOO()' if it detects the YOOHOO character. PROTOCOLS IN A NUTSHELL ------------------------------------------------------------------------------ Currently there are two matrix methods in use: DietIfna ... similar to the method described by the FidoNet Technical Standard Committee. VARIATION: * file transfers are done using sealink or telink-without-the-Modem7. * file attaches don't even attempt to do a modem7 file name. * Sealink run-ahead is based on the baud rate and can be as high as 24 packets for 9600 baud. Because of its built-in unreliability, there are no plans to incorporate the SLO (sealink overdrive) variation. * If the calling system transmits a .REQ file for file requests, the receiving system can respond to it. See "WaZOO File Requests" (below) for information on the .REQ file. * When there is nothing to send, a system should remain quiet. In other words, the end of a session can be determined by a timeout. * Systems are sensitive to file tags (aka "extensions"). There is no requirement that a bundle be sent: the session can consist of archived messages with no bundle. Here are the current tags: .PKT ... Type Two bundle .MO# ... LZW-archive containing zero or more Type Two bundles. .REQ ... WaZOO request list. ZedZap ..... plain zmodem. The originator does a batch send then goes into a receive batch mode. The called system does receive then send. VARIATION: * Unlike the true zmodem protocol described by Chuck Forsberg, ZedZap routines must be able to handle a batch mode that has no actual files. In other words, it is possible for there to be an init sequence followed immediately by a ZFIN sequence. * The maximum packet size is based on the baud rate. For example, at 2400 baud it's 2048 bytes. At 9600 baud, the packets are 8192 bytes. * ZedZap uses an adaptive packet size that appears in very recent Forsberg specs. The size of the packet adjusts during transmission based on line conditions. * Systems are sensitive to file tags as in DietIfna (above). File Req... Rick Huebner, who wrote the ZModem routines for Opus, designed the ZModem-based file request system. There's a section on file requests (below). WAZOO FILENAMES ------------------------------------------------------------------------------ MESSAGE BUNDLES...xxxxxxxx.PKT Normal (unarchived) messages are sent in a file name that has a tag of .PKT. The "x" characters should be hex digits. IMPLEMENTATION NOTE ------------------- There is no real requirement that a .PKT file be part of a matrix session. Opus 1.03 and below require a .PKT file for DIETIFNA, but this is a mistake that will be corrected. The correct way to do things is to send only what needs to be sent. If the calling system is doing a "poll" then only the YooHoo and a sealink end-of-batch sequence should be all that is required. LZ BUNDLES........xxxxxxxx.MO# Message bundles are often shipped in an archive that has been compressed with some 12-bit LZ utility. The file name consists of a name with hex digits. The tag is "MO" and a number (0-9). FILE REQUESTS.....xxxxxxxx.REQ This is explained below. In a nutshell, the file name consists of the receiving system's matrix address expressed as two 4-digit hex numbers. The file tag is .REQ. DIETIFNA FLOW AND NOTES ------------------------------------------------------------------------------ All file transfer is done using Sealink. This protocol is copyrighted by System Enhancements Associates. The sealink run-ahead (number of blocks in the slide) is based on the baud rate: BlocksToSlide = BaudRate / 400. The calling system: * Send YooHoo * Receive YooHoo/2u2 * Send bundles, files, file request (.REQ) files (in that order) * Receive bundles, files, requested files (in that order) Receiving system: * Receive YooHoo * Send YooHoo/2u2 * Receive bundles, files, file requests (in that order) * Send bundles, files, and respond to file requests that arrived from the remote system. ZEDZAP FLOW ------------------------------------------------------------------------------ The calling system: * Send YooHoo * Receive YooHoo/2u2 * Send bundles, files, file request (.REQ) files (in that order) * Receive bundles, files, file requests * If a file request (.REQ) file came in, respond to it Receiving system: * Receive YooHoo * Send YooHoo/2u2 * Receive bundles, files, file requests * Send bundles, files, our file requests, and respond to file requests that arrived from the remote system. * If we sent a .REQ file in the preceeding step, wait for the other system to respond. WAZOO FILE REQUESTS ------------------------------------------------------------------------------ IMPLEMENTATION NOTE ------------------- Opus-Cbcs 1.00-1.02 supports WaZOO file requests only for ZedZap (Zmodem) sessions. Beginning with v1.03, WaZOO file requests are supported in all methods. REQ FILE: A WaZOO file request is based on a request file. The name of a request file is similar to the .OUT and .FLO files used by OPUS-Cbcs. TEMPLATE: netnode.REQ EXAMPLE: 00010002.REQ ... a request being sent to 1/2 The .REQ file is simply a text file that contains the files we want from the remote system. Those file names can include wildcards, but should not contain a path. Optionally, there can be a password... if the sending system requires one. The "netnode" part of the file name is built from the remote systems net and node numbers. Both numbers become 4-character hex numbers in the file name. Let's say we're requesting THIS.ARC and all node lists from 12/2. The file name would be 000C0002.REQ. The contents would look like this: this.arc nodelist.* If the sysop of 12/2 requires a password of THAT to get the file THIS.ARC, the REQ file contents would have to change: this.arc !that nodelist.* Transaction-level passwords (of 6 or fewer characters) follow the file name: ! MECHANISM: During the WaZOO session, the .REQ file is simply transmitted to the other system. It goes "as is" like any other file. The other system can ignore the request, send some of the files, or send all of the files. There is no accounting or responsibilities on the part of the remote system. NOTES: * In the YooHoo packet, there's a bit that lets you know if the remote system currently accepts .REQ files. This will be a clue as to whether a .REQ file would be a waste of time or not. * If the first character of a line in the .REQ file is a semi-colon (";"), Opus 1.10+ will ignore that line. * You are not guaranteed to get back what you requested. It is possible that the remote system has implemented a "macro" situation where one word in a .REQ file can send back one or more files. The file names may have nothing to do with the contents of the .REQ file. * It is also possible that a .REQ file will trigger some kind of activity other than the sending of a file. Opus 1.10+ has this sort of capability. It doesn't have anything to do with the mechanics of WaZOO or .REQ files, so if you need more information about this you can refer to Opus documentation. FUTURE ------------------------------------------------------------------------------ All the material in this document is subject to growth and improvement. I consider nothing here sacred or proprietary. If you have suggestions for enhancements, they'll never be implemented if you keep them to yourself! Personally, I'd like to see another protocol that does run-time packeting of such things as echomail. A system like that would be driven by the receiving system. It would send "commands" like "Send me all new C_ECHO messages." Combining some high-octane code along with run-time Lempel-Zev compression, two matrix systems can totally avoid such time consuming chores as scanning/tossing echomail. In addition, there would be no need for a SEEN-BY line because the two systems could use a LASTREAD system like they use for regular callers. There's also room for such things as a Kermit-based method... for discussing things with a mainframe. STRUCTURES AND DECLARATIONS ------------------------------------------------------------------------------ #define ACK 0x06 #define NAK 0x15 #define ENQ 0x05 #define YOOHOO 0xf1 #define TSYNC 0xae struct _Hello begin word signal; /* always 'o' (0x6f) */ word hello_version; /* currently 1 (0x01) */ word product; /* product code */ word product_maj; /* major revision of the product */ word product_min; /* minor revision of the product */ char my_name[60]; /* Other end's name */ char sysop[20]; /* sysop's name */ word my_zone; /* 0== not supported */ word my_net; /* out primary net number */ word my_node; /* our primary node number */ word my_point; /* 0== not supported */ byte my_password[8]; /* ONLY 6 CHARACTERS ARE SIGNIFICANT !!!!! */ byte reserved2[8]; /* reserved by Opus */ word capabilities; /* see below */ byte reserved3[12]; /* for non-Opus systems with "approval" */ end; /* size 128 bytes */ /*------------------------------------------------------------------------*/ /* YOOHOO CAPABILITY VALUES */ /*------------------------------------------------------------------------*/ #define Y_DIETIFNA 0x0001 /* Can do fast LoTek 0000 0000 0000 0001 */ #define Bit_1 0x0002 /* reserved by Opus 0000 0000 0000 0010 */ #define Bit_2 0x0004 /* reserved by Opus 0000 0000 0000 0100 */ #define ZED_ZAPPER 0x0008 /* Can do ZModem/plain 0000 0000 0000 1000 */ #define Bit_4 0x0010 /* reserved by Opus 0000 0000 0001 0000 */ #define Bit_5 0x0020 /* reserved by Opus 0000 0000 0010 0000 */ #define Bit_6 0x0040 /* reserved by Opus 0000 0000 0100 0000 */ #define Bit_7 0x0080 /* reserved by Opus 0000 0000 1000 0000 */ #define Bit_8 0x0100 /* reserved by Opus 0000 0001 0000 0000 */ #define Bit_9 0x0200 /* reserved by Opus 0000 0010 0000 0000 */ #define Bit_a 0x0400 /* reserved by Opus 0000 0100 0000 0000 */ #define Bit_b 0x0800 /* reserved by Opus 0000 1000 0000 0000 */ #define Bit_c 0x1000 /* reserved by Opus 0001 0000 0000 0000 */ #define Bit_d 0x2000 /* reserved by Opus 0010 0000 0000 0000 */ #define Bit_e 0x4000 /* reserved by Opus 0100 0000 0000 0000 */ #define WZ_FREQ 0x8000 /* WZ file req. ok 1000 0000 0000 0000 */ +--------------------------------------------------------------------------+ | | | YOOHOO: SENDER | | | | ## Status/Action Stimulus Action (comment) Goto | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s1 | Set 30.second | | | s2 | | | failsafe | | | | | | timer | | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s2 | Send YOOHOO | | | s3 | | | character | | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s3 | Send TSYNC | | | s4 | | | character | | | | | | (SEE NOTE #1) | | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s4 | Read char | Nothing in 3 sec | report not an Opus | return | | | | or lost carrier | | | | | | or timer elapsed | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received ENQuire | send handshake | s8 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 'C' | Other end may be | s5 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received NAK | Other end may be | s6 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 01 Hex | Other end may be | s7 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received debris | try again | s4 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s5 | Read char | Nothing in 3 sec | Pretend other side | return | | | | | is a Fido | | | | | | responding to TSYNC | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Timer elapsed | report not an Opus | return | | | | or Carrier lost | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received ENQuire | send handshake | s8 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received NAK | Other end may be | s6 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 01 Hex | Other end IS a | return | | | | Received 00 Hex | Fido responding | | | | | Received 'C' | to the TSYNC | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received debris | try again | s4 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s6 | Read char | Nothing in 3 sec | report not an Opus | return | | | | or lost carrier | | | | | | or timer elapsed | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received ENQuire | send handshake | s8 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 'C' | Other end may be | s5 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received NAK | Other end IS a | return | | | | | Fido responding | | | | | | to the TSYNC | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 01 Hex | Other end may be | s7 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received debris | try again | s4 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s7 | Read char | Nothing in 3 sec | report not an Opus | return | | | | or lost carrier | | | | | | or timer elapsed | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received ENQuire | send handshake | s8 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 'C' | Other end may be | s5 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received NAK | Other end may be | s6 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received 01 Hex | Other end may be | s7 | | | | | Fido responding | | | | | | to the TSYNC. Need | | | | | | further checking. | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received FE Hex | Other end IS a | return | | | | | Fido responding | | | | | | to the TSYNC | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received debris | try again | s4 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s8 | Send HELLO | Successful | Looks like an OPUS | s9 | | | (see hello | | | | | | chart) +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Not successful | Repeat whole thing | s2 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s9 | Read char | Nothing in 5 sec | repeat whole thing | s2 | | | | or lost carrier | | | | | | or timer elapsed | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received YOOHOO | Another Opus, go | s10 | | | | | process receive | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received debris | Repeat whole thing | s2 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | s10 | Process other | Information | Report Success | return | | | side's YOOHOO | Successfully | | | | | (See receive | Exchanged | | | | | chart) | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Failure | Repeat whole thing | s2 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | +--------------------------------------------------------------------------+ NOTE #1. Sending the TSYNC character is needed only if you are also supporting the IFNA/FTSC method. TSYNC is not part of YooHoo/WaZOO. +--------------------------------------------------------------------------+ | | | SEND HELLO PACKET | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | h1 | Disable XON | | | h2 | | | Disable ^C/^K | | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | h2 | Send Header | Transmit the 128 | | h3 | | | | byte HELLO struct | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | h3 | Clear inbound | | | h4 | | | buffer | | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | h4 | Send CRC | Transmit the 16 | | h5 | | | | bit CRC of HELLO | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | h5 | Read char | Received ACK | Success | return | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received '?' | Try header again | h2 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Received debris | Failure | return | | | | | | | | ----+---------------+-------------------+---------------------+--------- | +--------------------------------------------------------------------------+ +--------------------------------------------------------------------------+ | | | YOOHOO: RECEIVER | | | | | | ## Status/Action Stimulus Action (comment) Goto | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r1 | Got YOOHOO | | Smells interesting | r3 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r2 | Got TSYNC | | Report LoTek | return | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r3 | Clear buffers | | | r4 | | | Disable XON | | | | | | Disable ^C/^K | | | | | | Set timer | | | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r4 | Send ENQuire | | Let other end know | r5 | | | | | we heard YOOHOO. | | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r5 | Watch for Hex | Timer elapsed? | 30 sec. elapsed . | return | | | 1f (Header) | | Report failure | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Carrier loss | Report failure | return | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Character not | Keep watching | r5 | | | | header (0x1f) | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Got header char | Get Hello string | r6 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r6 | Receive 128 | Nothing for 5 sec | Report failure | return | | | bytes (hello) | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Got all 128 bytes | | r7 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r7 | Get CRC | One or both CRC | Short packet | r8 | | | | characters timed | | | | | | out (over 3 sec) | | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Error | CRC isn't what it | r8 | | | | | should be | | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | CRC compares | Success | r9 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r8 | Error handler | Count expired? | 10 failures to get | return | | | Send '?' | | hello. Hang up. | | | | (0x3f) | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Count not expired | Try again | r5 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r9 | Clear inbound | Are we the | Report OPUS | return | | | Send ACK | instigator? | | | | | Send YOOHOO | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Not instigator | Send our Hello | r10 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r10 | Look for ENQ | Timer elapsed? | 5 sec. timeout | r11 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Character not ENQ | Debris | r11 | | | | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | ENQ received | Transmit Hello | r12 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r11 | Clear inbound | Count expired? | 5 retrys, failed. | return | | | Send YOOHOO | | | | | | +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Count not expired | Try again | r10 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | | | | | | | | r12 | Send HELLO | Successful | Success | return | | | (see hello | | | | | | chart) +- - - - - - - - - -+- - - - - - - - - - -+- - - - - | | | | | | | | | | Not successful | Repeat whole thing | r1 | | | | | | | | ----+---------------+-------------------+---------------------+--------- | +--------------------------------------------------------------------------+ ###