v3.0.0 Alpha 2

3.0.0 Alpha 2 release

This is an alpha release - it contains experimental features with commands and APIs that are subject to change. Whilst it should not crash your machine, the new features it contains should not be considered to be stable, and may differ in the final release version.

As with other releases, this can be run on any Agon Light compatible machine, including the Agon Light, Agon Light 2, Agon Console8 and Agon Origins Edition.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Producing new versions of the Agon firmware is a lot of work. Financially, I could really use the help.

What is new

This release is a snapshot of the current "system variables" branch work, and builds on the previous release. The primary improvement from alpha 1 is the addition of APIs that expose all of the new functionality, making them available for programs to use.

(NB the original 3.0.0-alpha2 release has been removed and replaced with this slightly newer version, owing to the discovery of one critical bug, and a mistake in the release process that meant that the original release git tag did not tag the correct code.)

It should be noted that whilst the underlying functionality for these new APIs has been extensively tested, the API wrappers themselves have not. Documentation for these new APIs have not yet been written at the time of release. They will be added to the community documentation site in due course. Preliminary documentation can be seen against the API implementations in mos_api.asm

New commands

Most new commands were added in Alpha 1 - see the release notes for more information.

IfThere <filepath> then <command> [else <command>]

This command works essentially the same as the If command (added in Alpha 1) but will instead look for the presence of a file or directory at the given filepath. The filepath is transformed before it is checked, so variables may be used.

Try <command>

Try will perform the given command, trapping any errors that may occur. It will set Try$ReturnCode with the return code value for the command, and if an error occurred it will set Try$Error to the corresponding error string.

The Try command allows for commands that can fail to be included in script files.

%<command>

Prefixing any command with the % character makes the command interpreter skip command alias resolution. This means for example that you could redefine an internal MOS command with an alias, but have the alias make sure it uses the original command.

Other changes

The argument substitution system, as used by command aliases and hotkeys, has been updated to mean that arguments enclosed with double-quotes are treated as a single argument.

The command line interpreter will also recognise arguments enclosed by double-quotes. This means that you can now refer to filenames that include spaces from the CLI.

NB at the time of this release, the tab-completion system does not support this, so it will not play ball correctly with double-quotes, or auto-complete filenames appropriately that include spaces.

The Sys$Date system variable is now writable, so you can change the system RTC date via setting that variable.

New APIs

All of the new functionality is now available via APIs. The full list of new APIs is as follows:

mos_unpackrtc:		EQU	23h

; MOS string functions
;
mos_pmatch:		EQU	28h
mos_getargument:	EQU	29h
mos_extractstring:	EQU	2Ah
mos_extractnumber:	EQU	2Bh
mos_escapestring:	EQU	2Ch

; System variables and related functions
;
mod_setvarval:		EQU	30h
mos_readvarval:		EQU	31h
mos_gsinit:		EQU	32h
mos_gsread:		EQU	33h
mos_gstrans:		EQU	34h
mos_substituteargs:	EQU	35h
mos_evaluateexpression:	EQU	36h	; not implemented, yet
; 37h not yet used

; Path resolution functions
;
mos_resolvepath:	EQU	38h
mos_getdirforpath:	EQU	39h
mos_getleafname:	EQU	3Ah
mos_isdirectory:	EQU	3Bh
mos_getabsolutepath:	EQU	3Ch

Documentation for these will be added to the community documentation site in due course.

v2.3.2

2.3.2 release of the Agon Console8 MOS

This is the ninth official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Release notes

This is a "patch" release that fixes some minor bugs in MOS.

The echo command has received a fix for a bug that prevented commands with multiple numbers inside angle-brackets from working.

MOS APIs mos_fread and mos_fwrite now properly support 16-bit address values, addressing issues when trying to use those calls from plain Z80 code. Shadow registers are now also preserved when calling ffs_fread and ffs_fwrite.

As of MOS 2.2, attempting to call an "unknown" MOS API would be trapped (rather than potentially causing a crash) - this would return a "not implemented" status code (23) in the HL register. This release now also returns that value in the A register, to be more consistent with other APIs which set the A register to a status value.

Upgrading

To update MOS you are strongly recommended to use the agon-flash utility, the latest release of which (v1.7 at the time of writing) can be downloaded here.

What's Changed

• fix echo angle-brackets support by @stevesims in #90
• address some api issues from #66 by @stevesims in #98
• bump version to 2.3.2 by @stevesims in #99

Full Changelog: v2.3.1...v2.3.2

v3.0.0 Alpha 1

Preliminary 3.0.0 version series release.

This is an alpha release - it contains experimental features with commands and APIs that are subject to change. Whilst it should not crash your machine, the new features it contains should not be considered to be stable, and may differ in the final release version.

As with other releases, this can be run on any Agon Light compatible machine, including the Agon Light, Agon Light 2, Agon Console8 and Agon Origins Edition.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Producing new versions of the Agon firmware is a lot of work. Financially, I could really use the help.

What is new

This release is a snapshot of the current "system variables" branch work. This branch adds the concept of "system variables" to the MOS command line, along with a few other accompanying features that make use of them.

Most commands will now have their arguments "transformed" before they are executed, allowing system variables to be used with almost every command that MOS supports.

Variables have a name and a value. Variable names are matched without case-sensitivity, and you can use a * wildcard to match names.

New and Changed Commands

Echo <string-to-transform>

The Echo command was added to MOS in 2.3, but has now been changed to support showing variables. The following command, for example, can display the current time:

echo The time is <Sys$Time> now

Variables must be placed inside angle brackets, as in the example above. If you use a variable name that doesn't exist then an empty string will be inserted, but the command will otherwise succeed.

Set <variable-name> <value>

Whilst MOS already had a Set command, it has now been rewritten to use system variables. When you use this command a string-type system variable of the given name will either be set or changed to the given value.

There are a few special system variables that are "code" type variables that have been added. Examples of these are the Sys$Date, Sys$Time and Sys$Year variables which expose the real-time clock as system variables. Attempting to set either the time or date variable will adjust the real-time clock on the system. (At the time of writing an attempt to set Sys$Date will be ignored - this is expected to change before the full 3.0 MOS release.). The prior uses of the Set command for keyboard and console are both supported via "code" variables, so existing scripts that use those commands will continue to work.

It should be noted that the "value" part of this command is transformed when the variable is set, so for example Set TimeNow The time is <sys$time> will set the TimeNow variable to a string with the time when the command was executed. Thus if you then did an echo <timenow> you would see the time when the set command was run.

SetMacro <variable-name> <value>

This works in a similar manner to the set command but will set a "macro" style variable. With a macro, the variable value is not pre-transformed when the variable is set, but instead will get transformed when the variable is used. This means that SetMacro TimeNow The time is <sys$time> would mean that a command to echo <TimeNow> would show the time when the echo command is executed.

SetEval <variable-name> <expression>

This release contains a preliminary version of this command, as there is not yet a full expression engine. For now, when you use SetEval it will create (or replace) the named variable with the result of the expression. If the expression is a number, or refers to a number variable, then the resultant variable will be a "number" type variable of the value given. If the expression is a string (or a macro) then the new variable will be a "string" type variable copy of the named variable.

Show [<variable-name>]

This will show all currently set system variables. If you provide a name (which can include wildcards) then it will show all variables that match that name.

Unset <variable-name>

Unsets a system variable matching the given variable name. This will work for any variable set, except for code variables which cannot be unset. As with the show command, the variable name given can include wildcards, in which case all variables that match the given name pattern will be removed.

Do <command>

This command will just perform the given command. The command string however will be transformed before being executed, which allows you to use system variables to define which command would be executed.

Help [<command(s)> | all]

The Help command has received a bit of a revamp. It will now match commands that are abbreviated with a ., showing all commands that match. (Help . is equivalent to help all.) You can also now list several different commands to get help for, and it will show help for all matching commands.

Hotkey <arguments>

This command works as it did before, however hotkeys are now stored as system variables named in the format Hotkey$1. As hotkeys are now implemented using system variables, you can set a macro variable with an appropriate name for a hotkey. Additionally the argument substitution is now more sophisticated, allowing for more than the previous %s substitution. You can how use %0 to %9 to place the first to tenth "argument" in the current command buffer into the new hotkey-derived command. It will also support %*3 to mean "place every argument from argument 3 onwards".

If <expression> then <command> [else <command>]

Allows for conditional command execution.

As noted above in this release of MOS there is no expression evaluation engine. For now, the expression can either be a number, or the name of a variable. If the number is not zero, or the variable is a non-zero number or evaluates to a non-empty string then the expression is deemed to be "true", otherwise it is "false".

Obey [-v] <filename> [<arguments>]

Runs an Obey (script) file. The obey command works in a similar manner to exec but offers a few more features. Firstly running a script file with obey will set a system variable Obey$Dir to reflect the directory in which the obey file is located. Secondly lines in an Obey file will have argument substitution run on them before they are executed.

The -v flag makes the Obey file execute in "verbose" mode, printing each line out before it is executed.

As with exec, if a command fails in an obey file then the file execution will stop and the error from that command reported.

By convention, an Obey file should use the file extension .obey.

RunBin <filename> [<arguments>]

This command will load and run a binary file. It differs from performing a load followed by a run in that it will work out the appropriate memory address to load the file into. It does this by comparing the path to the given file to the current Moslet$Path system variable, so moslets will get loaded and run at the appropriate moslet memory location.

Command Aliases

If you set a system variable named in the format Alias$name then this will set a new command alias of the given name. Aliases support argument substitution. Any arguments beyond the last used argument will be automatically appended to the resultant command.

Special System Variables

Path variables, and filing system paths

Any system variable that ends with $Path is considered to be a "path variable". Such a variable can point to a directory path, or provide a list of directories. The list can be comma, space, or semi-colon separated. This defines a filing system path.

A path variable will be used for file path resolution. If you try to access example:file.txt then the system will attempt to look up the variable example$Path. If there is no example$Path variable set, or if the variable points to a non-existent path, then you will see a Could not find path error. If multiple paths are present in the variable, the path resolution system will try all the options to find the file.

Paths need to be properly set, so you should take care to include the final slash in a path, as if you don't include it the resultant path will not include it and you may get unexpected results.

The system has two path variables it sets up on boot for its own use. You are free to add whatever additional path variables you like.

All existing filing system commands and APIs that accept a file name (or path) will perform path resolution. They will also now support variable substitution too, which is is performed before path resolution. This means for example that programs using the LOAD and SAVE APIs automatically have support for both paths and system variables.

Moslet$Path

This variable defines the directory, or directories, in which moslets can be found. By default the system will set this variable to /mos/.

Run$Path

This variable defines the paths that will be searched through to run a command from disc. By default, this is a macro variable that the system sets to <Moslet$Path>, ./, /bin/, which means that it will match the same behaviour as the run behaviour present in MOS 2.

You are free to change these variables as you see fit, so you can add other directories for the system to search to run programs from.

Current$Dir

This variable reflects the currently selected directory. It's a read-only "code" variable, so you may use it to see what the current directory is, but can only change directory via the cd command.

(Support for setting this variable may be added in the future, which would be the ...

v2.3.1

2.3.1 release of the Agon Console8 MOS

This is the eighth official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Release notes

This is a "patch" release that addresses issues discovered with the 2.3.0 release.

Issues addressed include:

• system stack space has been increased to 2kb, which fixes an issue whereby the copy command could cause a system crash
• fixes an issue with stepping through the command history on the MOS CLI
• fix a bug that prevented the |!token in an echo command from being interpreted correctly

More information on the 2.3.0 release can be found here

What's Changed

• Fix issues discovered in 2.3.0 by @stevesims in #88
• Bump version to 2.3.1 by @stevesims in #89

Full Changelog: v2.3.0...v2.3.1

v2.3.0

2.3.0 release of the Agon Console8 MOS

This is the seventh official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Upgrading

To update MOS you are strongly recommended to use the agon-flash utility, the latest release of which (v1.7 at the time of writing) can be downloaded here.

Release notes

This release adds some internal changes to MOS with the aim of making it more stable and reliable, and laying some building blocks for the future. There's a few new commands too!

Much of the original groundwork for this release was done by @envenomator - many thanks! @tomm built on Jeroen's work, and also added in some new safety features, such as blanking memory on a fresh boot and adding in a RST 038h handler which will can provide a "crash" report when a program misbehaves. There's also a filing system bug fix from @lennart-benschop to ensure that files are written with correct dates.

This version adds three new star commands to MOS, and two new APIs:

• *mem will show a report on system memory usage and availability
• *echo provides an "echo" command in the style of the Echo command on RISC OS
• *printf provides a more unix-style "echo" command
• RST 38h prints a crash report, which works in conjunction with memory being reset to 0xFF on boot to guard against execution of uninitialised memory
• ffs_api_ftruncate has been implemented which allows files to be truncated

What's Changed

• All the Rainbow MOS 2.3.0 changes by @tomm in #72
• Wipe memory on boot (to 0xff), add rst 038h handler (to guard execution of uninitialized memory) by @tomm in #59
• Fixed setting of timestamp when writing file by @lennart-benschop in #69
• ffs_api_ftruncate implementation (OS call $85) by @tomm in #70
• chore(): add missing colon by @andymccall in #71
• Move CLI history into the heap by @stevesims in #83
• reproduce envenomator’s tidyings of mos.c by @stevesims in #84
• bump version to Console8 2.3.0 for release by @stevesims in #85

New Contributors

• @tomm made their first contribution in #72
• @lennart-benschop made their first contribution in #69
• @andymccall made their first contribution in #71

Full Changelog: v2.2.3...v2.3.0

v2.2.3

2.2.3 release of the Agon Console8 MOS

This is the sixth official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Release notes

This is a "patch" release that addresses issues with the 2.2.0 release.

This release contains a small change compared to the 2.2.2 patch to make this release more robust, addressing some issues observed when using some MOS commands inside BASIC.

The 2.2.0 release was a significant release with a lot of new features that aim to improve the usage of your Agon system. Full information on the 2.2.0 release can be found here

With many thanks to @HeathenUK , @lennart-benschop, @envenomator and @tomm for helping investigate the issues with the 2.2.0 release.

What's Changed

• Less malloc mem by @stevesims in #53

Full Changelog: v2.2.2...v2.2.3

v2.2.2

2.2.2 release of the Agon Console8 MOS

This is the fifth official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Release notes

This is a "patch" release that addresses some bugs discovered with the 2.2.0 release.

Issues address include:

• on boot, we now ensure the eZ80 flash memory is definitely not writeable
• fix a crashing bug with *dir <non-existant-directory>
• fixed a potential issue with how autoexec.txt is run at boot time
• fixed a memory allocation issue that prevented some commands working properly in ADL BASIC
• fixed issues with copying or renaming files when a destination directory of ., .. or / was used

The 2.2.0 release was a significant release with a lot of new features that aim to improve the usage of your Agon system. Full information on the 2.2.0 release can be found here

With many thanks to @HeathenUK , @lennart-benschop, @envenomator and @tomm for helping investigate these issues.

What's Changed

• Guard against flash accidentally being left writeable by @HeathenUK in #50
• fix dir for non-existent directory and other things by @stevesims in #51

New Contributors

• @HeathenUK made their first contribution in #50

Full Changelog: v2.2.1...v2.2.2

v2.2.1

2.2.1 release of the Agon Console8 MOS

This is the fourth official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Release notes

This is a "patch" release that addresses some bugs discovered with the 2.2.0 release.

The 2.2.0 release was a significant release with a lot of new features that aim to improve the usage of your Agon system. Full information on the 2.2.0 release can be found here

What's Changed

• fix issues around copy and dir by @stevesims in #46

Full Changelog: v2.2.0...v2.2.1

v2.2.0

2.2.0 release of the Agon Console8 MOS

This is the third official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Release notes

New features in the 2.2.0 release, added some 2.1.0, are as follows:

• Changes/fixes from @breakintoprogram (added to the Quark codebase since it's 1.04 release)
• "comment" command support from @sadbeast
• enhanced VDU command from @HeathenUK
• tab command completion from @HeathenUK
• hotkey support from @HeathenUK
• support for a bin directory from @HeathenUK
• wildcard support for file and directory functions from @HeathenUK (with some tweaks from @stevesims)
• directory listing enhancements from @tomm (with some tweaks by @HeathenUK and @stevesims)
• additional filing system MOS APIs from @tomm
• improved help command from @stevesims
• enhanced "edit line" API from @stevesims
• page up/down command history support from @stevesims
• various other improvements and fixes from @stevesims
• a sparkling of Rainbow magic from @tomm

With thanks to @HeathenUK for doing so much good work on this release, and @tomm for creating his experimental "rainbow" MOS.

Upgrading

To update MOS you are strongly recommended to use the agon-flash utility, the latest release of which (v1.6 at the time of writing) can be downloaded here.

What's Changed

• Rainbow neu by @stevesims in #43

Full Changelog: v2.1.0...v2.2.0

v2.1.0

2.1.0 release of the Agon Console8 MOS

This is the second official release of the Agon Console8 variant of MOS. It is suitable to be installed and run on any and all Agon Console8 and Agon Light machines, and is fully compatible with either versions 1.4 RC2 or later of the Agon Quark VDP or version 2.0.0 or later of the Agon Console8 VDP software.

This software is fully functionally compatible with Agon Quark MOS version 1.4 RC3, as of 11th November 2023. It has adopted a different numbering scheme from Agon Quark MOS, hence the numbering change. It is functionally the same as the Quark version except for the addition of support for the EXEC command (introduced in 2.0.0).

With thanks to @breakintoprogram for his fantastic work on this project, and all the other contributors to previous versions.

Supporting development

If you would like to support the development of the Agon Console8 and Agon Light firmware, you can sponsor me on GitHub or join my Patreon.

Please also consider supporting @breakintoprogram on Ko-Fi

Upgrading

To update MOS you are strongly recommended to use the agon-flash utility, the latest release of which (v1.6 at the time of writing) can be downloaded here.

What's Changed since 2.0.0

• Proposed I2C driver and MOS API implementation by @envenomator in breakintoprogram/agon-mos#115

Full Changelog: v2.0.0...v2.1.0

MOS.bin crc32 checksum: 3adbb188