Tiny Machine Basic for the UT51 Single Board Computer

Reference Manual for Version 1.0

Industrologic, Inc.
3201 Highgate Lane
St. Charles, MO
63301
USA

Phone: (636) 723-4000
www.industrologic.com
info@industrologic.com




Trademark and Copyright Information

Tiny Machine Basic and TMB are Trademarks of Industrologic, Inc. 2000
This document is Copyright (c) 2010-2016 by Industrologic, Inc.
All rights reserved.

No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying or scanning, for any purpose other than the personal use by the purchaser of this product. Industrologic, Inc. reserves the right to revise this document at any time without obligation to notify any person of such revision. Industrologic, Inc. assumes no responsibility for any errors that may appear in this document.

Warning/Disclaimer

Whereas effort has been made to make the information in this document as useful and accurate as possible, Industrologic, Inc. assumes no responsibility for the application, usefulness, or completeness, of the information contained herein. Under no circumstance will Industrologic, Inc. be responsible or liable for any damages or losses including indirect or consequential damages or losses arising from either the use of any information contained within this manual or the use of any products or services referenced within this manual.


Overview and General Information

Tiny Machine Basic for the UT51 (TMB-UT51) is a simple BASIC language interpreter with a limited syntax and list of instructions. TMB-UT51 is not so much a high level language like most BASIC interpreters, but is a cross between BASIC and machine language. It has been written specifically for the 8 bit structure of the Intel 8051 instruction set compatible families of microcontrollers, and for program storage in an 8K (8192 byte) serial EEPROM.

A "command" consists of an instruction and its "argument", and will be performed as soon as entered. A program line entry consists of a number from 1 to 2730, a space, an instruction, and a byte or word argument, depending on the instruction type. Byte arguments can be entered as decimal values or quoted single character strings, e.g. "x".

Instructions entered while programming are saved as three-byte tokenized instructions, not as BASIC source code. This allows for up to 2730 program lines. (8192 / 3 = 2730). Instructions that involve line numbers or EEPROM locations will have word (2 byte) arguments. All other instructions will have byte arguments. Instruction arguments that are limited to a single byte (values from 0 to 255) and exceed this limit at run time will "roll over" or "roll under" back to a byte value, and will not cause a run-time error. Similarly, instructions that use a limited range of values and are given values outside that range will not cause a run-time error, but will either ignore the instruction or convert the illegal value to a legal value.

Instructions that manipulate an I/O port bit of the microcontroller must be used in ways that are compatible with the port hardware. If a port bit is to be used as an input, it must be set to a logic level "high" state, or "1". (On power up the port pins are set high.)

Comments may be added to program files created and saved on a host computer and uploaded, but the program saved in the UT51 will not contain comments. Comments must be on separate lines, and any line that does not begin with a program line number may be a comment. When comment lines are sent to the UT51 during program upload, syntax errors occur, and the lines are ignored.


Variables

26 byte variables exist in TMB-UT51 which are represented by the letters A through Z. These variables store byte values that can be read or assigned values by the user program. Although all 26 byte variables are considered general purpose, certain instructions read or write specific variables. The variables that are not used specifically by any instructions are C, D, E, F, G, I, J, K, L, N, O, P, Q, R, T, U, V, X, and Z.

The following is a list of byte variables that can be read and displayed, but cannot be assigned values by the user program. When used in this manner the user program must read KEY and INT often enough to insure that they contain current and valid values.

KEY    the ASCII value of the last character received at the USB/serial port
       (cleared after being read)
       (See Appendix A for a table of these values)
INT    the number of low going pulses that have occurred at
       the I/O signal INT (cleared after being read)
(A)    a special description of variable A used to display the ASCII
       character rather than the numeric value

Instructions

The following is a list of instructions where, unless otherwise specified, [arg] is an argument to the instruction in the form of a byte variable, number from 0 to 255, or single ASCII character. The command instructions will normally be used only as a command at the prompt, and the rest of the instructions will normally be used within a program, but may be used as a command at the prompt to see how the instruction works.

Command instructions:

BAUD=[arg]     Set baud rate of the USB/serial port to [arg], and save in EEPROM.
               Allowable values are 115 (115200), 57 (57600), 38 (38400),
               192 (19200), 96 (9600), 48 (4800), or 24 (2400). (If you change
               the baud rate in TMB-UT51, you will also need to change it in
               your terminal software!)

The communication parameters are always 8 data bits, 1 stop bit, and no parity. Although the microcontroller contains a hardware UART for sending and receiving serial data, it cannot provide all of the combinations of data bits, stop bits, and parity bit that more advanced UART's can provide. There is no communication error checking when receiving characters in TMB-UT51. Note: If you change the baud rate or communication mode in TMB-UT51, you will also need to change it in your terminal software!


Examples:
BAUD=96        set USB/serial port baud rate to 9600
BAUD=115       set USB/serial port baud rate to 115200


BOOTON         Run your program when TMB-UT51 starts (i.e., on power up)
BOOTOFF        Turn off the BOOTON feature (both are saved in EEPROM)
Note: The BOOTON feature can be overridden by shorting the INT signal on J2 to ground while power is applied to the UT51. TMB-UT51 will then return a prompt at 9600 baud (regardless of the rate specified with the BAUD instruction).

NEW            Erase all program lines
LIST           Display the program lines (if there are more than 20 lines the
               listing will pause until you press a key)
RUN            Run the program from the command prompt (>)
END            Stop the program and return to the prompt
The program can be stopped with the END instruction, by having no further lines to execute, (possibly by going to a non-existant line number above the rest of the lines), or by telling the program to go to line zero. If the program does not have a method of exiting in response to some program condition, the power will need to be cycled to return to the prompt.

Control and Program Flow instructions:

DELAY [arg]    Pause the program for [arg] tenths (1/10) of a second
GOTO [arg]     Jump to the instructions beginning at line number [arg]
GOSUB [arg]    Call subroutine at line number [arg] (1 layer deep only)
RETURN         Return to next instruction after the last GOSUB
LOOP [arg]     Begin a loop with [arg] iterations (1 layer deep only)
ENDLOOP        Terminate a loop
Subroutines and loops may only be one layer deep, that is, a subroutine may not contain another GOSUB instruction, and an ENDLOOP instruction must be performed before another LOOP instruction is performed.


Examples:
DELAY 255      delay 25.5 seconds

1 GOSUB 10     call subroutine at line 10
2 GOTO 1       jump to line 1
10 PRINT "A"   send an upper case A to the serial port
11 RETURN      jump to line following the GOSUB instruction

10 GOSUB A     call subroutine at the line number of the value of variable A
               (if the value of A is 20 it would be the same as GOSUB 20)

1 LOOP 255     start a loop of 255
2 PRINT "A"    send an upper case "A" to the serial port
3 ENDLOOP      jump back to line 2 until 255 loops have been done

Display and Keyboard instructions (Serial Port):

PRINT [arg]    Display a byte value in decimal/hexadecimal, or as character
               (This instruction sends characters out the serial port)
               See Appendix A for a table of these values

The PRINT instruction does not include a carriage return/line feed sequence (13D/10D or 0DH/0AH) after displaying a value or character like most BASIC languages. If either of these characters are desired they will need to be displayed separately.

Any character that has an ASCII value outside the range of normally displayable characters (32 to 126) can be sent as an ASCII value.

HEX            Display values in hexadecimal (try this at the command prompt)
DECIMAL        Display values in decimal (returns it to normal)
INPUT [arg]    Wait for a value to be entered (followed by a carriage return) and
               then put the value in [arg]. (This instruction waits for characters
               from the serial port). See Appendix A for a table of these values.

The ESCAPE key will cancel value entry with the INPUT instruction, (but not stop the program)


Examples:
PRINT 13       send a carriage return to the serial port
PRINT 10       send a line feed to the serial port
PRINT 27       send the "escape" character to the serial port
PRINT "A"      send an upper case A to the serial port
PRINT "a"      send a lower case A to the serial port
PRINT 97       send a lower case A to the serial port
INPUT A        wait for a value and then set variable A to that value
 
A=66           ASCII code for 'B"
PRINT (A)      send ASCII character "B" to serial port

Variable Manipulation instructions:

A=[arg]        Set byte variable A to [arg]
A=A+[arg]      Add the value in [arg] to variable A
A=A-[arg]      Subtract the value in [arg] from variable A
A=A*[arg]      Multiply variable A by the value in [arg]
A=A/[arg]      Divide variable A by the value in [arg], (remainder is discarded)
A=A MOD[arg]   Remainder of dividing variable A by the value in [arg]
A=A AND [arg]  Logical AND variable A by the value in [arg]
A=A OR [arg]   Logical OR variable A by the value in [arg]

IF A=0 [arg]   If variable A is zero jump to line number [arg]
IF A<>0 [arg]  If variable A is not zero jump to line number [arg]
IF A=B [arg]   If variable A equals variable B jump to line number [arg]
IF A<>B [arg]  If variable A does not equal variable B jump to line number [arg]
IF A<B [arg}   If variable A is less than variable B jump to line number [arg]
IF A>B [arg]   If variable A is greater than variable B jump to line number [arg]


Examples:
A=KEY          get value of last character at the Serial Port
B=67           set variable B to the ASCII value for "C", which is 67
IF A=B 30      if character was "C" then jump to line 30

A=A+B          add the value of variable B to variable A
A=A+10         add 10 to variable A (e.g., if A contained 10 it would
               become 20, if A contained 255 it would roll over to 9)
A=A-1          subtract 1 from A (e.g., if A contained 2 it would
               become 1, if A contained 0 it would roll under to 255)
A=A*10         multiply variable A by 10 (e.g., if A contained 10 it would
               become 100, if A contained 30 it would roll over to 44)
A=A/5          divide variable A by 5 (e.g., if A contained 10 it would
               become 2, if A contained 202 it would become 40)
A=A MOD 7      divide variable A by 7 and return the remainder in variable A
               (e.g., if A contained 10 it would become 3, if A contained 21 it
               would become 0)
A=A AND 128    logical AND variable A with 128 [80 hex] (e.g., if A contained 240
               [F0 hex] it would become 128 [80 hex])
               become 128, if A contained 30 it would roll over to 44)
A=A OR 16      logical OR variable A with 16 [10 hex] (e.g., if A contained 128
               [80 hex] it would become 144 [90 hex])

IF A=0 10      if variable A is equal to 0 then jump to line 10
IF A<>0 15     if variable A is not equal to 0 then jump to line 15
IF A<B 20      if variable A is less than variable B then jump to line 20

Port and Interrupt I/O instructions:

P1=[arg]          Set port P1 to [arg]
P1.X=[arg]        Set port P1 bit X (0-7) high if [arg] is 1, low if 0
INT=[arg]         Set digital I/O INT high if [arg] is 1, low if 0


Examples:
P1=1              set P1 bit 0 high, the other bits low
P1=128            set P1 bit 7 high, the other bits low
P1.7=0            set P1 bit 7 low
INT=1             set interrupt input high for use as an input

If any port bit is to be used as an input, it must be set high, (its power up setting.)

IF P1.0=0 [arg]   If port P1 bit 0 is low jump to line number [arg]
IF P1.0=1 [arg]   If port P1 bit 0 is high jump to line number [arg]
IF P1.1=0 [arg]   If port P1 bit 1 is low jump to line number [arg]
IF P1.1=1 [arg]   If port P1 bit 1 is high jump to line number [arg]
IF P1.2=0 [arg]   If port P1 bit 2 is low jump to line number [arg]
IF P1.2=1 [arg]   If port P1 bit 2 is high jump to line number [arg]
IF P1.3=0 [arg]   If port P1 bit 3 is low jump to line number [arg]
IF P1.3=1 [arg]   If port P1 bit 3 is high jump to line number [arg]
IF P1.4=0 [arg]   If port P1 bit 4 is low jump to line number [arg]
IF P1.4=1 [arg]   If port P1 bit 4 is high jump to line number [arg]
IF P1.5=0 [arg]   If port P1 bit 5 is low jump to line number [arg]
IF P1.5=1 [arg]   If port P1 bit 5 is high jump to line number [arg]
IF P1.6=0 [arg]   If port P1 bit 6 is low jump to line number [arg]
IF P1.6=1 [arg]   If port P1 bit 6 is high jump to line number [arg]
IF P1.7=0 [arg]   If port P1 bit 7 is low jump to line number [arg]
IF P1.7=1 [arg]   If port P1 bit 7 is high jump to line number [arg]
IF INT=0 [arg]    If digital I/O INT is low jump to line number [arg]
IF INT=1 [arg]    If digital I/O INT is high jump to line number [arg]

Timer instructions

TMB-UT51 includes two software countdown timers that can be individually set for periods of up to 255 hours, 255 minutes, or 255 seconds. Unlike the DELAY instruction, which pauses the program while waiting for the time to elapse, the countdown timers can be set, and will then run in the background. They can then be tested periodically while the program continues to see if they have timed out.
SETTIMER 1          set timer #1 from the values in variables H, M, and S
                    where H=hours, M=minutes, and S=seconds
SETTIMER 2          set timer #2

CLEARTIMER 1        turn off timer #1 so that it can no longer cause a timeout
CLEARTIMER 2        turn off timer #2 so that it can no longer cause a timeout

IF TIMER1=0 [arg]   If timer #1 has not timed out jump to line number [arg]
IF TIMER1=1 [arg]   If timer #1 has timed out jump to line number [arg]
IF TIMER2=0 [arg]   If timer #2 has not timed out jump to line number [arg]
IF TIMER2=1 [arg]   If timer #2 has timed out jump to line number [arg]


Example:
H=0                 zero hours
M=30                30 minutes
S=0                 zero seconds
SETTIMER 1          set timer #1 to timeout after 30 seconds

IF TIMER1=1 100     if timer #1 times out go to line number 100

EEPROM instructions:

Part of the EEPROM used to store the user program can also be used to store program data such as configuration information that must be saved if the power is removed from the UT51. EEPROM addresses 0 through 8189 correspond to TMB-UT51 line numbers 1 through 2730 since each program line uses 3 bytes. EEPROM address 8190 is used to store the BOOTON/BOOTOFF status and EEPROM address 8191 is used to store the baud rate. Using an EEPROM address associated with a program line's storage will overwrite any program line stored there. Likewise, entering a program line whose storage includes an EEPROM address will overwrite the data stored there.

When data is written to an EEPROM address, it is likely that the data will represent program instructions and arguments, which TMB-UT51 will attempt to RUN and LIST. In order to prevent the program from running this data as an instruction, an END instruction must be placed at a line number lower than any data address used so that the program will stop before reaching the data. If this is not done, the program may do any number of undesirable things, e.g., erasing itself or changing the baud rate unexpectedly. It is also suggested that the highest possible EEPROM addresses be used for data so that it is LISTED after the normal program lines.

Most EEPROMs may be written tens of thousands of times, but even this limit could be exceeded if the program wrote to the EEPROM in an unintended loop caused by incorrect programming, so some caution should be used. EEPROMs may be read an unlimited number of times.

WRITEEE [arg]  Write the value in variable A to the EEPROM byte at address [arg]

READEE [arg]   Read the EEPROM byte at address [arg], put the value in variable A
               (The argument to EEPROM instructions can be a byte or word)

Examples:
A=21           set variable A value
WRITTEE 8189   write variable A to EEPROM location 8189 (highest recommended)
READEE 8189    read EEPROM location 8189 and place value in variable A

Appendix A

The following is a table of character codes and their equivalent (ASCII) characters. These values are useful when using the PRINT instruction or when testing variables (like the variable KEY) for a specific character.

Decimal          Control Char. Control      Decimal               Decimal
Value   Character  Abbreviation  Key        Value   Character     Value   Character
-------------------------------------------------------------------------------------------
00      NULL                NUL  ^@         45      - (hyphen)    90      Z    
01      START OF HEADING    SOH  ^A         46      . (period)    91      [ (left bracket)
02      START OF TEXT       STX  ^B         47      /             92      \ (backslash)
03      END OF TEXT         ETX  ^C         48      0             93      ] (right bracket)
04      END OF TRANSMIT     EOT  ^D         49      1             94      ^ (carat)
05      ENQUIRY             ENQ  ^E         50      2             95      _ (underscore)
06      ACKNOWLEDGE         ACK  ^F         51      3             96      ` (accent)
07      BEEP                BEL  ^G         52      4             97      a
08      BACK SPACE          BS   ^H         53      5             98      b
09      HORIZONTAL TAB      HT   ^I         54      6             99      c
10      LINE FEED           LF   ^J         55      7             100     d
11      VERTICAL TAB        VT   ^K         56      8             101     e
12      FORM FEED           FF   ^L         57      9             102     f
13      CARRIAGE RETURN     CR   ^M         58      :             103     g
14      SHIFT OUT           SO   ^N         59      ;             104     h
15      SHIFT IN            SI   ^O         60      <             105     i
15      DEVICE LINK ESC     DLE  ^P         61      =             106     j
17      DC1 X-ON            DC1  ^Q         62      >             107     k
18      DC2                 DC2  ^R         63      ?             108     l
19      DC3 X-OFF           DC3  ^S         64      @             109     m
20      DC4                 DC4  ^T         65      A             110     n
21      NEG. ACKNOWLEDGE    NAK  ^U         66      B             111     o
22      SYNC. IDLE          SYN  ^V         67      C             112     p
23      END OF TX BLOCK     ETB  ^W         68      D             113     q
24      CANCEL              CAN  ^X         69      E             114     r
25      END MEDIUM          EM   ^Y         70      F             115     s
26      SUBSTITUTE          SUB  ^Z         71      G             116     t
27      ESCAPE              ESC             72      H             117     u
28      RIGHT ARROW (on PC)                 73      I             118     v
29      LEFT ARROW  (on PC)                 74      J             119     w
30      UP ARROW    (on PC)                 75      K             120     x
31      DOWN ARROW  (on PC)                 76      L             121     y
32      BLANK SPACE                         77      M             122     z
33      !                                   78      N             123     { (left brace)
34      " (double quote)                    79      O             124     | (vertical bar) 
35      # (number sign)                     80      P             125     } (right brace)
36      $                                   81      Q             126     ~ (tilde)
37      %                                   82      R             127     DELETE
38      &                                   83      S
39      ' (single quote)                    84      T
40      ( (open parenthesis)                85      U
41      ) (close parenthesis)               86      V
42      *                                   87      W
43      +                                   88      X
44      , (comma)                           89      Y


end of manual
log file