Your Quiver
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 - z88dk
Download the z88dk release for your operating system using the link above in the quiver. These instructions will tailor to Windows users, but Linux users will be experienced enough to interpret the differences.
1) Download z88dk from the link above in the quiver.
2) Uncompress all files from z88dk into C:\z88dk
Step 2 - Download Hello World C Example
Download the Hello World C from the above resource above. You will need to extract these files in a folder. Within the folder should be the following files:
- build.bat
- HelloWorld.c
- NABU.c
- NABU.h
- patterns.h
- tms9918.c
- tms9918.h
Step 3 - View HelloWorld.c File
We can now open the main file (HelloWorld.c) to view the contents. Visual Studio Code is a sound 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 application. Specifically, the ORG address of $140D, and notice there is 3 NOP at the very beginning. The NABU BIOS loads the application at $1410, but it calls $140D the entry point. If the 3 NOPs and ORG are not at the beginning of the file, your program will not work.
Step 4 - Build Batch File
Look at the build.bat batch file included with the Hello World C example program. The batch file contains simple DOS commands that compile the Hello World C source code into a .nabu binary. You need to be in the z88dk command prompt environment when executing this batch file.
To view the batch file, right-click on the Hello world 1.bat file and select EDIT.
Step 5 - Compile Program
Compiling the HelloWorld.C file to a Nabu program is as easy. We will execute a shell command prompt for the z88dk environment, navigate into the folder containing the project, and run the build batch file.
1) Navigate to the z88dk folder
2) Double-click on the z88dk_prompt.bat file (for windows users). Or, Linux users can run the set_environment.sh file
3) In the new command shell, navigate to the Hello World C example files folder.
Example: cd \nabu\helloworld
4) Type BUILD to launch the build process.
Step 6 - 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, therefore, 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 C 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.
What's Next?
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.