
 Copyright 2012-2014, Xilinx, Inc. All rights reserved.
This file contains confidential and proprietary information of Xilinx, Inc. and is
protected under U.S. and international copyright and other intellectual property laws.

Disclaimer:
  This disclaimer is not a license and does not grant any rights to the materials
  distributed herewith. Except as otherwise provided in a valid license issued to you
  by Xilinx, and to the maximum extent permitted by applicable law: (1) THESE MATERIALS
  ARE MADE AVAILABLE "AS IS" AND WITH ALL FAULTS, AND XILINX HEREBY DISCLAIMS ALL
  WARRANTIES AND CONDITIONS, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED
  TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR
  PURPOSE; and (2) Xilinx shall not be liable (whether in contract or tort, including
  negligence, or under any other theory of liability) for any loss or damage of any
  kind or nature related to, arising under or in connection with these materials,
  including for any direct, or any indirect, special, incidental, or consequential
  loss or damage (including loss of data, profits, goodwill, or any type of loss or
  damage suffered as a result of any action brought by a third party) even if such
  damage or loss was reasonably foreseeable or Xilinx had been advised of the
  possibility of the same.

CRITICAL APPLICATIONS
  Xilinx products are not designed or intended to be fail-safe, or for use in any
  application requiring fail-safe performance, such as life-support or safety devices
  or systems, Class III medical devices, nuclear facilities, applications related to
  the deployment of airbags, or any other applications that could lead to death,
  personal injury, or severe property or environmental damage (individually and
  collectively, "Critical Applications"). Customer assumes the sole risk and
  liability of any use of Xilinx products in Critical Applications, subject only to
  applicable laws and regulations governing limitations on product liability.

THIS COPYRIGHT NOTICE AND DISCLAIMER MUST BE RETAINED AS PART OF THIS FILE AT ALL TIMES. 



-------------------------------------------------------------------------------------------------
PicoTerm v1.97 
-------------------------------------------------------------------------------------------------


           ____  _         _____
          |  _ \(_) ___ __|_   _|__ _ __ _ __ ____
          | |_) | |/ __/ _ \| |/ _ \ '__| '_ ` _  \ 
          |  __/| | (_| (_) | |  __/ |  | | | | | | 
          |_|   |_|\___\___/|_|\___|_|  |_| |_| |_| 




11th April 2014

Ken Chapman - Xilinx Ltd - email:chapman@xilinx.com


PicoTerm is primarily a simple PC based terminal ideally suited for communication with PicoBlaze 
based designs that utilise the UART macros connected to a USB/UART port on a development 
board or evaluation kit. However, given that PicoTerm is a simple terminal that can be used to
communicate with any 'COM' port it could be used with virtually any hardware and design.

The primary motivation for the development of PicoTerm was to provide a quick and reliable way 
to establish a working connection with a PicoBlaze based UART design. Whilst this should be 
easy to achieve with any terminal application, correctly setting all the communication and 
ASCII options often makes this a challenge. PicoTerm has been pre-configured to match with the 
parameters required for a PicoBlaze/UART designs and has a default BAUD rate of 115200. This 
means that in most cases only the COM port needs to be specified and it even helps to make 
that easier to do.

PicoTerm also has some features that you would not expect to find with a normal terminal. These 
special features are described later in this document and will hopefully appeal to users of 
PicoBlaze for fun, education or serious applications. The 'PicoTerm_routines.psm' file 
provided with PicoTerm contains a set of KCPSM6 routines with descriptions ready to be used with
PicoTerm. What will you use the virtual 7-Segment Display for? 

   
Summary of PicoTerm Features
----------------------------

   - Easy setup
   - 1.6:1 aspect ratio (47 lines of 144 characters)
   - 8 text colours
   - Virtual 7-Segment Display (4-Digits)
   - Virtual LED Display (8 Red + 8 Amber + 8 Green)
   - Virtual Switches Window (16-Switches)
   - 256 x 256 graphic display 
   - Date and Time information
   - Random numbers
   - Writing log files
   - Reading text files


In this file
------------

System Requirements 
Usage
  Quick Start Method                             <- This is all you really need  
  How To Find The COM Port Number                <- to start using PicoTerm 
  Closing PicoTerm
  Opening PicoTerm with command line options
PicoTerm Features
  Control Codes (Characters)
  Special Features and Control 
    Escape Sequences
Device Control Strings
  'Ping' Sequences
  Time String Sequence
  Time Value Sequence
  Date String Sequence
  Date Value Sequence
  Pseudo Random Number Sequence
  Opening and closing a LOG file
  Hide DCS Transactions Window
  PicoTerm Application Control
  Virtual LED Display
  Virtual 7-Segment Display
  Virtual Switches
  Graphic Display
  Reading Text Files
Invalid Characters and Control Sequences
BAUD Rates and Character Rates


-------------------------------------------------------------------------------------------------
System Requirements 
-------------------------------------------------------------------------------------------------

Windows-XP or Windows-7 Operating System.

A 'COM' port to communicate with - This appears to be obvious but do remember that when using a 
                                   USB/UART connection a driver may need to be installed to 
                                   provide you with a 'virtual COM port'. You also need to have 
                                   the hardware connected to your PC and power turned on.

You need to know the number of the COM port and the required BAUD rate (see 'Usage' section).



-------------------------------------------------------------------------------------------------
Usage
-------------------------------------------------------------------------------------------------


Quick Start Method
------------------

PicoTerm has the communication fixed to 8-bit, 1 Stop Bit, No Parity and No Handshake which is 
immediately compatible with the UART macros provided with PicoBlaze. This means that the only 
two variables are the number of the COM port and the BAUD rate. However, even the BAUD rate
defaults to 115200 so if you use this in your design (e.g. as set in the reference designs 
provided with the KCPSM6 version of PicoBlaze) then you don't have to worry about that either.

So if the required BAUD rate is indeed 115200 then simply execute PicoTerm and it will prompt
you to enter a COM Port number. All you need to do is enter the correct COM number. 


How To Find The COM Port Number
-------------------------------

Although the COM port number is the only piece of information that you need, this vital piece 
of information may not be so obvious especially when using a USB/UART where a virtual COM port
number has been automatically allocated by the driver. But don't worry, we can look that 
information up and it is then quick and easy way to make connection attempts with PicoTerm.

To find the possible COM port number on your PC make sure your hardware is connected and 
has the power turned on....

  Right click on 'My Computer' and select 'System Properties'
    Select the 'Hardware' tab.
      Click on 'Device Manager'
        Scan down the list to find 'Ports (COM & LPT)
          Click on '+' to open this section and review COM port numbers.

   For example, a Xilinx Evaluation Kit such as the VC707 board will show something like...
    
      Silicon Labs (CP210x USB to UART Bridge (COM13)   

   Hint - Temporarily disconnecting the USB cable connected to a USB/UART port will typically
          cause the COM port list in the 'Device Manager' to update so you can see which COM 
          port disappears and reappears as you unplug and reconnect it.    


Having entered a COM port number into PicoTerm, it will attempt to open that port. If it is 
unable to open that port then it will tell you. It may be that you specified an invalid port 
number but you should also remember to check that you have no other applications open that are 
already accessing the same port before trying again. 

When a COM port is opened successfully then a message similar to the following will be displayed.

   COM13 is open for communication at 115200 baud.

Then as soon as anything is received from that port, or any key is pressed on the keyboard, the
screen will automatically clear and start displaying any received characters. So don't expect 
to see the message above if your hardware is transmitting information as you connect (it will
be obvious that it is working anyway!).



Closing PicoTerm
----------------

To close PicoTerm press the 'Esc' key or close the window. Although no issues have been 
encountered when simply closing the PicoTerm window, using the 'Esc' key is preferred as it 
does result in a definitive closing of the COM port at the end of the session.

The application (e.g. PicoBlaze) can also issue a 'Device Control String' (DCS) forcing
PicoTerm to close (full description later in this file).



Opening PicoTerm with command line options
------------------------------------------

There are three optional command line options available. 

   PicoTerm -c<port> -b<baud> -w

You can invoke PicoTerm from a command line in a 'Command Prompt' window or within a Batch
file. However, it is probably easier to create a PicoTerm shortcut (or several shortcuts) 
and edit the properties. 

How to create a short cut and edit its properties...
   Locate 'PicoTerm.exe' in Explorer.
     Right click on 'PicoTerm.exe' and select 'Create Shortcut'. 
       This should make a shortcut in the same directory.
       In Win7 the file name is called 'PicoTerm.exe - Shortcut'.
       Note that the icon has a small arrow inside a white box on it.
          If you wish, modify the name of the shortcut (e.g. 'PicoTerm for COM13').
            Then Right click on the shortcut and select 'Properties'.
               Append the required options to the 'Target'.
               e.g. Target:  C:\utilities\PicoTerm\PicoTerm.exe -c13 -b9600 -w 
                  If you want the shortcut on your desktop then simply drag the icon to it.

Valid command line options...

   -c<port>
 
   This option is useful when you always want to open the same COM port. Providing you specify 
   a COM port which is accessible (i.e. make sure any USB/UART bridge is connected and powered) 
   then your PicoTerm session will start immediately. 

   -b<baud>

   As previously explained, PicoTerm defaults to a BAUD rate of 115200. However, PicoTerm
   can support the following BAUD rates when specified using this option.
     1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800 and 921600. 
   Note that not all COM ports (real or virtual) support all of these rates. Also be aware 
   that higher BAUD rates don't necessarily mean high average data rates will be achieved.
   Please take a while to read the 'BAUD Rates and Character Rates' section later in this 
   document if you anticipate the transmission of reception of significant quantities of data.

   -w

   This option instructs PicoTerm to open a LOG file in the same directory in which the 
   PicoTerm executable (PicoTerm.exe) is located. All visible characters displayed in the
   main terminal window will also be written to the LOG file. The LOG file is automatically 
   given a name containing the date and time consistent with when it was opened. For example,
   'PicoTerm_08May2013_154530.txt' is a LOG file opened at 15:45:30 on the 8th May 2013. 
   The writing of LOG files can also be controlled by Device Control Strings (DCS). Please
   see 'Opening and closing a LOG file' later in this document for details.


   Examples

     PicoTerm -c5                     Open COM5 with default baud rate of 115200  

     PicoTerm -c 13                   Open COM13 with default baud rate of 115200  

     PicoTerm -c13 -b9600             Open COM13 with baud rate of 9600  

     PicoTerm -b9600                  Set baud rate to 9600 but still prompt for port number.   

     PicoTerm -w                      Write a LOG file but still prompt for port number. 

     PicoTerm -c13 -w                 Open COM13 with baud rate of 115200 and write a LOG file.  

   
-------------------------------------------------------------------------------------------------
PicoTerm Features
-------------------------------------------------------------------------------------------------

PicoTerm is first and foremost a simple terminal application but even as a basic terminal it does
incorporate some features that make it more compatible with typical PicoBlaze applications as 
well as for general use.

Wide display with 1.6:1 aspect ratio - Fits well on most landscape monitors and supports 47 lines 
of 144 characters. As with most applications, the physical window size can be adjusted by 
dragging the borders with your mouse but the active terminal size remains 144 x 47 characters.
No characters are displayed once the end of a line has been reached (i.e. line wrapping has been
deliberately prevented from occurring) but will automatically scroll. 


Control Codes (Characters)
--------------------------

The following commonly used control codes (characters) are supported...

'CR'                    - Carriage return with automatic Line Feed with. Note that this avoids
(0D hex = 13)             the requirement for Line Feed characters (0A hex = 10) to be 
Carriage Return           transmitted (except for special circumstances) which helps to keep
                          PicoBlaze programs smaller and easier to develop. Whilst other 
                          terminals can support this automatic line feed functionality it can 
                          often be difficult to find an ASCII setup option to enable it and your
                          display can be a real mess until you do!

'LF' Line Feed          - Feeds a new line but the cursor remains at the same position
(0A hex = 10)             along the new line as it was on the previous line.
Line Feed

'VT'                    - Moves cursor up one line. Note that the cursor cannot move up if
(0B hex = 10)             it is already located on the top line of the visible screen. 
Vertical Tab              (i.e. the cursor has to have space to move up into, it will not 
                          cause the display to scroll downwards within the visible screen).

'BS' or 'DEL'           - Moves the cursor one position to the left and deletes any character 
(08 hex = 8)              previously in that position. If the cursor is already at the start 
(7F hex = 127)            of a line then any character at the start of the line will be 
Back Space or Delete      deleted and the cursor will not move (i.e. start of the current line).
                          
'HT'                    - Advances the cursor to the start of the next column automatically 
(09 hex = 9)              clearing any previously displayed characters between the current 
Horizontal Tab            cursor position and its new position. Each column is 8 characters 
                          wide so the display width of 144 characters is exactly 18 columns.

'BEL' (07 hex = 7)      - Will make a short sound (providing your speaker is turned on!).

'NUL' (00 hex = 0)      - This does nothing at all!


  Hint - CR, LF, VT, BS, DEL, HT, BEL and NUL are predefined constants in the KCPSM6 assembler.

All other control codes (i.e. other codes in the range 01 to 1F hex) are automatically replaced 
with a '*' character. The display of this visible character makes it easier to observe and 
debug applications during development. (See also 'Invalid Characters and Control Sequences'
later in the document).



Special Features and Control 
----------------------------

The application (e.g. PicoBlaze) is able to control the main PicoTerm terminal window and 
to open and control a variety of independent features such as virtual LEDs and Switches. 
A selection of 'Escape Sequences' and 'Device Control Strings' (DCS) enable the application
to exert control over PicoTerm features whilst not being displayed as characters in their 
own right (i.e. in much the same way that a 'CR' control character starts a new line but 
is itself invisible). 

The remainder of this document describes each of the features available and the sequences used
to control them. The scale of the documentation may appear a little daunting at first but the
majority of features are actually straightforward to use and examples are provided in the 
PicoBlaze for Spartan-6, Virtex-6 and 7-Series (KCPSM6) package. Remember that everything 
beyond this point is optional but it is very much hoped that you will enjoy using the special
features available and that they will enhance your projects.

As with most technology, it is possible to encounter difficulties especially when using the 
more advanced features. This document ends with two sections to help you when developing 
applications using the special features. The first is called 'Invalid Characters and 
Control Sequences' and explains what PicoTerm will do if you should make a mistake and how it
tries to be as helpful as it can under those circumstances. The second section is called 'BAUD 
Rates and Character Rates' which you are advised to read if you anticipate the use of 
prolonged periods of communication at relatively high data rates such as when writing or reading
information to or from files on your PC.



-------------------------------------------------------------------------------------------------
Escape Sequences
-------------------------------------------------------------------------------------------------


PicoTerm supports the following 'Escape Sequences'....

  Move cursor to HOME position (upper-left of screen) and set text colour to black.

    'ESC' (1B hex = 27)
    '['   (5B hex = 91)
    'H'   (48 hex = 72)

  Clear screen, move cursor to HOME position and set text colour to black.

    'ESC' (1B hex = 27)
    '['   (5B hex = 91)
    '2'   (32 hex = 50)
    'J'   (4A hex = 74)
 
  
  Set the colour for the display of characters that follow.
 
    'ESC'    (1B hex = 27)
    '['      (5B hex = 91)
    colour   (Where 'colour' is one of the following values)
             (  1E hex = 30'd   Black                      )      
             (  1F hex = 31'd   Red                        )  
             (  20 hex = 32'd   Green                      ) 
             (  21 hex = 33'd   Yellow                     ) 
             (  22 hex = 34'd   Blue                       ) 
             (  23 hex = 35'd   Magenta                    ) 
             (  24 hex = 36'd   Cyan                       ) 
             (  25 hex = 37'd   Grey                       )
             (  26 hex = 38'd   White                      )


  Hint - ESC is predefined constant in the KCPSM6 assembler.

  Hint - 'White' is the background colour so it cannot be seen! It may be used to clear 
         previously displayed text but spaces (20 hex) in any colour would do this as well.


-------------------------------------------------------------------------------------------------
Device Control Strings
-------------------------------------------------------------------------------------------------


PicoTerm also implements some 'Device Control Strings' (DCS) that can be useful in PicoBlaze
applications. When PicoTerm receives one of the DCS sequences then it will perform a special 
operation. Some DCS commands will result in PicoTerm responding with another Device Control 
String containing appropriate information such as the time on the PC whilst others are used 
to open and control separate windows such as the virtual 7-Segment digits display.

When a DCS is used to facilitate the transfer of information between PicoBlaze (or similar) 
and the PC (e.g. a request for time) then a 'PicoTerm DCS Transactions' window will automatically
open and display a message confirming the request and information exchanged. This ensures 
that all communications with PicoTerm results in something visible on the PC screen which is 
often reassuring as well as useful during PicoBlaze (or similar) code development. 

The contents of a Device Control String may contain bytes of any value (i.e. data in the range 
00 to FF hex). The following characters that begin and end all 'Device Control Strings' have 
codes that are also beyond the normal 7-bit ASCII range. 
  'DCS' = 'Device Control String' character (90 hex = 144).
   'ST' = 'String Terminator' character (9C hex = 156).

Hint - DCS and ST are predefined constants in the KCPSM6 assembler.

Hint - When PicoTerm responds with a Device Control String it always starts with the same 
       character that was used to make the request. Although PicoBlaze (or similar) would have
       made the request, and therefore should know what response to expect, it is often convenient
       to implement a DCS handing routine that can operate fairly independently. Therefore, having
       the first character of the response string to identify the meaning of the information can
       be very useful for such a handling routine. Note that the 'ping' sequence is a special 
       case (see description below). 

Hint - Even if PicoTerm makes a DCS request for some information, the PicoTerm DCS response  
       may not be the very next thing waiting to be read from the UART receiver. Other keyboard
       characters may still be waiting in the receiver FIFO buffer and need to be processed 
       first. 

Note that PicoTerm will always transmit a complete DCS response. Keyboard entries can be made 
during the time that a DCS request and response is taking place but keyboard characters will 
always be transmitted either before or after the DCS response (i.e. will never become part 
of the response string).


Summary of 'Device Control Strings' (DCS) available in this version (full details below).

D - Read Date string
d - Read Date value
G - Plot point in graphic display
g - Plot character in graphic display
h - Hide transaction window
L - LED display
N - Request a Pseudo Random Number
P - 'Ping' with PicoTerm version request
p - 'Ping'
q - Force PicoTerm to restart
Q - Force PicoTerm application to quit
R - Read default text file
r - Read any text file with auto prompt
S - Read switches
s - Set switches
T - Read Time string
t - Read Time value
V - Fill a box in the graphic display
v - Draw a line in the graphic display
W - Open a LOG file
w - Close the LOG file
7 - Seven segment display




  'Ping' Sequences
  ----------------

    A 'Ping' sequence provides a simple way for PicoBlaze (or similar) to determine if it 
    is communicating with PicoTerm rather than a different terminal. It is a good idea to 
    check that PicoTerm is being used if your application goes on to use any of its special 
    features provided. There are two forms of 'Ping' request which are shown below (note 
    the specification of either lower case 'p' or upper case 'P').

      Simple 'Ping'                    'Ping' with version 
      Request to PicoTerm              Request to PicoTerm


        'DCS'   (90 hex = 144)          'DCS'   (90 hex = 144)
        'p'     (50 hex = 80 )            'P'   (70 hex = 112)
        'ST'    (9C hex = 156)           'ST'   (9C hex = 156)

    Depending of the type of 'Ping' request that PicoTerm receives, it will display 'Ping!' 
    or 'Ping! v1.93' in the 'PicoTerm DCS Transaction' window. It will then respond with 
    the appropriate DCS sequence shown below.

      Simple 'Ping'                     'Ping' with version 
      Response from PicoTerm            Response from PicoTerm

       'DCS'                            'DCS'      
       'P'    (upper case)              'p'   (lower case)
       'ST'                             'v'   version text string
                                        '1'    e.g. v1.93
                                        '.'
                                        '9'
                                        '3'
                                        'ST'

    Following the 'DCS', the first character of the response contains the opposite case of 
    letter to that used in the request. For example, the simple 'Ping' request contains a 
    lower case 'p' (70 hex = 112) and the response contains an upper case 'P' (50 Hex = 80).
    This case reversal ensures that a simple echo or loop-back connection cannot be confused 
    with a connection to PicoTerm. All other DCS responses made by PicoTerm begin with the 
    exact same character used in the request so this is only a special case for 'Ping'.

    The set of special features provided by PicoTerm is increasing over time. When an 
    application requires a specific feature to be present, the 'Ping' with version 
    request enables the application to verify that PicoTerm is connected and to verify that
    it is of a suitable version. The response contains the version in the form of a 5-character 
    ASCII text string. Note that the version request was introduced in PicoTerm v1.93 so 
    earlier versions will report that a 'P' request is an 'Invalid string!'.



  Time String Sequence
  --------------------

    Request to PicoTerm


    'DCS'     (90 hex = 144)
    'T'       (54 hex = 84 )   upper case 'T'
    'ST'      (9C hex = 156)

    PicoTerm response is a string of 8 ASCII characters describing the current time
    on the PC. The time is 24-hour with an hour value range of '00' to '23'.
    For example...   14:27:58 

    'DCS'
    'T'  
    '1'
    '4'
    ':'
    '2'
    '7'
    ':'
    '5'
    '8'
    'ST' 


  Time Value Sequence
  -------------------

    Request to PicoTerm

    'DCS'     (90 hex = 144)
    't'       (74 hex = 116)   lower case 't'
    'ST'      (9C hex = 156)

    PicoTerm response is a series of 3 byte values representing the current time on the 
    PC in hours, minutes and seconds. 

    'DCS'
    't'  
    hours     (byte value 00 to 17 hex = 0 to 23)
    minutes   (byte value 00 to 3B hex = 0 to 59)
    seconds   (byte value 00 to 3B hex = 0 to 59)
    'ST' 


  Date String Sequence
  --------------------

    Request to PicoTerm

    'DCS'     (90 hex = 144)
    'D'       (44 hex = 68 )   upper case 'D'
    'ST'      (9C hex = 156)

    PicoTerm response is a string of 11 ASCII characters describing the current date 
    on the PC. The day is always represented by 2 characters, the month by 3 characters
    and the year by 4 characters. For example...   02 May 2012

    'DCS'    
    'D'
    '0'
    '2'
    ' '
    'M'
    'a'
    'y'
    ' '
    '2'
    '0'
    '1'
    '2'
    'ST' 


  Date Value Sequence
  -------------------

    Request to PicoTerm

    'DCS'     (90 hex = 144)
    'd'       (64 hex = 100)   lower case 'd'
    'ST'      (9C hex = 156)

    PicoTerm response is a series of 3 byte values representing the current date on the 
    PC as year, month and day.  

    'DCS'  
    'd'  
    year      (byte value 00 to 63 hex = 0 to 99)   e.g. '12' for the year 2012.
    month     (byte value 01 to 0C hex = 1 to 12)
    day       (byte value 01 to 1F hex = 1 to 31)
    'ST' 



  Pseudo Random Number Sequence
  -----------------------------

    The following sequence includes a 24-bit value (3-bytes) which defines the maximum value 
    which the random number returned by PicoTerm can be.

    'DCS'            (90 hex = 144)
    'N'              (4E hex = 78 )
    max(0)           (maximum value[7:0])
    max(1)           (maximum value[15:8])
    max(2)           (maximum value[23:16])
    'ST'             (9C hex = 156)

    PicoTerm will respond with the following sequence containing a 24-bit (3-byte) pseudo random
    number in the range 0 up to, and including, the maximum value specified during the request. 

    'DCS'      
    'N'
    random(0)        (random number[7:0])
    random(1)        (random number[15:8])
    random(2)        (random number[23:16])
    'ST'        

    A message will be displayed in the 'PicoTerm DCS Transaction' indicating that a request was 
    received and showing both the maximum value and random number returned (as 6-digit hex values).
    For example, the message 'Random (0003FF) -> 000142' indicates that the maximum value 
    specified in the request was 0003FF hex and the random number generated and returned on 
    this occasion was 000142 hex. 


    Analysis of a significant quantity of random numbers returned by PicoTerm would reveal that
    their values are evenly distributed across the 0 to 'maximum value' range.

    Hint - Specifying an appropriate 'maximum value' ensures that ALL responses will be valid
           and suitable for immediate use in your application.  

    Hint - Exercise great care if you request a larger number than your application actually 
           needs. Reducing a series of larger values to make a series of smaller values can 
           easily result in an uneven distribution of values. This is why the DCS request 
           allows you to define a 'maximum value' and it is strongly recommended that you 
           use this feature.

    Hint - Requesting a value within the full 24-bit range ('DCS', 'N', 255, 255, 255 'ST') can 
           be used to obtain three random byte values each with the range 0 to 255 and the 
           property of even distribution. This only works because EVERYTHING is consistent with
           a power of two but again care should be taken not to extract smaller values from 
           each byte unless out of range values are discarded. 




  Opening and closing a LOG file
  ------------------------------

    PicoBlaze (or similar) can use the following DCS sequence to instruct PicoTerm to open a
    LOG file. Once a LOG file is open, all visible characters displayed in the main terminal 
    window will also be written to the LOG file. Whilst the LOG file cannot reflect the full 
    effect of all control characters and escape sequences, it attempts to provide a clean 
    and logical representation which is typically ideal for capturing automatically generated
    information. 

    Request PicoTerm to open a LOG file

    'DCS'     (90 hex = 144)
    'W'       (57 hex = 87 )   upper case 'W'
    'ST'      (9C hex = 156)

    When PicoTerm receives this sequence it will open a LOG file in the same directory in which 
    the PicoTerm executable (PicoTerm.exe) is located. PicoTerm automatically names the LOG file 
    'PicoTerm' followed by a date and time stamp (consistent with when it was opened) and with a 
    '.txt' file extension. For example, 'PicoTerm_08May2013_154530.txt' is the name of a LOG 
    file opened at 15:45:30 on the 8th May 2013.

    An 'Opening LOG file' message will be displayed in DCS Transactions window when a LOG file 
    is opened. The file name and location will also be displayed in the DCS Transactions window.

    Note that if the open LOG file sequence is received whilst a LOG file is already open then 
    PicoTerm will automatically close the current file and open a new one.

    Request PicoTerm to close the LOG file

    'DCS'     (90 hex = 144)
    'w'       (77 hex = 119)   lower case 'w'
    'ST'      (9C hex = 156)

    When PicoTerm receives this sequence it will close the LOG file. This will be confirmed by a
    by a 'Closing LOG file' message in the is displayed in DCS Transactions window. If this 
    sequence is received whilst no LOG file is currently open then an 'Attempt to close a LOG file 
    that is not open!' message will be displayed.


  Hide DCS Transactions Window
  ----------------------------

    The messages displayed in the 'DCS Transactions Window' can be very useful during the 
    development of an application. They show you the values being sent back to you in 
    response to your requests and will also help you to see when mistakes have been made.
    However, this window can be distracting once an application is fully developed and stable
    so this sequence can be used to close the 'DCS Transactions Window' or to prevent it from 
    opening in the first place. PicoTerm will not issue a DCS response to this request.

    'DCS'     (90 hex = 144)
    'h'       (68 hex = 104)
    'ST'      (9C hex = 156)


  PicoTerm Application Control
  ----------------------------

    The DCS shown below can be used to force the PicoTerm application on the PC to close (Quit).
    One situation in which this may be used is when a design uses PicoTerm to display various 
    information during initialisation and then automatically closes PicoTerm if everything
    works correctly or stays open to display an initialisation error.

    'DCS'     (90 hex = 144)
    'Q'       (51 hex = 81 )   upper case 'Q'
    'ST'      (9C hex = 156)

    The following DCS effectively forces the PicoTerm application to restart (a soft quit). The 
    main window will remain open but the screen will be cleared and the cursor set in the HOME
    position (equivalent to the '[2J' escape sequence). Any PicoTerm feature windows that are 
    open will be closed (e.g. virtual LED window). It can be useful to use this DCS during 
    code development.

    'DCS'     (90 hex = 144)
    'q'       (71 hex = 113)   upper case 'q'
    'ST'      (9C hex = 156)



Virtual LED Display
-------------------

The PicoTerm Virtual LED Display is a pop-up window containing 24 virtual LEDs. There are 8 red,
8 yellow (amber) and 8 green LEDs arranged in 3 rows as shown below.

         
                      7   6   5   4   3   2   1   0
         
             Red      O   O   O   O   O   O   O   O
             Amber    O   O   O   O   O   O   O   O
             Green    O   O   O   O   O   O   O   O
         

The virtual display is opened and updated using a 'Device Control String' (DCS) sequence. When 
PicoTerm receives the first virtual LED display DCS sequence it will open the virtual LED window
with the specified LEDs 'turned on'. Subsequent virtual LED display DCS sequences will modify 
the LEDs to reflect the new control values provided. Note that PicoTerm does not transmit 
a DCS sequence back to the COM port.

The DCS sequence for the virtual LED display is as follows (please read the 'Device Control 
Strings' section above if you are unfamiliar with this concept)...

    'DCS'                  (90 hex = 144)
    'L'                    (4C hex = 76 )
    RED_control_byte    
    YELLOW_control_byte    
    GREEN_control_byte    
    'ST'                   (9C hex = 156)

The virtual LEDs of each colour are controlled by the corresponding bits contained in each of 
control bytes. For example the least significant bit of 'GREEN_control_byte' will control the 
virtual LED in the lower right hand corner of the display.




Virtual 7-Segment Display
-------------------------

The PicoTerm Virtual 7-Segment Display is a pop-up window containing a virtual 4-digit, 
7-segment display. The digits and their segments are identified below.


              Digit 3             Digit 2             Digit 1             Digit 0

                 a                   a                   a                   a
                ___                 ___                 ___                 ___
              |     |
            f |     | b         f |     | b         f |     | b         f |     | b 
              |  g  |             |  g  |             |  g  |             |  g  |
                ___                 ___                 ___                 ___
    
              |     |             |     |             |     |             |     |
            e |     | c         e |     | c         e |     | c         e |     | c
              |  d  |             |  d  |             |  d  |             |  d  |
                ___   p            ___    p             ___   p             ___   p


The virtual display is opened and updated using a 'Device Control String' (DCS) sequence. When 
PicoTerm receives the first virtual display DCS sequence it will open the window and display 
the digits with the specified segments 'turned on'. Subsequent virtual display DCS sequences 
will modify the display to reflect the new control values provided. Note that PicoTerm does 
not transmit a DCS sequence back to the COM port.

The DCS sequence for the virtual 7-Segment display is as follows (please read the 'Device Control 
Strings' section above if you are unfamiliar with this concept)...

    'DCS'                         (90 hex = 144)
    '7'                           (37 hex = 55 )
    digit0_segment_control_byte    
    digit1_segment_control_byte    
    digit2_segment_control_byte    
    digit3_segment_control_byte    
    'ST'                          (9C hex = 156)

The segments of each digit are controlled by the bits contained in the control bytes. Each 
digit has 7 segments and a decimal point and a segment will be 'turned on' when the corresponding
bit of the control byte is High (1).

           Segment  Bit
        
              a      0
              b      1                  
              c      2
              d      3
              e      4
              f      5
              g      6
              p      7   decimal point


Hint - See the 'nibble_to_7seg' routine provided in the 'PicoTerm_routines.psm' file.




Virtual Switches
----------------

PicoTerm Virtual Switches is a pop-up window containing 16 virtual switches. Each switch has  
the appearance of a square black button with an embedded green LED. Clicking on a virtual 
button will toggle the state of the switch and the virtual LED will indicate the current
state, i.e. LED on means switch is turned on ('1').

        
      15  14  13  12  11  10   9   8   7   6   5   4   3   2   1   0
      
       O   O   O   O   O   O   O   O   O   O   O   O   O   O   O   O

There are two 'Device Control String' (DCS) sequences that can be used in conjunction with the 
virtual switches. The first time either sequence is received by PicoTerm the Virtual Switches 
display will be opened.

The first and most useful DCS sequence is used to read the current states of switches. If this
is also used to open the window then all 16 switches will initially be off ('0').

    Request to PicoTerm to read virtual switches

    'DCS'     (90 hex = 144)
    'S'       (53 hex = 83 )   upper case 'S'
    'ST'      (9C hex = 156)

In response to each use of the above DCS sequence, PicoTerm will respond with the following 
DCS sequence reporting the current states of all 16 switches.

    PicoTerm response

    'DCS'  
    'S'  
    switches(0)     (current states of switches[7:0])
    switches(1)     (current states of switches[15:8])
    'ST' 

Note that whilst the effect of clicking on a switch is immediately reflected by its indicator
LED, PicoTerm will only generate a DCS sequence in response to a DCS request. Hence, PicoBlaze
must issue a DCS request in order to determine the current states of the switches (this is
similar to the way in which PicoBlaze would need to read an input port to determine the current 
states of physical switches). 

In the top right of the virtual switches window is an small dot. When this dot is green it 
indicates that the current switch settings have not changed since the last DCS request and 
response occurred and implies that PicoBlaze has up to date information (of course the 
PicoBlaze program is responsible for processing and using the information correctly). When 
a virtual switch is changed the dot will become red until the time of the next DCS request. 
Hence a red dot indicates that PicoBlaze has not read the latest states of the switches.

The second DCS sequence shown below can be used to set the 16 virtual switches either when 
opening the window or during operation. PicoTerm will set the indicator LEDs on each switch as 
defined by the two byte values provided. 
    Request to PicoTerm to set virtual switches

    'DCS'           (90 hex = 144)
    's'             (73 hex = 115)   lower case 's'
    switches(0)     (new states for switches[7:0])
    switches(1)     (new states for switches[15:8])
    'ST'            (9C hex = 156)

PicoTerm does not generate a DCS response to this sequence because the state of the switches 
is known.



Graphic Display
---------------

This display contains a grid of 256 x 256 points allowing simple graphs, shapes and patterns 
to be plotted using 9 colours. Characters can also be displayed enabling graphs to be annotated 
with scales and labels etc.

There are four 'Device Control String' (DCS) sequences available for use with the graphic 
display. The 'PicoTerm Graphic Display' pop-up window will automatically open the first time 
any one of these sequences is used.

  G - Plot a single point.
  v - Draw a line between two points.
  V - Fill the box defined by two points. 
  g - Display a character at a specified position.


Each sequence is described in greater detail below. However, all sequences require one or two 
points to be specified as X-Y coordinates. Although a 256 x 256 display does not provide the 
kind of high resolution we have become used to these days, the primary objective of PicoTerm 
is to be easy to use. With that in mind, the X-Y coordinates are simple byte values (00 to FF 
hex (0'd to 255'd) which are a natural fit with both UART communication and PicoBlaze.   

          Y |(0,255)    (255,255)          
            |                              As illustrated, the lower-left corner is the  
            |       (X,Y)                  display origin (0,0) is the lower-left corner     
            |                              which feels natural and easy to work with. 
            |(0,0)        (255,0)
             -------------------- 
                                X


Likewise, all sequences require you to specify the colour of the object to be displayed. 
The following values define each of the 9 colours available. 

     1E hex = 30'd   Black (also used if colour value provided is outside normal range) 
     1F hex = 31'd   Red        
     20 hex = 32'd   Green      
     21 hex = 33'd   Yellow     
     22 hex = 34'd   Blue       
     23 hex = 35'd   Magenta    
     24 hex = 36'd   Cyan       
     25 hex = 37'd   Grey 
     26 hex = 38'd   White 

  Hint - This is the same colour palette available for text in the main PicoTerm window.
         In this case, 'white' can really be useful because it will be visible when plotting
         in an area previously set to a different colour. Alternatively, you can think in 
         terms of White allowing you to 'clear' points. Regardless, 'white' soon becomes a 
         useful colour in the display window.


 
  Sequence to set a single point
  ------------------------------

    'DCS'     (90 hex = 144)
    'G'       (47 hex = 71 )   upper case 'G'
     x              
     y      
     colour
    'ST'      (9C hex = 156)
     
  This sequence can be used to set any of the 65,536 points to one of the 9 colours. It is 
  typically used when plotting simple graphs but its simplicity actually provides you with 
  the flexibility to do anything.

  It is worth noting that when operating with a default baud rate of 115200, it will take 
  ~521us to transmit this 6-character DCS sequence. This implies a plotting rate of 1,920 
  points per second. Hence a simple line graph consisting of 256 points can be plotted in 
  133ms which is reasonable. However, attempting to set all 65,536 point (e.g. to display 
  a 256x256 image) would take over 34 seconds and generally a technique to avoid!



  Sequence to draw a line between two points.
  -------------------------------------------

    'DCS'     (90 hex = 144)
    'v'       (76 hex = 118)   lower case 'v'
     x1       Start of line (x1,y1) 
     y1
     x2       End of line (x2,y2) 
     y2
     colour
    'ST'      (9C hex = 156)

  This sequence defines the points at the start (x1,y1) and end (x2,y2) of a line. PicoTerm 
  works out the vector and sets all the points required to form a continuous line of the 
  colour specified. Although this 8-character DCS sequence will take slightly longer to 
  transmit (~694us at 115200 baud) it could set up to 256 points in one transaction and is 
  a faster way to draw lines than plotting individual points. Note that there are no 
  restrictions concerning the relative positions of the start and end points; PicoTerm will 
  draw a connecting line of whatever length and in whatever direction is needed to connect them.

  Hint - Even though vertical and horizontal lines (e.g. graph axes) are easy to plot as 
         a series of individual points, using this sequence makes plotting faster and much 
         easier to define. When plotting a graph, you may find the overall appearance is 
         improved when using short connecting lines rather than isolated points.



  Sequence to fill a box defined by two points.
  ---------------------------------------------

    'DCS'     (90 hex = 144)
    'V'       (56 hex = 86 )   upper case 'V'
     x1       First Corner (x1,y1) 
     y1
     x2       Second Corner (x2,y2) 
     y2
     colour
    'ST'      (9C hex = 156)

  This sequence defines the points at two diagonally opposite corners of a rectangular (or 
  square) box which PicoTerm will completely fill with the specified colour. As with drawing 
  lines, there are no restrictions concerning the relative positions of the two points but it 
  is generally easier to think in terms of the first point (x1,y1) being in the lower-left 
  corner and the second point (x2,y2) being in the upper-right corner.

  This sequence can dramatically improve the speed at which large areas can have all points 
  set to the same colour. For example, specifying points (0,0) and (255,255) and the colour 
  white will effectively 'clear' the entire display in one transaction (~694us at 115200 baud).

  Hint - A grey rectangle can be a good background for a graph. When presenting more than one 
         graph at a time (e.g. one at the top and another at the bottom) the grey rectangles 
         can really help define the plotting area of each.



  Sequence to display a character.
  --------------------------------
 
    'DCS'       (90 hex = 144)
    'g'         (67 hex = 103)   lower case 'g'
     x              
     y      
     colour
     character
    'ST'        (9C hex = 156)

  This sequence allows a character to be displayed at any position using any colour. There are 
  two font sizes available (small and large). The X-Y coordinates specifies the lower-left 
  corner of a small 'virtual box' which the character will occupy. 

                                                                     * * * * .
  The 'virtual box' of a large font character is 5-points            * . . . *
  wide and 7-points tall. The specified X-Y coordinate always        * . . . *    5 x 7
  defines the lower-left corner even if that point is not            * * * * .   character
  used by the character. The image on to the right illustrates       * . . . .    'box'
  the 15 points out of a possible 35 points that PicoTerm will       * . . . .
  set to the specified colour in order to display a capital 'P'.    y* . . . .
                                                                     x
           
  Small font size characters are exactly half the size of the large font size characters with 
  a 'virtual box' that is 2.5 points wide and 3.5-points tall. In practice, PicoTerm uses the 
  same 5 x 7 bit map for each character but then divides each regular point into four smaller 
  points. 

  Hint - When displaying text or a label, space small characters at 3-point intervals and large
         characters at 6-point intervals.

  Note that when each character is displayed, only the points required to form the character are
  set and all other points within the 'virtual box' will remain the same. When using the small 
  font size then only the required quarters of each regular point will be set so even the 
  remainder of a regular point will remain the same. This is equivalent to writing on a piece 
  of paper with a pen and means that labels can be added to a graph (or refreshed) without 
  obliterating all the information that has been previously plotted. 

  Hint - The above may sound natural and obvious but it is completely different to the way in
         which characters are displayed in the main PicoTerm window. Displaying a space (20 hex)
         in the main window will completely clear a previous character at the same location 
         whereas displaying a space in the graphic window has no effect at all. If you do 
         really need to clear the whole 'virtual box' of a character in the graphic window 
         then use the solid 5x7 'box' character (see later) with colour set to white.

  The 'character' value is based on standard ASCII codes and indeed values in the range 20 to 
  7E hex (32'd to 126'd) will all result in the display of the expected ASCII character. 
  However, codes in the range 00 to 1F hex (0'd to 31'd) and 7F (127'd) are traditionally 
  associated with control which is not relevant to the graphic window so some other useful 
  characters, symbols and shapes have been assigned to these codes as shown in the table below.

  A small font size character will be displayed when the code in the range 00 to 7F hex (0'd to 
  127'd). Simply add 80 hex (128'd) to the normal codes to display the character using the 
  large font size (i.e. codes in the range 80 to FF hex (128'd to 255'd) are large font). 


       Non-standard 'character' codes
      
        Hex   Dec   character
      
        00      0    edged 5x7 'virtual box'
        01      1    up arrow
        02      2    right arrow
        03      3    down arrow
        04      4    left arrow
        05      5    degrees
        06      6    micro
        07      7    pi
        08      8    ohm
        09      9    British Pound
        0A     10    Euro
        0B     11    Sigma (upper case)
        0C     12    Sigma (lower case)
        0D     13    divide
        0E     14    Hourglass
        0F     15    Bus cross
        10     16    Bus lines
        11     17    reserved (solid box)
        12     18    reserved (solid box)
        13     19    reserved (solid box)
        14     20    reserved (solid box)
        15     21    reserved (solid box)
        16     22    reserved (solid box)
        17     23    reserved (solid box)
        18     24    single point (0,0)
        19     25    single point (1,0)
        1A     26    single point (0,1)
        1B     27    single point (1,1)
        1C     28    solid 5x5 triangle (upper-left)
        1D     29    solid 5x5 triangle (lower-left)
        1E     30    solid 5x5 triangle (upper-right)
        1F     31    solid 5x5 triangle (lower-right)
        7F    127    solid 5x7 'virtual box'


  Hint - The four 'single point' characters used with a small font size enable each
         quadrant of the regular point specified in the X-Y coordinate to be set. 
         This opens the potential to implement a scheme that increases the plotting
         resolution to 512 x 512 points (262,144 virtual points).




Reading Text Files
------------------

PicoTerm provides two DCS commands that enable PicoBlaze (or similar) to read text files from 
the PC on which PicoTerm is running. Although the scheme is straightforward, it should be 
appreciated that the act of reading a text file will typically require PicoBlaze (or similar)
to receive and process a relatively high number of characters in a timely manner. It is therefore
recommended that you consider how your application will ensure that its UART receiver buffer will
always be read at a rate that ensures that it does not overflow when PicoTerm is continuously 
reading characters from the text file and transmitting them to your application.

The PicoTerm definition of a 'text file' is that it should primarily contain only characters with
ASCII codes 20 to 7E hex (32 to 126 decimal). This is all the normal visible characters including
'A' to 'Z', 'a' to 'z', '0' to '9', a space and various standard symbols. PicoTerm will also read
and transmit a carriage return (0D hex = 13 decimal) which is generally understood to mean the 
end of a line. However, if PicoTerm reads a horizontal tab (09 hex = 9 decimal) from a file it 
will automatically replace it with a space (20 hex = 32 decimal) before it is transmitted. If 
PicoTerm reads any of the other character codes it will ignore them and they will not be 
transmitted.

Both of the DCS commands read the contents of a text file and transmit them to the COM port in 
exactly the same way. The only difference between the commands is the way in which the file to 
be read is specified...

    This first DCS sequence requests PicoTerm to read a file with the name 'picoreadfile.txt'
    which must be located in the same directory as 'PicoTerm.exe'. Although this requires you 
    to have previously provided the correctly named file in the correct location, this command 
    allows your application to automatically read the file without any delay. For example, this 
    can be a good way to load a set of parameters for an application as part of an initialisation 
    procedure 

    'DCS'     (90 hex = 144)
    'R'       (52 hex = 82 )    upper case 'R'
    'ST'      (9C hex = 156)


    The second DCS sequence shown below will also request PicoTerm to read a file but this 
    command will result in PicoTerm prompting the user to 'Specify file to be read:'. The prompt 
    will appear in a new 'PicoTerm Read File' window that will pop up. Whilst this command is 
    flexible about the file to be read, waiting for the file to be specified will effectively
    cause PicoTerm to freeze and that will generally force your application to wait as well. 
    Waiting is normally acceptable but it is clearly quiet different behavior to the 'R' command.

    'DCS'     (90 hex = 144)
    'r'       (72 hex = 114)    lower case 'r'
    'ST'      (9C hex = 156)


    When specifying the file to be read...
      - Any file extension can be used (e.g. .hex or .mcs) providing the actual contents 
        of the file conform to the definition of a 'text file' as previously described.
      - By default, PicoTerm will look for the file in the same directory as that in 
        which 'PicoTerm.exe' is located.
      - The file specification may include an absolute path to the location of the file
           e.g.  C:\Designs\PicoBlaze\kc705_kcpsm6_i2c_eeprom.mcs
      - The file specification may include a path relative to the location of 'PicoTerm.exe'
           e.g.  read_files\eeprom_data_files\filter_coefficients.hex

    Hint - It is possible to paste a file specification into the 'PicoTerm Read File' window 
           using Ctrl+V which can save typing and help avoid mistakes.

 
As soon as PicoTerm has received either command it will immediately acknowledge that it is 
entering the read file mode by transmitting 'DCS' followed by 'R' or 'r' to the COM port. The 
application should then be aware that an attempt is being made to read a file. When the 'r' 
command is used there will then be a pause whilst the user specifies the file to be read.

Providing PicoTerm is able to open the file specified, each character is read and transmitted 
by PicoTerm and the application must receive and process them until the end of the file is 
reached which will be indicated by PicoBlaze transmitting an 'ST' character. Hence the normal 
complete response to a read file command is...
     'DCS', 'R' (or 'r'), 'c', 'c', 'c', 'c', 'c', 'c', ......, 'c', 'c', 'ST'
Where 'c' represents a character from the text file and clearly the number of characters in 
the response depends on the size of the file being read.

If PicoTerm is unable to locate and open the file (or the file is empty) then the response 
will be as shown below and the application should recognise this to be a failure to read
the file and take suitable actions. 
     'DCS', 'R' (or 'r'), 'ST'
           
Throughout the read file process, PicoTerm will display messages in the 'PicoTerm DCS 
Transactions' window which can be useful when developing your application. As each character
is read from a file and transmitted it will also be displayed in the 'PicoTerm Read File' 
window providing a clear indication of progress. On completion, a message is displayed in the
transactions window and the 'PicoTerm Read File' window will close automatically. 

When a file is in the process of being read, PicoTerm is still able to receive characters 
from the application but there are limitations and special cases which are important to 
understand and often key to the implementation of a successful application.

During the reading of a file, the application can only display plain text in the main terminal 
window. It is not possible to use any other Device Control Strings (DCS) or Escape sequences 
until the read command has completed (i.e. 'ST' has been received). In practice, the primary 
focus of the application should be receiving the file being read so the amount of characters 
sent for display in the terminal window should normally be limited to that of status information
using as few characters as practically possible. Remember that the 'PicoTerm Read File' window 
already indicates progress.

   Hint - A common mistake is that PicoBlaze (or similar) tries to transmit too many characters 
          to PicoTerm resulting in the buffer of its transmit UART becoming full. Then while 
          PicoBlaze waits for space to appear in the transmit buffer the buffer its UART 
          receiver overflows because it is no longer keeping up with the continuous flow of 
          characters PicoTerm is reading from the file.

If the application is unable to receive and process all the characters at the rate at which 
PicoTerm is reading and transmitting them then it is possible for the application to stop and 
start the flow by transmitting 'XOFF' and 'XON' control characters.

        'XON'   (11 hex = 17)  Also known as control character 'DC1'  
        'XOFF'  (13 hex = 19)  Also known as control character 'DC3'  

If for any reason the application would like to terminate the reading of the file early then
it simply needs to transmit a 'DCS' and PicoTerm will stop reading and transmitting characters 
from the file, display a message in the transaction window and close the 'PicoTerm Read File' 
window. PicoTerm will then continue to process the DCS command that has been started so it 
is good practice to use a valid sequence (e.g. the 'ping' sequence).  

When PicoTerm receives 'XOFF' it will stop reading and transmitting the file. PicoTerm will 
then wait until it receives 'XON' before it resumes. PicoTerm will continue to receive and 
display characters in the main terminal window so that the application can still display status
information. The 'PicoTerm Read File' window provides a visual indication of how the reading 
of the file is being interrupted (i.e. it may appear to be making slow progress or even stop 
if the is a significant time between 'XOFF' and 'XON' control codes).
 
In many cases, the need to interrupt the file read and flow of characters from PicoTerm to 
the application is related to the performance of something else in the system. For example, 
programming a FLASH memory is typically performed one 'page' at a time. A page of data 
(typically 256 or 512 bytes) can be quickly loaded into a RAM buffer but it can then take several
milliseconds for the page to program the FLASH memory cells. If the buffer in the UART receiver
is liable to overflow whilst the application is forced to wait for the FLASH memory to be ready 
then 'XOFF' and 'XON' flow control could be the solution.

When PicoTerm receives an 'XOFF' character it will immediately stop transmitting characters. 
However, there may be a quite considerable latency in the system and the application should 
expect to continue receiving characters. How many characters are received before the flow stops
really depends on the system and some experimentation is advisable to establish whether the 
buffer in the UART receiver is adequate or if it necessary to issue 'XOFF' early so that
takes effect in time. The following is an indication of where the latency can be in a system.
   a) PicoBlaze sends 'XOFF' to its UART transmitter.
   b) The UART Transmitter has a 16-character buffer so maybe there are up to 15 other 
      characters to be transmitted before the 'XOFF' is actually on its way (note the 
      application will benefit from limiting the transmission of status information when 
      reading a file).
   c) When a USB/UART bridge is used then these devices also have a buffer which may 
      be holding characters in front of the 'XOFF'.
   d) On your PC, the COM port (or virtual COM port in the case of a USB/UART bridge) 
      almost certainly has a buffer which may further delay PicoTerm receiving characters .
   e) When PicoTerm transmits characters read from the file then also pass to the COM port 
      which has a buffer. In the case of a virtual COM port it is possible that several 
      characters are queued up before transmission in a burst.
   f) A USB/UART bridge device has a buffer such that bursts of characters received from
      the USB can be transmitted by the UART.

Although the above description can make this sound like a potentially nasty problem, it is rarely
an issue in practice when a USB/UART bridge and corresponding Virtual COM port driver is being 
used. This is because the average character transmission rate is often much less than the 
BAUD rate of the UART implies. The PicoTerm default BAUD rate is 115200 and this means that a
character (start bit, 8 data bits and a stop bit) is transmitted in ~87us. This implies that 
PicoTerm could be reading and transmitting 11,520 characters per second. If you actually use 
a PC with a traditional RS232 serial port then you may actually observe a character rate close 
to this but the interaction of Virtual COM port driver with the USB/UART device typically 
results in relatively large gaps between the transmission of each character or large gaps  
between small bursts of characters. The actual character rate very much depends on the 
manufacturer of the USB/UART device and the Virtual COM port driver they provide. 

The following experimental observation have been made by reading a large text file... 

    The Spartan-6 ATLYS board has an EXAR XR21V1410 USB/UART bridge device.
      Average read rate of ~2,000 characters per second.
  
    KC705 board with a Silicon Labs CP2103GM USB/UART bridge device.
      Average read rate of ~1,960 characters per second.



-------------------------------------------------------------------------------------------------
Invalid Characters and Control Sequences
-------------------------------------------------------------------------------------------------

In an ideal world your application will only transmit valid characters and valid escape and DCS
sequences to PicoTerm and everything will work precisely as intended. However, mistakes do 
happen especially during code development so it is useful to know how PicoTerm has been designed
to react when it receives unexpected characters and sequences.

Any control codes (i.e. codes in the range 01 to 1F hex) and all 8-bit codes (80 to FF hex)
not supported by PicoTerm are automatically replaced with a '*' character. The display of
this visible character makes it easier to observe and debug applications during development.

The most common mistakes when developing an application are the incorrect preparation of a 
character code (e.g. when converting a binary value into its ASCII representation) or the 
incorrect implementation of a Device Control String (DCS) resulting in raw 8-bit values then 
being interpreted by PicoTerm as ASCII characters (see below).

When an escape sequence does not match with any of those supported then PicoTerm will abandon
the processing of the sequence at the earliest opportunity with any subsequent characters being 
displayed in the main terminal window. For example, if a mistake is made when attempting to 
issue a clear screen sequence...
         
   invalid sequence  'ESC'  '['  '3'  'J'  is transmitted to PicoTerm 
   correct sequence  'ESC'  '['  '2'  'J'  (contains '2' rather than '3')

... PicoTerm will abandon the sequence as soon as '3' is received and then both '3' and 'J' will
be displayed in the main terminal window. Not what you expected, but being observable helps.  

In a similar way, when a DCS sequence does not match with any of those supported then PicoTerm
will abandon the processing of the sequence at the earliest opportunity. 'Invalid string! will 
be displayed in the 'PicoTerm DCS Transactions' window and any subsequent characters will be 
displayed in the main terminal window. Since some DCS sequences are associated with byte data, 
the subsequent characters displayed could be anything and quite often '*' would be observed 
because byte values can easily be in the range 128 to 255 (80 to FF hex). 



-------------------------------------------------------------------------------------------------
BAUD Rates and Character Rates
-------------------------------------------------------------------------------------------------

The BAUD rate defines the number of bits per second transmitted or received when a 'character' 
(or byte) is transferred between PicoTerm and a device (e.g. PicoBlaze). The serial transfer of
each 'character' consists of a start bit, 8 data bits and a stop bit. So at the default BAUD rate
of 115200 bits/s it will take 10/115200 = 86.8us to transmit or receive one 'character'. It is 
therefore reasonable and tempting to assume that 115200/10 = 11,520 characters can be transferred
per second. However, this is not always the case and it also means that higher BAUD rates do NOT
always result in faster communication rates of multiple characters (or bytes).

When using PicoTerm with a USB/UART bridge and Virtual COM port, the typical maximum CONTINUOUS 
communication rates achieved are in the region of 2,000 characters per second from the PC running
PicoTerm to a peripheral and 4,000 characters per second from a peripheral to PicoTerm. These 
rates far exceed the requirements of applications involving simple human interaction but reading
and writing files, or heavy use of some of the special features (e.g. the graphics window), can 
lead to issues or otherwise unexpected results. So if you have applications for which you 
anticipate potentially high character rates then please review the descriptions below.


Character Rate from a PC running PicoTerm to the Peripheral
-----------------------------------------------------------

When PicoTerm is used with a USB/UART device then it is typical for the Virtual COM port driver
to leave additional gaps between characters (or between bursts of characters). These gaps lower 
the average character rate. Maximum rates in the region of 2,000 characters per second are 
typical. In practice, this rate reduction will normally only be noticed when an application 
attempts to read files containing a significant amount of data (i.e. many thousands of 
characters). Whilst this rate reduction can be disappointing, it often makes it easier for your
application to cope with the data flow without resorting to large buffers of flow control 
mechanisms. Please see 'Reading Text Files' section earlier in this file for further descriptions.

Ultimately, the communication rate from PicoTerm running on the PC to the peripheral is a self-
regulating limitation that must be accepted when using a virtual COM port. It simply means that 
it will probably take longer to read a file than you may have expected to take.


Character Rate from the Peripheral to a PC running PicoTerm 
-----------------------------------------------------------

In this direction the limitation is less obvious and affords your application a reasonable 
degree of flexibility. However, it is the application that is ultimately responsible for the 
character rate and this must be kept within certain limits for reliable communication to take
place. 

Hint - High character or data rates are most likely to occur when attempting to write a 
       large amount of information to a LOG file but can also be attributed to high usage of 
       certain Device Control Strings (DCS) used to control one or more of the special PicoTerm
       features. A high transfer rate can be beneficial when writing a lot of information to a
       file or plotting a complex graphic but in these cases it may be necessary to accept the 
       limitations and implement a scheme that will deliberately lower the overall data rate. 
       However, there are situations in which it high data rates occur which relate to 
       inappropriate use of DCS and can easily be avoided. For example, it is theoretically 
       possible transmit the DCS to update the virtual 7-Segment over 1,600 times a second but
       there is no way that the user would observe more than a few changes of the display per 
       second so such a high update rate is therefore unnecessary. Likewise, it is pointless 
       polling the virtual switches more than a few times a second as no user would change 
       them that fast. 

When using the default BAUD rate of 115200 the maximum communication rate that can be achieved 
is 11,520 characters per second. A virtual COM port working with a USB/UART device is able to 
operate at this rate but PicoTerm will only be able to process in the region of 4,000 characters 
per second. Virtual buffers in PicoTerm and the virtual COM port driver are able to accumulate a
backlog of characters when the received data rate is of a higher than PicoTerm can process. 
However, the backlog cannot be allowed to grow indefinitely and therefore it is the responsibility 
of the application to ensure that the AVERAGE character rate is suitable for PicoTerm. 

Hint - When developing an application it is helpful to think in terms of an average character 
       rate relative to a period of ~10 seconds. As such, the transmission of <4,000 characters
       every second is ideal but the transmission of 40,000 characters in 3.5 seconds is also 
       acceptable providing very few characters are transmitted during the next 6.5 seconds to
       achieve the same average rate over a 10 second period.

If the application CONTINUOUSLY transmits 11,520 characters per second to PicoTerm, which only 
processes 4,000 characters per second, the backlog will grow by 6,520 characters per second.
If this is sustained then the backlog will reach 60,000 characters after ~9 seconds and PicoTerm
will display a 'WARNING - High Average Data Rate!' message in the DCS Transactions Window (the 
DCS Transactions will pop up if not already open). The warning is a clear indication that the 
communication rate is unsustainable; it would take at least as long again before any data would
be lost but it is recommended that the application is modified to avoid this message from ever 
being displayed. If the warning message is generated then a 'Good News - Average Data Rate has
reduced!' message will be displayed when the backlog falls back below 20,000 characters. 

Hint - It would take PicoTerm up to 15 seconds to clear a backlog of 60,000 characters. Whilst
       PicoTerm will reliably clear such a large backlog, it is often undesirable for your 
       PicoTerm display(s) to be that far behind your application. So in general, it is far 
       better to craft your application so that it does not transmit more than ~4,000 characters
       in any one second as this will result in the timely display of all information.

Hint - When transmitting large amounts of information from an application to PicoTerm (e.g. 
       writing information to a LOG file) you could issue a 'ping' request after every few 
       thousand characters have been transmitted and then wait for the 'ping' response. In this
       way your application would wait for PicoTerm to clear any backlog before it continued
       ensuring that the PicoTerm display(s) was never more than a second behind the application.  
        


-------------------------------------------------------------------------------------------------
End of 'PicoTerm_README.txt'
-------------------------------------------------------------------------------------------------
