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.
+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 BBC BASIC for Agon documentation here.
+To run, load into memory and run as follows:
+ +It is possible to automatically CHAIN (load and run) a BBC BASIC program by passing the filename as a parameter: +
+Note that passing a . as the first parameter of RUN is informing MOS to use the default value there (&40000)
+BBC BASIC needs a full 64K segment, so cannot be run from the MOS folder as a star command.
+The following * commands are supported
+Syntax: *BYE
Exit BASIC and return to MOS.
+Syntax: *EDIT linenum
Pull a line into the editor for editing.
+Syntax: *FX osbyte, params
Execute an OSBYTE command.
+The only OSBYTE commands supported at the moment are:
+And from MOS 1.03 or above
+Syntax: *VERSION
Display the current version of BBC BASIC
+In addition, any of the MOS commands can be called by prefixing them with a *
+See the MOS documentation for more details
+The following statements are not currently implemented:
+The following statements differ from the BBC Basic standard:
+REM does not tokenise any statements within comments. This is to bring it inline with string literals for internationalisation.
+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.
+The modes differ from those on the BBC series of microcomputers. The full list can be found here in the VDP documentation.
+Syntax: COLOUR c
Change the the current text output colour
+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
Syntax: GCOL mode,c
Set the graphics colour c, and the "mode" of graphics paint operations.
Colour values are interpreted as per the COLOUR command, i.e. values below 128 will set the foreground colour, and values above 128 set the background colour.
+Versions of the VDP earlier than 1.04 only supported mode 0, with all painting operations just setting on-screen pixels.
+VDP 1.04 introduced partial support for mode 4, which inverts the pixel. Mode 4 would only apply to straight line drawing operations. The mode would affect all applicable plot operations.
+As of Console8 VDP 2.6.0, all 8 of the basic modes are supported for all currently supported plot operations. Separate plot modes are now tracked for foreground and background colours, and the mode is applied to the graphics operation.
+The full array of available modes is as follows:
+| Mode | +Effect | +
|---|---|
| 0 | +Set on-screen pixel to target colour value | +
| 1 | +OR value with the on-screen pixel | +
| 2 | +AND value with the on-screen pixel | +
| 3 | +EOR value with the on-screen pixel | +
| 4 | +Invert the on-screen pixel | +
| 5 | +No operation | +
| 6 | +AND the inverse of the specified colour with the on-screen pixel | +
| 7 | +OR the inverse of the specified colour with the on-screen pixel | +
Syntax: POINT(x,y)
This returns the physical colour index of the colour at pixel position (x, y)
+Syntax: PLOT mode,x,y
For information on the various PLOT modes, please see the VDP PLOT command documentation
+Syntax: GET$(x,y)
Returns the ASCII character at position x,y
+Syntax: GET(x,y) (from BBC BASIC 1.05)
As GET$, but returns the ASCII code of the character at position x, y
+Syntax: GET(p)
Read and return the value of Z80 port p
+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)Access the ESP32 RTC data
+Example:
+ +NB: This is a virtual string variable; at the moment only getting the time works. Setting is not yet implemented.
+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.
+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
+MLTThe assembler will only compile 8-bit Z80 code and there are currently no plans for extending the instruction set much further in this version.
+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:
+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)
+Documentation for the full list of system variables can be found in the MOS API documentation.
+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 +
+To do this correctly, you must call the star command indirectly using the OSCLI command
+Example: This will work +
+ + + + + + + + + + + + + +Most frequently asked questions (and answers) to using the Agon platform
+No, and there are no immediate plans on doing this to reduce the amount of time spent doing documentation.
+The official hardware and software components that are part of the Quark firmware are open source, including BBC BASIC for Agon. Please check the license of any third party applications.
+Okay, so you've ordered your Agon Light, and are wondering what else you will need to purchase.
+Minimum: +- A PS/2 compatible keyboard +- A micro USB card
+NB: +- The orginal Agon Light requires a PS/2 keyboard, or a USB keyboard that supports the PS/2 protocol with a USB to PS/2 adaptor. +- The Agon Light 2 requires a USB keyboard that supports the PS/2 protocol, or a PS/2 keyboard with a PS/2 to USB adaptor.
+Officially it is not designed to run CP/M out of the box. There are however third-party developers who are porting CP/M to the platform, and the official build will support this.
+Check out the Popup MOS repository; click the green 'Code' icon and select 'Download ZIP' from the dropdown menu. Unzip the file and copy over everything from the 'popup-os-main' folder to an empty SD card. The card should have folders like demos/docs/games/mos/utils in the root of the card
+Another great distribution is Agon Mite which has a monthly release cycle.
+These repositories are a volunteer effort, periodically collecting the latest versions of software out there. If you need a more recent version of any package, because sometimes development goes pretty fast; please download it individually to your SD card.
+Any class-10 micro SD card of a decent quality will do fine
+You should aim for a maximum card size of 32GB. Larger cards are supported (using FAT32), but you may run into issues partitioning and formatting them.
+Format the card using a FAT32 layout
+Most distributions contain both the BBC BASIC binary (bbcbasic.bin), and an autoexec.txt file at top level of SD card. The latter contains commands for auto loading BBC Basic. If you'd like to disable auto loading BBC BASIC; remove it, or change the content to suit your own requirements.
+All Agon platforms can be powered using a USB cable to your PC, or a USB wall-charger. The load is relatively light, usually below 200mA with a connected keyboard. Which USB cable you need, depends on the variant of Agon you buy. For example, the Olimex AgonLight2 is powered from a USB-C interface, while the Agon Console8 can be powered using a USB-B interface. The latter can also be powered with 5v DC jack connector.
+It really depends on the current firmware versions on your Agon. The Agon contains firmware for both the OS (MOS) and graphics unit (VDP).
+If both VDP and MOS are currently still at 1.03, as most Olimex AgonLight2 boards are, follow this detailed guide to upgrade it. This is only necessary once; from 1.04 onwards, all upgrades can be done with the flash tool.
+If you are running at least VDP and MOS 1.04, just install the flash tool, get the appropriate firmware files (see below for examples) and read the short documentation on the page to upgrade both VDP and MOS in one go. The latest version can be found under the releases tab. The page also has a link to help you upgrade, if you are running an even older version than 1.03.
+this flowchart provides an overview of the overall process, instructions for all version combinations of VDP and MOS and additional links to use, depending on your current version starting points.
+I recommend using the Console8 firmware. +- Console8 MOS firmware +- Console8 VDP firmware
+We recommend using the Console8 firmware, as most development currently takes place there while staying compatible with previously released software. It's important to mention that the latest, most interesting games, make use of features that are only available in the Console8 (VDP) firmware, so make sure to use that.
+Yes, either way.
+All Agon variants have a jumper location on the PCB marked 'ESP-PROG' or 'ESP-PROG1'. For programming the VDP over the USB interface, this needs to be CLOSED, i.e. both pins should be connected using the removable jumper. It is present on the PCB, to provide the option to prohibit the ESP32 to go into programming mode on reset, likely due to the way the USB serial driver behaves on your PC. If this happens to you occasionally and it looks like the Agon doesn't boot on a reset, it may be just waiting for an external programming session that never happens, spewing messages over the USB serial; in that case remove the jumper or leave it open, but remember to close it again before programming it externally over USB. The position of this jumper is ignored when programming the VDP using the flash tool from the MOS prompt. +I recommend to leave this jumper in the CLOSED position, unless you experience problems resetting your Agon.
+All Agon variants have a jumper to either enable, or prohibit the UART between the eZ80 and ESP32. During normal operation of the Agon, both ICs should be able to 'talk' to each other; this jumper was provided in case communication between them would somehow cause issues during programming either IC. AFAIK there haven't been cases to date where this proved necessary, but the option is at least there. If your Agon doesn't do anything after you have received it from your vendor, you may check this jumper's position. Cases have been reported of boards not working due to an incorrect factory jumper setting.
+The AgonLight/AgonLight2/AgonLight Origins edition have this jumper labeled as 'UART-DIS' or 'UART-DIS1', which should be left OPEN to not disable communications and have a working Agon
+The Agon Console8 has this jumper labeled as 'UART-EN1', which should be CLOSED to enable communications and have a working Agon.
+All Agon variants have a jumper to enable/disable the onboard buzzer, labeled 'BUZ-EN', 'BUZ_EN1' or 'BUZZER'. Leaving the jumper open disables the buzzer, while closing it enables it, whichever is your preference.
+No, not unless you will be developing your own Agon MOS firmware AND need to be comfortably sure you can recover it under ALL circumstances. And even then you may very well get by using one of the community-provided options. People in the community owning SMART cables are seldomly using them nowadays.
+Again, for regular update purposes, the Zilog SMART cable is unnecessary and a waste of money. If it's bricking you're worried about; there is a simple solution requiring just a few dupont cables and a clear step-by-step plan to recover your Agon. In any case, you can at least buy a new Agon for the price of the Zilog SMART cable. Ease your worries.
+The Agon-compatible Zilog product numbers are: +- ZUSBSC00100ZACG (discontinued) +- ZUSBASC0200ZACG (current; requires v5.3.5 or later of Zilog’s ZDS -II IDE)
+ATTENTION: the cable with product number ZUSBESC0200ZACG is NOT suitable for Agon!
+Absolutely (and this has been tested), but cecause literally ANY version can be flashed, please be mindful going back to older versions. The Pleistocene may not have a wall-outlet to charge your time travel device.
+Do yourselves a big favor, and stay away from anything below Quark 1.03, or that Zilog ZDS cable I mentioned you shouldn't buy, might suddenly start get interesting again.
+Yes, it can be used with any Agon platform.
+To program an older VDP (1.03 or earlier) to a newer version, you need to connect the Agon using a USB (data) cable. Some very cheap USB cables may only have wires for powering/charging a USB device, without any wired datalines. Fortunately these are becoming scarce nowadays, but if all else fails, you might be using the wrong cable (or have the incorrect jumper setting; see above)
+The Agon will present a virtual serial port (COM) on your PC, that communicates directly with the ESP32 graphics chip (VDP).
+It depends on the OS you have. In Linux, when you insert your USB cable and type 'dmesg | grep tty', it should show.
+In Windows, it should show up in device manager, or in powershell type '[System.IO.Ports.SerialPort]::getportnames()'.
+In Mac OS, you can type 'ls /dev/tty.*' in Terminal to list all com ports currently attached.
+A legitimate question that you need to ask the respective vendor of your Agon.
+You need a keyboard that supports the PS/2 protocol, regardless of the physical connection that it has. Some Agon variants have a PS/2 interface, so any keyboard with a PS/2 connector should be fine. +However, a number of Agon variants use a USB connector for their keyboard interface; for these you either need a USB keyboard that still supports the PS/2 protocol in backward compatibility mode (and it is usually hard to find out if it does), or a regular PS/2 keyboard with a PASSIVE PS/2-to-USB connector. An example for the latter, which is known to work well is this one. This is a pass-through connector, that just rewires the PS/2 signals to the USB connector. Perfect for the Agon.
+A PS/2-to-USB connector cannot make use of active logic and/or microcontrollers inside the connector. If the connector is dirt-cheap, it's usually passive, but even active converters can be offered relatively cheap.
+If a PS/2->USB converter has both a PS/2 keyboard and PS/2 mouse cable, a thick USB connector and/or a 'bulge' in the middle of the cable AND it doesn't specifically mention the term PASSIVE, it's a dead giveaway to be an active (non-supported) converter. Don't buy these: they scan/convert the PS/2 signals to a USB HID protocol that the Agon doesn't support. Examples to avoid 1 and 2
+Sure, there's a crowd-sourced spreadsheet here with a list of known working keyboards.
+If you have one, and it's not on the list, then please feel free to add an entry.
+You can use the following command from the MOS command line, from BBC BASIC (using the *), or loaded on boot/reset using a line in the autoexec.txt file on your SD card:
+
*SET KEYBOARD n
+The keyboard layout for UK = 0, US = 1 +Other available layouts are available from MOS 1.03+, documented here
+Use the following command:
+*BYE
+Check out these links for your particular Agon edition: +- Byte Attic AgonLight R1.0 +- Byte Attic Agon Origins edition +- Olimex AgonLight2 +- Agon Console8
+We're listing a few here, though there will certainly be others: +- Sabotrax/agon-software +- The Byte Attic - Agon overview
+The main differences are:
+And there are some minor revisions to discrete components on the board. Other than that, it is functionally identical to the original Agon Light design.
+Historically, this has been a problem when the VDP firmware was built using the Arduino IDE. You are strongly advised to use PlatformIO to build the VDP firmware, and to update to the latest versions; in doing so you should no longer have any issues with screen modes. PlatformIO takes care of all the dependencies and settings and thus is much easier to use than the Arduino IDE. The Console8 VDP firmware no longer supports being built using the Arduino IDE and instead is built using PlatformIO to avoid these kind of issues.
+If you wish to still use the Arduino IDE and are building the Quark variant of the VDP firmware, you will need to make sure you have PSRAM enabled in the Arduino IDE settings when you compile and transfer the VDP code.
+Have a look at this excellent guide. +We also provide some documentation at our community site.
+Your AGON may have a 'tests' folder with some BBC BASIC examples; if it doesn't, they can be found here.
+The AGON comes pre-shipped with BASIC as it is a good language to start coding with, but you are not limited to it. The following languages are supported:
+We would recommend watching and learning these excellent tutorials
+Download the latest version of the onboard assembler. Don't dally using the one that came with your uSD card package, things move quickly in this space - use the latest.
+Assuming you already know some C/C++, start downloading the best C/C++ cross-development toolchain there currently is, and look at some online examples from tools/games.
+There is an excellent Forth implementation available here
+The community is building out at set of markdown documents to detail several aspects. These are extremely useful to a programmer.
+A memory map can be found here
+Buckle up!
+All suggestions are welcome, though the developers will be concentrating on key features. If we think your idea has legs, we'll add it to the pile.
+You might have found an opportunity to make a valuable contribution to the Agon community. Take a look at the community documentation and create a pull request.
+Perhaps you have some cool ideas and you want to run them past people, or you want to watch some of the developers talk, or you've followed all the instructions here and broke something and now you'd like to ask around to see if someone else has had the same experience? There is a Discord server available for Agon & Console 8 community discussions.
+ + + + + + + + + + + + + +GPIO, or General Purpose Input and Output, is an interface on a computer that is not dedicated to a single task. On the Agon this is exposed as a series of pins for the user to interface to. This might be for input controls, such as a joystick or buttons, motion sensors, or outputs to control your Christmas tree lights, send data to other displays, microprocessors, or even connect to the internet.
+Whilst sharing many similar pins, there are some variations across the range of Agon machines.
+The first generation Agon Light has a double row of 32 pins, whereas the Agon Light 2 has a double row of 34 pins. The additional pair of pins have been added for a battery power supply connection.
+The Agon Console 8 adds a few extra rows for additional connectivity to other parts of the ESP processor.
+More information about using these features can be found in the MOS-API documentation.
+Viewed from the back, component side up, with the connector to the right of the board.
+
Viewed from the back, component side up, with the connector to the right of the board. A slight change with an additional pair of pins to the right hand side. The pin numbering is the same as the Agon Light 2 by Olimex.
+
The general layout is the same as the Origins Edition, apart from pins 1 & 2.
+
Olimex's proprietary UEXT connector is mounted next to the main IO bus.
+Note that although there are duplicate pins exposed on the UEXT conector as the main IO bus, they are connected to the same pins on the ez80 chip. They are there for convenience, but do not provide any additional hardware ports.
+It is sometimes useful to have the duplicate pins for different purposes. For example, connecting a Nintendo Nunchuck controller on the UEXT using Olimex's adapter board, and a joystick on the main IO bus.
+
Viewed from the top front, component side up.
+The Console 8's pin numbering is different and although they look similar at first, some of the pins do not align with those of the Agon Light, so do not plug an Agon Light peripheral into the io bus of a Console 8. +Pins marked * go via a transputer.
+
The MOS API can be used by external applications to access MOS functionality.
+Please note that this documentation uses assembler in the examples in a format that is compatible with the Zilog ZDS II assembler. The assembler syntax used in BBC BASIC is similar, but not identical. Additionally you will need to use the new ADL version of BBC BASIC to use the new eZ80 ADL mode and extended instruction set.
+This documentation is not intended as a tutorial on eZ80 assembler, but as a reference for those who are already familiar with the eZ80 or Z80 instruction set and wish to use MOS APIs in their programs.
+There are four RST instructions for accessing MOS functionality from Z80.
+
RST 00h: Reset the eZ80RST 08h: Execute a MOS commandRST 10h: Output a single character to the VDPRST 18h: Output a stream of characters to the VDP (MOS 1.03 or above)In addition, if you are using the Zilog ZDS II assembler you may wish to include the file mos_api.inc in your project. The Console8 version can be found in the folder src of project agon-mos. The original Quark versions of this file can be found in the folder src of project agon-mos.
NB:
+RST.LIS opcode in an eZ80 assembler will ensure the MOS RST instructions are called regardless of the eZ80s current addressing mode.mos_api.inc file you will find:Further information on the RST handlers provided by MOS are as follows:
RST 08h: Execute a MOS commandParameters:
+A: MOS command number to executeNB:
+mos_api.inc with EQUs for all the MOS commandsMacro:
+;
+; Macro for calling the API
+; Parameters:
+; - `F`unction: One of the function numbers listed above
+;
+MOSCALL: MACRO function
+ LD A, function
+ RST.LIS 08h
+ ENDMACRO
+Example:
+; OSRDCH: Read a character in from the ESP32 keyboard handler
+;
+OSRDCH: MOSCALL mos_getkey
+ OR A
+ JR Z, OSRDCH ; Loop until key is pressed
+ RET
+RST 10h: Output a single character to the VDPParameters:
+A: Character to outputExample:
+; OSWRCH: Write a character out to the ESP32 VDU handler via the MOS
+; A: Character to write
+;
+OSWRCH: RST.LIS 10h ; This calls a RST in the eZ80 address space
+ RET
+RST 18h: Output a stream of characters to the VDP (MOS 1.03 or above)Parameters:
+HL(U): Address of the data stream (16-bit for Z80 mode, 24-bit for ADL mode)BC: Length of stream (or 0 if the stream is delimited)A: Stream delimiter (if BC=0)Returns:
+- A: Last character displayed (length mode) OR Delimeter (delimeter mode)
+- BC: 0
+- HL(U): Address of last character displayed + 1 (length mode) OR location of delimeter (delimeter mode)
+- E: Value of A upon entry
Example:
+; Write a stream of characters to the VDP
+; HLU: Address of buffer containing data - if in 16-bit segment, U will be replaced by MB
+; BC: Number of characters to write out, or 0 if the data is delimited
+; A: End of data delimiter, i.e. 0 for C strings
+;
+ LD HL, text ; Address of text
+ LD BC, 0 ; Set to 0, so length ignored...
+ LD A, 0 ; Use character in A as delimiter
+ RST.LIS 18h ; This calls a RST in the eZ80 address space
+ RET
+;
+text: DB "Hello World", 0
+MOS API calls can be executed from a classic 64K Z80 segment or whilst the eZ80 is running in 24-bit ADL mode. For classic mode, 16 bit registers are passed as pointers to the MOS commands; these are automatically promoted to 24 bit by adding the MB register to bits 16-23 of the register. When running in ADL mode, a 24-bit register will be passed, but MB must be set to 0.
+The following MOS commands are supported:
+0x00: mos_getkeyRead a keypress from the VDP
+Parameters: None
+Returns:
+- A: The keycode of the character pressed
0x01: mos_loadLoad a file from SD card
+Parameters:
+- HL(U): Address of filename (zero terminated)
+- DE(U): Address at which to load
+- BC(U): Maximum allowed size (bytes)
Preserves: HL(U), DE(U), BC(U)
Returns:
+- A: File error, or 0 if OK
+- F: Carry reset if no room for file, otherwise set
0x02: mos_saveSave a file to SD card
+Parameters:
+HL(U): Address of filename (zero terminated)DE(U): Address to save fromBC(U): Number of bytes to savePreserves: HL(U), DE(U), BC(U)
Returns:
+A: File error, or 0 if OKF: Carry set0x03: mos_cdChange current directory on the SD card
+Parameters:
+HL(U): Address of path (zero terminated)Preserves: HL(U)
Returns:
+A: File error, or 0 if OK0x04: mos_dirList SD card folder contents to screen.
+This is a simple directory listing command that will list the contents of the current directory to the screen. More advanced directory listing functionality for applications to use is available via the FatFS commands API.
+Parameters:
+HL(U): Address of path (zero terminated)Preserves: HL(U)
Returns:
+A: File error, or 0 if OK0x05: mos_delDelete a file or folder from the SD card
+Parameters:
+HL(U): Address of path (zero terminated)Preserves: HL(U)
Returns:
+A: File error, or 0 if OK0x06: mos_renRename a file on the SD card
+Parameters:
+HL(U): Address of filename1 (zero terminated)DE(U): Address of filename2 (zero terminated)Preserves: HL(U), DE(U)
Returns:
+A: File error, or 0 if OK0x07: mos_mkdirMake a folder on the SD card
+Parameters:
+HL(U): Address of path (zero terminated)Preserves: HL(U)
Returns:
+A: File error, or 0 if OK0x08: mos_sysvarsFetch a pointer to the system variables
+Parameters: None
+Returns:
+IXU: Pointer to the MOS system variable area (this is always 24 bit)0x09: mos_editlineInvoke the line editor
+Parameters:
+HL(U): Address of the bufferBC(U): Buffer lengthE: Flags to control editor behaviourPreserves: HL(U), BC(U), DE(U)
Returns:
+- A: Key that was used to exit the input loop (CR=13, ESC=27)
Editor behaviour flags are as follows: +| Bit | Description | +| --- | ----------- | +| 0 | When set, buffer will be cleared before use | +| 1 | When set, tab-completion for MOS commands and files is enabled * | +| 2 | When set, hotkeys are disabled * | +| 3 | When set, input history will be disabled * | +| 4-7 | Reserved for future use (for future compatibility, ensure these are set to zero) |
+* Support for editor control flags was added in Console8 MOS 2.2.0. Prior to this the only documented values for E were 0 and 1 to indicate whether the buffer should be cleared.
0x0A: mos_fopenGet a file handle
+Parameters:
+HL(U): Address of filename (zero terminated)C: ModePreserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns:
+- A: Filehandle, or 0 if couldn't open
Mode can be one of: fa_read, fa_write, fa_open_existing, fa_create_new, fa_create_always, fa_open_always or fa_open_append
+NB: If you open the file using mos_fopen, you must close it using mos_fclose, not ffs_api_fclose
+0x0B: mos_fcloseClose a file handle
+Parameters:
+C: Filehandle, or 0 to close all open filesPreserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns:
+A: Number of files still open0x0C: mos_fgetcGet a character from an open file
+Parameters:
+C: FilehandlePreserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns:
+- A: Character read
+- F: C set if last character in file, otherwise NC (MOS 1.04 or greater)
0x0D: mos_fputcWrite a character to an open file
+Parameters:
+C: FilehandleB: Character to writePreserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns: None
+0x0E: mos_feofCheck for end of file
+Parameters:
+C: FilehandlePreserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns:
+- A: 1 if at end of file, otherwise 0
0x0F: mos_getErrorCopy an error string to a buffer
+Parameters:
+E: The error codeHL(U): Address of buffer to copy message intoBC(U): Size of bufferPreserves: DE(U), HL(U), BC(U)
Returns: None
+0x10: mos_oscliExecute a MOS command
+Parameters:
+HL(U): Pointer the the MOS command stringPreserves: HL(U)
Returns:
+A: MOS error codeNB previously documentation for this command was incorrect, as it documented additional parameters in DE(U) and BC(U). These registers are not currently used.
0x11: mos_copyCopy a file on the SD card
+Parameters:
+HL(U): Address of filename1 (zero terminated)DE(U): Address of filename2 (zero terminated)Preserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns:
+A: File error, or 0 if OKNB: Requires MOS 1.03 or greater
+0x12: mos_getrtcGet a time string from the RTC (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a buffer to copy the string to (at least 32 bytes)Preserves: HL(U)
Returns:
+A: Length of time string0x13: mos_setrtcSet the RTC (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a 6-byte buffer with the time data in+0: Year (offset from 1980, so 1989 is 9)
++1: Month (1 to 12)
++2: Day of Month (1 to 31)
++3: Hour (0 to 23)
++4: Minute (0 to 59)
++5: Second (0 to 59)
+Preserves: HL(U)
Returns: None
+0x14: mos_setintvectorSet an interrupt vector (Requires MOS 1.03 or above)
+Parameters:
+E: Interrupt vector number to setHLU: Address of new interrupt vector (24-bit pointer)Preserves: HLU, DEU
Returns:
+HL(U): Address of the previous interrupt vector (24-bit pointer)0x15: mos_uopenOpen UART1 (Requires MOS 1.03 or above)
+To handle the received interrupts, you will need to assign a handler to UART1's interrupt vector (0x1A).
+Parameters:
+IXU: Pointer to a UART struct+0: Baud rate (24-bit, little endian)
++3: Data bits (5, 6, 7 or 8)
++4: Stop bits (1 or 2)
++5: Parity bits (0: None, 1: Odd, 3: Even)
++6: Flow control (0: None, 1: Hardware)
++7: Enabled interrupts
+ - Bit 0: Set to enable received data interrupt
+ - Bit 1: Set to enable transmit data interrupt
+ - Bit 2: Set to enable line status change interrupt
+ - Bit 3: Set to enable modem status change interrupt
+ - Bit 4: Set to enable transmit complete interrupt
+Preserves: HL(U)
Returns:
+A: Error code (always 0)0x16: mos_ucloseClose UART1 (Requires MOS 1.03 or above)
+0x17: mos_ugetcRead a character from UART1 (Requires MOS 1.03 or above)
+Returns:
+A: The character readF: C if successful, NC if the UART is closed0x18: mos_uputcWrite a character to UART1 (Requires MOS 1.03 or above)
+Parameters:
+C: The character to writeReturns:
+F: C if successful, NC if the UART is closed0x19: mos_getfilGet a pointer to a FIL structure in MOS (Requires MOS 1.03 or above)
+Parameters:
+C: FilehandlePreserves: BC(U)
Returns:
+HLU: 24-bit pointer to a FIL structure (in MOS RAM)0x1A: mos_freadRead a block of data from a file (Requires MOS 1.03 or above)
+Parameters:
+C: FilehandleHLU: Pointer to a buffer to read the data intoDEU: Number of bytes to readPreserves: HL(U), BC(U)
Returns:
+DEU: Number of bytes read0x1B: mos_fwriteWrite a block of data to a file (Requires MOS 1.03 or above)
+Parameters:
+C: FilehandleHLU: Pointer to a buffer that contains the data to write DEU: Number of bytes to write outPreserves: HL(U), BC(U)
Returns:
+DEU: Number of bytes written0x1C: mos_flseekMove the read/write pointer in a file (Requires MOS 1.03 or above)
+Parameters:
+C: FilehandleHLU: Least significant 3 bytes of the offset from the start of the fileE: Most significant byte of the offset (set to 0 for files < 16MB)Preserves: HL(U), BC(U), DE(U)
Returns:
+A: FRESULT0x1D: mos_setkbvectorAllows user programs to access VDP keyboard packets without overriding the entire uart0 interrupt handler. +The user program registered, will be called during the uart0 interrupt handler, being passed the address of the full VDP keyboard packet. Normal MOS key handling is disabled when a user program is registered.
+Parameters:
+C: Address length in HL (0 = 24bit, 1 = 16bit). If 1 then set the top byte of HLU(callback address) to MB (for ADL=0 callers)HL(U): Callback address of user program to register, or 0 to clear any previously registered vectorReturns: Nothing upon registration. The user program can expect the full VDP packet address in DE(24-bit) upon entry.
+example code that registers a custom handler.
+0x1E: mos_getkbmapFetch a pointer to the virtual keyboard map (Requires MOS 1.04 RC2 or above)
+Parameters: None
+Returns:
+IXU: Pointer to the keyboard bitmap (this is always 24 bit)0x1F: mos_i2c_openOpen the I2C bus as Master (Requires MOS 1.04 RC3 or above)
+Parameters:
+C: Frequency ID (1: 57600, 2: 115200, 3: 230400)Preserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns: None
+0x20: mos_i2c_closeClose the I2C bus (Requires MOS 1.04 RC3 or above)
+Parameters: None
+Preserves: HL(U), BC(U), DE(U), IX(U), IY(U)
Returns: None
+0x21: mos_i2c_writeWrite a block of bytes to the I2C bus (Requires MOS 1.04 RC3 or above)
+Parameters:
+C: I2C AddressB: Number of bytes to write (maximum 32)HL(U): Pointer to a buffer to read the bytes fromPreserves: HL(U), DE(U), IX(U), IY(U)
Returns:
+- A: Status
+ - 0: OK
+ - 1: No response from I2C slave
+ - 2: Data NACK
+ - 4: Bus arbitration lost
+ - 8: Bus error
0x22: mos_i2c_readRead a block of bytes from the I2C bus (Requires MOS 1.04 RC3 or above)
+Parameters:
+C: I2C AddressB: Number of bytes to read (maximum 32)HL(U): Pointer to a buffer to write the bytes toPreserves: HL(U), DE(U), IX(U), IY(U)
Returns:
+- A: Status
+ - 0: OK
+ - 1: No response from I2C slave
+ - 2: Data NACK
+ - 4: Bus arbitration lost
+ - 8: Bus error
MOS makes use of FatFS to access the SD card. Some of FatFS's functionality is exposed via the MOS API. The exact API calls listed here may be expanded in later versions of MOS.
+For more information on FatFS data structures and functions, see the FatFS documentation.
+0x80: ffs_fopenOpen a file (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to an empty FIL structureDE(U): Pointer to a C (zero-terminated) filename stringC: File open modePreserves: HL(U), DE(U), C
Returns:
+A: FRESULTExample:
+ LD HL, fil ; FIL buffer
+ LD DE, filename ; Filename (0 terminated)
+ LD C, fa_read ; Mode
+ MOSCALL ffs_fopen ; Open the file
+ LD DE, buffer ; Where to store the read file
+ LD BC, 256 ; Number of bytes to read
+ MOSCALL ffs_fread ; Read the data in
+ PUSH BC ; Preserve number of bytes read
+ MOSCALL ffs_fclose ; Close the file
+ POP BC ; BC: Number of bytes read
+ RET
+
+filename: DB "example.txt", 0 ; The file to read
+
+fil: DS FIL_SIZE ; FIL buffer (defined in mos_api.inc)
+buffer: DS 256 ; Buffer for storing read data
+0x81: ffs_fcloseClose a file (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a FIL structurePreserves: HL(U)
Returns:
+A: FRESULTSee ffs_fopen for an example
+0x82: ffs_freadRead from a file (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a FIL structureDE(U): Pointer to a buffer to store the data inBC(U): Number of bytes to read (typically the size of the buffer)Preserves: HL(U), DE(U)
Returns:
+BC(U): Number of bytes readA: FRESULTSee ffs_fopen for an example
+0x83: ffs_fwriteWrite to a file (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a FIL structureDE(U): Pointer to a buffer to read the data fromBC(U): Number of bytes to write (typically the size of the buffer)Preserves: HL(U), DE(U)
Returns:
+BC(U): Number of bytes writtenA: FRESULTExample:
+ LD HL, fil ; FIL buffer
+ LD DE, filename ; Filename (0 terminated)
+ LD C, fa_write | fa_create_always ; Mode
+ MOSCALL ffs_fopen ; Open the file
+ LD DE, buffer ; Location of data to write
+ LD BC, 256 ; Number of bytes to write
+ MOSCALL ffs_write ; Write the data
+ MOSCALL ffs_fclose ; Close the file
+ RET
+
+filename: DB "example.txt", 0 ; The file to read
+
+fil: DS FIL_SIZE ; FIL buffer (defined in mos_api.inc)
+buffer: DS 256 ; Buffer containing data to write out
+0x84: ffs_fseekMove the read/write pointer in a file (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a FIL structureDE(U): Least significant 3 bytes of the offset from the start of the fileC: Most significant byte of the offset (set to 0 for files < 16MB)Preserves: HL(U), DE(U), BC(U)
0x8E: ffs_feofDetect end of file (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a FIL structurePreserves: HL(U)
Returns:
+A: 1 if at the end of the file, otherwise 00x91: ffs_dopenOpen a directory (Requires Console8 MOS 2.2.0 or above)
+Parameters:
+HL(U): Pointer to a blank DIR structureDE(U): Pointer to a C (zero-terminated) directory path stringPreserves: HL(U), DE(U)
Returns:
+A: FRESULT0x92: ffs_dcloseClose a directory (Requires Console8 MOS 2.2.0 or above)
+Parameters:
+HL(U): Pointer to a DIR structurePreserves: HL(U)
Returns:
+A: FRESULT0x93: ffs_dreadRead next directory entry into a FILINFO data structure (Requires Console8 MOS 2.2.0 or above)
+Parameters:
+HL(U): Pointer to a DIR structureDE(U): Pointer to a FILINFO structurePreserves: HL(U), DE(U)
Returns:
+A: FRESULT0x96: ffs_statGet file information (Requires MOS 1.03 or above)
+Parameters:
+HL(U): Pointer to a FILINFO structureDE(U): Pointer to a C (zero-terminated) filename stringPreserves: HL(U), DE(U)
Returns:
+A: FRESULTExample:
+ LD HL, filinfo ; FILINFO buffer
+ LD DE, filename ; Filename (0 terminated)
+ MOSCALL ffs_stat
+ RET
+
+filename: DB "example.txt", 0 ; The file to read
+
+filinfo: DS FILINFO_SIZE ; FILINFO buffer (defined in mos_api.inc)
+0x9E: ffs_getcwdGet the current working directory (Requires Console8 MOS 2.2.0 or above)
+Parameters:
+HL(U): Pointer to a buffer to store the directory path inBC(U): Maximum length of the bufferPreserves: HL(U), BC(U)
Returns:
+A: FRESULTThe MOS API command mos_sysvars returns a pointer to the base of the MOS system variables area in IXU - A 24-bit pointer.
The following system variables are available in mos_api.inc:
+; System variable indexes for api_sysvars
+; Index into _sysvars in globals.asm
+;
+sysvar_time: EQU 00h ; 4: Clock timer in centiseconds (incremented by 2 every VBLANK)
+sysvar_vpd_pflags: EQU 04h ; 1: Flags to indicate completion of VDP commands
+sysvar_keyascii: EQU 05h ; 1: ASCII keycode, or 0 if no key is pressed
+sysvar_keymods: EQU 06h ; 1: Keycode modifiers
+sysvar_cursorX: EQU 07h ; 1: Cursor X position
+sysvar_cursorY: EQU 08h ; 1: Cursor Y position
+sysvar_scrchar: EQU 09h ; 1: Character read from screen
+sysvar_scrpixel: EQU 0Ah ; 3: Pixel data read from screen (R,B,G)
+sysvar_audioChannel: EQU 0Dh ; 1: Audio channel
+sysvar_audioSuccess: EQU 0Eh ; 1: Audio channel note queued (0 = no, 1 = yes)
+sysvar_scrWidth: EQU 0Fh ; 2: Screen width in pixels
+sysvar_scrHeight: EQU 11h ; 2: Screen height in pixels
+sysvar_scrCols: EQU 13h ; 1: Screen columns in characters
+sysvar_scrRows: EQU 14h ; 1: Screen rows in characters
+sysvar_scrColours: EQU 15h ; 1: Number of colours displayed
+sysvar_scrpixelIndex: EQU 16h ; 1: Index of pixel data read from screen
+sysvar_vkeycode: EQU 17h ; 1: Virtual key code from FabGL
+sysvar_vkeydown EQU 18h ; 1: Virtual key state from FabGL (0=up, 1=down)
+sysvar_vkeycount: EQU 19h ; 1: Incremented every time a key packet is received
+sysvar_rtc: EQU 1Ah ; 8: Real time clock data
+sysvar_keydelay: EQU 22h ; 2: Keyboard repeat delay
+sysvar_keyrate: EQU 24h ; 2: Keyboard repeat rate
+sysvar_keyled: EQU 26h ; 1: Keyboard LED status
+sysvar_scrMode: EQU 27h ; 1: Screen mode (from MOS 1.04)
+sysvar_rtc_enable: EQU 28h ; 1: RTC enable status (from Console8 MOS 2.0.0)
+sysvar_mouseX: EQU 29h ; 2: Mouse X position
+sysvar_mouseY: EQU 2Bh ; 2: Mouse Y position
+sysvar_mouseButtons: EQU 2Dh ; 1: Mouse left+right+middle buttons (bits 0-2, 0=up, 1=down)
+sysvar_mouseWheel: EQU 2Eh ; 1: Mouse wheel delta
+sysvar_mouseXDelta: EQU 2Fh ; 2: Mouse X delta
+sysvar_mouseYDelta: EQU 31h ; 2: Mouse Y delta
+The MOS is a command line Machine Operating System, similar to CP/M or DOS, that provides a human interface to the Agon file system.
+It also provides the MOS API for programmers to use that provides some basic facilities for file I/O and other common operations for BBC BASIC and other third-party applications.
+This documentation explains the general features of MOS, as well as commands it offers and how to use them. It covers the Quark 1.04 version of MOS, and the later Console8 MOS versions up to and including 2.2.3. Versions of MOS prior to Quark 1.04 may be missing some features described below.
+To get the most out of MOS, you will need the following:
+Technically MOS will work without an SD card, but you won't be able to do much with it.
+On powering on, your Agon will automatically mount the SD card and look for an autoexec.txt file in the root folder. If it finds one, it will execute the commands in the file.
MOS also supports a mos folder to add in some additional commands, and from Console8 MOS 2.2.0 onwards it also supports a bin folder for executables.
mos folderThe mos folder is a special folder that must be placed at the top level of your SD card that can be used to extend the functionality of MOS.
When you attempt to use a command that is not built into MOS, it will look in the mos folder on the SD card for a file with the same name as the command with a .bin extension. If it finds one, it will execute that file as if it were a built-in command.
Commands provided via the mos folder are known as "moslets". These have a special requirement in that they must be built to run from memory address 0x0B0000 onwards. The use of this address is intended to allow moslets to run without affecting the main user program space. The idea being that this will let you use a moslets from within BASIC without having to worry about it overwriting your program.
bin folderFrom Console8 MOS 2.2.0 onwards, MOS will also support a bin folder at the top level of your SD card.
The bin folder can be used to store programs that can be run from MOS. These differ from moslets in that they are expected to be full standalone programs that will be run and executed at the default memory address of 0x040000, and thus will overwrite existing programs.
If you have attempted to use a command that was not built into MOS, and was not found in the mos folder, MOS will then look in the bin folder for a file with the same name as the command with a .bin extension. If it finds one, it will load and run that file.
NB there is currently no way to control the memory address that a program in the bin folder will be loaded to, so if you have a program that needs to be loaded at a specific address, you will need to use the LOAD command to load it manually. Additionally there is no way to control the manner in which MOS searches for commands, so if you have a program in the bin folder that you want to run, you will need to ensure that there is no built-in command or moslet with the same name. These limitations may be changed in the future.
autoexec.txt fileIf, at boot-up time, MOS detects an autoexec.txt file in the root folder of the SD card, it will read the file in, and execute the MOS commands in the file sequentially from top to bottom.
For example, to set keyboard to US, load BBC BASIC from the root folder, change to the test folder, then run BASIC
+ +The manner in which this file is executed differs slightly between Quark 1.04 and the Console8 releases. Quark will blindly execute the commands and silently carry on if there is an error, whereas Console8 will stop execution if there is an error in the file, report the error as well as which line the error occurred on.
+As of Console8 MOS 2.2.0 the autoexec.txt file will run on every boot. Previous versions of MOS (including Quark 1.04) would only run the autoexec.txt file on a "hard reset" (i.e. a power cycle, or press of the reset button) and not on a soft reset (i.e. a CTRL+ALT+DEL).
Presssing CTRL+ALT+DEL will reboot MOS on the eZ80. (CTRL+SHIFT+ESC for MOS 1.02 or earlier)
NB: This assumes that MOS is still talking to the VDP, as it is the VDP that is responsible for detecting the keypresses. Sometimes a soft reboot key combination will therefore not work, and you may need to instead press the reset button on your Agon.
+MOS provides a command line interface (CLI) that allows you to interact with the Agon file system and perform some basic control over your Agon computer.
+The MOS CLI is loosely inspired by the Acorn MOS present in the BBC Micro and later Acorn computer systems like the Archimedes.
+MOS works alongside the Agon's VDP, using the facilities of the VDP to display text on the screen and accept input from the keyboard. The VDP provides some useful facilities, such as a "paged mode" that will stop the screen from scrolling until you press the SHIFT key to continue, or ESCAPE to exit. Paged mode can be toggled on and off by pressing CTRL+N and CTRL+O respectively.
MOS provides a simple line editor that allows you to edit the current command line before submitting it to the system. This same line editor is available for third-party applications like BBC BASIC to use.
+The line editor allows you to move the cursor around the current line of text, insert and delete characters, and submit the line to the system. Whilst much of the functionality on Agon is inspired by the BBC Micro, the line editor differs - there is no "copy" cursor system on the Agon. This line editor is similar to those that you will find on modern operating systems like MacOS, Linux or Windows.
+The MOS CLI line editor will also provide some basic command history, keeping track of the last 10 commands the user has entered. Pressing the UP arrow key when at the beginning of a line will replace the current line with the last entered command. Similarly pressing the DOWN arrow key at the end of a line will cycle through the command history in the opposite direction. The HOME and END keys will move the cursor to the start and end of the current line respectively.
The Console8 MOS 2.2.0 release also adds support for pressing the PAGE UP and PAGE DOWN keys to quickly step through the command history.
Also added to the 2.2.0 release is "tab completion". If you start typing a command and then press the TAB key, MOS will attempt to complete the command for you. This includes both built-in commands, moslets found in the mos folder, programs found in the current directory, and programs found in the bin folder.
There is also support for programmable function keys in the 2.2.0 release. For more information on that see the HOTKEY command.
+On versions of MOS prior to the 2.2.0 release, the MOS command prompt is a simple * character. This is the point at which you can enter commands to the system.
From the Console8 MOS 2.2.0 release onwards the prompt has been extended to include the current directory. This is to help you keep track of where you are in the file system. The prompt will look something like this:
+ +(It is intended that future versions of MOS will allow you to customise the prompt to your liking.)
+MOS offers a number of commands that allow you to interact with the Agon file system and control your computer. These commands are entered at the MOS command prompt, and are executed by pressing the RETURN key. If you are inside BBC BASIC, you can also enter MOS commands by preceding them with an asterisk *.
MOS commands are case-insensitive, and can be abbreviated with a dot .. For example, DELETE myfile and DEL. myfile are equivalent. When you abbreviate a command, the first matching command is used, so whilst there are several commands that begin with C, C. will execute the CAT. Commands that accept multiple parameters will expect those parameters to be space-delimited. Numbers are in decimal, but can be prefixed with an ampersand & for hexadecimal.
To aid users coming from other systems, several commands have aliases, for example DELETE and ERASE are equivalent. The aliases are listed in the command descriptions below.
Commands are described below. Commands parameters are described with angle brackers <param> and optional parameters are indicated with square brackets [<param>] or [-flag], and alternative parameters are shown either side of a | character.
Any command that requires a memory address will expect a 24-bit address value.
+The commands available in MOS are as follows:
+. (dot)Syntax: *. [<path>] (Alias for CAT)
This command is an alias for the CAT command. If a path is provided, it will list the contents of that directory, otherwise it will list the contents of the current directory.
CATSyntax: *CAT [-l] [<path>] (Aliases include DIR and .)
The "Catalogue" command, which displays a directory listing of the current directory, or of the directory at the path given.
+From Console8 MOS 2.2.0 onwards, the -l flag can be used to display the long form of the directory listing, which includes the file size and date/time of last modification, otherwise a shorter form of the directory listing will be displayed. Versions of MOS prior to 2.2.0 will always display the long form of the directory listing.
CDSyntax: *CD <path>
Change current directory.
+The path provided to the CD command uses / as the directory separator, and can be either an absolute path or a relative path. The root directory is /. CD .. can be used to move up one directory level.
CDIRSyntax: *CDIR <path>
This command is an alias for the CD command.
Available from Console8 MOS 2.2.0 onwards.
+CLSSyntax: *CLS
Clear the screen.
+(This command performs a VDU 12, which is the same as the CLS command in BBC BASIC.)
COPYSyntax: *COPY <source> <destination>
Create a copy of a file.
+From Console8 MOS 2.2.0 onwards, the COPY command will also support the use of wildcards in the source file name, such as *.txt, and can support the destination being a directory.
CPSyntax: *CP <source> <destination>
This command is an alias for the COPY command.
Available from Console8 MOS 2.2.0 onwards.
+CREDITSSyntax: *CREDITS
Outputs some credits and version numbers for third-party libraries used in the Agon firmware.
+DELETESyntax: *DELETE <filename> (Aliases include ERASE)
Delete a file or folder (must be empty).
+DIRSyntax: *DIR [<path>]
This command is an alias for the CAT command.
ERASESyntax: *ERASE <filename>
This command is an alias for the DELETE command.
EXECSyntax: *EXEC <filename>
Executes commands from a text file.
+Commands will be executed one at a time. If an error occurs processing a command, execution will stop and the error will be reported.
+(This is essentially how the autoexec.txt file is processed at boot time.)
NB: This command is not available in Quark 1.04.
+HELPSyntax: *HELP [<command> | all]
Displays help information for a command. If no command is provided, a list of available commands will be displayed.
+NB prior to Console8 MOS 2.2.0 the HELP command required a command name to be provided, or the all keyword to display all commands.
HOTKEYSyntax: *HOTKEY [<n> [<command string>]]
Sets or clears programmable function keys.
+Using this command you can set the function keys F1-F12 on your to perform a specific command. There are three ways in which this command works:
+1. If no parameters are provided, then the current hotkeys will be displayed.
+2. If a function key number n is provided alone without a command string, then the current command assigned to that function key will be cleared.
+3. If a function key number n and a command string are provided, then the command string will be assigned to that function key.
+ - If the command string includes %s then the current input line will be substituted in place of %s.
JMPSyntax: *JMP <address>
Jumps to the specified address in memory. Using this command, you can jump to any address in memory, including the ROM. If used from the MOS command line, the processor will be in the eZ80 ADL mode.
+LOADSyntax: *LOAD <filename> [<address>]
Load a file from the SD card into the specified address in memory. If no address parameters is specified, then the address will default to &40000.
MKDIRSyntax: *MKDIR <name>
Make a new directory on the SD card.
+MOUNTSyntax: *MOUNT
Mount the SD card.
+If you have ejected your SD card, you can use this command to re-mount it.
+MOVESyntax: *MOVE <source> <destination>
This command is an alias for the RENAME command.
MVSyntax: *MV <source> <destination>
This command is an alias for the RENAME command, and is only available from Console8 MOS 2.2.0 onwards.
RENAMESyntax: *RENAME <source> <destination> (Aliases include MOVE)
This is the command to rename a file or move a file to a different folder.
+To rename a file in the same folder.
+*RENAME autoexec.txt autoexec.bak
Rename a file and move to a different folder (the destination folder must exist).
+*RENAME test.bas archive/test.bas
From Console8 MOS 2.2.0 onwards, the RENAME command also supports allowing the destination to specify a directory. If the destination is a directory, the source file will be moved to that directory and keep the same filename. Additionally if the destination is a directory then the source file specified can include a wildcard, such as *.txt.
RMSyntax: *RM <filename>
This command is an alias for the DELETE command, and is only available from Console8 MOS 2.2.0 onwards.
RUNSyntax: *RUN <address | .> [<parameters>]
Call an executable binary loaded in memory. If no parameters are passed, then the address will default to &40000. The address parameter can also be replaced with . to indicate that the default address of &40000 should be used. Any additional parameters will be passed through to the executable.
When using the RUN command MOS will check the header of the executable to determine which mode it is in, and will run the executable in the appropriate mode. This allows you to run both Z80 mode executables, which are restricted to 64kb of RAM, and ADL mode executables which can use all 512kb of memory. The header starts at byte 64 of the executable, which must contain MOS. Byte 68 must be a 0 byte to indicate Z80 mode, or a 1 byte to indicate ADL mode.
When a program is executed using the RUN command, MOS will set up the following processor registers:
A will be set to the current memory bank value MBDE(U) the execution address passed to RUNHL(U) pointer to additional parameters passed to RUNSAVESyntax: *SAVE <filename> <address> <size>
Save a block of memory to the SD card.
+SETSyntax: *SET <option> <value>
Set a system option.
+NB before Console8 MOS 2.2.0 the SET command was case-sensitive for the option name.
Syntax: *SET KEYBOARD <n>
Sets the current system keyboard layout.
+* These layouts are only supported from Console8 MOS 2.2.0 onwards. The exact keyboard layouts supported will depend on the version of the VDP firmware you have installed. Prior to Console8 MOS 2.2.0 keyboard values of 9 or above would be ignored. From Console8 MOS 2.2.0 onwards any keyboard value can be specified - if the keyboard layout is not supported by the VDP firmware then it will be ignored.
+Syntax: *SET CONSOLE <n>
Sets the console mode, where if n is 0 then console mode will be disabled, and if n is 1 then console mode will be enabled.
When console mode is enabled, all (initial) "command" and text bytes sent to the VDP will be echoed out of the VDP to any attached USB serial device. This can be useful for debugging purposes.
+It is recommended that instead of using this command, if you are running Console8 VDP 2.5.0 or later, you should use VDU 2 instead to enable the "printer", which also outputs from the VDP to the same serial device. The main difference is that the "printer" device will filter out any control codes, providing a safer output, whereas the console mode will output everything. The printer can be disabled with VDU 3. Additionally pressing CTRL+B on the keyboard will enable the printer, CTRL+C will disable it, and CTRL+P will toggle it.
TIMESyntax:
+- *TIME
+- *TIME <yyyy> <mm> <dd> <hh> <mm> <ss>
Set and read the ESP32 real-time clock
+TYPESyntax: *TYPE <filename>
Display the contents of a text file on the screen.
+VDUSyntax: *VDU <char1> <char2> ... <charN>
Write a stream of character bytes to the VDP. This can be used to perform various control functions, such as clearing the screen, changing the screen mode, setting the cursor position, or changing the text colour. More information on VDU commands can be found in the VDP documentation.
+This command is similar to the VDU command in BBC BASIC, but instead of separating arguments with commas you must instead separate them with spaces.
Prior to Console8 MOS 2.2.0, the VDU command would only accept 8-bit numbers as arguments. Any values provided greater than 255 would be ignored.
From Console8 MOS 2.2.0 onwards this command will now also support 16-bit numbers as arguments, and several different ways to indicate hexidecimal numbers. The BBC BASIC standard of suffixing a number with a semicolon character ; to indicate a 16-bit number is supported. As well as the & prefix for hexidecimal numbers, you can also use 0x as a prefix, or h as a suffix. Hexidecimal numbers provided greater than 255 will always be treated as 16-bit numbers.
Addresses are 24-bit, unless otherwise specified
+&000000 - &01FFFF: MOS (Flash ROM)&040000 - &0BDFFF: User RAM&0B0000 - &0B7FFF: Storage for loading MOS star command executables off SD card &0BC000 - 0BFFFFF: Global heap and stackIn the Agon Projects Git, there are a handful of useful templates and projects.
+There are three template projects that can be used as a basis for your projects:
+All three apps act as MOS extensions; the resultant binary can be copied into the mos folder on the SD card, can be executed as a star command, and will display any passed parameters.
Both can be run as star commands from MOS.
+ + + + + + + + + + + + + +The Agon Light, and its variants, is a retro-style computer platform that is designed to be inexpensive and easy to manufacture, using commonly available parts.
+The platform is designed to be easy to understand, and easy to program. It is designed to be a platform that is suitable for learning about computers, and learning about programming.
+Please note this is a preliminary guide to the Agon Light platform, and is subject to change. The Agon Light platform is still under development, and this guide is still being written.
+The primary processor on which you run programs is an eZ80. This is a microcontroller based on the Zilog Z80 processor, which was used in many computers and arcade machines in the 1970s and 1980s. The eZ80 is a modern version of the Z80, with a few enhancements. It has attached to it 512KB of RAM, which is considerably more than the 64KB that was common in the 1980s. Also attached to the eZ80 chip is an SD card interface, allowing an SD card to be used for storage.
+The eZ80 was chosen as the main processor of the Agon Light because of its historic ubiquity, and because it is still manufactured today. It is a relatively simple processor, and is easy to understand and program.
+Whilst the eZ80 is manufactured today, none of the video chips that were used in computers of the 1970s and 1980s are still manufactured, so for video output a different solution is needed. To solve this problem the Agon Light uses a separate video processor, which we call the VDP, the Video Display Processor. This chip is responsible for sound and video output, and also keyboard and mouse input. Technically, this is an ESP32-Pico-D4 chip, which has attached to it an 8MB RAM chip which is used for screen memory and storing bitmaps and sound samples.
+The exact technical details of the VDP however for most programmers is not important - in the Agon platform, from a software perspective, the VDP is designed to be used via a simple API, with the details of how it works abstracted away. Indeed, when using an emulator of the Agon Light, the VDP chip is not emulated at all, and the emulator instead runs a compiled version of the VDP firmware using the host computer's video and audio hardware.
+Effectively, the design of the Agon Light is that of two computers in one. The eZ80 is the computer that is used to run programs, and the VDP is a computer that draws the screen and plays sound. The eZ80 and the VDP communicate with each other using a high speed serial interface.
+Some other retro-inspired computers take a different approach to solving the video output problem. Often this involves making use of an FPGA chip, which is a chip that can be programmed to behave like any other chip. This is a very flexible solution, but it is also very expensive. The Agon Light takes a different approach, using a separate video processor chip, which is much cheaper than an FPGA.
+The use of what is effectively a separate computer for the VDP in the Agon platform creates a significant architectural difference to many classic home computers of the 8-bit, 16-bit and early 32-bit era. Those classic computers would usually use a shared area of memory that the main processor and the video processor would both have access to. This shared memory would be used to store the screen memory, and the main processor would write to this memory to update the screen. This is not the case with the Agon platform. The eZ80 and the VDP have no shared memory, and the VDP has no access to the eZ80's RAM. This means that the VDP cannot read the screen memory directly, and the eZ80 cannot write directly to the screen memory. Instead, the VDP has to be sent commands to draw things to the screen, and the eZ80 has to be sent commands to read things from the screen. This is a significant difference to many classic computers, and is something that programmers need to be aware of when writing programs for the Agon platform.
+From a software perspective, a significant inspiration for the Agon Light was the BBC Micro, a popular computer in the UK from the 1980s designed and built by Acorn Computers Ltd.. (Acorn went on to design the ARM processor, which is now the most commonly used processor design in the world.) The BBC Micro was part of the BBC's Computer Literacy Project, which was a project to introduce computers to the UK population with an emphasis on education. The BBC Micro was designed to be easy to use, and to be used in schools by children.
+There are several significant differences between the Agon Light and the BBC Micro, but the two most important ones are the main processor, and the video system. A BBC Micro was based on the 6502 CPU, which was a competitor to the Z80. The 6502 was a simpler processor than the Z80, and was cheaper to manufacture, and given the relative simplicity often significantly faster than the Z80. The 6502 was used in many popular computers of the 1970s and 1980s, including the Apple II, the Commodore 64, and the Atari 2600. The Z80 was used in many other popular computers of the 1970s and 1980s, including the Sinclair ZX80, the Sinclair ZX81, the Sinclair Spectrum, the Amstrad CPC, and the MSX. The BBC Micro however was designed from the ground up to be a computer capable of having multiple processors, and the first second processor option available for the computer was the Z80. A version of BBC BASIC was produced for Acorn's Z80 second processor, and this is the version of BBC BASIC that the Agon Light is directly based on.
+An important part of the BBC Micro was BBC BASIC, a well respected version of the BASIC programming language. Compared to other versions of BASIC, BBC BASIC was very powerful since it included many advanced features, such as procedures, functions, and recursion. It also included many commands for graphics and sound, which made it easy to write games and other programs that used graphics and sound.
+The original version of BBC BASIC for the 6502 processor was written by Sophie Wilson of Acorn. The version of BBC BASIC for the Z80 was written by R.T.Russell, and was based on the original version by Sophie Wilson. The version of BBC BASIC for the Agon Light is directly based on R.T.Russell's version, and is largely compatible with the BBC Micro version.
+BBC BASIC has an inbuilt assembler, which allows for machine code to be embedded within BASIC programs. This is a very powerful feature, and allows for programs to be written that make use of the full power of the processor. Machine code can run very many times faster than interpreted BASIC. It should be noted that the Z80 version of BASIC as used on the Agon platform has an assembler for the Z80 built in, whereas the original 6502 version of BASIC for the BBC Micro included an assembler for the 6502 processor. Programs written for the BBC Micro that include assembler code will therefore not run on the Agon Light without rewriting those assembler routines.
+There is now a newer version of BBC BASIC for the Agon platform known as the "ADL version". The original Z80 version of BBC BASIC was restricted to work within 64KB of RAM. This limitation was due to the fact that the Z80 processor only has 16 address lines (also referred to as a 16-bit address bus), so technically it can only address 64KB of RAM.
+The newer eZ80 CPU used in the Agon Light has a 24-bit address bus, which means that it can potentially address up to 16MB of RAM. Agon Light machines come with 512KB of RAM attached to the eZ80 CPU.
+To allow programs to make use of this extra RAM, and some other new facilities, the eZ80 has extensions known as "ADL mode". This mode extends some processor registers to 24 bits, and allows for the use of the extra RAM. The ADL version of BBC BASIC is designed to make use of this extra RAM, and to allow for programs to be written that make use of more than 64KB of RAM.
+The ADL version of BBC BASIC also includes modifications to the assembler to allow for the use of newer ADL machine code instructions. This means that programs written for the ADL version of BBC BASIC may not run on the original Z80 version of BBC BASIC.
+The other significant difference between the Agon Light and the BBC Micro is the video system. As video output is handled by a separate processor, and there is no shared memory between the two processors within an Agon Light, the design of the Agon system does not allow for the video system to work in the same kind of manner as a BBC Micro. From a software perspective, however, the Agon Light is designed to be as similar as possible to the BBC Micro, and the video system is designed to be as similar as possible to the BBC Micro video system. This means that many programs written for the BBC Micro can be ported to the Agon Light with minimal changes.
+Using BASIC on a BBC Micro, the primary way to draw things to the screen was via simple keywords such as PRINT, MOVE, DRAW, PLOT, COLOUR (etc.) and most importantly VDU. It is the VDU keyword that sent commands to the video system. Effectively all of the other keywords that drew onto the screen (or changed drawing settings) are just shorthand for VDU commands.
The same is true on the Agon Light. The Agon's VDP processor has been written to understand the same VDU commands as the BBC Micro, and so the same keywords that draw things to the screen on a BBC Micro will also draw things to the screen on an Agon Light. This means that many programs written in BBC BASIC for the BBC Micro can be ported to the Agon Light with minimal changes.
The Agon Light also includes a number of additional VDU commands that are not present on the BBC Micro, which allow for more advanced graphics and sound effects. These commands are documented in the VDP section of this documentation.
The nature of the MOS/VDP split on the Agon platform carries with it some limitations that you should be aware of.
+The nature of the VDP is that it is, essentially, a stream processor. It accepts a stream of data from the eZ80, and interprets that as a stream of commands and data. In regular use, there is no command to indicate the beginning of a command stream, and no command to indicate the end of a command stream. The VDU commands that the VDP interprets are of a variable length, ranging from a single byte to potentially over 64kb. A single VDU statement in BASIC could be a complete command from the perspective of the VDP, or it could be the first part of a command that is continued in the next VDU statement. For commands that are intended to send across a large amount of data, such as a bitmap or a sound sample, the data is typically sent using a series of VDU statements, each of which is a part of the same command.
Care must therefore be taken to ensure that the VDP is sent complete commands, and that commands are not interleaved. For instance, it may be tempting when transfering over a sound sample to use PRINT or DRAW statements to show progress. This will not work, because the VDP will interpret the PRINT or DRAW statements (which will have been translated into a raw VDU byte command stream) as part of the sound sample data.
To solve this issue, the VDP provides a Buffered Commands API. This allows for data to be sent to the VDP in discrete chunks, sent to one of over 65000 buffers. Once all of the data has been sent, a command can be sent to the VDP to make use of the data in the buffer, whether that is to use the buffer as a sound sample, a bitmap, or a sequence of VDU commands. So to print a progress bar whilst sending a sound sample, you would send the sound sample data to a buffer a chunk at a time using the Buffered Commands API "add block" command, and after each chunk use drawing commands to update the progress bar. Once all of the sound sample data has been sent, you would then send a command to the VDP to identify that data as a sound sample, and/or use other commands to play that sample.
+ + + + + + + + + + + + + +Please note that this list is far from exhaustive. If you have a project that you would like to add to this list, please submit a pull request.
+https://github.com/tomm/popup-mos
+A batteries-included SDCard template for Agon Light / Agon Light 2 / Console8
+https://github.com/envenomator/agon-flash
+A utility to flash a MOS image to the eZ80F92 Flash without a ZDS USB cable, and to update the VDP firmware.
+[https://github.com/envenomator/agon-hexload](https://github.com/envenomator/agon-hexload
+Playing microSD jockey during assemble/compile/transfer/test/debug cycles is no fun at all. This utility shortens this cycle significantly by removing the need to physically bring over new binaries to the Agon.
+With the hexload command you are able to transmit Intel I32 hex files to one of the Agon serial ports and run your code immediately from memory.
+https://github.com/envenomator/agon-ez80asm
+A fully-featured eZ80 assembler that runs on the Agon.
+https://github.com/lennart-benschop/agon-forth
+https://github.com/lennart-benschop/agon-utilities
+A selection of handy utilities including copy, compare, more, memfill, font, and a full-screen editor with nano-style key bindings.
+https://github.com/envenomator/agon-sokoban
+Sokoban game for AGON
+ + + + + + + + + + + + + +This guide lists all the required steps to upgrade an Agon, which has been delivered to you with older MOS/VDP version 1.03, to a later version. +Please follow each step as closely as possible and make sure that each item on the preparation list is completed before attempting the first upgrade steps.
+For the Olimex AgonLight2 - please make sure the jumpers on the board are placed like this: the LEFT jumper is unconnected/open/placed on just one pin, the RIGHT jumper is connected/closed/placed on both pins
+
If it doesn't exist yet, create a folder named 'mos' on the SD card
+Change to the subfolder of the VDP release you'd like to upgrade to:
+Start the upgrade script with the serial/COM port you noted earlier - COMXX and /dev/ttyUSBXXX are examples here:
+Done
+ + + + + + + + + + + + + +NB this document is very outdated and needs to be rewritten. If you have found your way here, please be aware that the instructions below are no longer correct, or the best way to udpate your Agon machine.
+Instructions kindly collated by Tim Delmare
+The responsibility for any issues during and/or after the firmware upgrade lies with the user
+This has been tested on:
+There are reported compatibility issues with the Arduino IDE / ESPTools running on MacOS, especially with the M series CPUs. I have collated some of the workarounds in the 'Configuring the Arduino IDE' steps.
+If you have already configured the Arduino IDE for Agon then you can skip this step, otherwise follow the instructions here: Arduino IDE Settings
+If you do not have the Zilog cable then the order in which you do things is especially important. Update the MOS first. If you update the VDP first, you will not be able to update MOS using the Agon MOS Flash Upgrader due to changes in the MOS.
+mos in the root directory if one does not already exist. Copy flash.bin to this directory*BYE to quit BBC BASICCD / to return to root directory (you can also use backslash)FLASH MOS.bin 0x81E397C9Once this has succeeded the Agon will not work properly until you upgrade VDP.
+Note that compilation may take several minutes. Once this is complete, and the Arduino IDE has uploaded the new code to the ESP32 on the Agon, the Agon should automatically reboot with the latest and greatest.
+ + + + + + + + + + + + + +The VDP is the Agon's Visual Display Processor. It is responsible for:
+It runs on the ESP32-Pico-D4 co-processor and uses a fork of the FabGL library (known as vdp-gl) to support those functions.
+At a higher level, its input is a byte stream from the eZ80F92 main CPU over an internal high-speed UART connection @ 1,152,000 baud (384,000 baud for versions of MOS/VDP prior to 1.03). This stream contains a mixture of text and control characters. These control characters are mapped to the BBC BASIC VDU control characters, a choice made as BBC BASIC for Agon is the pre-installed programming language of Agon. As a result, we refer to the commands that the VDP understands as VDU commands.
+The ESP32 also outputs data back to the eZ80F92, for example keyboard data and screen information via a custom serial protocol.
+The VDU statement in BBC BASIC essentially just means "send this data to the VDP". It will accept any number of integer arguments between 0 and 255, separated by commas. If a value is immediately followed by a semicolon ; instead of a comma then the value is a little-endian word from 0 to 65535.
Example:
+VDU 25, 69, 640; 512;: Plot a dot in the center of the screen
VDU 65: Print the letter "A", without a newline
A single VDU statement in BASIC can potentially contain multiple commands for the VDP to interpret, or a VDU command could instead be split across multiple VDU statements. Other BASIC keywords that generate screen output are effectively just wrappers for VDU command sequences.
For example, the following code snippets are all directly equivalent, and result in an identical command stream being sent to the VDP:
+ + + + +MOS also supports a VDU command which can be used to send VDU commands to the VDP. This is useful for testing the VDP without having to write a BASIC program. Its command is simpler than the BASIC equivalent, accepting only 8-bit integer values between 0 and 255, separated by spaces.
+Example:
+VDU 17 15: Set the text foreground colour to 15
As of Console8 MOS 2.2.0, the VDU command is now more sophisticated and can support sending 16-bit values as well as 8-bit values. More information can be found in the MOS documentation.
MOS offers two ways to send VDU commands from assembly code. The first is to use the RST 10h call, which will send the byte in the A register to the VDP. The second is to use a RST 18h call which is used to send multiple bytes to the VDP at once. (Neither of these calls require the string VDU to be included in the data sent to the VDP, and both require raw binary values to be sent, rather than an ASCII string.)
More information about these can be found in the MOS API documentation.
+The aim is that the Agon's VDP should be as compatible as practical with the BBC Micro's VDU command, as well as the VDU commands supported by later versions of Acorn and R.T.Russell's BBC BASICs. Where necessary, some extensions have been added to help facilitate the Agon's unique features and architecture.
+For a more detailed description of VDU commands supported by the Agon's VDP, see VDU Commands.
+The following is a high-level list of the VDU sequences that are supported:
+VDU 0: Null (no operation)VDU 1: Send next character to "printer" (if "printer" is enabled) §§VDU 2: Enable "printer" §§VDU 3: Disable "printer" §§VDU 4: Write text at text cursorVDU 5: Write text at graphics cursorVDU 6: Enable screen (opposite of VDU 21) §§VDU 7: Make a short beep (BEL)VDU 8: Move cursor back one characterVDU 9: Move cursor forward one characterVDU 10: Move cursor down one lineVDU 11: Move cursor up one lineVDU 12: Clear text area (CLS)VDU 13: Carriage returnVDU 14: Page mode On *VDU 15: Page mode Off *VDU 16: Clear graphics area (CLG)VDU 17, colour: Define text colour (COLOUR)VDU 18, mode, colour: Define graphics colour (GCOL mode, colour)VDU 19, l, p, r, g, b: Define logical colour (COLOUR l, p / COLOUR l, r, g, b)VDU 20: Reset palette and text/graphics colours and drawing modes §§VDU 21: Disable screen (turns of VDU command processing, except for VDU 1 and VDU 6) §§VDU 22, n: Select screen mode (MODE n)VDU 23, n: Re-program display character / System CommandsVDU 24, left; bottom; right; top;: Set graphics viewport **VDU 25, mode, x; y;: PLOT commandVDU 26: Reset graphics and text viewports **VDU 27, char: Output character to screen §VDU 28, left, bottom, right, top: Set text viewport **VDU 29, x; y;: Set graphics originVDU 30: Home cursorVDU 31, x, y: Move text cursor to x, y text position (TAB(x, y))VDU 127: BackspaceAll other characters, i.e. those in the range of 32 to 126 and 128 to 255, are sent to the screen as ASCII, unaltered.
+Any VDU command that is the VDP does not recognise (such as VDU 2 when running on Quark 1.04) will be ignored.
* Requires VDP 1.03 or above
+ ** Requires VDP 1.04 or above
+ § Requires Console8 VDP 2.3.0 or above
+ §§ Requires Console8 VDP 2.5.0 or above
VDU 23 essentially has a split purpose. The first is to redefine the system font display characters, and the second is to send commands to the VDP to control and access more sophisticated behaviour.
For more information on these commands and a full list, please consult the VDU 23 section of the VDU Commands document. This includes the Bitmap and Sprite API.
Amongst this you will also find system commands, which start with VDU 23, 0, most of which are unique to the Agon platform. Within the system commands set you will find the Audio API, Buffered Commands API, Font API, and Context Management API.