Before you follow the tutorial below, there are a few items you will need for the adventure. These include specification documents, and a compiler.
NABU API Manual
The NABU API is a set of subroutines embeddeed in the downloadable operating system (DOS) that makes the hardware more accessible to programmers. Currently, we do not have a development environment configured to use the subroutines, but we're working on it. In the meantime, this document shares the list of available subroutines.
Step 1 - Download Files
Download the Hello World from the above resource links. You will need to extract these files in the same folder. Within the folder, should be the following files:
- Hello World 1.asm
- Hello World 1.bat
Step 2 - View ASM File
We can now open the assembly file (Hello World 1.asm) to view the contents. Visual Studio Code is a good editor for viewing/editing assembly source code files; others may prefer Notepad++. However, any text editor will do.
We do not need to make any changes to this file. However, you can scroll through to see the specifics that make this a NABU binary. Specifically, the ORG address of $140D, and notice there are 3 NOP at the very beginning. This is because the NABU BIOS loads the application at $1410, but it calls $140D as the entry point. If the 3 NOP's are not at the beginning of the file, those commands will be missed.
The port labels at the top of the file define the port addresses for the sound, video, keyboard, and communication hardware.
Step 3 - Batch File
Let us now look at the batch file included with the Hello World example program. The batch file contains simple DOS commands that compile the Hello World 1 assembly source code into a .nabu binary.
To view the batch file, right-click on the Hello world 1.bat file and select EDIT.
Step 4 - Compile Program
Compiling the Hello World 1.asm file to a nabu program is as easy as double-clicking on the batch file. Every time a change is made to the source code file, the binary needs to be recompiled by also double-clicking on the batch file.
Double-click the batch file and ensure there are no errors. You should now have a new file in the folder labelled 000001.nabu
Step 5 - Upload to NABU
Now comes the best part! We get to upload the file to the NABU PC using the NABU Internet Adapter. At this stage, we have assumed you have already successfully used the internet adapter to use the default NABU Network software on the NABU PC and, therefor, have a working RS422 to USB cable.
1) Load the NABU Internet Adapter application
2) View the Settings menu
3) Navigate to the SOURCE tab and select the checkbox next to Use Local Folder
4) Press the Select Segment Folder button and navigate to the folder working folder with the Hello World and the 000001.Nabu files.
5) Save the configuration and return to the main screen
6) Under the File menu, select the Clear PAK Cache option. This will clear any PAK files that have been cached because we will load our Hello World program instead of the NABU Network Main Menu.
7) Power on the NABU and see your program run!
What Have We Just Done?
The ROM in the NABU contains a small program that communicates with the NABU Network Adapter and requests a program called The Main Menu by its PAK identifier 000001.
As the ROM downloads the program, it begins writing it to the memory address $1410. Once the entire program has been downloaded, the ROM calls memory address $140D, and the program starts running. The difference between the loading address and execute address is 3 bytes, which is why we have 3 NOP at the start of the program.
What we are doing in this tutorial is replacing the main menu (000001) with our program. The ROM does not know that we did that, nor does it care. All the ROM does it transfer the program and CALL the memory location to execute it. Using this method, we can load any homebrew software onto the NABU PC.
We also have a C compiler working for the NABU, using z88dk. Because there are many libraries included with z88dk for game developers, this will be a great environment. We will add information and tutorial using the z88dk C compiler in the future.
In the meantime, we encourage people to create and share programs to continue growing the NABU community.