Introduction
A personal computer is required for operations with most embedded systems for long term storage, compilation, and communications with the internet. The term program provides the following facilities:
- Download COG9 Basic programs and data files into the embedded system's mass storage or directly into Flash and RAM.
- Communicate with COG9 Basic's (or any other program's) control program-things you type in a command window go to the embedded system and things it displays are echoed on the terminal.
- Upload data from the embedded system into the PC's file system.
1.1 Requirements
You need the following to run term:
- A computer running Windows XP or newer.
- The term.exe program.
- A common place to put the term.exe program.
- A way to talk to a serial port-COM1 → COM9.
- Something to talk to (could be another PC, embedded system, modem, ...).
1.2 Installation
The program is available as a Windows install script named term_install.exe. This installs the program in the 32 bit Program Files directory (this can change in newer systems) under the directory og9\bin. An uninstall script is also included. The program can be accessed by a button in the startup menu but this is not recommended as an initial error will cause the terminal to crash. It is best that you start the program from the command window.
1.3 The License
term is covered by the GNU Public License. This leaves you free to do pretty much whatever you want other than to sell it outright. There are no guarantees either.
Chapter 2
The Command Line Interface
term runs through the command line interface program. In Windows, this program is called cmd.exe. If you've installed the program as directed and can execute it, you can retrieve all the current information by entering term? in the command line window.
All command line options can occur in any order. There are defaults for each.
2.1 COM port
The communications port has a precompiled default (currently COM7 for obscure reasons) but any port from COM1 to COM9 is permissible. A common problem is the use of USB serial communications adapters. Every new one you plug in is assigned a new communications port number and eventually you reach COM10 which the current version of our Compiler can't handle. The solution is to:
- Activate the device manager.
- Find the serial communications port list.
- Locate the COM port you're having trouble with.
- Examine its properties.
- Go to the advanced section where the port number will be listed.
- Select a different COM port number less than 10.
- Ignore the system complaint and do it anyway.
- Don't override a hardware UART communications port (usually COM1 and COM2). These have disappeared from most computers so it's unlikely you'll be bothered. Microsoft likes to change this interface with every new release so you're on your own.
2.2 Baud Rate
Entering a number (in any order) modifies the baud rate from the default (usually 9600 baud). The following values and abbreviations are implemented:
| Number | Abbreviation |
|---|---|
| 110 | |
| 300 | |
| 600 | |
| 1200 | |
| 2400 | |
| 4800 | |
| 9600 | 9.6k |
| 19200 | 19.2k |
| 38400 | 38.4k |
| 57600 | 57.6k |
| 115200 | 115.2k |
2.3 Other Command Line Options
Other command line options can be interspersed at will.
| Option | Abbreviation | Description |
|---|---|---|
| -noisy | -n | Generate messages about what's happening. All messages are prefixed by CTERM: to indicate where they're coming from. |
| -nonewline | -nnl | Do not generate a new line code(\n) when encountering a |
| -newline | -nl | Do generate a new line code(\n) when receiving a |
| -quiet | -q | Don't generate messages about what's happening. |
| -sendsizennn | -ssnnn | Set the size of the download message to any value from 1 to 255. The default is 64. |
| -uploadfilename | -ufilename | Open the file name specified in append mode to continue uploading from some previous effort. New uploaded data will be appended to this file. |
Chapter 3
Escape Codes
Escape codes allow the remote connection to control the term's operation. The remote sends an ASCII escape code (decimal 27) followed by a control character and perhaps additional information.
3.1 Open File to Download es D filename 0
This sequence sets term to start downloading a file to the remote. The filename following the D must be present in the current directory that term is running in or must be the fully qualified name for somewhere else. The file name is terminated with a code 0 character. term will send a 1 in response if the file could be opened and 0 if not. The file name may not have more than 254 characters. Only one file can be open for input at one time. The file is closed automatically when end of file is reached.
3.2 Request Buffer of Download File es d
The remote sends this request when it's ready to receive a buffer from the open input file. term responds with a single byte indicating the number of characters to follow and then that number of characters. If this count is 0, end-of-file has been reached. The remote must have previously opened a file for download and you must not send a read request after the file is closed. The buffer size defaults to 64 bytes but you can use the -sendsize nnn or ss nnn command line options to set this as high as 255 or as low as 1 (very slow).
3.3 Change Send Buffer Size es s n
This command lets the remote temporarily change the send buffer size to the byte following. Sizes from 1 to 255 are permitted. Setting the size too small will cause very slow download transfers. A setting value of 0 will cause an error.
3.4 Open a File to Upload es U filename 0
When the remote sends this sequence, term is ready to accept characters from the remote to store in a file. The filename can be fully qualified (up to 254 characters) or just the name of a file in the current directory. term responds with a 1 if the file was opened for output and 0 if this somehow or other failed. Uploading the file is then accomplished by sending es u or es v sequences. Only one file can be open for output at a time.
3.5 Upload a Record es u nnn...
This escape sequence sends a string of bytes from 1 to 255 to term for storage in the open upload file. The 'u' is followed by a single byte indicating the number of bytes that follow (1-255). If this count is 0, the upload file is closed permanently. When the write has completed, term sends a 1 in response. The upload file must be open for this to function.
3.6 Upload Append Mode es v nnn...
This escape sequence also sends a string of bytes from 1 to 255 to term for storage in the open upload file. The 'v' is followed by a single byte indicating the number of bytes that follow (1-255). If this count is 0, the upload file is closed permanently. After the record is written, the upload file is closed and then reopened in append mode. Consequently, if the term host crashes or is turned off, the complete file to this point will be available. When this activity has completed, term sends a 1 to the embedded system or 0 if the activity failed (disk full, etc.). The upload file must be open for this to function. 'u' and 'v' escape sequences can be mixed on the same upload file.