TCP Extension

Represent socket access from Raw extensions. This is registered as 0x22 in RawExtensions.py

Usage

Client Socket Commands

command	Message format	Errors
open	0x22 + handle-byte + 0x01 + "hostname:port"	0 : failed to connect
close	0x22 + handle-byte + 0x02	n/a
write	0x22 + handle-byte + 0x03 + [ data array ]	0 : failed to write
read	0x22 + handle-byte + 0x04 + size-msb + size-lsb	n/a

Server Socket Commands

command	Message format	Errors
bind	0x22 + server-byte + 0x05 + "interface:port"	0 : failed to bind
unbind	0x22 + server-byte + 0x06	n/a
accept	0x22 + server-byte + 0x07	0 : no connection, 255 : server socket failed

Send a message starting with 0x22 as the first byte. The second byte should be socket handle number to use. The third byte is the command to process, followed by command specific arguments.

Client Sockets

Socket handle numbers are a single byte 0-255, assigned arbitrarily by the TI code when it passes the value in the open command.

For command 0x01 open / follow with string in the form of "hostname:port". Tipi will return a message of 255 if connected or 0 if failed to connect. The string will be assumed to be the message length - 1. To connect as handle 0x00 to www.google.com port 80 the message bytes could be:

0x22 0x00 0x01 'w' 'w' 'w' '.' 'g' 'o' 'o' 'g' 'l' 'e' '.' 'c' 'o' 'm' ':' '8' '0'

For command 0x02 close / no parameters. Tipi will return 255. To close socket with handle 0x00:

0x22 0x00 0x02

For command 0x03 write / follow with bytes to write to socket. Tipi will return after bytes are written with 255 or 0 if failed to write. To write "HELLO" to socket with handle 0x00:

0x22 0x00 0x03 'H' 'E' 'L' 'L' 'O'

For 0x04 read / follow with max size to read as int (two bytes, [msb,lsb]). Tipi will return message of read socket data no greater than max size. It may read from 0 to max size. This depends on the available bytes in the socket buffer on the Raspberry PI's TCP stack. Reading 0 bytes does not indicate that the there is no more data, just that it hasn't been buffered yet. Use higher-level protocols to determine completeness. TIPI returns a 0 length array if the socket is not open. To request reading upto 2k from the socket with handle 0x00:

0x22 0x00 0x04 0x02 0x00

Note on read - if the remote system disconnects, it will not be detected by reading alone. However, attempts to write will eventually fail in the case of a remote initiated disconnect.

Server Sockets

Server sockets are not opened, instead you bind a listening port, and then accept incoming connections. A successful accept creates a socket handle that you can use just like client sockets with read, write, and close. Then when you are done listening, unbind the server socket. This will close all connected sockets.

To facilitate this, 3 additional commands are available that process server sockets. Each of these have a server-byte parameter instead of a handle-byte. This server-byte is another handle, but used to identify which bound server socket to interact with when later accepting, or unbinding. The server-byte value can be from 0-255.

For command 0x05 bind / follow with an interface address and port string separated by a colon. The interface address can be '*' to allow incoming connections to all network interfaces on the Raspberry PI. This will return a 255 if binding is successful, or 0 if it fails. A typical message sequence to listen on all interfaces port 8080:

0x22 0x00 0x05 '*' ':' '8' '0' '8' '0'

For command 0x06 unbind / no additional parameters. A message to unbind server socket with handle 0x00:

0x22 0x00 0x06

For command 0x07 accept / no additional parameters. Accept will not block. It will return 0 if no incoming socket is connected. It will return 255 if the server socket is invalid. If a socket is connected, it will return a handle-byte from 1-254 to be used with the read, write, and close commands. A message to accept a connection from server socket bound as 0x00:

0x22 0x00 0x07

Note: close and unbind respond with a constant message of 0x255, and that must be received, before more messages can be sent.

Examples

Assembly language HTTP interaction: Stuart Conner's TI-99/4A Pages

C(gcc) telnet client: tipi/examples in Github