breakintoprogram / agon-bbc-basic

Official AGON QUARK Firmware: BASIC Interpreter

agon-bbc-basic

A port of BBC Basic for Z80 to the Agon

What is the Agon

Agon is a modern, fully open-source, 8-bit microcomputer and microcontroller in one small, low-cost board. As a computer, it is a standalone device that requires no host PC: it puts out its own video (VGA), audio (2 identical mono channels), accepts a PS/2 keyboard and has its own mass-storage in the form of a µSD card.

https://www.thebyteattic.com/p/agon.html

What is BBC Basic for Z80?

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.

Why am I doing this?

I've worked with Bernardo Kastrup aka The Byte Attic on another one of his projects, porting BBC Basic for Z80 to the Cerberus 2080. When he decided to design the Agon, he asked me whether I'd be interested in providing the firmware for it.

Assembling

This project is designed to be assembled and linked using the Zilog ZDS II toolkit - see the readme in MOS for more details.

NB:

• The project is configured to download this to RAM at &40000 via the ZDS cable
• Source level debugging not working correctly as this runs in a 64K Z80 segment in the eZ80 RAM

Loadig BBC Basic for Z80 on the Agon

1. Download the binary bbcbasic.bin from agon-bbc-basic releases
2. Copy it to the root directory of the Agon SD card
3. Insert the SD card into the AGON and reset/boot it
4. In the Agon MOS, check the file is on the SD card with a CAT or . command
5. Type the following commands:
   • LOAD bbcbasic.bin
   • RUN
6. You should then be greeted with the BBC Basic for Z80 prompt

Documentation

The AGON documentation can now be found on the Agon Light Documentation Wiki

License

This code is distributable under the terms of a zlib license. Read the file COPYING for more information.

Many thanks to R.T. Russell for open sourcing the source code, and David Given for facilitating this.

http://cowlark.com/2019-06-14-bbcbasic-opensource/index.html

The BASIC interpreter, as originally written by R.T. Russell and downloaded from David Given's GitHub page, has been modified slightly, either for compatibility reasons when assembling using the ZDS IDE, or for development reasons for this release.

The original files are: eval.z80, exec.z80, fpp.z80, patch.z80, main.z80, ram.z80 and sorry.z80, bbcbasic.txt, the license (COPYING) and all the files in the examples folder.

Any additions or modifications I've made to port this to the Agon have been released under the same licensing terms as the original code, along with any tools, examples or utilities contained within this project. Code that has been copied or inspired by other sources is clearly marked, with the appropriate accreditations.

Dean Belfield

Twitter: @breakintoprogram Blog: http://www.breakintoprogram.co.uk

agon-bbc-basic's Issues

Change POINT to return the colour index, not the (r,g,b) value

Point currently returns the RGB value of the pixel. Modify to return the index in the VDP palette

Update BBC BASIC port handling to simplify AGON ports

CLS does not clear sprites. It would be nice if it incorporated the command VDU 23,27,7,0, so even the sprites would be cleared.

Add GET(x,y)

Copy implementation from Spectrum Next version

ESC not working in BBC BASIC when outputting long listings

LIST calls LTRAP near the end of the loop (~line 680 of main.asm). This assumes that ESC flag has been set elsewhere, i.e. during keyboard read interrupt.

Implement PTR# and EXT#

BBC BASIC functions in patch.asm

• GETPTR
• PUTPTR
• GETEXT

Palette support in BBC BASIC

Add COLOUR l, r, g, b
Send VDU 19. l, 16, r, g, b

GCOL no longer working

I'm running the lastest MOS 1.03rc3, VDP 1.03rc3 and BBCBASIC1.04rc3 and the example programs like cube.bbc and mandelbrot.bbc both give a syntax error with GCOL.

Implement OSBYTE &A0 to read sysvars

Stretch goal: Implement =VDU(n)

Default file extension to ".bbc" if not specified

Implement the SYS keyword/command

It would be useful to have a SYS command to allow easier access to the underlying MOS function calls.

Acorn added the SYS command to BBC BASIC V, and Richard Russell has included SYS in his more recent BBC BASIC interpreters.

Without the implementation of a SYS command accessing MOS functions is restrictively hard as it requires custom z80 assembler code to be written. This puts it out of reach for all but the most experienced developers.

Consider Displaying BBC BASIC (Agon) Version info on startup

BASIC currently shows the version number for the BBC BASIC (Z80) code on which it has been based rather than the BBC BASIC (Agon) version number which is more important for determining if a user has the correct version of BASIC for their firmware.

If it showed both version numbers on startup, this might help speed up the process of finding answers when new users post problems on github, facebook, discord, etc

MOS commands that try to access file freeze when launched from Basic

When I try to run a MOS command from Basic, as soon as it attempts to access a file, it freezes. Ctrl-Alt-Del won't work either.

Commands like this no longer work when launched from Basic.

*more file
*comp file1 file

The problem started with the code checked in during 2023-03-26, code checked out at the start of this day, worked fine.
They still work fine when I launch them directly from the MOS prompt. The programs I try to run are from my agon-utilities repo. They are 24-bit mode programs (ADL=1) and I take care to set MB to 0 and restore the original value when I exit the program. This has always worked correctly since I developed these and I could always run them from Basic.

Change COLOUR l, r, g, b to COLOUR l, p

Bring in-line with the other changes to the Agon colour handling.
Set logical colour L to the physical colour P
Look the physical colour up in the colour lookup table

Enhancement: Provide ASCII keycode support in GET($)/INKEY($) commands to detect keypresses of Fn keys and cursor keys

Currently, Agon Basic commands like GET and INKEY return a zero for key presses such as the F1 through F12 keys and the individual cursor keys. It would be useful if ASCII code values were returned when pressing these special keys.

I'm not sure what the ASCII code mappings should be for these keys with non-printable characters; there does not appear to be any particular standard to follow. Some possible candidates:

[1] Re-use any FabGL ASCII code mappings for the extra keys
[2] Emulate the ASCII code mappings from a popular BBC Basic system (e.g. the Acorn BBC Micro)
[3] A brand new ASCII code mapping unique to the AgonLight

No such variable at line ...

Load and run the example .BAS file. The message No such variable at line 50010 will be displayed.

I'm not sure what is going wrong. Perhaps Agon BBC Basic gets confused when READing DATA within a REPEAT/UNTIL within a procedure after a READ of data was previously performed from a different procedure.

Mode Command not validating input

Tested on a BBC (haven't tested on Z80 BBC Basic though)
the command
MODE 0'
changes mode and then throws a "Syntax Error"
on a BBC it throws the error without doing anything.
It looks like the basic is not validating the parameter correctly.

Fix BBC BASIC REM command to stop tokenising

File main.asm ~ line 1108 - REM is token code 0xF4 (label REM)

Add parameters to BBC BASIC to chain and run a BASIC program from the command line

Add clock support to BBC BASIC

Via TIME$ virtual variable

In sorry.asm; GETIMS and PUTIMS

The sprites_1.bbc demo sometimes fails to properly clear the screen. Garbage stays behind from previous things that were on the screen earlier (I sent you a picture via Twitter DM), and the garbage seems to be treated like sprites too, as it is not overwritten.

Modes 2, 4 and 5 work reliably on my screen. But modes 0, 1 and 3 do not. The latter cut characters or images and aren't centralized properly. I will send you pictures via Twitter DMs.

Logical Screen Coordinates are off in Mode 1 and Mode 2

Logical screen coordinates look fine in MODE 0 but slightly off in MODE 1 and 2. Tested using the code:
10 CLS
20 MOVE 0,0
30 DRAW 1279, 1023

INPUT statement from the command line does not work correctly

Not sure whether this is a quirk of the language or a bug I've introduced. Check against CP/M version.

When using GET or GET$, the Esc key is disabled

Improve BBC BASIC *BYE command

As an Agon user
I would like BBC BASIC to return cleanly to MOS without doing a RST 00h
So that I can run BBC BASIC scripts in autoexec.txt

Serial port support in BBC BASIC

This was reported by Russell Davis (@ukscone) on Twitter

btw just a quicky bbcbasic question. there is nothing to do with reading/writing the serial port built into your bbcbasic is there? or even builtin mos either. i know some basics could open/read/write/close serial streams but i was never a big bbcbasic user so i don't know if it could. basically need to workout what i need to do to hook up my wifi modem to the agon and do stuff. also seen the nabu pc cloud-cp/m? interesting idea

Consider Changing Version Numbers to Be Consistent with VDP and MOS

At present, new users are expected to know that MOS/VDP 1.03 go with BBC BASIC (Agon) 1.04.

It would be simpler if MOS, VDP and BASIC shared identical major and minor version numbers where they are compatible, with new, upgraded compatible versions of BBC BASIC taking a patch release number, eg BBC BASIC (Agon) 1.04.02.

That way users would know that major and minor numbers need to be identical for a three components of the Quark firmware.

Documentation?

Great project!

I'd like to help with some beginner friendly documentation.

• I see the language differs from bbcsdl ?
• There is a dedicated documentation for Version 3/CPM on http://www.bbcbasic.co.uk/bbcbasic/mancpm/bbc2.html
• There is a file with the differences: bbcbasic.txt which seems to me not up to date (e.g. command MODE)
• Also the internal assembler needs some beginner friendly docs!

I aim for a text that can be converted to HTML and/or a PDF/Book.

Do you have any additional documentation to the BASIC commands, external to this repository?
Is there a list of valid VDU calls/parameters?

INKEY With Negative values

INKEY does not appear to support the option to use negative numbers to check if a particular key is being pressed, it looks as if its treating the negative as just a large number and waiting a long time before continuing.

From https://www.bbcbasic.co.uk/bbcwin/tutorial/chapter13.html

INKEY (not INKEY$) has an extended functionality in that it can be used to test for individual keys being pressed. To do this, we give it a negative argument. The table of values used to represent the required key is not related to the ASCII code and is given in full in the help files under INKEY / INKEY$. When used in this way, it returns immediately with a value of TRUE (–1) or FALSE (0) depending on whether the required key was pressed. Again, this is really good for games:

Extend BBC BASIC to support setting of keyboard delay and rate, and get/set the LED state

*FX 11, n: Selects keyboard auto-repeat delay
*FX 12, n: Selects keyboard auto-repeat rate
*FX 118, n: Keyboard LED control

SAVE and LOAD ASCII files from BBC BASIC

As a user I would like to be able to save and load BBC BASIC files in ASCII rather than tokenised BBC BASIC for Z80 format.

Add support for ADVAL function

Olimex now provides Wii Nunchuck joystick/controller with UEXT interface. It would be useful to have the ADVAL function to read the states of the controller.

fireworks example in tests causes freeze after pressing escape

if I
*CD /TESTS
LOAD "FIREWORKS.BAS"
RUN

and press escape it stops but doesn't return to the BASIC prompt it just freezes, pressing warmboot keysequence doesn't do anything and to get back to a usable Agon I have to press the reset button

INKEY/INKEY$(n) does not work correctly when program is first run

Running the following program

10 PRINT INKEY(1000);
20 GOTO 10

will read the CR key for the first second or so (the last key pressed after typing RUN)

BBC BASIC works like GET, but with a timeout, i.e. will obey keyboard repeat rate/delay

Support some frequently used OSBYTE calls using USR &FFF4

Some BASIC programs (especially those using MODE 7 for teletext graphics) use an expression like

(USR &FFF4 AND &FF00) DIV 256

to read the character on the screen under the cursor. This is equivalent to

ASC(GET$(POS, VPOS))

Could this (and maybe a few other frequently used OSBYTE calls) be implemented? BBC Basic for DOS and BBC Basic for SDL do implement this functionality.

BBC BASIC does not reset the screen mode after a *BYE command

Add more modern BBC BASIC features

The z80 version of BBC BASIC dates back a long way and whilst it is broadly equivalent and compatible with BBC BASIC version 4 it is missing out on quite a few keywords and features that Acorn added to BASIC V and are present in other newer versions of BASIC produced by Richard Russell.

We should consider improving the BASIC interpreter to include some of these newer features.

Examples of a few features I've missed so far has been bit-shifting operators >> and <<, support for specifying the filename on the first line of a program, multi-line IF statements, CASE statements and WHILE loops. As I'd already noted in #58 including a SYS call would be very useful.

One other thing that would be really good to support is the ability to load in libraries with the INSTALL statement. This would be very useful for sharing code and would for instance make using the agon512k library much simpler.

Support for second serial device in BBC BASIC

This card is a duplicate of: #15

Dependency: https://github.com/users/breakintoprogram/projects/1/views/7?pane=issue&itemId=21491121

Acceptance Criteria:

• I want the device to have sensible defaults (9600,8,N,1)
• I want a simple interface to configure the serial port via MOS
• I want to be able to open and close the serial device using OSOPEN, OSSHUT
• I want to be able to send and receive bytes using OSBPUT, OSBGET

Implement the ENVELOPE command for enhancing SOUND

BBC Basic provides the ENVELOPE command to compliment SOUND. Looks like there is a pull request in VDP to provide enhanced sound functionality, so perhaps it can be utilized for this request. Not sure the same syntax as BBC one can be provided, but it would make it easier to define the parameters compared to the long-winded VDU statements described in the pull request.
Note up to 4 ENVELOPEs can be defined in BBC BASIC.
As a site note on SOUND:
BBC Basic uses channel 0 for noise and 1-3 for tunes where as Agon BASIC uses channels 0-2 for tunes.
The volume parameter can be used for ENVELOPE numbers (1-4)

BASIC programs saved as BAS which contain empty lines do not load properly into Agon BASIC.

A saved BASIC program listing which resembles the following ...

     5 :::::::::::::::
    10 : REM Hello W :
    15 :::::::::::::::
    20
    25 PRINT "Hello there, World!"
    30 GOTO 25

... will currently load into Agon BASIC as the following instead:

     5 :::::::::::::::
    10 : REM Hello W :
    15 :::::::::::::::

This gives the impression that when the LOADer encounters a blank line, such as in Line 20 above, the LOADer believes that the EOF has been reached.

Currently, such BASIC program listings could only be authored outside of Agon BASIC (such as in Nano or in the BBC BASIC IDE), since it is not possible within BBC BASIC to enter a line number without any keywords or tokens and press Enter without it being interpreted as manually deleting a line of BASIC code (whether it exists or not in the listing.

Interestingly, a BBC tokenized program with an empty line does LOAD into Agon BASIC without issue, which leads me to believe that support for BAS program listings with empty lines is merely a limitation of the text loading support of the LOAD command.

SIDE NOTE: If folks wish to be able to enter empty lines of code within Agon BASIC, then the BASIC/MOS editor would need to be enhanced to support the entry of empty line numbers, but it should only support that behavior when the line number does not already exist, otherwise support for manually deleting a line of BASIC code by entering its line number would be broken. An alternative way to support this behavior within Agon BASIC might be to enforce a definition that an empty line of BASIC is a line number followed by at least one space.

Cannot concatenate command after FX

The following code should print "TEST", but does not:

*FX 19 : PRINT "TEST"

But this does print "TEST1" and "TEST2" as expected:

PRINT "TEST1" : PRINT "TEST2"

So it looks like it is not possible to concatenate anything after a *FX command?

Modify the BBC BASIC MODE test so that it displays a testcard graphic

As an AGON tester
I want to be able to cycle through all the modes
And see that the graphics and colours all work
So that I can help establish which modes work on most common monitors

After running the sprite test and/or some other programs, then loading the Mandelbrot test without reseting the system, the fractal started being drawn somewhere in the middle of the screen, instead of the top-left. Somehow it got confused, probably when switching screen modes, I guess.

Any way to change the keyboard layout (say, from UK to US) from BASIC?

Bad Program reported for plain text .BAS files

I ran into an issue where attempting to load a plain text .BAS resulted in me seeing a Bad program error.

On investigation I found this was caused by the file having LF character line endings. Changing the file to use CRLF fixed the issue.

As many modern computers and editors now default to using LF only for line endings BASIC should really support that.

If you let "sprites5.bbc" run for a while, then interrupt with ESC, and then CHAIN "sprites2.bbc", it can crash

This bug was reported by Lennart Benschop on 23/12/2023.
It shows the reboot message for Agon VPD 1.02 and then hangs

In the sprites_1.bbc test, one or two sprites always seem to flicker in an unstable way, unlike the rest.

BBCBASIC needs twice ENTER on command line and permanent on running a basic program

After every command on BASIC interpreter i must press ENTER twice.

If i run the BASIC programs from tests folder, it looks like a STEP-BY-STEP interpreting.
I must always press ENTER two times to interpreting the next BASIC command.

If i start MANDLEBROT.BBC i hold down the ENTER key and it takes a long time if he start drawing on the bottom.
By SPRITES4.BBC it goes by holding down the ENTER key in a assembly view.

On MOS the Keyboard works fine.

I have AgonLight2 from OLIMEX and tested it with two keyboards (Cherry G80-3000 and Cherry G83-13014).
VDU and MOS have Version 1.03
BBCBASIC is 3.00 / 1.04

Prompt to overwrite when saving in BBC BASIC

As an Agon BBC BASIC programmer
I want to be given the prompt "File exists. Do you want to overwrite (Y/n)?"
If I try to save over a file that already exists
So that I don't get a confusing error message and be expected to *ERASE BASIC files before saving over them