BBC BASIC for Agon - breakintoprogram/agon-docs GitHub Wiki
What is BBC BASIC for Agon?
The original version of BBC Basic was written by Sophie Wilson at Acorn in 1981 for the BBC Micro range of computers, and was designed to support the UK Computer Literacy Project. R.T.Russell was involved in the specification of BBC Basic, and wrote his own Z80 version that was subsequently ported to a number of Z80 based machines. I highly recommend reading his account of this on his website for more details.
As an aside, R.T.Russell still supports BBC Basic, and has ported it for a number of modern platforms, including Android, Windows, and SDL, which are available from his website here.
BBC BASIC for Agon is a port of his BBC BASIC for Z80, which is now open source, with a number of modifications to make it run on Agon.
Implementation on the Agon Light
BBC BASIC for Z80 runs in Z80 mode, that is within a 64K segment. The interpreter takes around 16K of RAM, leaving around 48K available for user programs and data.
If you are not familiar with the BASIC programming language, or need a refresher on BBC BASIC, please refer to the official documentation here, specifically chapters 1 to 4, and the appendices from A onwards.
It needs a full 64K segment, so cannot be run from the MOS folder as a star command.
To run, load into memory and run as follows:
LOAD bbcbasic.bin
RUN
It is possible to automatically CHAIN (load and run) a BBC BASIC program by passing the filename as a parameter:
LOAD bbcbasic.bin
RUN . /path/to/file.bas
Note that passing a . as the first parameter of RUN is informing MOS to use the default value there (&40000)
Changes specific to Agon Light
Star Commands
The following * commands are supported
BYE
Syntax: *BYE
Exit BASIC and return to MOS.
EDIT
Syntax: *EDIT linenum
Pull a line into the editor for editing.
FX
Syntax: *FX osbyte, params
Execute an OSBYTE command.
The only OSBYTE commands supported at the moment are:
- 19: Wait for vertical blank retrace
And from MOS 1.03 or above
- 11: Set keyboard repeat delay in ms (250, 500, 750 or 1000)
- 12: Set keyboard repeat rate ins ms (between 33 and 500ms)
- 118: Set keyboard LED (Bit 0: Scroll Lock, Bit 1: Caps Lock, Bit 2: Num Lock) - does not currently change status, just the LED
VERSION
Syntax: *VERSION
Display the current version of BBC BASIC
MOS commands
In addition, any of the MOS commands can be called by prefixing them with a *
See the MOS documentation for more details
BASIC
The following statements are not currently implemented:
- ENVELOPE
- ADVAL
The following statements differ from the BBC Basic standard:
REM
REM does not tokenise any statements within comments. This is to bring it inline with string literals for internationalisation.
LOAD
SAVE
The following file extensions are supported:
.BBC
: LOAD and SAVE in BBC BASIC for Z80 tokenised format.BAS
: LOAD and SAVE in plain text format (also.TXT
and.ASC
)
If a file extension is omitted, ".BBC" is assumed.
MODE
The modes differ from those on the BBC series of microcomputers. Please refer to the VDP documentation for more details.
COLOUR
Syntax: COLOUR c
Change the the current text output colour
- If c is between 0 and 79, the foreground text colour will be set
- If c is between 128 and 207, the background text colour will be set
The following two commands are only applicable to paletted modes with less than 64 colours.
Syntax: COLOUR l,p
Set the logical colour l to the physical colour p
Syntax: COLOUR l,r,g,b
GCOL
Syntax: GCOL mode,c
Set the graphics colour to c; mode is currently ignored.
POINT
Syntax: POINT(x,y)
This returns the physical colour index of the colour at pixel position (x, y)
PLOT
Syntax: PLOT mode,x,y
Plot supports the following operations:
- 4: Move
- 5: Line
- 80: Filled Triangle
- 144: Circle with radius specified either by x or y
- 148: Circle passing through point x,y
GET$
Syntax: GET$(x,y)
Returns the ASCII character at position x,y
SOUND
Syntax: SOUND channel,volume,pitch,duration
Play a sound through the Agon Light buzzer and audio output jack
Channel
: 0 to 2Volume
: 0 (off) to -15 (full volume)Pitch
: 0 to 255Duration
: -1 to 254 (duration in 20ths of a second, -1 = play forever)
TIME$
Access the ESP32 RTC data
Example:
10 REM CLOCK
20 :
30 CLS
40 PRINT TAB(2,2); TIME$
50 GOTO 40
NB: This is a virtual string variable; at the moment only getting the time works. Setting is not yet implemented.
VDU
The VDU commands on the Agon Light will be familiar to those who have coded on Acorn machines. Please read the VDP documentation for details on what VDU commands are supported.
Inline Assembler
BBC BASIC for Z80, like its 6502 counterpart, includes an inline assembler. For instructions on usage, please refer to the original documentation.
In addition to the standard set of Z80 instructions, the following eZ80 instructions have been added
MLT
The assembler will only compile 8-bit Z80 code and there are currently no plans for extending the instruction set much further in this version.
Integration with MOS
For the most part, the MOS is transparent to BASIC; most of the operations via the MOS and VDP are accessed via normal BBC BASIC statements, with the following exceptions:
Accessing the MOS system variables
MOS has a small system variables area which is in an area of RAM outside of its 64K segment. To access these, you will need to do an OSBYTE call
Example: Print the least significant byte of the internal clock counter
10 L%=&00 : REM The system variable to fetch
20 A%=&A0 : REM The OSBYTE number
30 PRINT USR(&FFF4)
For a full list of system variables, please refer to mos_api.inc.
Running star commands with variables
The star command parser does not use the same evaluator as BBC BASIC, so whilst commands can be run in BASIC, variable names are treated as literals.
Example: This will not work
10 INPUT "Filename";f$
20 INPUT "Load Address";addr%
30 *LOAD f$ addr%
To do this correctly, you must call the star command indirectly using the OSCLI command
Example: This will work
30 OSCLI("LOAD " + f$ + " " + STR$(addr%))