Home    FAQ    Site Map    Order    E-query us

NucBasic™(Now U Can) User Manual

NucBasic™ is derived from Jeff Frohwein's seminal GB Basic. The accolades are his - the bugs are mine!

  1. What is NucBasic™?
  2. Getting Started
  3. NucBasic™ Key Assignments
  4. Hello World
  5. Downloading your NucBasic™ Program to ROM
  6. Statements
  7. Variables
  8. DATA / READ / RESTORE / INPUT
  9. FOR / NEXT loops
  10. IF / THEN branches
  11. GOSUB Subroutines
  12. Functions / Keywords
  13. Error Messages
  14. Sample NucMorse.bas program
  15. Version History
  16. Feedback
What is NucBasic™?
NucBasic™ is a floating-point BASIC interpreter for the GatesBoy™ / Game Boy combination that allows you to write & execute programs up to 7.4K bytes in size. These programs can interact with external sensors, actuators and servo motors via the DB25 connector of the GatesBoy™ Cartridge. NucBasic™ programs can be written on a PC, debugged using an emulator and downloaded to the GatesBoy™ where they can run automatically when switched on.

Getting Started
The complete source code and binary ROM for NucBasic is included in the Rom2Cart package . Download the NucBasic.gb ROM file to a GatesBoy™ / Game Boy or load this file in a Game Boy Emulator.

NucBasic™ Key Assignments

Game Boy NucBasic™ NOCASH Emulator
B Input Tab
START Backspace Enter
A Enter Space
SELECT CapsToggle Left Ctrl
SELECT & START Break Left Ctrl / Enter

Hello World
Switch on the Game Boy. If "Ok" is not displayed at the bottom of the screen, you must stop the program that is running. Do this by pressing two keys together to send the Break signal (Left Control and Enter on the PC, or Select and Start on the Game Boy). See above for key assignments.

You should now erase any existing program in RAM memory prior to starting to write your new program. Type in "NEW" Enter, as follows: use the cursor keys to select "N" on the onscreen keyboard and press the Input key (Tab key on the PC, or "A" on the Game Boy). Then move the cursor to "E" on the onscreen keyboard and press the Input key. Move the cursor to the letter "W" and press the Input key. Now press the Enter key (space on the PC or "A" on the Game Boy). NucBasic™ should respond with "Ok".

You are now ready to write your first program. "Type" the following:

1 PRINT "HELLO WORLD"

Tips: "Space" is found to the right of the digit 9 on the onscreen keyboard.
         If you make a mess typing in a line you can cancel the line by typing @

Now press the Enter key (space on the PC or "A" on the Game Boy). NucBasic™ will respond with "Ok". You have just written your first program! Run the program by typing "RUN" Enter. NucBasic™ will type "HELLO WORLD" on the screen, then "Ok" on the next line (because it's waiting for your next command).

Downloading your NucBasic™ Program to ROM
See NucMorse.bas below for an example of a NucBasic™ program. This program autoruns because of the RUN command on the last line.
The MergNucB.bat file uses the MergNucB.com utility to merge a NucBasic™ program at the end of the ROM.

Statements
Most statements can be used in "direct input" mode. For Example: RUN, LIST, PRINT Z. Statements which form part of a program, however, require a line number. A space after the number is optional.
Multi statement lines are allowed. The separator is :
For Example:
10 L = 4 : REM set Loop count
or, the equivalent:
10 L = 4 : ' set Loop count

Variables
String variables are not supported.

Variable names may be a letter, or a letter and a number. For example:

A , B , C , and C1 are all valid variable names.

Variables are not case sensitive. For example, c1 and C1 are equivalent.

Variables can be assigned a value with or without the LET keyword. For example:

A=10 and LET A=10 are equivalent.

Single dimension arrays are supported, with or without an explicit statement of their size.

DIM(20) A, and DIM B, will set up an array of size 20 for the variable "A", and an array of default size 10 for variable "B".

&H may be used for entering hex values. (e.g: POKE &HFF00,&HFF)

DATA / READ / RESTORE / INPUT
The DATA statement can be used to introduce one or more of a series of constants into a program. READ statements will read these values.

The RESTORE statement will "recycle" the data contained in DATA statements, and read by subsequent READ statements, starting from the specified line number, or from the beginning of the program if this line number is omitted.

The INPUT (I.) statement prints ? and waits for the input of a floating point number from the user. It is normally used in conjunction with the PRINT command to prompt the user. For Example:
PRINT "What is your age";
INPUT A

FOR / NEXT loops
FOR / NEXT loops cause the program to execute a group of statements a certain number of times. For Example:

10 FOR I=1 TO 10
20 PRINT I
30 NEXT I

will cause 1 - 10 to be printed on the screen. An optional STEP parameter can be used if you wish to decrement the loop counter or to assign an increment other than 1. For Example:

10 FOR I=1 TO 10 STEP 2
20 PRINT I
30 NEXT I

will cause 1, 3, 5, 7 and 9 to be printed on the screen.

IF / THEN branches
IF / THEN conditional branches are implemented as single statements. For Example:

10 IF A=4 THEN GOTO 100

GOSUB Subroutines
Subroutines are implemented and must end with the RETURN statement. For Example:

10 IF A=4 THEN GOSUB 100
20 PRINT "A can = 4 - or not"
30 END
100 PRINT "A=4"
110 RETURN

Functions / Keywords
ABS    AUTO    CLEAR    COLOR    COS    DELAY    END    FREE    GOTO    INT    KEYPAD    LET    LINE    LINK    LIST    LOAD    LOCATE    MEMTOP    NEW    PEEK    POINT    POKE    PRINT    REG    REM    RENUM    RND    RUN    SAVE    SCREEN    SERVO    SGN    SIN    SINIT    SOUT    SOUND    SPEED    SQR    STEP    STOP    TAB    TAN    USR   

ABS(x) Return the absolute value of x.
AUTO(x) Not used.
CLEAR(x) Clear all variables.
COLOR (x) Set drawing color to x. 0=Black, 1=Dark Gray, 2=Light Gray, 3=White, & 4=XOR. (Defaults to XOR on program execution.)
COS(x) Return the cosine of x given in radians.
DELAY(x) (D.) Delay from 10ms to 655 seconds. (Delay length = x * 10ms)
END End program.
FREE Display remaining amount of free memory.
GOTO n (G.) Go to line n .
INT(x) Returns the integer part of x.
KEYPAD(x) If x=0, the following bits are returned if that button is pressed.
128 - Start 8 - Down
64 - Select 4 - Up
32 - B 2 - Left
16 - A 1 - Right
If x>0, then x is ANDed with the bits above.
If the result = zero, 0 is returned.
If result >< zero, a 1 is returned.

LET Assign a value to a variable (optional).
LINE x1,y1,x2,y2 Draw a line on the screen using COLOR. (0<=x<=127,0<=y<=119)
LINK Not Used.
LIST [x][-][x] (L.) List lines of the program. Starting and/or ending line numbers are optional. The two speeds for the LIST function are controlled by the UP / DOWN keypad. LIST starts in fast speed.
LOAD Not Used.
LOCATE y,x Position cursor with coordinates y,x.
MEMTOP x Set last address of RAM for NucBasic™ to use. On power up or reset this defaults to $dfff. Lowering this value reserves memory (for USR, for example). Note: All variables are CLEARed when this instruction is executed.
NEW Erase all program lines in memory.
PEEK(x) Returns value of a memory location x.
POINT x,y Draw a point on the screen using COLOR. (0<=x<=127,0<=y<=119)
POKE x,y Write value y to a memory location x.
PRINT (P. or ?) Prints to screen and then prints a carriage return. This carriage return can be surpressed if a ; is added at the end of the PRINT statement. For example:
10 PRINT 1
20 PRINT 2
will print 1 and 2 on separate lines and
10 PRINT 1 ;
20 PRINT 2
will print 1 and 2 on the same line.
REG x,y Sets value of cpu BC register (x) and cpu DE register (y). Normally called just prior to USR.
REM ( ' ) Remark.
RENUM Renumber program.
RND(x) Returns a random number between 0 and 1. x is ignored.
RUN (R.) Execute program.
SAVE Not Used.
SCREEN x If x=0, set text mode. If x=1, set graphics mode.
SERVO x,y Not Used.
SGN(x) Returns 1 if x>or=0. Else returns value -1.
SIN(x) Returns the sine of x given in radians.
SINIT x,y Not Used.
SOUT x Not Used.
SOUND x,y Generate a sound of frequency x for y * 10 milli-seconds. If y=65535, sound will stay on infinitely. If y=0, sound is turned off.
SPEED x x=0, Set single speed mode. (Default on powerup.) x=1, Set double speed mode. (Only has an effect on GB Colo(u)r.
SQR(x) Returns the square root of x.
STEP Not Used.
STOP Same as end but displays line number last executed.
TAB(x) Used with PRINT command for moving cursor to column x.
TAN(x) Returns the tangent of x radians.
USR(x) This function is normally called just after REG, and calls an assembly language routine at address x. It returns the value in HL. In this way, you can extend the language.

Error Messages
Argument error - no variable name following DIM statement
Control Stack error - missing index after FOR statement; missing NEXT; improper nesting (i.e. overlapping) FOR loops; Control Stack empty
Direct Input error - Some statements e.g. REM or DATA are not legal when you are typing commands directly e.g. RUN or LIST for immediate execution. Perhaps you have forgotten the line number?
Divide by 0 error - variable or expression is divided by 0
Duplicate error - variable name already defined
Floating point error - more than 6 digits of precision for floating point calculations?
Illegal function call error - square root of a negative number?
Input error - error in floating point input
Line too long error - maximum input line = 80 characters (including CR)
Out of DATA error - there are more READs than DATA values
Out of memory error - memory allocation would go beyond MEMTOP
Out of range error - POKE value greater than 255; index out of bounds for a dimensioned variable (e.g. index greater than defined dimension size; greater than 10 if no dimension specified; negative index for a floating point number).
Overflow error - number overflow
SINtax error - you have probably misspelled a key word
Undefined line number error - cannot find requested line number e.g. the line number specified by a GOSUB or GOTO statement.

Sample Code
Example NucBasic™ Program NucMorse.bas

1 REM NucBasic Program NucMorse.bas
2 ' dnathan@gatesboy.com 14 November 2001
3 ' Example program for GatesBoy™ cartridge
4 ' Demonstrates use of a switch and LED connected to DB25 connector
5 ' Connect a normally open switch between Pin 16 and Pin 11
6 ' Connect a LED between Pin 15 and Pin 10 via a 10 KOhm resistor
7 ' You can specify the number of times SOS is sent
8 ' And the time period in 1/100 sec for a single DIT
9 ' A countdown timer waits for the switch to be closed
10 GOSUB 100 : ' Initialise
15 T = 100 : ' Timeout in cycles
20 GOSUB 200 : ' Check switch
21 PRINT T;: ' Timeout
22 IF T < 0 THEN GOTO 95
24 IF S1 = 1 THEN GOTO 20 : ' S1 = 1 = Switch not pressed
26 FOR N1 = 1 TO N : ' N = Number of SOS
28 PRINT "SOS number " ; N1
32 F = 3 : D = 1
36 GOSUB 300 : ' Send F Flashes, D Duration 1*P = DIT, 3*DIT = 'S'
38 DELAY 5*P : ' Time between letters is 5*Period
40 F = 3 : D = 4
44 GOSUB 300 : ' Send F Flashes, D Duration 3*P = DAH, 3*DAH = 'O'
46 DELAY 5*P : ' Time between letters is 5*Period
48 F = 3 : D = 1
60 GOSUB 300 : ' Send F Flashes, D Duration 1*P = DIT, 3*DIT = 'S'
62 DELAY 10*P : ' Time betweem SOSs is 10*Period
65 NEXT N1
70 PRINT "": ' New line
80 PRINT N1 - 1 ; "SOS completed"
85 PRINT "MORSE ENDED"
90 END
95 PRINT "": ' New Line
96 PRINT "Switch timeout"
98 GOTO 26
99 END

100 ' Initialise
102 POKE &HB015,2 : ' Set Pin 15 out, Pin 16 In
105 POKE &HB017,0 : ' DRIVE_D bit 1 = 0 for Low Slew rate
110 ' DATAOUT_D bit 1 = 1 for Pin 15 High = LED Off
115 POKE &HB013,2 : ' Turn Off LED = High at Pin 15
120 PRINT "MORSE"
125 PRINT "Connect Switch"
130 PRINT "Between Pin 16"
135 PRINT "and Pin 11"
140 PRINT "Connect LED"
145 PRINT "Between Pin 15"
150 PRINT "and Pin 10 via a "
155 PRINT "10 KOhm resistor"
160 PRINT "No of times to send SOS";
165 INPUT N
170 PRINT "Period for DIT in 1/100 sec";
175 INPUT P
198 ' End of Initialise
199 RETURN

200 ' Read Switch - Read Port D
210 S1 = PEEK(&HB011)
220 'PRINT "PEEK =";S1
230 S1 = S1 - 2 * INT(S1/2) : ' Extract Bit 0
240 T = T - 1 : ' Decrement Timeout
250 'PRINT "Switch =";S1 : ' S1 = 0 when switch closed
299 RETURN : ' End of Read Switch

300 FOR F1 = 1 TO F : ' Send F flashes
310 POKE &HB013,0 : PRINT "ON ";
320 SOUND 1000, D*P
330 DELAY D*P : ' DELAY 1 = 10 ms
340 POKE &HB013,2 : PRINT "Off ";
350 DELAY P : ' Time between flashes is = Period
360 NEXT F1
399 RETURN : ' End F flashes

CLS
RUN

Feedback
This is a FeedbackFriendly site. Feedback to NucBasic@gatesboy.com


NucBasic.htm (this file) Version 1.02, Updated 20 November 2001
The latest version can be found at http://www.gatesboy.com/NucBasic.htm

Version History
Version 1.02 20 November 2001.
Rom2Cart package now includes the MergNucB.com utility so that writing and merging a NucBasic™ program with the NucBasic.gb Interpreter ROM is a snap.
Version 1.00 13 November 2001 - Original Release


GatesBoy™ and NucBasic™ are trademarks of David Nathan Creations Ltd.
Game Boy & Nintendo are trademarks of Nintendo Co., Ltd. of Kyoto, Japan.