Isetta - Software manual
------------------------

3-5-2025
3-10-2025 update


You completed the soldering
---------------------------

When all components are soldered on Isetta, the resulting circuit will do almost nothing.
The only thing that it will do, is send a horizontal sync signal to the VGA monitor.
The VGA monitor will do nothing (because it also needs a vertical sync sync signal and
picture information). (You could check that horizontal sync signal with an oscilloscope, 
this should be 5 volt with short negative-going pulses, the repeat rate is 32 microseconds).

You can also check the operating voltage: Between F1 and F2 (near USB power input) should
be 5 volts (+- 5%). A few devices run on 3.3 volts: The serial flash U10, the micro-SD card, the
sound output register U49, and the WiFi interface. The pcb has a voltage regulator U52, that 
converts 5 V to 3.3 V.
All other devices run on 5 volts.


Connection
----------

Isetta must be connected to the Isetta programmer pcb, and the programmer pcb must be connected
to a Raspberry Pi (RPi). The actual connect should be done while both devices have no power.
When connecting, to Isetta and RPi, check if you don't have a mis-alignment by one pin. That
might destroy something once power is applied.


Files needed
------------


On the Raspberry Pi, you must put the following files (all in the same directory):
  - isetta_rpi        // A python3 program for the Raspberry pi.
  - ucodeYYMMDD       // Microcode for Isetta (no file extension)


Only the two mentioned files need to be on the RPi. All other files should
be on the micro-SD card.


Hardware test
-------------

Start the isetta_rpi with the following command on RPi (in a terminal window):
 (prompt) python3 isetta_rpi    // This supposes that python3 is on your RPi, it normally is.

You will get a menu. Choose option A (All tests). The RPi will now test the Isetta
hardware. You can always stop the RPi program with control-C.
( Communication between RPi and Isetta has a small chance of going wrong. Therefore, if the
test program gives an error, retry the test. If the error persists, always with the same 
message, it is a real error).
If a real error is found, switch power off and carefully check if you see problems on the
pcb, like a bad solder joint, pins shorted by a small amount of solder, missing parts or
parts with a wrong partnumber.

These tests will cover a lot of components (but not all), so if there are no errors there is
a good chance that your Isetta will work.


Programming the microcode
-------------------------

The microcode is organized in pages. There are 32 pages, numbered 0 - 31. (decimal).
At the moment, not all pages are used.

The programmer programs the pages in pairs. You instruct it to program an even-numbered page, 
and it will also program the following uneven page (without showing it).

Start the isetta_rpi with the following command on RPi (in a terminal window):
 (prompt) python3 isetta_rpi   


You will get a menu. Choose the programming option: P [enter]

You will now be asked to enter the filename of the microcode, enter: ucodeYYMMDD

After a short time, you get a prompt, and you should enter the (even) pagenumbers that you
want to program. (There is a small chance that an error will appear. Then simply try again).
Because of the non-optimal communication, it is advised to enter only a single page number at a time.

 (prompt) 0 [enter]     // program page 0 (will also program page 1)

During programming, sometimes an error occurs. The specific action will then be retried, indicated
by 'retry'. If the retry succeeds, you see 'retry ok'. (can also occur during Verify).
After each block of 256 locations, there is a message with that programmed location addresses.

After the page 0 (and 1) are programmed, you get the main menu again. It is strongly
advised to check if programming went well, so choose the Verify option: V [enter]  
Then enter the page you want to verify:
 (prompt) 0 [enter]     // verify page 0 (will also verify page 1)
At the end of the verify, you will see the error count.
If the verify gives errors, you have to repeat the programming for this page (The
 programming command will first erase the selected page).

If you get nothing but errors, there is probably a soldering problem in your programmer or in Isetta.


When programming page 0 has succeeded, continue with programming and verifying
page 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24

(The filename will not be asked again as long as you don't close the program.)


Check if Isetta will wake up
----------------------------

After successfully programming the microcode, we will start Isetta.

First, remove power from Isetta and RPi (for RPi, give shutdown command and wait
with removing power until the green LED no longer flashes). Then disconnect 
the programmer from Isetta.

Connect the I/O to Isetta: VGA screen, keyboard, mouse
(The mouse should have a scrollwheel, a mouse without scrollwheel doesn't work properly).

And insert a micro-SD card that has the required contents (At least it must have 
the file SYMISA.PAK in the root).

Now connect Isetta to the power (and perhaps it is needed to press the RESET button on Isetta). 

After a few seconds, the screen should show a desktop, with a cyan taskbar with startbutton at the bottom, and a few icons on the desktop. This is the start-up screen of the SymbOS operating system.

If you see that, CONGRATULATIONS ! Isetta is working !

(Of course, there still could be problems in I/O devices.)

Next to check, do you see the mouse pointer moving when you move the mouse ? Then the mouse is working.

Click on the start button and then on RUN. Use the keyboard to type something. Does it appear ? Then the keyboard is working. Click Cancel.


Some SymbOS examples
--------------------

1) Task manager
Double click the task manager icon. The task manager window will come up. By dragging the title bar, you
can drag it to any position. It shows CPU load and memory usage. Total memory will be around 384 kB.

2) Date and Time
Double click on the time (at the right side of the task bar). You can now set the time and the date
(click on Apply for both the time and date). The clock will run until you disconnect power from Isetta.
It will also keep running if you give a shutdown command (Screen and power LED switch OFF, restart
with the button at the front).

3) SymCommander
Double click the SymCommander icon. A big window, that covers the whole desktop, will appear. 
Make it smaller by clicking the middle button of the three that you see in the upper right top.
By dragging the black/white square at the lower right of the window, you can change the size.
There are now two sections where you can navigate the SD card.
(If you clicked once on the window (so that it has focus), you can use the scrollwheel of the mouse.)
A "*.exe" is an executable and can be started by double-clicking on it.

4) Picture viewer
Use the SymCommander to start the program "Symsee.exe". Use the third button from the left to
open a file selection window. Pictures are found in directories named graphics or pictures, and
have file extension SGX.
In the Options section you can start a slide show, that automatically selects a new picture
every 5 seconds (add 3 seconds for loading that picture...).
SymbOS supports two main graphics formats, 4-color and 16-color. Isetta supports both.


Sound check
-----------

Connect an amplifier with speaker to the sound output of Isetta (3.5 mm plug).
Or connect a speaker to the "SPKR" connections at the front side of Isetta.

On Isetta, use the SymCommander (or the RUN command) to start the "soundd.exe". That is an extension for SymbOS, called a "Deamon", to handle sound. It only has to be started once after a reset on Isetta.

Then start the program "soundt.exe". That is the sound test program.
 - Select a music file in the file select box, like Csong.spm or Msi.spm
 - In the file select box, click Open.
 - In the "Tester for sound deamon", click Load and then click Play.

Some games also have music or sound effects, like chucky (cegg.exe). Before you start such a game, be
sure that soundd.exe has been executed after system reset.

While SymbOS supports two sound systems, PSG(AY-3-8910) and OPL4, Isetta has only the AY-3-8910.



Games
-----

Chess.exe     The most classy game of all
Gamelife.exe  Conway's game of life
Longcat.exe   Puzzle game
Lymings.exe   Save the lemmings (has music)
Mineswep.exe  MineSweeper
Pacman.exe    Pacman
Sokoban.exe   Help the worker to push the boxes to the destination positions
              (You might first set Puzzles/Classic)
Cegg.exe      Collect eggs, but avoid the angry chickens (has sound effects)
Sol.exe       Solitaire
Sudoku.exe    Sudoku



Utilities
---------

Symcalc.exe    Spreadsheet
Calc.exe       Calculator (simple/scientific)
Progcalc.exe   Programmer's calculator (supports Hex, Binary, Octal)
Notepad.exe    Simple text editor
Wordpad.exe    Text editor
Symon.exe      Memory monitor, shows a map of memory use


On the website SymbOS.org you can find more applications. You can download them and add them
to your SD card.

The End
-------










