NutEm/PC — A Nut Firmware Interpreter Built On ooREXX/Win

Update 11/1/2023:

Blinky simulation, afore distributed as tokenized executable only (sourceless), is now part of the main program, licensed under the QPL 1.0.

Update 10/21/2023:

Import Voyager Programs – self-acting type in of program listings

Update 9/19/2023:

RAM-tv with extra branch node for HP15C, « Special » shows buffers of INTEG, SOLVE, and Im-part of complex stack

TOC:

1. A Brief Description
2. Prerequisites, Install and Run it
3. Connectivity
4. .CFG File in Detail
5. Controls of This Program
    – RAM tree-view
    – Import Voyager Programs
6. Emulator or Simulation?
    – Time Chip Simulation
    – Card Reader Simulation
    – IR Printer Module Simulation
    – External Thermal Printer Simulation
    – Wand Virtual Paper Keyboard
    – Software Defined Wand
7. Features, Constraints, Known Bugs
8. Manuals of The Role Models
9. The Fine Print

A Brief Description

Once upon a time Hewlett-Packard sold pocket calculators based on a proprietary "Nut" CPU. This CPU worked in famous HP-41C/CV/CX and the "Voyager" series (HP-10C, -11C, -12C, -15C, and -16C). With the time the firmware of these machines leaked out what resulted in emulators, simulations, virtual remakes. The firmware interpreter I publish herewith is a great grandchild of those, and in contrast to my feasibility study NutEm on mainframe it's now NutEm/PC with several enhancements worth to mention.

The HP41 series is extensible by many plug in ROMs and devices. ROMs which add more functions only, by firmware or software or both, will run directly in NutEm/PC. In contrast, devices with special hardware need to be simulated to work in a remake. NutEm/PC comes with five such devices, the Time Module, two versions of the HP-82143A Printer (a simple one for text only and an external also apt to plot graphics), the Card Reader, IR Printer Module aka "Blinky", and the Wand enabling a virtual paper keyboard and to scan barcodes, utilisable directly by the running HP41.

Beyond That

For me this hope turned true. In rather short time I was able to add simulations of
i) the HP 82242A Infrared Printer Module (to my knowledge the first simulation of it at all) and
ii) the HP 82104A Card Reader (CR). Like the role model the CR reads "magnetic cards" (files representing them) from HP-67 and -97 too, in addition several useful file types from LIF disk dumps (read only) and user code programs as RAW files (read/write) – but those written tagged for HP41 to avoid mishaps with other variants.
Meanwhile also the simulated wand works reasonable well and the service ROM shows TIME IC OK — all in all a pretty nice achievement me think.

My goal is not to be a better emulator than the well known but to have a toy that serves as a simple aid for testing. For some time now there exist other quite suitable simulations/emulators/virtual remakes of those HP calculators prolonging their time of use. Nonetheless I publish my NutEm/PC, perhaps someone else may find it convenient too to waste some time with it.

Prerequisites, Install and Run it

First things first:

□ As of today there exist two variants of portable ooRexx, one based on ooRexx 5.oo (not beta any more), and another running ooRexx 5.1.0 beta. How to setup NutEm/PC as a "portable app" on a memory stick is described in this post. Consequently following description is solely about the conventional installation.
□ After many (too many) looong years in beta state ooRexx 5.oo is published at last and I switched to it. Although I once migrated NutEm from VM/ESA to ooRexx V4.1.3 I do not maintain an adequate revision of NutEm/PC for it. Thus, to use youngest enhancements, you are forced to install latest ooRexx.

To run NutEm/PC you need:

• Windows,
• Open Object REXX V5.0.0 at minimum, see oorexx of "Open Object Rexx",
  (I was asked which addressing mode of ooRexx I'd recommend, 32- or 64-bit. Honestly I only may say sorry, I have no clue which one is less buggy.)
• ooDialog is now bundled with ooRexx 5.oo, so for this there is no extra supplement to install,
• optional a viewer like IrfanView to show backside images,
• if and only if you plan to run the Software Defined Wand, then IrfanView (version 4.62 or maybe newer) is indispensable.

To run any of the a. m. calculators you do need copies of its firmware (ROM). For your convenience I add following for a first try:

Voyagers:

11C and 16C (virtual remakes of 12C and 15C are available from HP in here)

HP41

CV version GFF, CX patched by J-F to enable display of lower case letters > e.

HP41 add-on

Time, 82143A and 82242A printer, Card Reader, Wand, PPC ROM, and HP-41 Advantage Advanced Solutions Pac.

More ROMs to find

for HP41

see here and there, and if still not enough more here;

for Voyagers

here and there, see also on this pen drive.

ROM file format etcetera

The ROMs enclosed with NutEm/PC are unchanged for HP41, but patched for Voyagers to fix a stack-lift bug in HP-11C and -16C. During start-up of NutEm/PC a pause mod is applied (non-permanently) to get – regardless the speed of your PC – a 1.2 seconds delay for PSE, MEM, and View Mant (by ClrPref). To achieve this the C=C-1 X in the delay loop is replaced by 1F0, an invalid opcode. Following an example for the HP11C, similar at different spots for the others.

original:                   patched:
0D11 046 C=0    X           0D11 046 C=0    X
0D12 21C PT=    2           0D12 21C PT=    2
0D13 210 LC     8           0D13 210 LC     8
0D14 266 C=C-1  X           0D14 1F0 ** loop patch **
0D15 3FB JNC    -01 0D14    0D15 3FB JNC    -01 0D14

Install it

Notes:
– Keep the organization of subdirectories, 'HTML' at least, otherwise you have plenty to trim in some .CFG files. If you move 'HTML' or its content you even have to modify the program or hit F1 is of little help.
– The software defined wand needs R/W access to the installation directory to write temporary files.

First Run and Subsequent Runs

NutEm/PC is a console application which displays some information, warnings and trace output on the console window only. In contrast, "real" errors will pop up in a message window in the middle of the screen. If not interested in information of minor importance, you may prepare one or several shortcut links which start NutEm/PC without console window.

Windows offers several ways to start NutEmPC.rx (but you did know that already):

• open a command window in the directory where you installed NutEm/PC and enter (without quotes) "nutempc" or "rexx nutempc.rx", it depends on your choice of suffixes at installation of ooREXX,
• start the windows explorer, navigate to the directory where you installed NutEm/PC and double-click NutEmPC.rx or right-click it and select open
  (alas drag-n-drop of a .CFG file to the REXX program does not work),
• single-click a shortcut link you prepared before.

NutEm/PC optionally takes one argument and/or one option. More tailoring is done within a .CFG file.

    [REXX] NutEmPC[.rx] [CFG-fileID] [ #KEY]

CFG-fileID

a file-ID or name of a .CFG file ('.CFG' will be appended if missing), default is 'NutEmPC'.

KEY

This option is obsolete in that it is now available interactively. I do not remove it to keep NutEm/PC backward compatible.
It is, separated by ' #' (blank and "Gartenzaun" = garden fence, croisillon) one single letter as designation of a key that will be "held down at ON time".
– Meaningful for Voyagers are one of ',./*-+'

• dot or comma to change the decimal separator,
• dash to get a reset,
• slash for a keyboard test,
• the rest for a single self-test or same repeated endless until interrupted.

– For HP41

• 'BA' (back arrow) induces a complete reset (MEMORY LOST).
• With a PANAME ROM plugged one of '.,AKMTV' are also operatively, see Appendice ON of its manual (or Appendix ON of its translation).

For subsequent runs you don't need to edit .CFG files unless you like to change something.

Connectivity

.CFG File in Detail

File-ID

Filename and -type at will, but if type is CFG then filename is sufficing as argument for NutEm/PC.

Content

The .CFG file may contain blank lines, comments, section headers, keywords, and assignments.

Blank lines (optional)

Blank lines are ignored.

Comments (optional)

a semicolon, ';' (w/o quotes), and all to the right of it in its line is ignored. It has no effect on subsequent lines.

Section headers

Section headers are set in square brackets. These are:

[MODEL]

This section is not optional. It must contain one and only one of the keywords
HP41
10C
11C
12C
15C or
16C to set the calculator model to emulate.

[RAM] (optional)

To simulate continuous memory, one single entry only: file-ID of RAM file, possible with path or location and path, file-type at will.
By omitting this section, either as a whole or its entry, the calculator will power-up with a virgin RAM which is named "## trial run ##.mem" if saved to disk.

[ROM]

This section is not optional. For Voyagers: a single ROM file-ID.
For HP41: list of ROM file-IDs, prefixed by page (hex) and primary/secondary tag and arbitrary "chip-ID" for same-time bank-switched ROMs. HP41 ROM files are copies of single 4k pages, either for primary bank (tag 0) or secondary bank (tag 1). In contrast, ROMs of Voyagers are in one file each. About the ROM file format see here. The "chip-ID" groups ROMs which are bank-switched together. An example:

[ROM]
;page p/s cID fID
 0    0       .\Coconut\hpcx0.MClst
 1    0       .\Coconut\hpcx1.MClst
 2    0       .\Coconut\hpcx2.MClst
 3    0   CX  .\Coconut\hpcx3.MClst
;4    0       .\Coconut\service.MClst
 5    0   CX  .\Coconut\hpcx5.MClst
 5    1   CX  .\Coconut\hpcx5sec.MClst	; bank 2
 6    0       .\Coconut\pr1e.MClst
 8    0   ADV .\Coconut\adv1.MClst
 9    0   ADV .\Coconut\adv2.MClst
 9    1   ADV .\Coconut\adv2sec.MClst	; bank 2
 A    0       .\Coconut\voranoge.MClst	; use only on a 41CX
 B    0       .\Coconut\rbx1b.MClst
 C    0       .\Coconut\ppc10.MClst
 D    0       .\Coconut\ppc20.MClst
 E    0       .\Coconut\crdr1g.MClst
 F    0       .\Coconut\zen.MClst

Example for a Voyager:

[ROM]
.\Voyagers\hp10c.MClst

[INI] (optional)

Few assignments in the format separator-name-separator-value, each on a new line. Separators may be any single character not present in name.
Recognized names and their possible values are:
DECSEP – . | , — decimal separator for 'Copy complete X-register', default is comma (Voyagers only, on HP41 flag 28 is relevant)
PSS – ((numeric value)) — seconds to show "splash screen" at start-up, default delay is 1.6 seconds what may be too long
RVSADR – 0 | 1 — enable/disable RAM-tv self-acting display refresh, default is 1 (enabled)
TITLE – ((headline)) — caption of calculator window
TYTRA – TRACE | FULLTRACE — get a firmware trace in a shell window, either w/o or with CPU registers included
Example:

[INI]
/title/NutEm/PC running 11C (CHS stack lift bug patched)
/tytra/TRACE		; Display commands on CRT
=decsep=.

[MNL] (optional)

Reference to manuals in system menu by assignments (format same as in section [INI]). If nothing is set the system menu will show a link to literature.hpcalc.org to lookup there the manual in question.
Recognized names (set one or none) and their possible values are:
ALLIN – ((subdir)) — will show one item in system menu, that opens a Windows explorer at 'subdir'. This option is handy if there are more formats than PDF to lookup.
SHOSOM – ((subdir)) — will show up to six items in system menu, which reference associated PDFs found in 'subdir' – associated by means of the first number in a PDF's filename, it must match the number in calculator's designation in section [MODEL].
Example:

[MNL]
/shosom/.\mnl

[PERIP] (reserved for future use)

List of additional peripherals (HP41 only). This section is "deprecated" as all peripherals are guessed self-acting by their ROMs when included. Despite this [PERIP] remains reserved for future use.

[BLKY] (requisite for "Blinky" only)

HP41 only (solely valid if no section [THPR] was specified before), not before [ROM] section. Few assignments to define where to find the IR printer simulation and how to connect it. Dedicated HP82240B printer simulation may be started automatically but will only be closed self-acting at session end if requested so with keyword qxp set to .true or 1.
The example ought to be obvious enough:

[BLKY]		; connectivity of IR printer module
/port/5025
/dip/127.0.0.1
/IrPrIPa/C:\PRGM\HP-Emulators\HP82240B	; IR Printer Installation Path
/qxp/1		; at shutdown also quit external printer if NutEm/PC started it

[THPR] (optional)

HP41 only (solely valid if no section [BLKY] was specified before).
Note: Presence of this section determines which printer simulation will be used, w/o the internal (text only) or with it the external simulation will be started. Both need the HP82143A printer ROM included in a. m. [ROM] section.
Few assignments to define where to find the thermal printer simulation and how to connect it. Dedicated HP82143A printer simulation (version 1.14 or newer) may be started automatically but will only be closed self-acting at session end if requested so with keyword qxp set to .true or 1.
The example ought to be obvious enough:

[THPR]
/port/5026
/dip/127.0.0.1
/IrPrIPa/C:\PRGM\HP-Emulators\HP82240B     ; IR Printer Installation Path
/inifile/port 5026  ; the only option to set which printer to simulate is an INI file
/qxp/1              ; at shutdown also Quit eXternal Printer if NutEm/PC started it

[WAND] (optional)

HP41 only. Where to find files defining the Virtual Wand Paper Keyboard (format same as in section [INI]). The "tool tip directory" is optional, filenames of tool tips are "hardwired". For the software defined wand the IrfanView executable is essential.
Example:

[WAND]
/dirtt/.\Coconut\qrg\
/xiv/C:\Program Files (x86)\IrfanView\i_view32.exe

Controls of this program

Buttons: Same as role model. Underscores in button's caption
         denote its acceleration key (see note 1).
Keys: F1        - show this help file
                  (if suffix HTM is affiliated with a browser),
      F2        - display About information,
      F10       - activate context menu,
      Ctrl+C    - copy display to clipboard,
      Ctrl+X    - copy X-register in full precision to clipboard,
      Ctrl+V    - use clipboard content as input (see note 2),
      Backspace = Back Arrow,
      Pause     = Enter,
      End       = R/S,
      Return    - hit selected button,
      Esc       - save RAM then quit the program,
Context Menu: shown by right mouse click not on buttons
      Copy      - takes display as is to the clipboard
      Paste     - use clipboard content to push short cuts
      Quit      - save RAM then end NutEm/PC
System Menu: Underscored letters indicate which key will launch an option
      Quit w/o saving RAM      - ends NutEm/PC keeping RAM of previous session
      Reset Nut cycles counter - reset CPU count to zero
      Sho RAM                  - display RAM as tree-view (see note 3)
      Show PRGM...             - list user program (see note 4)
      Get PRGM from clipboard  - import Voyager program (see note 5)
      Copy figure as displayed - copy display to clipboard
      Copy complete X-register - copy X-register in full precision to clipboard
      Paste from clipboard     - import clipboard content (note 2)
      Sho BS image...          - show reverse side of role model (note 6)
      1 - Mnl_1.PDF            }
      2 - Mnl_2.PDF            } manuals found in directory set in .CFG file,
      3 - Mnl_3.PDF            }
or -  Related Manuals...       - show directory as set in .CFG file,
or -  Manuals online...        - show https://literature.hpcalc.org
      More details...          - same as F1 (see note 7)
      About...                 - guess what...

Notes:

1. The buttons' caption change according to shift status and with it also acceleration keys. On HP41 shift and alpha is relevant, on Voyagers it is f-shift, g-shift, and user mode.
2. Pastes either a number to X-register, or in PRGM mode into program, or in Alpha mode (HP41 only) uppercased to alpha register (a ZEN ROM may disturb this process.) A number is interpreted to detect thousand's separators, comma, sign and exponent. What may not belong to the figure will be missed silently. This fuzzy logic is not perfect, so use with caution.
3. Mind the warning about the edit feature of RAM-tv.
4. This menu item is only available for Voyagers, to list HP41 programs use a printer of your choice.
5. This menu item is only available for Voyagers, to import HP41 programs use either CR or Wand.
6. This menu item requires suffix .GIF to be linked with a viewer (if none available a browser might do).
7. This menu item requires suffix .HTM to be linked with a browser.

Besides easy handling by keyboard and mouse the later offers two additional options:

• For the HP41 hit-n-hold is an important element of the man-machine-interface. For most keys (ON is one of the exceptions) keeping a key held down it first shows the function it will execute, and, if still held down for a moment, NULL will be displayed to indicate, you may release the key now with no further action than NULL disappearing.
  Voyager models offer hit-n-hold for few keys only to allow a prolonged readout, e. g. 'View Mantissa' (Clr Pref) or MEM (storage status), while the HP-15C provides even some rare cases of hold-until-Null.
   
• {ON+key} is a gesture for rarely used features like changing the decimal separator on Voyagers or reset HP41 to factory-set. This option is available if the simulated machine is off, if the Ctrl key is held down, with a right mouse click (if reversed 'the other right') to the calculator's button in question. (Paname ROM is respected.)

RAM-tv – show/edit RAM

Red neon alert — same warnings apply for "RAM tree view" as for RAMED of ZENROM:

«Make sure that you have first stored your programs and data onto magnetic cards or other massstorage media. Experimenting with Synthetics can corrupt programs/data held in memory.»
(End cit.)

I recommend, before using RAM tree view in R/W mode, to end and restart current session of NutEm/PC, so in case of mishap you may use menu point 'Quit w/o saving RAM' to recover the state before last restart. This works for both, the Voyagers and the HP41.

Core features explained with 41's RAM-tv

The display, grouped in seven sections and sorting registers in reverse order, was certainly influenced by fig. 3.7.1 'HP-41 Memory Configuration' shown in ZENROM Usr. Mnl., p. 36. While the sections (branches, "parents") are shown in bold the registers (leaf nodes, "children") are displayed in normal font and indented. They are prefixed by their address, on "First Page" also by the register's tag, what enables a fast find by simply typing its letter. The 56 bits of a register, or 14 nibbles, are grouped to seven bytes, byte #6 to the left, #0 to the right. Data registers also indicate the register number. Except on "First Page" empty registers stay hidden, consequently empty branches can not be expanded, e. g. Data after CLRG. While running the HP41 displayed registers are updated instantly when changed. Changing the 'curtain' (address of R0) or 'chain head' (address of permanent .END.) in register 'c' ("First Page", @00D) updates the affected branches (Data, PRGM, and/or Buffer).

Handling of RAM-tv is possible quite similarly by mouse and keyboard, while incremental search for items' beginnings is only possible by keyboard. Home, End, Page up, Page down, Arrow up and Arrow down do the expected. The effect of Arrow left and right depends what is highlighted when hit, primarily a selected branch will be expanded or collapsed. If a child is selected Arrow left jumps to its parent.

Left mouse clicks (single and double) select an item, if it is a branch it's expanded. Same time an afore expanded branch will be collapsed. To keep more than one branch open the same time press Ctrl while selecting it. The mouse wheel scrolls the display (if applicable). A right mouse click presents a context menu which allows to toggle 'Read Only' and 'Read/Write' mode, indicated in the window's caption.

In 'Read/Write' mode single registers content may be edited (but not the branch names). A register is "opened" by a single left mouse click on a selected leaf node or either with F2, F11, Enter (not Return), Insert, or 8. Edit (an enforced overtype mode) is possible by typing hex values only (0..9 and A..F) and pasting from clip board. End of edit is done by Return or Esc which nullifies all changes, taking the focus off the RAM-tv dialog window causes an end of edit like Return. Moving the caret (here: overtype mark) may be done by arrow keys (including same time Ctrl for next or previous word, Home, End, Next, Prior) or mouse (left button, single click). Marking nibbles or bytes for copy to clip board is done with the a. m. keys plus same time Shift) or hoovering the cursor while left mouse button is held down.

Since empty registers are not displayed (besides few exceptions) they are not at call for edit. Press Ctrl+Insert (same time, sorry) to enter the address of an empty register you'd like to modify. Entry of address is assisted but not too restrictive (to avoid maledictions), therefore invalid input is sorted out in a subsequent step showing error messages if necessary.

Peculiarities of Voyager's RAM-tv

Common to all Voyagers, and in contrast to the HP41, the content of the X register is only preserved within the CPU, hence not available for display in RAM-tv. To have a look save it in a register or use X<>Y.

Data registers get to the rhs affixed an 'R' followed by the register number or, if applicable, the "dotted" register number, while "named" registers, like stack registers and the TVM registers of the 12C, are tagged with their designation on the lhs (thereby enabling incremental search). Single exception is register "I" on the 15C – it is labelled with "Ri".

One more speciality of the 15C are matrices. Related registers are tagged with a lower case letter of the matrix designation followed by row and column number. Changing a matrix's dimension, e. g. from 2x3 to 3x2, updates the associated tags instantly.

The HP15C uses "buffers" or temporary scratch registers to operate INTEG, SOLVE, and the imaginary stack in complex mode. Non-zero buffer registers are shown under the branch node Special. (About the use of memory space see HP-15C Owner's Handbook, Appendix C, "Memory Allocation".)

Data registers of the 16C are only tagged in float mode. The integer modes permit word sizes which are stored unaligned with regard to the 14 nibbles = 1 register memory. Even though not impossible to show actual register numbers in any case I simply was too lazy to realign the words accordingly.

Notes:

1. In contrast to RAMED of ZENROM there is no insert mode when editing in PRGM area,
2. altering an HP41's X-, alpha-, and flag-registers does instantly refresh the calculator display by executing CLD (in fact by running CLDSP with corresponding consequences, mind the note in VASM listing: « RESETS CATALOGFLAG, SHIFT, DATAENTRY, AND MSGFLAG », that is why this automatism may be suppressed)
   – in contrast the display of no Voyager will be updated self-acting by RAM-tv,
3. RAM-tv is not brand-new but may still be buggy, in case of doubtful display hit Return (not Enter) to restart it.

Import Voyager Programs

A listings apt for import may look like this:

#! 12C under NutEm/PC
* Pi by Vieta
* HP12C program by Tony(NZ)
|...+....1....+....2....|
01-       2  2
02-   44  0  STO 0
03-   43 21  SQRT
04-44 10  0  STO / 0
05-       2  2
06-44 20  0  STO * 0
07-   43 34  X<=Y?
08-43,33 11  GTO 11
09-      40  +
10-43,33 03  GTO 03
11-   45  0  RCL 0

• All lines up to and including the scale are optional.
• The first line begins with a "shebang" so as to indicate by "12C" (in this example) the program's origin and/or target machine.
• Lines starting with "*" (asterisk) are ignored, by that comments may be inserted ad lib.
• The scale is ignored.
• The following program listing is the same as displayed with menu item Show PRGM... . Relevant for the import are only the key codes between the dash after the line numbers and the two blanks separating "comments", these are used to type in the program.

Notes:

• Red neon alert as for RAM-tv applies here too. Read it and act as adviced.
• While this import feature enables swap of emulators (two at present) it can not mangage the migration of routines between different Voyager models. Besides the shebang check there is no analysis, if a given file is de facto a program listing – it remains users' responsibility not to import arbitrary rubbish.
• It also remains users' responsibility to have enough free memory for the program to import, and to set the program pointer to the spot where to insert it. In case of mishap, stay calm, there is a menu option Quit w/o saving RAM as mentioned in Red neon alert, you remember?
• It is unwise to merge programs for models which use line numbers as GTO target.

Emulator or Simulation?

In contrast to the Voyager models, which are not extensible, the HP41 system offers many optional additions. While the "firmware interpreter" is virtually complete regarding the CPU, some of the simulated peripherals focus on the most important features. For example, the inbuilt 82143A may print text but no graphics. That is why I call this a simulation, it imitates only selected aspects of the real-world printer, not the entire printer.

NutEm/PC comes with several peripherals, completing the 'virtual machine', moving nothing but electrons (at times the operator too). Here some details:

Time Chip Simulation

My reasoning is, unlike on a real processor, when firmware commands are simulated they all take a different time span to execute due to their complexity and implementation, moreover NutEm/PC runs on a multitasking system with its typical uncertainties. Therefore it's quite impossible to have the (also simulated, not emulated) time chip in sync with the wall clock time. Consequently I run the virtual calculator with a virtual time base. For this I simply use the simulated Nut CPU, 64 command cycles (word time) take almost 1/100th second nominally – no matter how long this lasts. By that the very pernickety service ROM passes all tests and shows TIME IC OK after all. Neither test content nor addresses are stored within the time chip simulation, otherwise I could fake the tests at once by a direct jump to the wanted result. Record a trace log and check it.

Without service ROM, time and date of the host-PC are master, what makes CORRECT, SETAF, SETDATE and SETIME of time module pointless.

Card Reader Simulation

NutEm/PC simulates this by writing and reading card contents to/from PC files. If the data or program to write exceeds a card's track capacity of 16 registers, the simulation "inserts" self-acting extra empty cards. Tracks belonging to a data set or program are written to a single file. When reading such a "deck of cards" it is processed in one go.

"Cards" from the predecessors HP-67 and -97 are available from Tony Nixon's classic calculator emulator – scroll his site to Try it all out and the downloads thereafter, he offers the HP-97 as "stand-alone emulator". Those card files contain a single track only. Moreover they are concealed, but Tony was so kind and showed me i) how to decode it, and ii) all details about data on magnetic cards of HP67/97. For this I also "hide" my card's content and will not publish neither the source how I read Tony's HP67/97 cards nor how I treat mine. Sorry, but it's kind of a moral obligation with respect to Tony's kind assistance, without his help my CR simulation would still be incomplete.

Card Reader Simulation Extensions
As input for the CR there exists only what you saved afore and the Application PACs for HP-67/97 (scroll to Application PAC). Most HP41 software offered in the Internet is either within plug-in modules (ROM or MOD), or LIF-disk dumps, or RAW files (literally "raw", almost unspoilt program dumps), some bar code scans, or plain program listings. Thus I enabled the CR simulation to take also RAW files and LIF-disk dumps too. The various input formats are transformed to "virtual magnetic cards" then imported the same way as usual. This kind of RAW utilisation has the square advantage that it behaves in perfect compliance with GETP/GETSUB of XF, WNDLNK/WNDSUB of Wand, RSUB/MRG of CR, and READP/READSUB of MassMem. In contrast, I never got accustomed to those emulators throwing in ENDs here and there when reading RAW files, blithely disregarding decades of common usages.

In addition NutEm/PC may also read from LIF disk dumps the file types 'E040'x (41WALL), 'E050'x (41KEYS), 'E060'x (41STAT), 'E080'x (41PRGM), and 'E0D0'x (41DATA), without difficulty.

In contrast, there is a problem when reading RAW files, this option requires user's attention. — Why? – well, a sad story of ignorance and bliss, in short, there are emulators for HP41 and HP-42S which both use for the same task but now and again differing content, the same suffix and the same file format despite the existing chance to jeopardize an emulated calculator by reading RAW files from the wrong model. Sure, it's not lethal, but kind of nasty surprise if it happens to you. Therefore take precautions not to read RAW files originating from Emu42. There is no way (now and hardly in future although simplest to realise while writing the RAW) to prevent this misuse.

NutEm/PC offers the feature to save programs as RAW files. Proceed like saving a program to magnetic cards but change in the save file dialog file-type to *.RAW — or: choose *.RAW as PC file-type before you hit the [Insert empty card] button. Resulting RAW files are marked "provenience NutEm/PC" (in fact a single bit flipped) to make it obvious it contains a program from and for HP41. Reading such RAW files is done right away, while those untagged will query the user "Potentially unsafe input – deny or allow?" before processing (or not at will). Reading and writing RAW files is part of the CR simulation, therefore only at call when a CR module is "plugged" in the .CFG file.

An emulator may optionally bundle several programs in one RAW file. In contrast, by design the CR can process only a single program at once. That is why the CR simulation reads the first routine of a bundle and saves the remaining in a temporary file which could be read next. Due to the standard CR behaviour this makes it easy to keep actually required routines only.

IR Printer Module Simulation

I refuted this belief: NutEm/PC effectively simulates the operation of "Blinky" using the unidirectional interface of the HP82240B Printer Simulator. As described in the corresponding manuals, it prints text and graphic. Printing bar code is possible, theoretically, see this append in the HP41 forum. (The 82162A simulation prints bar code on the same virtual output device but much faster.)

Using the IR printer module reveals quite soon an important difference to both, the 82143A and 82162A printers. "Important" in respect to daily habits which end at a sudden. While the two other printers have a mode slider to set MAN–TRACE–NORM which i) shows at a quick glance the currently set print mode, and ii) allows even during a key sequence to change the mood and shift the slider to another mode – with the IR printer module this is not possible any longer. Before printing a program as compacted listing you have to enter XEQ "TRACE" first, even though, that is only needed if it wasn't already in trace mode.

To compensate for the missing slider as indicator, I display the status of the IR printer module between the topmost and next key row. The leftmost RE: stands for Red Eye what is in actual fact the IR protocol, but the abbreviation of "Blinky Status" could be misconceived. The rightmost value, prefixed by BB: is the "water level" of Blinky Buffer. The rest is quite obvious, otherwise... look elsewhere.

Notes:
– The function TESTP (Test Printer) returns BAD at once. Without detailed descriptions of the additional hardware within the IR printer module, it's effectively impossible to find out what exactly this function is about to test, I guess.
– Since I discovered how to simulate Blinky I kept its routines under cover, for no rational reason. Now I publish it, also for no reasonable cause.

External Thermal Printer Simulation

By reason of the unidirectional connection the simulation of the thermal printer status and its flags remains part of NutEm/PC. Consequently this applies also to the printer control panel with its main operating elements. A brief explanation (it's precisely the role model's functionality — well, it ain't my fault, it's the printer's firmware that works this way):

ON/OFF button:

a power cycle clears the printer's buffer. This only applies to the 82143A buffer, data that was already transferred to the external simulation is not affected.

Print button:

prints either the X-register of the HP41 or – if in Alpha mode – its Alpha register. Whereas, with the HP41 in PRGM mode, either PRX or PRA is inserted.

Advance button:

prints, if applicable, the buffer content right-justified and advances paper by one line, in PRGM mode inserts an ADV command.

Mode switches:

changes the printer mode as indicated. In contrast to the IR Printer Module flags 15 and 16 are not concerned.

Note: To use an 82143A its ROM must be included in .CFG file section [ROM], page 6. To connect it to the external simulation, also a valid [THPR] section is de rigueur. Otherwise the internal simulation is run (part of NutEm since the very beginning, the same in current NutEm/PC).

Wand Virtual Paper Keyboard

The Wand "Paper" Keyboard is a simple dialog window with eight buttons to the top – additional four buttons if the IR printer module is included – which give fast access to the functions I use most (assumedly, subject to change without notice). The larger area below shows a tree view with branch nodes (headers and subheading) in bold and leaf nodes non-emphasized, representing corresponding code mainly (see CAT 2 details below for an exception). By this means, to run a function not available on the calculator keyboard, there is no need any more to press XEQ-ALPHA-name of function up to seven letters-ALPHA, a simple "point&shoot" with a mouse click is sufficient now.

Tool Tips pop up Quick Reference Guide
This feature makes the virtual paper keyboard the information centre for oblivious users. When hovering the mouse pointer over a leaf node a balloon message will pop up presenting hints about the function in question. There are few exceptions for the HP41, e. g. for numbers and single characters, in contrast to the plug-in modules where currently only several selected are included: ADV Pac A, CARD RDR, EXT FCN 1C, EXT FCN 2D, PLOTTER, PPC ROM (largely), PRINTER (82143A), PRINTER 3B, RAMBOX 32, THRML 1A, TIME 1C, TIME 2C, WAND, X-I/O 1A, ZENROM.

Because tool tip data is stored in external files (external to the REXX source) it may be extended and/or personalised pretty easily.

Some Details
To avoid the need of a refresh button for CAT 1 entries, the global chain is analysed whenever that branch is expanded. Any changes of global alpha labels (new and/or removed) is immediately reflected by a simple collapse and expand of the "CAT 1" node.

To build the list of CAT 2 entries only the first FAT entry of each ROM is analysed. With it (and few more identifiers) the remaining function names are taken from a list. Example (see screen shot): -VORANOGE 3, my Voyager Random Number Generator Version 3 is (currently) not listed in the overall XROM file. Hence the entry for page 7 (where I placed it on trial) can't be expanded, thus it's not shown in bold, even though it's no executable function.

Few ROMs > 4 k do not have an extra CAT-2 entry for the second page. Then the virtual paper keyboard shows the corresponding ROM-ID in twin brackets, see PG D in the exmple, it's the 2nd 4 k of the PPCROM.

Besides direct executing functions the 'Wand Paper Keyboard' may also be used for general input. So why not throw in some numbers, conversion factors, mathematical constants, physical values. NutEm/PC actually lacks a user exit to customise this section. But, since I do not program for others, just for me, highly likely it will be missing forever and ever.

How is this awesome "Paper Keyboard" linked with the Wand?
Wand implies scanning bar codes. The bar codes of the virtual paper keyboard exist behind the scenes as tantamount strings of hex values. They may be shown with the wand function WNDTST or (more detailed) with the PPC ROM program BA.

Software Defined Wand

The only way to access the SDW is by a right mouse click on the a. m. Virtual Paper Keyboard (everywhere except the buttons). Indispensable prerequisites are, besides a mouse and IrfanView as a snapshot transformer, some barcodes of adequate quality.
What does adequate mean in this regard? Pixel pap fails, no doubt, but something like shown on the left might work, even so, due to a reduction in size and depending on your screen resolution, some distinct moiré interference for the narrow bars emerge. Likely it will take few unsuccessful attempts, thus this is the lower limit of adequate quality. Click on the graphic to see the exemplar in original size – which scans flawlessly – with a width of two pixels for the narrow black and white bars, and four for the wide bars. Alternatively you may also zoom in the display of this HTML, at 130% for instance I observe almost no failed attempts, if at all .

Make it work:

➊ Add (only once) three items in the .CFG file you gonna use: — i) in [ROM] section link the ROM file of an HP82153A Wand to a page above 7 (what will pop up the Wand Virtual Paper Keyboard at program start), — ii) insert a section [WAND] – see details here, — iii) define the full path of the IrfanView executable (that enables the start of the SDW with a right mouse click on the virtual paper keyboard).
Furthermore – it's essential – ensure R/W access to the directory that contains NutEm/PC. Otherwise IrfanView will fail writing crucial files.
➋ Show barcode to scan on the screen in horizontal orientation, then start NutEm/PC. Lines to scan must be displayed completely, when partially covered by some other window or clipped by the edge of the screen no successful scan is possible. To detect the end of a barcode line there must follow a white area of about three times the width of a wide bar.
➌ With a right-click on the virtual paper keyboard pop up the SDW dialog window, when it has the focus following scan options are available. Place the mouse pointer close to the first line to scan, either to the left of it and press E (lower case is fine), or to the right of it and press W. Do not press any key of the mouse, it would select the window under the mouse pointer, except you alternatively hit S so then to indicate diagonally opposite corners of a square "cutting through" the barcode in W/E direction not including a white border above or below it. Now the SDW will either display a hint what went wrong or else the captured data in hex. In the later case the data is forwarded to the simulated HP41 which will act accordingly.

Notes:

• When scanning from PDFs do not use the "fist" cursor, some remnants of it in the screen copy thwart the use of E or W as scan start, only option S will work.
• This SDW is not perfect. It runs with average settings to cope with "snow" and similar noise. To keep it simple there are no options to screw up those settings, neither temporary nor in the .CFG file. It remains users' task to find or prepare a scan template of adequate quality.

Features, Constraints, Known Bugs

Features worth to mention:

General

• every setup saves its dialog windows positions for use in next session
• Hit-n-hold – an important element of the user interface, functional when using the mouse to operate the calculator
  (if you prefer operation by key board you probably like it speedy hence no hit-n-hold at this)
• {ON+key} available by Ctrl + right mouse button (also as option at program launch)
• key captions changing with shift status
• fuzzy logic for pasting numbers
• 41's beeper someway imitated vaguely only but at least you'll be warned when typing the 24th character in alpha
• trace logs shown with ZENROM style mnemonics
• trace log shows display changes and read values of RDROM what simplifies to locate code sections
• in trace log POWOFF is correctly shown as double word command
• CPU cycle count shown at display update, resettable in system menu
• modification of setup with ease using the text editor of your choice

Card Reader

• CR handles besides "normal" program-, data-, status-, and write-all-cards (read and write) also
  – HP-67/-97 cards (read only),
  – RAW files (R/W), and some
  – HP41 related LIF file-types within LIF disk dumps (R/O)
• CR shows also file types in lists of LIF disk dumps
• CR quickens handling of long lists by enhanced keyboard control

Printer

• the very first time (AFAIK) – simulation of 82242A infrared printer module
• XEQ/INP context menu to reuse marked strings of internal 82143A output,
  in CAT 1 listings cursor placement on a program name is sufficent as input for XEQ option
• HP41 with 82143A printer – transliterating 'synthetics' to human readable, e.g. RCL M in place of RCL [ as the role model
• PRINT or PAPER ADVANCE key pressed on 82143A will wake up HP41

Time

• executing TIME CHIP test of service ROM 2A shows "TIME IC  OK" – hooray!
• Time with SW (stop watch) and alarms – accurate to a fifths of a second (that is the pace maker's watch for events frequency at idle time)

Wand

• the game-changer – with Wand Virtual Paper Keyboard all commands and programs are at call by a mouse click, also showing quick reference infos
• a Software Defined Wand scans barcode directly on the screen

RAM tree view

• Nearly new – branch node «Special» shows 15C-buffers of INTEG, SOLVE, and Im-part of complex stack
• changing content in RAM-tv will update display of HP41
• show/edit RAM now also for Voyagers

Voyagers

• Voyager's display may blink, now simulated too
• Voyager program listings shown with HP41-like mnemonics
• New: Voyager program listings may be imported

Constraints, missing, annoying:

• The surface looks nasty
  — by design, to make it distinguishably different (nevertheless NutEm/PC is an emulator of the CPU-simulating kind), moreover, a photo-realistic skin would enforce also a display looking real beyond reproach, what in turn would make many lower case letters hard to read,
• graphics (but no bar code) with external 82143A printer only, bar code with 82242A IR printer module awful – "ofool!!" – slow
  — instead use my oo82162A IL2IR bridge, pretty fast with Emu41,
• no HP-IL for now
  — instead use Emu41 or – if it's just about to read in data and programs from LIF disk dumps – use the CR expansions,
• NutEm/PC is distinctly faster than the originals
  — albeit about 1600 times slower than the PC versions from HP (find 12C and 15C with others in this package).

Bugs:

• NutEm/PC showed the same error as Nonpareil – fixed.
• Not all bugs are fixed yet, two three showed only once and never again, so they could bite once more.
• Another one bites at fast scrolling (using the mouse wheel) a list of LIF disk dumps. It's missing a throttle to limit new requests for time-consuming evaluation of LIF disks.

Manuals of The Role Models

1. Amass all kind of files you like within quick reach in one directory. A single menu point in system menu will show it in Windows explorer. This option is favourable if there is more you need than just PDFs, e. g. the "HP-41 Quick Ref, Card for Synthetic Programming.GIF" or .JPEG or whatsoever.
2. Collect all relevant PDF manuals related to machines NutEm/PC emulates in one directory. The first number in the filenames must match the model number, e. g. for "HP11C USR MNL Rel 15-12-85.PDF" it is 11. Up to six PDFs belonging to the actually emulated calculator will be linked directly in the system menu.
3. Choosing none of the a. m. options the menu point 'Manual...' links to literature.hpcalc.org where the manual(s) in question may be found.

The fine print

Furthermore, for the parts with source code:
(iii) If you manage to improve this program you have to inform me as stipulated in following THE Q PUBLIC LICENSE (QPL).
(iv) Over and above that applies the QPL below:

THE Q PUBLIC LICENSE version 1.0