1. General
Emu42 is based on the sources of Emu48 and is an emulator for the Hewlett Packard Pioneer serie calculators HP10B, HP14B, HP17B, HP17BII, HP20S, HP21S, HP22S, HP32S, HP32SII, HP27S and HP42S and for the Clamshell calculators HP19BII and HP28S hardware. These calculators are based on the 1LR2 Lewis, the 1LR3 Sacajawea or on the 1LU7 Bert chip.
2. Acknowledgements
I want to thank Raymond Del Tondo who convinced me to begin with a HP42S emulator and for his HP42S ROM entry point list. A big thank also to Cyrille de Brebisson for his technical assistance, without him the emulator would only be a "Proof of concept". Jean-François Garnier spent a lot of knowledge and material on the HP17BII and HP28S calculator. Warren Furlow's V41 emulator spent some basic parts of the HP42S User Code import/export handling. Lode Vandevenne spent the PNG image decoder. Also thanks to Sébastien Carlier for his Emu48 v1.0, without him this emulator would never have been created. A big thank to Erik Ehrling and Michael Faulhaber for their beta testing and suggestions. And finally I want to thank all the unnamed authors for publishing material about these calculators.
3. ROM Images
You need ROM images. The necessary ROM images are copyrighted by Hewlett Packard and I have no license to distribute them. Please don't ask me, I will not send you mine.
ROM images are valid in a packed (even address lower nibble, odd address higher nibble) or unpacked (one nibble per byte with even address first) form. They can be validated with the LEWISCRC.EXE command line utility. LEWISCRC.EXE is part of the Emu42 installation package or binary distribution or can be downloaded separately here. To do that, start a Command Prompt while running Windows, and type:
Lewiscrc <image-file>
where <image-file> is the ROM image you want to test. As result you will get a report of the Checksum/CRC check.
4. Installation
To install Emu42, unzip the emulator and the required emulator skins into an empty directory or use the Emu42 installer package. Finally copy your ROM images into this directory and adjust the ROM image name to the name used in the corresponding KML script. When you first run Emu42, it will detect the directory in which you installed it, and will write the configuration to the registry at HKCU\Software\Emu42.
5. How to Start
When Emu42 is installed and you have put the valid ROM image(s) into your Emu42 installation directory, you can start Emu42. You'll see a "Choose Your KML Script" box.
KML (Keyboard Mapping Language) scripts define the visual aspects of Emu42, the behaviour of the buttons, of the keyboard, ... It's a great way to customize your copy of Emu42.
Check in this dialog that the path in the "Emu42 Directory" text area points to the directory in which you installed the Emu42 KML files. Click the refresh button ("V") after modifying the directory path manually to update the list box or use the ("...") button to start a directory browser.
Choose a KML script in the list box for your calculator ROM you put into Emu42's directory.
Available scripts from the author at the moment are:
- Christoph's Real HP-10B
- Christoph's Real HP-14B
- Christoph's Real HP-17B
- Christoph's Real HP-17BII
- Christoph's Real HP-19BII
- Christoph's Real HP-20S
- Christoph's Real HP-21S
- Christoph's Real HP-22S
- Christoph's Real HP-27S
- Christoph's Real HP-28S
- Christoph's Real HP-32S
- Christoph's Real HP-32SII
- Christoph's Real HP-42S
If you are interested in writing new scripts, get the KML 2.0 documentation from the authors Emu48 page.
Having selected a script, press OK to start the emulator. In most cases, when Emu42 crash after pressing the OK button, you are using an invalid ROM image. While it's running, you can use the "View/Change KML Script..." command to change the visual aspect of Emu42.
6. Command Line
The command line syntax is "Emu42 [file]". The parameter sets the filename of the emulation state file independent from the "LastDocument" setting, normally reponsible for opening the last used state file. The argument is optional.
7. Virtual Keyboard
There are two ways to use the virtual keyboard on the emulated calculator:
The easiest way to use the emulated calculator is by using the mouse. The KML script defines buttons with an area where mouse clicks take effect. The active area is indicated by changing the cursor from an arrow to a hand cursor. Pressing the left mouse button over an active area will press the virtual button. When the mouse cursor leaves the virtual key area with still the left mouse button pressed, the virtual button is automatically released. The visual aspect of a pressed or released virtual button is defined in the KML script. In some cases you need to press more than one key on the emulator. For these cases press the virtual key with the right mouse button. When you release the mouse button or leave the area of the virtual key, the key is still held. To release all held virtual buttons, just use the left mouse button again. A single release of a hold virtual key isn't possible.
Another convenient way is using the PC keyboard. The KML script language supports a large variety of commands to implement this feature. So keyboard usage mostly depends on your used KML script and not on the emulator. Because of this it's impossible to say what's happen when you press a key on the PC keyboard. Some Windows specific accelerator keys like F10 cannot be overloaded by the KML script. For further details read the KML 2.0 documentation mentioned before please.
8. File Menu
8.1 New...
Creates a new emulation session. You're asked for a KML script where you can select the calculator type and skin to emulate.
8.2 Open...
Opens a previously saved emulation session. The emulation continues at the same position where the session was aborted. Loading emulation sessions made with a different ROM revision may destroy the memory content or may cause other unpredictable results.
8.3 Save
Saves the current session with the actual name.
8.4 Save As...
Saves the current session with a new name. You're also get this dialog when you Exit a new session without a state file name.
8.5 Close
Closes the current session without closing the emulator.
8.6 Settings
This calls the Settings dialog. This dialog has four sections: General, Disassembler, Sound and Infrared Printer.
8.6.1 General section
- Authentic Calculator Speed
When this option is checked, the emulation speed will be similar to the real calculator, on the Lewis chip depending on the RATE control register content.
- Show Title
When this option is checked, the window title bar is visible.
- Show Menu
When this option is checked, the menu bar is enabled. If unchecked, the menu is accessible as context menu in the client area outside the calculator button definitions.
- Always On Top
When this option is checked, the emulator window will always be the topmost one.
- Activation Follows Mouse
This option enables a X-Mouse style windows activation. When the mouse is moved over the emulator window, the emulator is getting the focus and popping up into foreground.
- Single Instance
When this option is checked, only one instance of the emulator can be started. If another running instance is detected, the detected instance is set into foreground as active window and get a request to change his state file to the given one by the current instance. Then the current instance is terminated.
- Automatically Save Files
When this option is checked, the current state file will automatically saved when you change to another state file, but not when you close the emulator program.
- Automatically Save Files On Exit
When this option is checked, the current state file will be saved automatically when the emulator program is closed.
- Show Load Object Warning
When this option is checked, you'll get a warning message box when you try to load an object with the Load Object... menu command. If this option is unchecked, the warning will be skipped.
- Always Show KML Compilation Result
When this option is checked, you see the results of the KML (Keyboard Mapping Language) interpreter at every KML script load.
8.6.2 Disassembler section
Choosing the assembler syntax:
- HP Mnemonics
This is the standard syntax used by HP.
- Class Mnemonics
Class (Clarke assembler) was written by Lutz Vieweg in 1991, at a time when HP had not published their own development tools. The syntax is very similar to the AG and STAR mnemonics used at this time. Especially published assembler programs written for the HP28S use the similar AG syntax.
8.6.3 Sound section
A new implementation of the sound engine made ROM patches for sound output obsolete. The new sound engine emulates the behaviour of the beeper output ports and only work in connection with a sound card. Using the legacy PC speaker mode isn't possible any more. The old beeper method with a ROM patch has been removed, so you have to remove the ROM beep patches from your KML scripts. Actually the program informs you when detecting ROM beep patches by opening the "KML Script Compilation Result" dialog reporting an error.
For the sound generation the calculator must know his own CPU strobe frequency. On the real calculator the speed depends on various settings like component tolerances, actual temperature, humidity and other variables. The actual speed is measured by the calculator firmware at a cold- or at a warmstart and stored in the =CSPEED variable. The content of this calculator variable has direct influence on the resulting frequency and duration. On the emulator the CPU strobe frequency is set by the registry key HKCU\Software\Emu42\Emulator\LewisCycles. The content of this variable multiplied by 16384 is the CPU strobe frequency in Hz used by the emulator. Because older versions of the emulator were not able to measure the CPU strobe frequency properly or the content of the LewisCycles has been changed since the last measurement, the =CSPEED variable of this session file may contain a wrong frequency value. You easily may discover this by measuring the actual duration of a 10s beep. A deviance less than 1s is ok, otherwise you should perform a warmstart of the calculator in this session file. Alternatively you may execute a Reset Calculator. This recalls the measuring routine and save the result in the speed variable. Both restart variants purge the stack content!
- Volume
The output volume can be set with the Volume slider relative to the Windows Master Volume control.
- Device
By default the sound device is set to "Standard Audio", but you can also manually choose the output device. When you change the Standard Audio device in the Operating System settings dialog, the internal device numbering may change, and so the manually selected audio device.
8.6.4 Infrared Printer
The emulator has the ability to print data to a HP82240A/B printer simulation. The data transfer to the printer simulator is done over UDP. In this section you can the define the IPv4 address and the port the printer simulator is listening. A suitable HP82240B printer simulation can be found here.
8.7 Exit
Quit emulation. The default actions at finishing are defined in the Settings dialog. If the current session is "Untitled" you are asked for a session file name using the Save As... dialog. If you quit the emulator without a given filename, you're asked for choosing a KML script at next startup.
9. Edit Menu
9.1 Load Object...
This is only valid for the HP28S, HP32S, HP32SII and the HP42S emulation.
- HP28S
You can load HP28S binary objects to stack level 1. Therefore the object must begin with "HPHP28-S". If the binary header isn't present, the object is loaded as string. Dropping HP objects over the emulator window will also load objects. Be sure that the emulator isn't busy before doing this.
- HP32S and HP32SII
You can load HP32S or HP32SII User Code programs directly at bottom of the calculators program memory. These programs should begin with a label and end with a RTN instruction. Other program configurations may cause unpredictable results at loading. The file to load must begin with a header, in the case of a HP32S object with "RAW31" and in the case of a HP32SII object with "RAW32", both created by Save Object.... If the object and the calculator share label names, loading is aborted with an error showing the labels used in the calculator and the one used in the object file.
When you now load the User Code into memory be sure that the last program in memory has a RTN instruction. If not, both programs, the last in memory and the loaded one, will be merged.
- HP42S
You can load HP42S User Code programs directly into top of the calculator memory. The file must be in a special RAW file created by Save Object... in the HP42S emulation of Emu42 or by Put User Code... of Warren Furlow's V41 emulator. Please remember that the HP42S command set is only compatible to the HP41C and HP41CV non synthetic command set. Some of the HP41CX or plug in module commands are unknown in the HP42S. Non HP42S suitable files can't be edited with the internal editor, you'll get a "Machine Reset" when you try to modify the illegal commands. These RAW files have no special header, so it's very difficult to distinguish them from other files. Make sure that you only use RAW files containing HP41/42 user code programs else your calculator memory maybe get corrupted.
When you load the User Code into memory make sure that the last program in memory has an END instruction. If not, both programs will be merged. The easiest way to append an end instruction at the last program in memory is executing GTO .. on the calculator.
9.2 Save Object...
This is only valid for the HP28S, HP32S, HP32SII and the HP42S emulation.
- HP28S
Saves the current object on stack level 1 as a HP28S binary object to disk.
- HP32S and HP32SII
You get a selection box with all User Code programs located in memory leading by an initial LBL and ending with a RTN User Code instruction. All other used labels between the initial label and the RTN are shown in brackets. LBL "0" is a special label to mark a program at top of memory which has no leading label. Select one or more of the programs to export.
The User Code programs of the HP32S and HP32SII are not compatible as they use different keycodes for the same function. So you cannot save a HP32S program and load it into a HP32SII emulation or vice versa.
- HP42S
You get a selection box with all User Code programs located in memory. Global labels between the first global label and the END instruction of a User Code program are not viewed. This avoids having code parts more than once in the export file. Select one or more of the programs to export. It's recommended to use the file extension RAW for the exported files on the PC. This is the default extension of the V41 emulator. Remember please, having more than one User Code program in an export file is a Emu42 extension, V41 until Release 8E supports only one User Code program in each RAW file.
When you want to import User Code programs created by Emu42 into V41 you should consider that the HP42S has an extended command set. Unknown commands on the HP41 will be displayed as XROM xx,yy where xx and yy are command specific numbers. Beside this the HP42S has a zero byte after each number in his programs, the HP41 only between consecutive numbers. Unnecessary zero bytes are removed by the normal packing cycle in the HP41 so you don't have to take care about it.
9.3 Copy Screen
Copy the screen content in text and bitmap format to the clipboard. The text format on the graphic models work only with the regular font on the regular character positions. Graphic and the soft menu buttons cannot be shown in text mode. The actual used Latin-1 Supplement codepage don't support all text characters, at the position of such a character the MIDDLE DOT U+00B7 character is used in the clipboard text output instead.
9.4 Copy Stack
This menu item is enabled for all supported calculator models.
The decimal point of "Real Numbers" in the clipboard is equal to the calculator setting. This is important when you try to paste the numbers into a program using the locale settings of the host operating system.
Unsupported objects will be ignored. This prevents sending binary objects to the clipboard.
- HP28S
Copy a "Real Number", "Complex Number" or "String" object on stack level 1 to the clipboard.
- HP42S
Copy a "Real Number" or "Complex Number" object from the X-register to the clipboard.
- Others
Copy a "Real Number" object in the X- or result-register to the clipboard.
9.5 Paste Stack
This is only valid for the HP10B, HP20S, HP21S, HP22S, HP28S, HP32S, HP32SII and HP42S emulation.
To import "Real Numbers" from the clipboard, the decimal point character of the clipboard and calculator must not match any more. There's an auto detection for decoding the thousands separator and decimal point character. The thousands separator is removed at decoding. A real number is detected in the case of valid real number characters in the clipboard.
"Complex Numbers" must be in the form (a,b) when using the decimal point or in the form (a;b) when using the decimal comma. Using a thousands separator is not allowed in complex number strings because in decimal point mode, the comma is used as separator between real and imaginary part of the number. The Cartesian or algebraic form a+bi is not supported.
- HP10B, HP20S, HP21S and HP22S
If the clipboard text field content is representing a real number, paste the text field content of the clipboard to the display-register of the emulated calculator. Therefore no operator must be pending, otherwise the paste request is refused.
- HP28S
Paste the text field content of the clipboard to stack level 1 of the emulated calculator. If the clipboard content is representing a real number, the number will be saved as "Real Number" object. Is the content a complex number object, the number will be saved as "Complex Number" object, otherwise cases as "String" object.
- HP32S and HP32SII
If the clipboard text field content is representing a real number, paste the text field content of the clipboard to the X-register of the emulated calculator.
- HP42S
Paste the text field content of the clipboard to the X-register of the emulated calculator. If the clipboard content is representing a real number, the number will be saved as "Real Number" object. Is the content a complex number object, the number will be saved as "Complex Number" object, in all other cases as "String" object. The "String" object is limited up to 6 characters.
9.6 Reset Calculator
This emulates the Reset pin of the internal CPU.
9.7 Backup
9.7.1 Backup Save
This saves the current emulator status into a backup slot. If the backup slot already contains data, it will be overwritten.
9.7.2 Backup Restore
This restores a previous saved emulator status without request. If you changed the calculator model meanwhile, the emulator will switch back to the model used in the backup.
9.7.3 Backup Delete
This deletes the data in the backup slot.
10. View Menu
10.1 Change KML Script...
This allows you to change the skin of the current emulated calculator. In opposite to the New... command you see only scripts emulating the same calculator model.
11. Tools Menu
11.1 Disassembler...
This is a simple disassembler.
Enter the address to disassemble in hexadecimal into the "Address (HEX)" field and press <Return>. With the "Next Address" button the next opcode is disassembled. With the "Copy Data" button you can copy selected lines from the list box to the clipboard.
11.2 Debugger...
The assembler code debugger of the emulator. For more details refer to the extra documentation of the debugger please.
11.3 Macro
The keyboard macro recorder unit.
11.3.1 Macro Record...
Prompts a dialog to enter the macro file for the data to record. After accepting the confirm message, every key event is recorded into the macro file with it's time information.
11.3.2 Macro Play...
Prompts a dialog box to ask for the keyboard macro file to play. The replay starts immediately after opening the selected file.
11.3.3 Macro Stop
Stops recording or replaying a keyboard macro file.
11.3.4 Macro Settings...
Settings for the Macro Replay mode
- Real
Replay macro with the original recording speed.
- Manual
Replay macro with the speed set by the speed slider.
12. Help Menu
12.1 Help Topics
Show this document.
12.2 About Emu42...
Show the version, copyright and license message.
13. DDE Server
Emu42 has an integrated DDE server to transmit data from and to the HP stack. Because only the HP28S has a stack, all DDE transfers are ignored on the other calculators. You have the same restrictions like with the commands "Load object..." and "Save Object...", that a running program may corrupt memory. In difference you can choose the stack level for the transfer in the DDE item field. Take care to transmit data only after the acknowledge of the last DDE transaction.
Technical data:
| Servicename: | Emu42 |
| Topicname: | Stack |
| Item: | 1 (stack level) |
| Clipboardformat: | "CF_HPOBJ" (user defined) |
The DDE commands CONNECT, POKE and REQUEST are supported.
The structure of the clipboard format "CF_HPOBJ":
| 4 Byte (length of object, LSB first) | HP object (normal HP object) |
14. License
Emu42 - A HP10B/14B/17B/17BII/19BII/20S/21S/22S/27S/28S/32S/32SII/42S Emulator
Copyright (C) 2024 Christoph Gießelink
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.