Check the BASIC Engine NG page for information on the retired "BASIC Engine NG" bare-metal H3 platform, and the "classic" BASIC Engine page for information on the legacy ESP8266-based BASIC Engine platform.

What is the BASIC Engine RX?

The BASIC Engine RX is a firmware for very low-cost single-board computers with great 2D color graphics and sound capabilities similar to early to mid-1990s computers and video game consoles. It can be used on widely available and Orange Pi single-board computers (as well as most other devices built around an Allwinner H3 or H2+ chip) and runs from an SD card.

The RX platform has a ton of new and improved features compared to both the BASIC Engine NG and the classic BASIC Engine. To make it easier to spot the differences I have marked them in green and blue, respectively.

What can it do?

Screenshots

ng screen boot
Figure 1. Boot screen
ng screen shmup
Figure 2. Shmup demo
ng screen helpja
Figure 3. Online help in Japanese
ng screen brot
Figure 4. Mandelbrot set explorer

Features

Hardware support

The BASIC Engine RX makes use of most of the features built into the H3 and H2+ chips and boards:

  • all four CPU cores are used (three for Engine BASIC, one for the Linux support system)

  • up to 2GB of RAM, or however much your board has

  • HDMI, DVI and composite video output

  • 16-bit digital sound at 48 kHz through analog stereo and over HDMI

  • full compatibility with all MicroSD cards (no, that’s not a given…​)

  • all USB keyboards, mice, most game pads, mass storage devices and hubs that you want to hook up should work

  • control of all GPIO pins as well as SPI and I2C controllers available on the expansion connector

  • wired networking (Ethernet) (WiFi is in development)

  • hardware-accelerated video encoding

(Note that not all H3-based boards have connectors for all interfaces. If you are adventurous and your soldering skills are up to snuff you may be able to add them yourself, though…​)

Software

The BASIC interpreter "Engine BASIC" allows you to use the BASIC Engine as a standalone computer and write programs in BASIC and some other programming languages. It gives you easy access to the hardware’s capabilities and has a lot of nifty features.

Engine BASIC is not based on any existing system. It runs on the "bare metal". That means that it is not constrained by an operating system that controls what you and your program are and are not allowed to do, and it certainly won’t impose any unnecessary restrictions on you. Engine BASIC is for beginners, and therefore tries to make it hard for you to shoot yourself in the foot. But if you insist, it will not stand in your way.

Another benefit of its "bare-metal" architecture is that your program is the only thing that matters. There are no things going on in the background that may cause delays, jankiness or instabilities. If your program doesn’t work exactly as desired every single time, you did something wrong. Or I did. But it will never be because a scheduled update is installed in the background while you are trying to get stuff done.

While you and Engine BASIC are enjoying yourselves, there is still an adult in the room. One of the CPU cores on your BASIC Engine is dedicated to a Linux system that takes care of the less exciting but still essential bits. It will never interfere with what you and Engine BASIC are doing, but when asked it will provide you with keyboard and controller input, file system and network access. It can also record what you are doing in a video file on the SD card, so you can post it for others to enjoy. Or attach it to a bug report.

Linux has second-to-none hardware support and can handle virtually all game controllers, joysticks, keyboards, mice, wireless networking devices, USB microphones and similar things you may want to hook up to the USB ports or the expansion connector on your board, and it also makes its extensive set of powerful command-line utilities available to be used from Engine BASIC with the SHELL command.

On first start you will be presented with a menu in which you will have to select which board you are using. The system will then repartition the SD card so it can be used for BASIC programs and data. Once that initial setup is done, the BASIC Engine is able to boot from power-on to the BASIC prompt in about eight to nine seconds.

Graphics and sound

Graphics and sound are the most important features in any home computer and game console. Here’s what the BASIC Engine has to offer:

  • True color text and graphics at 4:3 and widescreen resolutions from 160x200 up to 1920x1200 pixels

  • video modes are scaled up to a fixed output resolution to get the best possible image on any TV or computer monitors

  • Software sprites (up to 32 sprites sized up to 32x32 pixels).

  • Scrollable tiled background graphics engine with up to four layers.

  • Wavetable synthesizer and PLAY command that renders music in MML format.

  • Loading and saving of most image file formats to and from video memory, including PNG and JPG

  • Insanely great custom text fonts specifically made for the BASIC Engine by Damián Vila

  • Ability to record video and audio output without performance impact directly to SD card; if you connect a USB microphone before starting the recording you can add your commentary right then and there.

Special BASIC language features

Engine BASIC is old-school. Lines have numbers. GOTO 12*32^whatever is a valid command. (Seriously, it is.)

But when you have programmed for more than a certain amount of time (an hour for some, ten years for others) it will happen to you that you look at a program and don’t understand what it does. Even though you wrote it yourself. That’s the point at which you will begin to appreciate some of these not completely traditional features of Engine BASIC:

  • Structured programming constructs (DO/LOOP, WHILE/WEND, IF/THEN/ELSE/ENDIF blocks).

  • Labels and named procedures with local variables.

  • Numbers are double-precision floating point.

  • String and numeric list types (particularly useful for game programming).

  • Escape codes for PRINT, similar to the control characters in Commodore BASIC.

  • Event handlers (sprite collision, end-of-music, errors, game controller input).

Development features

Programming is about telling a machine what to do. But you need to do the telling, and you need to stay on top of what you told it. These features help you with that:

  • A "screen editor" similar to Commodore BASIC’s allows you to manipulate on-screen code and commands directly, while also permitting scrolling within the program in memory. Whatever is written on the screen, wherever it is located, you can just move the cursor there, change it, and press Enter, and it will be executed, or saved to memory.

  • Syntax highlighting and automatic indentation in LIST command. It is inconceivable to me how anybody, including myself, could ever get anything done before syntax highlighting.

  • Loading of programs with or without line numbers. Engine BASIC programs have line numbers, but if you don’t want to have anything to do with them, you can write your program without. Engine BASIC will just make them up when loading it, and remove them again when saving it back.

  • HELP command provides a built-in reference for all elements of the BASIC language. I use it all the time, even though I wrote most of it myself.

  • A number of classic UTF-8 text editors are included; the default editor is JOE, the editor I use. It’s the best editor. That’s why I use it. If it weren’t the best, I wouldn’t use it. qed. If you, however, have problems with elemental logic there are various other options included, such as mg, nano, uemacs and vim.

Internationalization

Engine BASIC speaks your language. It is available in English, German, French, Spanish and Japanese, with all system messages and help texts translated. National keyboards layouts for all supported languages are available.

Unicode and UTF-8 are fully supported by Engine BASIC. The built-in fonts support various alphabetic scripts as well as Japanese kana. Kanji fonts are loaded as required. A basic Japanese input method is available.

BASIC and system extensions

Engine BASIC has a ton of features out of the box, but if you’re like me you will always think: "But what if it could do…​?".

If you’re also like me, you are a professional software developer and know that feature creep is the black plague of software engineering. To resolve this dilemma, Engine BASIC provides a module framework.

It is possible to extend the Engine BASIC system with custom modules programmed in C, assembler or (with external tools) C++ and other compiled languages that are loaded at run time, giving you endless possibilities to augment its functionality: new BASIC commands, graphical capabilities, device drivers, utility programs, new input and output methods, ports of programs from other platforms etc.

An extensive API is provided for extension developers, consisting of standard library and Engine BASIC-specific functions. An on-board C compiler makes it possible to develop extensions (or any other programs) on the BASIC Engine itself.

Such modules (and Engine BASIC itself) can be debugged from the Linux support system using an on-board debugger via the serial console or an SSH connection to the board.

The modules directory in the demos repository provides examples showing you how to use the API. It also shows how to cross-compile modules on a different computer for projects that require a well-optimizing compiler for maximum performance.

The Lua language and the SAM speech synthesizer that were built into the firmware on the classic BASIC Engine platform are now provided as modules.

Other features

  • Z-code interpreter for playing interactive fiction games. It’s just mandatory.

  • Customizable color scheme, start-up screen mode and font.

  • A switchable video filter gives a choice between crisp integral scaling and filtered (but full-screen) output.

  • An automated test suite adapted from Bywater BASIC makes sure that the BASIC core always works as intended.

How to install it

You can download nightly built SD card images that are ready to use and contain the firmware, all support files and demos from the git_builds directory for H3 RX.

Once you have unpacked the SD card image and written it to an SD card ("Balena Etcher" and "dd" have been successfully used to do so, but any other tool for writing SD card images will do) you can place it in the SD card slot of a supported H3 or H2+ board (and most unsupported ones), and the device will be ready to use.

On first boot you will be presented with a menu that allows you to choose which specific board you are using. Select the correct entry with the cursor keys and press enter.

(If you cannot find your specific model you can select a different board with a similar feature set. This is not guaranteed to work, but the likelihood that it will is quite high.)

How to use it

Introduction to BASIC Programming

If you have never programmed a computer in BASIC or any other programming language, you may want to start with the Introduction to BASIC Programming.

Reference Manual

Consult the Engine BASIC RX Reference Manual to find out how to make the most of the capabilities of Engine BASIC.

Cheat Sheets

The Engine BASIC cheat sheets provide a handy reference for beginners:

Cheat sheet #1: Handling BASIC Programs
Cheat sheet #2: Flow Control

Demos

BASIC demo programs can be found in the Engine BASIC demos repository. Note that all of these demos are included on the nightly SD card image.

How to contribute

Source code

Compiling the firmware

The BASIC Engine RX firmware uses the buildroot system found at basicengine-buildroot, branch jh.

If you do not usually use your system for development, you may have to install a number of requirements first. See the buildroot manual for details. In addition, the help2man package is required.

Once the dependencies are installed, run make basicengine_h3_defconfig, then make. The buildroot build system will now download and compile a large number of components, including a full Linux system and two compiler toolchains. This might take a while.

When the build succeeds, you will find an SD card image (sdcard.img) in the output/images directory.

Contact

If you have any questions or suggestions related to the BASIC Engine, check the BASIC Engine Forum.