File Menu

The file menu is used to start new emulated calculators from ROM files or to send files to the currently running calculator.

The New Calculator... menu option can be used to open a ROM file and start up a new calculator. Each calculator runs in it's own MDI window and is (currently) completely isolated from all of the other calculators.

The Send File... menu option can be used to send files to the current emulated calculator. Note that the rules for sending files to the emulated calculator are the same as for running a real calculator - it must be switched on, and should be at the homescreen (83/83+) or in the Receive menu (82).

Debug Menu

This is where you can get access to the various simple debugging tools and options.

Using the Windows menu you can open a number of different windows showing information about the currently running calculator. See the relevant section below on what each window does and can be used for.

Under Load you can choose to run a script (see the scripts section) or load a debugging information file. The debugging information file (which can be output from Brass natively) contains information on modules, labels, breakpoints and variables.

When Run is ticked, the emulated calculator runs. Untick this menu option to pause the emulation. Note that if the calculator encounters a breakpoint and breaking on breakpoints is enabled, the calculator will freeze.

You can use the Step menu item to manually step one instruction at a time. If you hit a breakpoint, you can use this item to step over it.

The Reset item resets the emulated calculator.

When ticked, Break On Breakpoints pauses the emulated calculator when a breakpoint is hit. Use the Step menu item to step over it.

You can use Clear All Breakpoints to clear all the current breakpoints.

Options Menu

This menu can be used to set the options for the debugger.

The Customise Keys menu opens up the simple key binding editor. You have a list of calculator buttons (for example, [on]) under which it lists the PC keys that apply to that key (you can have multiple PC keys bound to a single calculator button). Right click a calculator button name to add a new binding or remove all of the existing ones. When you choose to add a new one, the interface 'freezes' until you press a key. This key is bound to the selected calculator button. Do note that the two calculator buttons 'matrx' and 'apps' are, in fact, the same thing.

The Video menu can be used to change the appearance of the emulated calculator's LCD. Set LCD Colours has options for changing the bright/dark colours used to display the LCD, and a Reset button to reset them to the LCD-ish default colours. The other options on the Video menu are to control the way the 96x64 pixel calculator display is scaled up to display on your screen - from unscaled, through LCD-pixel effect 'Zoom' filters to the 'Smooth' filters.

LCD Window

This window is always visible. It displays the current calculator screen. Not a lot to say about it, except that you can stretch it larger by dragging one of the corners. Right-click on the display to open a menu with options to Copy to Clipboard (which copies the current screen to the clipboard) or Save (which saves a screenshot in one of a variety of formats).

Memory Window

This viewer displays the current 64KB Z80 address space in groups of 16-byte rows. The column on the left shows the start address for each row. You can click on a cell to select it - the address is displayed in the bottom-right hand corner. You can type an address (in hexadecimal) into the box in the bottom right (pressing Enter jumps to it).

The button on the left pops open a menu listing all the exported labels from the debugging information file, grouped into modules. Clicking on a label jumps to it.

Clicking the button marked ASCII switches to the ASCII view - clicking it switches back to Values view.

You can add breakpoints from this editor - just right click a cell and select Add Breakpoint.

Registers Window

Not a lot to describe here - just a simple viewer window

Variables Window

(Not implemented)

Breakpoints Window

This window lists the currently active breakpoints. When a breakpoint is hit, it is selected and the font describing it is emboldened (if the window is not already open, it is opened automatically).

Right-clicking a breakpoint gives you options: Delete, which removes a breakpoint, and Jump To, which jumps to the memory address of the breakpoint in the memory viewer window.

Scripts

Scripts can be used to control an emulated calculator - for example, to reset, load, and run a particular program you are working on. Script files are just plain text. The semicolon character (;) can be used for comments.

Here are the available commands you can use in a script file.

Command Description
key-down key [pause] Press a calculator key. If a value follows it, run the calculator for that many cycles after pressing the key.
key-up key [pause] Performs the same action as key-down but releases the key instead.
key-press key [pause] Presses a key, runs for pause cycles, releases the key, runs for pause cycles. If you don't specify a value for pause, it defaults to 1000000.
run cycles Runs the calculator for a particular number of CPU cycles.
send-file filename Sends a file to the emulated calculator.
reset-calc Resets the emulated calculator.
breakpoints-on Enables breaking on breakpoints.
breakpoints-off Disables breaking on breakpoints.

Here's an example script:

reset-calc            ; Reset the calculator
run 6000000           ; Run for about a second to warm up
key-press on 6000000  ; Switch on
send-file ion.8xg     ; Send Ion
key-press prgm
key-press enter
key-press enter
run 6000000           ; Wait for it to install
send-file program.8xp ; Send the program
key-press prgm
key-press enter
key-press enter
run 6000000
breakpoints-on        ; Only enable these at the last minute
key-press enter

You can use command/batch-file style environment variables inside the script files (use the %variable% syntax).

You can load a script file on the command-line using -s filename.