Atarimax Maxflash USB Cartridge Programmer
Maxflash Cartridge Programmer and Cartridge Bus Interface with USB Interface
©2015 Steven J Tucker
Chapter 3: Using the Maxflash Studio Software
The Maxflash Studio software is based around the concept of creating 'Workbooks' that represent the final configuration you would like programmed into your multi-cart.
Workbooks are like any other file, such as a Microsoft Word document, they contain your data and are not directly linked to any physical cartridge.
You can create, edit and save your workbook designs without ever needing to connect your cartridge.
Once you have used the Maxflash Studio to create the layout you desire for your multi-cart, then and only then do you need to connect your cartridge for programming.
To get started quickly, a Demonstration Workbook is included with the Maxflash Studio application. I highly recommend you start by opening this workbook and familiarizing yourself with the editing controls described in the sections below.
The Maxflash Studio software also includes a number of utility functions for working with cartridges and images directly such as:
Tour of the Maxflash Studio Software
This scrolling control is the main active interface to adding, removing and manipulating the contents of your workbook.
The numbers on the left are 'slot numbers' for the content stored in your workbook.
These numbers represent the position those images will have on the on-screen menu of your final cartridge.
This control is disabled when no Workbook is open.
This control displays a view of what your on-screen Multi-Cart menu will look like when used on a real Atari Computer. This display is updated in response to your workbook changes and will scroll along with the Multi-Cart editing window.
This control is blank unless a workbook is open for editing.
The style editing controls allow you to change the text and appearance of the Multi-Cart Workbook on-screen menu.
These controls are disabled when no workbook is open.
This scrolling text window displays the current state of the software operation including cartridge connection and programming functions.
This control is always enabled.
This line near the bottom of the window displays the current workbook collection size, fill percentage and cartridge fit indicators.
These indicators are always enabled.
This line at the bottom of the window displays the current cartridge connection state, as well as the state of any current cartridge programming operation.
These indicators are always enabled.
These controls start and stop live programming of your cartridge based on the current workbook contents.
These controls are only enabled when the USB Programmer is connected to the system.
The Collection Status Bar, Status Monitor and Event Log
The Collection Status Bar shows how much space the current content and options used in your workbook will require on a real Maxflash Multi-Cart.
The actual number of bytes required by your current collection contents are displayed as text in the main body of this bar.
The background of this bar is a fullness indicator, where the blue portion of the bar will eventually grow to fill the entire status bar as you reach the limit of the smallest Maxflash cartridge your current collection will fit in.
The colored '1mbit' and '8mbit' indicators at the right side of this bar are simple on/off indicators that quickly tell if you the current collection will fit into a 1mbit or 8mbit Maxflash cartridge.
For example if both the 1mbit and 8mbit indicators are green, the current collection will fit into either a 1mbit or 8mbit flash cartridge. If the 1mbit indicator is grayed and the 8mbit indicator is green, the current collection will only fit in an 8mbit flash cartridge.
One additional note, the background of the blue 'fullness' indicator indicates how much space would be taken up in the smallest Maxflash cartridge the collection will currently fit in.
For example, if the green 1mbit and 8mbit indicators are lit and the bar is half way full, then the collection would take up approximately half of a 1mbit flash cartridge.
If only the 8mbit green indicator is lit and the bar is half way full, then the collection would take up approximately half of an 8mbit flash cartridge and would not fit into a 1mbit flash cartridge.
The Status Monitor bar at the bottom of the screen is where the state of the connection to your USB Programmer is displayed.
If your programmer is connected and visible to the Maxflash Studio software, the message 'PROGRAMMER CONNECTED' will be displayed in this bar, otherwise 'PROGRAMMER DISCONNECTED' will be seen.
The other indicators on this bar show the current state of hardware operations like programming or dumping a cartridge.
Should you need to make a bug report, please include the state of these indicators in your report.
The event log is a verbose display of status and error messages that occur while using the Maxflash Studio Software.
For example when adding content to your workbook, if it is recognized by the internal MD5 database, its name and signature will be displayed in this area.
While Synchronizing your cartridge the current progress will be displayed in this window.
Should you need to make a bug report, please include any error messages displayed in this window. You can get an easy to e-mail copy of the contents of this window by right-clicking anywhere in the status display and sending the contents to a text file.
Creating a New Workbook
By creating a new workbook, you are essentially creating a new blank Multi-Cart document.
To this document you will add content such as XEX/COM/EXE files, ROM images, ATR disk images and other customizations before previewing it or programming it to a Maxflash cartridge.
Having this information stored in a normal document means you never have to 'hot edit' your cartridge and your Workbook can be backed up to CD-ROM, e-mailed to friends, etc.
To create a new workbook, select 'File' from the drop down menu, and then 'New'.
Your new blank workbook is now loaded and you can begin editing your multi-cart document.
To save your workbook to disk, select 'File' and then 'Save As' and give your workbook a name such as 'My Workbook.mcw'.
Note: '.MCW' is the file extension for Maxflash Studio Workbooks.
Adding Atari 8-bit content to your Workbook
Adding content to your workbook is required if you want to have any items other than the menu itself on your cartridge.
The Maxflash Studio software supports importing these formats into a workbook:
Please note, images or files that already represent whole finished flash cartridges, such as Maxflash ISP Programming images (aka ATR Programming Images) or Maxflash BIN Cartridge images can be written directly to a cartridge using the 'Tools' menu and do not need to be imported into a workbook.
In creating the Maxflash Studio software I also created a hand groomed database of over 1200 Atari EXE Binary Load files from the Jellystone Park and Holmes software archives.
This database will automatically recognize the MD5 fingerprint nearly all the commonly found Atari EXE format games and set the title and load options automatically at the time of import.
Binary load EXE files are also the most compatible type of image to use in a multi-cart, so if you are looking for a particular game, always try to find it in EXE/COM/XEX format before resorting to a less cartridge friendly format like ATR.
Typically these may be found with .EXE, .XEX, or .COM extensions. For more information on where to find these types of files, refer to the 'Finding Content for your Maxflash Multi-Cart' chapter later in this documentation.
To add a EXE binary load image, ATR disk image or 8k ROM image to your workbook, right click in the Live Editing Window on the slot number you want to assign.
This will bring up the Load Content Context Menu shown on the right.
Select the 'Load from File(s)' for the type of content you would like to load which will bring up the file select dialog, then select your image to process it.
Another convenient way to add one or more images to your workbook is to simply drag those images from the Windows Explorer and drop them on the slot you want to fill in the Multi-Cart Editing Window.
If you open or drag and drop more than one image they will be added starting at the selected slot number, replacing any existing content without prompting.
As stated above, if your content is recognized by the current database, it will be automatically assigned a menu friendly name and its load options will be set to those in the compatibility database.
If your content is not in the current MD5 database, its filename will be used as the description, which you can change by double clicking on the name shown in the live editing window.
Exporting Content from your Workbook
The Maxflash Studio software also supports exporting content back out of a workbook.
To export an already loaded file from your workbook, right-click on the entry in the live editing window and select the 'Save to File' option appropriate for the content type in that slot.
Removing Content from your Workbook
To remove an entry currently in your Workbook and make that slot blank, right click on the desired slot and select the 'Clear Slot' menu option.
Alternately, you can press the DELETE key while a line in the live editing control is highlighted.
Pressing SHIFT+DELETE will delete the entry currently highlighted and move the entries below up by one line.
Both the ROM Image and its description will be removed from your workbook.
Setting the Menu Name and other Load Options for an entry
Once you have successfully loaded content into your workbook, you can change its on-screen name and configure its load options.
Every game in your workbook has a completely independent set of load options, allowing you to use any combination of load options for any combination of games in a single workbook, without restriction.
To change the on-screen menu display name, right-click on the entry in the live editing window and select 'Edit Menu Title and Settings' from the context menu. You can also access these settings by simply double-clicking on any entry in the live editing window.
Note: The screen display on the Atari 8-bit computer is limited to 40 characters per line, with a few reserved for the display of the menu entry number. You will be able to see exactly how your menu title will appear by looking at it in the Live Menu Preview window after editing.
The options available will depend on the type of content loaded in the slot you are editing.
After editing the options for the slot in question, press Save to apply your settings or Cancel to discard them.
This control is enabled for all image types.
This text control will allow you to edit the name used for this entry in the on-screen menu of your cartridge.
The maximum length for this entry is 40 character, but remember a few are reserved for display of the on-screen menu item numbers, so be sure to check how your title looks in the live menu preview after editing.
This control is enabled for EXE Binary Load images and 8k ROM Images.
These check boxes allow you to have the on-screen menu install a 'translator' OS on 64k XL/XE computers before loading and running the content in that slot.
For example, many older games like Alley Cat require a 'translator' disk to run on the XL/XE computers. Enabling the 'install Atari 800 OS' checkbox for an entry is the equivalent of enabling an 'instant translator disk' before loading and running the program in that slot.
In this way programs that normally only run on an Atari 400/800 computer, or an XL computer with an OS upgrade can be made to run without any special intervention.
The second option in this set allows you to load a 'translator' copy of the standard XL/XE OS into RAM before running the content in that slot.
This option is for advanced users who may have an XL/XE computer with a heavily modified OS in ROM. This forces the XL/XE computer to be running the standard XL/XE OS at the time a game is loaded, possibly avoiding any conflicts with the special ROM OS installed.
Please note that these options are not enabled for ATR disk images because a custom, patched Atari 800 compatible OS is automatically enabled for all disk images.
These controls are enabled only for Binary Load files.
Atari Binary Load Files (aka EXE/XEX/COM files) can be difficult to load because they were often originally designed to be loaded with whatever specific boot loader, DOS or mini-DOS the person who created them was using at the time. Some of these files have truly absurd loading requirements that no single loader can meet without being able to move around in the Atari memory space.
Anyone used to trying to load these files using a real Atari computer may remember spending many hours trying to figure out what particular DOS or pirate boot loader was required to get a file to run correctly, or at all.
With the Maxflash Studio software I have attempted to solve this problem by making the EXE loader completely relocatable anywhere in memory. In addition to this flexibility, the loader itself can re-locate its own memory usage to anywhere in page zero, making it one of the most flexible and capable EXE program loaders available for the Atari 8-bit computers.
In order to make the Maxflash Studio software even easier to use I have hand created a signature database of over 1200 Atari EXE games. This database is included with the Maxflash Studio software and if the game you are importing into your workbook is recognized, all the options required to make it load and run correctly will be automatically set without any intervention on your part. Even the title will be set to a short, menu friendly name, regardless of whatever the original filename was.
This automatic recognition database makes creating a multi-cart from EXE/COM/XEX files an extremely fast and fun experience, but there are still plenty of files out there the Maxflash Studio may not recognize and for those you may need to manually adjust the boot loader memory options.
The most commonly used and compatible memory locations for the boot loader are 0x0700, 0x0600 and 0x0100.
The most commonly used and compatible unpacker page zero locations are 0x30, 0x00, 0xF0 and 0xE0.
If you are not an experienced Atari 8-bit user and find configuration of these options confusing or obtuse I highly recommend you visit the Atarimax Flash Cartridge Discussion Forum and ask the other Maxflash Studio users there to recommend some load options that will work best with your file. Chances are someone there already knows what options will work perfectly with your file.
These controls are only enabled for Binary Load files.
In addition to differing memory usage, many EXE files make assumptions about what the state of the Atari 8-bit computer will be when they are run.
Enabling the 'Perform warmstart before passing control to RUN vector' option will cause the EXE loader to perform a 'soft reset' of the Atari computer OS just before running but after loading the program in question.
This should really only be enabled for games that will not load otherwise, as it can actually interfere with the loading of some titles.
These options are enabled only for ATR Disk Images.
While your flash cartridge is not a disk drive, using special OS patches and loading software it can simulate a disk drive for many programs that use the 'legal' Atari OS disk read and write calls.
Checking the 'Enable BASIC' option will force the internal Atari BASIC on XL/XE series computers to ON before booting the virtual disk.
While some disk boot games and utilities require BASIC, most do not. Games that do not require BASIC may crash, fail to load or display the message 'REMOVE CARTRIDGE' with this option enabled. Only enable this option if you are sure the game in question requires BASIC.
Checking the 'Disable non-maskable interrupts during cartridge access' will cause the virtual disk loader to temporarily disable interrupts while accessing data from the cartridge. This should only be enabled for games that absolutely require it and is typically indicated by a game that loads fine, but crashes later when trying to access the 'disk'.
Many disk based games have multiple disks. The Maxflash Studio software supports automatic creation of disk sets for games that use up to four disks.
When you select a disk image entry from the on-screen menu, the on-screen menu software automatically constructs a 'disk set' of four disks from the selection and the next three disks listed on the menu.
When running your game, press SHIFT+CTRL+# to switch to another disk in the set while the Atari is running.
For example, if entry #10 on the menu is 'Conan Disk 1' and entry #11 is 'Conan Disk 2', you would select entry #10 to run the game, then press SHIFT+CTRL+2 on the Atari keyboard to 'insert' disk #2 when prompted to do so by the game software.
In addition to multiple disk sides, the software also supports bypassing the ROM disk patch to allow software running on the Atari to access a real disk. This can allow you to load and save games to a real read/write disk while keeping the faster ROM disk in memory.
To bypass the installed ROM disk handler, hold down the SELECT+OPTION keys for the duration of the desired disk access. Access to the ROM disk will be automatically restored when you release the SELECT+OPTION key combination.
If you would like to completely unlink the ROM disk patch, press START+SELECT+OPTION during any disk access. The ROM disk handler will be removed from memory until you restart the Atari computer.
For example if you wanted to boot a DOS disk from the cartridge for instant DOS access, but wanted to just turn off the ROM disk afterward, you could just hold START+SELECT+OPTION while using any option on the DOS menu to remove the ROM disk patch from memory.
Once you have set the menu title and load options for your content and verified it is working, you can add your item to the built in recognition database.
Adding your item to the database means that the title and options you have set for this file will be automatically pre-set if you ever import that item into a workbook again.
To add your item to the database, right click on it in the Live Editing window and select the 'Add/Update Signature Database' option from the context menu.
Moving content around in your Workbook
To swap two slots in your workbook, just grab the slot ID number shown in the left column, for example 001, and while holding down the left mouse button, drop it on the slot ID number you wish to exchange it with.
While dragging a small arrow will appear to assist you in selecting the correct place to drop the content.
To insert a blank line in your workbook, press SHIFT+INSERT and all the entries will be moved down by one slot.
Sorting the entries in your Workbook
The editing controls also support sorting and compacting the entries of your workbook.
To compact your workbook and move all the entries to the top of the workbook, select 'Compact Workbook' from the Edit menu at the top of the screen.
To compact your workbook and sort the entries in alphabetical order, select the 'Compact and Sort Workbook' option from the Edit menu at the top of the screen.
Customizing the look of your Multi-Cart menu
The look of your Multi-Cart menu can be extensively customized.
The 8-bit computer displays text on the screen using a soft font called a 'Character Set'.
The Multi-Cart Studio software includes a selection of these character sets and will let you preview them live before having to make any changes to your real multi-cart.
By default in a new workbook, the standard Atari 8-bit character set is used, which is very readable, even on small televisions.
To change the on-screen menu font, click on the 'Listing Font' button on the main Multi-Cart Studio interface.
This will bring up the Character Set Preview and Selection window shown here.
This is a interactive window that will display the complete character set and allow you get a magnified look at any of the characters by just hovering your mouse pointer over it.
To select a new character set, just use the drop-down menu at the bottom of the dialog to select any of the pre-installed character sets.
As you select a new set, the character set preview will automatically update to show you the full contents of this character set.
If you like your selection, press 'Save' to add it to your workbook, or 'Cancel' to do nothing.
Once you have added the character set to your workbook, the Live Menu Preview on the right side will update and display your menu in the new character set, exactly how it will appear on the real Atari 8-bit Computer!
The Maxflash Studio comes with a number of character sets, but if you would like to add your own Character Sets, just deposit those files into the 'Character Sets' directory in the Maxflash Studio installation folder.
The header (top) and footer (bottom) lines of your multi-cart on screen menu will by default display a title and instructions on how to use the menu.
You can change the text of these lines to anything you desire by pressing the 'Header Text' or 'Footer Text' buttons no the main Multi-Cart Studio interface.
These changes will be reflected immediately in the Live Menu Preview.
The header and footer of the on-screen menu display a color gradient. To change the color of this gradient use the color assignment buttons in the editing controls area.
Using any of these controls will bring up the on-screen GTIA color picker. To select your color just move your mouse over the square you want and click it.
Please note that for the top and bottom lines, the color represents the start or end color of the gradient, respectively.
For menu entries, the selection changes the background color.
Setting the Global Options for your Workbook
Every EXE, ROM or ATR file in your workbook has its own set of individual load settings, as explained above.
However, each workbook also has a set of 'Global' options that configure how the on-screen menu will behave.
To access the global setting for your workbook, select 'Edit' from the top menu, then 'Workbook Options'.
Enabling the 'Change Background Colors while working' option will cause the on-screen menu to stuff the contents of the data it is moving around into the GTIA background color register while working. This debugging option can be useful to show visually, for example, if a program is loading data from the ROM disk.
Enabling the 'Enable colors, sounds and animations in the on-screen menu' option will cause the on-screen menu to use colors and sounds. This option is ON by default. If disabled the menu will be a simple blue screen with white text and no sounds will be generated.
Enabling the 'Reverse sense of cartridge bypass' option will cause the software programmed into your final cartridge to do nothing unless OPTION is held during power up. Normally the Maxflash On-Screen Menu software will not load if OPTION is pressed, allowing even a programmed cartridge to be easily erased and re-programmed in-system.
Enabling the 'Run item #1 on menu without prompting' option will cause your final cartridge to automatically load and run the item in slot #1 without ever displaying the on-screen menu. This option is extremely useful for creating cartridges that are not multi-carts, just single purpose auto-start cartridges that look, feel and load just like a standard ROM cartridge.
Enabling the 'Turn ANTIC off while loading' option will cause the on-screen menu software to disable ANTIC completely before attempting to load any content. This is only recommended for debugging, as many games do not properly initialize ANTIC and will display a black screen if ANTIC is turned off when they are loaded.
Enabling the 'Decrease delay between items when moving up/down menu' will cause the delay between moving up and down the menu to be less when up or down is held on the joystick of keyboard, resulting in faster menu navigation for those with quick reflexes.
Remember to Save Changes to your Workbook
After making any changes to your workbook it is very important that you save your workbook to your hard disk.
Synchronizing will save the contents of your workbook to cartridge, but unless you save your workbook to disk, you will lose your ability to make incremental changes to the current cartridge configuration and will have to build your workbook over again the next time you start the Multi-Cart Studio software.