Agon Light C Development

How to write code for the Agon Light (and Console8) using C instead of BASIC, under Linux. It might work with WSL2 in Windows, and it might work on a Mac.

By the end of this you’ll end up with a fairly standard Linux C programming environment with a Makefile and all the usual trimmings.

This mostly just combines the instructions from the AgDev github repo and some useful links. If you know where to look for this information it’s obvious and easy. If you try to find it using just Google, you’ll get lost. Just like how you got lost with the outdated documentation Olimex provide when you bought their version of the board and wondered if your firmware was outdated or not.

Step 1 – Install the Compiler

First we need the actual compiler. This is known as the CE C/C++ Toolchain and is actually indended for the TI-84 Plus calculator and some other calculators. They all use the eZ80 CPU, just like the Agon. It gets referred to as “CE Dev”.

The compiler toolchain can be downloaded from this link. All I did was download the Linux tar.gz file and uncompress it. You don’t need to put it anywhere special, it doesn’t get “installed”, I just put it inside my home directory.

Don’t forget to edit your shell to set the PATH variable correctly.

Step 2 – Install the Agon Compiler Patches

The next thing to do is adapt the toolchain so it can create code for the Agon Light. On the AgDev GitHub Repo is a very easy to follow readme that explains what to do. This is known as “AgDev”.

All you do is clone the repo to your computer, the copy the contents of the “AgDev” folder right over the top of the compiler toolchain. If you end up with a folder inside the compiler toolchain’s folder called “AgDev”, you’ve done it wrong. Move everything up one directory.

Step 3 – Profit! (or maybe create a template)

If you want an easier life, go to my github repo and clone that. It does all the stuff below for you.

The way this works is quite clever. Go into the AgExamples folder and there’s an example called “hello_world”.

This is an excellent template folder to use for your own projects. It gives you all that is needed.

Try it out, type “make”. It should work.

Have a look in the Makefile, it’s suspiciously empty – all the important parts are included from another Makefile elsewhere.

The Makefile is clever enough to compile anything in the “src” directory that is C, C++ or assembly source. You don’t need it hack it or make lists of source files to be compiled.

If you know how, you can also freely mix C and assembly. Read the CE Dev compiler toolchain documentation, it explains a lot of its inner workings.

You will also find an “invaders” demo, it uses C++ and mostly works but I think it’s a bit outdated compared to the Agon’s current firmware so some parts don’t work correctly. I wouldn’t write C++, stick to C.

Step 4 – The Emulator

There is an excellent emulator available, it works best in Linux. Grab it from the fab-agon-emulator GitHub repo.

It’s written in Rust, you’ll need to work out how to install the Rust development system for your Linux distro. If parts of it fail to compile, you need to install Rust properly.

The emulator has a fake SD card that presents itself as a folder. Copy your compiled binary into there, you can then boot the emulator and load your code.

On a high DPI display you might need to set the scaling to something like 200% or the screen will be tiny.

Where to go next

The Agon’s VDP is programmed using printf. If you look at the Agon’s VDP documentation it’s almost identical to the BBC Micro’s VDU commands. The Agon Light documentation wiki is a place to go if you have a plain Agon Light running MOS.

However, if you own a Console8 or have installed the Console8 firmware on your Agon Light, you’ll find the Console8 documentation more relevant. It also consistently spells “VDP” correctly 😉

The compiler toolchain is a “proper” LLVM compiler toolchain, so modern code editors that work with the likes of GCC and so on will work with this, including understanding error messages and compiler errors.

I use NeoVim, but you could probably use VS Code or anything else.