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

Update 10/22/2024:

• "The internationalisation update" — display and printer no longer restricted to codepage 1252, see Prerequisites
• read HP41 program listings, see Card Reader Extensions

Since 2/24/2024:

spot the difference contest – who is first to find a discrepancy in print-out of simulated and real Blinky?

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/Exchange Voyager Programs
6. Emulator or Simulation?
    – Time Chip Simulation
    – Card Reader Simulation
    – IR Printer Module Simulation
    – Thermal Printer Simulations
    – 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),
• IR Printer Module aka "Blinky",
• the Card Reader apt to digest HP67/97 cards too, and
• the Wand enabling a virtual paper keyboard and to scan barcodes, utilisable directly by the running HP41.

Furthermore

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 ever) 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 pleasing 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

Think first, consider:

∎ NutEm/PC requires a Beta UTF-8 enabled PC to get rid of CL§ surrogating CLΣ amongst others. Since this is an all affecting step (it even requires a reboot), ensure the programs you do need will still work. Moreover, backup your machine beforehand.
∎ Due to portable ooRexx there is no need to install ooRexx while it does not relieve from enabling Beta UTF-8 as mentioned afore. How to setup NutEm/PC as a "portable app" is explained here in detail. The following description is solely about the conventional installation, which, BTW, is much simpler.
∎ Installation of ooRexx will specify at user's option suffixes of three files types. Since I rejected the defaults, within this distribution suffix .rx indicates an ooRexx interpreter file while .rex denotes a sourceless executable file.
∎ I maintain only one version of NutEm/PC, if you find by chance a revision what still runs with ooRexx V4.1.3 it lacks for sure the youngest enhancements. Inverse conclusion: to run the current release the prerequisites must be met, without fuss or quibble.

To run NutEm/PC you need:

• Windows Beta UTF-8 enabled, for details and 'how-to' see this description from Microsoft,
• the fonts Courier New, Consolas, and Lucida Console (Windows versions 7..11 have them in storage),
• Open Object REXX V5.0.0, see oorexx of "Open Object Rexx",
• optional a viewer like IrfanView to show backside images,
• if and only if you like to run the Software Defined Wand (SDW), then IrfanView version 4.62 (or younger I hope) is indispensable;
  in addition the SDW needs R/W access to the installation directory to write and remove temporary files.

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, CR, Wand, HP-41 Advantage Advanced Solutions Pac, PPC ROM, and Voyagers' Pseudorandom Number Generator.

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.

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

1. There is no automated installation procedure. Unzip NutEmPC.ZIP to a directory named at will, a directory of its own or not, it's up to you.
2. If you picked the x64 version of ooRexx then also unpack NutL64.zip to get the appropriate tokenized subroutines.
3. 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.

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 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, with suffix .CFG filename is sufficing as argument for NutEm/PC.

Content

The .CFG file may contain blank lines, comments, EOF marker, 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.

EOF marker (optional)

A record solely consisting of '/*' (w/o quotes, comments possible) marks the logical End of File: all lines past this marker are ignored. It allows to keep some currently unneeded settings for later use.

Section headers

Section headers are set in square brackets. These are, together with the section's content:
 

[MODEL] (mandatory)

This section 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, mandatory 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] (mandatory)

Voyagers: a single ROM file-ID. Example:

[ROM]
.\Voyagers\hp10c.MClst

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). With the [ROM] section in sequence before [BLKY] and [THPR] those will be selected self-acting depending on "plugged" printer. 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

[INI] (optional)

Few assignments in the format separator-name-separator-value, each on a separate 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

[BLKY] (requisite for "Blinky")

HP41 only, not before [ROM] section, ignored w/o 82242A printer "plugged".
Few assignments to define where to find the IR printer simulation and how to connect it. Apt HP82240B printer simulation may be started automatically but will only be closed self-acting at session end if requested so by 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, not before [ROM] section, ignored w/o 82143A printer "plugged".
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 chance 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

[CREX] (optional)

HP41 only. Modules to consider when converting HP41 program listings to CR input, see PRLst within Card Reader Simulation Extensions.
Format is arbitrary separation character, ROM-ID, same separation character, four-letter tag
Example:

[CREX]
/10/C 81        ; PPC ROM
/20/0000        ; PPC ROM
/08/BC41        ; SKWIDBC
~05~Z)LA        ; ZENROM
/30/CR1G        ; CR
/29/PR1B        ; PR

[PERIP] (reserved for future use)

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

 ↑ 

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,
System Menu: Underscored letters indicate which key will launch an option
      Quit w/o saving RAM      - end NutEm/PC but keep 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...
Context Menu: shown by right mouse click not on buttons
      Copy       - take display as is to the clipboard
      Paste      - use clipboard content to push short cuts
      Slow disp. - toggle 'retard display' option (note 8)
      Quick quit - end NutEm/PC but do not save RAM

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.
8. Display change may be decelerated to a real 41's pace. In few situations this feature may show irritating effects and for that is's optional (not for Voyagers).

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

• hit-n-hold a key is for the HP41 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 some cases of hold-until-Null. For a complete list see this thread.
• {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 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/Exchange Voyager Programs

A listing 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 at any line of the listing.
• 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.
• Since only key codes are relevant for import, inline comments may be added at will.

Notes:

• Red neon alert as for RAM-tv applies here too. Read it and act as advised.
• While this import feature enables swap of emulators (two at present) it can't manage 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 'cloned 41', all running on unpatched ROMs. One little exception, for the wand I prefer a modification with a lowered pitch of the scan tone, what does in no way change its functionality (in the ZIP its ROM copy is unaltered). One big exception – not peripherals but the PSE delay of the OS is adjusted as described here.

My achievements in detail:

 ↑ 

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.

Note: The CR simulation of NutEm/PC passes all related tests of Service Module SM-1C (item ET-11966), only the speed test reports the motor to run more than 20% too fast. This has no impact on the operation of the simulation.

Card Reader Simulation Extensions

Besides the a.m. card types NutEm/PC handles also the following:

• RAW – HP41 program dumps, untreated hence raw
• LIF – dumps of LIF formatted disks, thereof:
  • 41WALL, 'E040'x
  • 41KEYS, 'E050'x
  • 41STAT, 'E060'x
  • 41PRGM, 'E080'x
  • 41DATA, 'E0D0'x
• PRLst – PRGM print-out, either
  • printed with setting MAN, TRACE, or NORM,
  • filed as Unicode with BOM or plain ASCII.

1. The various input formats are transformed to "virtual magnetic cards" then imported the same way as usual.
2. RAW format is apt to read and write programs. See additional remarks below.
3. IO of RAW files is part of the CR simulation, therefore only at call when a CR module is "plugged" in the .CFG file.
4. LIF and PRLst files are considered as read only.
5. Reading PRLst (program listing) is experimental. It fails for sure for synthetic text, depending the input file for umpteen more causes.
   See details further down.

RAW files are in use by several simulations for various models. While some are marked to which calculator they belong, for HP41 and HP-41S till now this data was missing — intentionally, I was told. IMO a sad story of ignorance and bliss. In short, although the HP-42S is an HP41 offspring inserting programs from the wrong model may jeopardize an emulated calculator. Sure, it's not lethal, but certainly a nasty surprise if it happens to you. Therefore NutEm/PC takes precautions not to read untagged RAW files without user's affirmation.

Processing RAW files like magnetic cards has the square advantage, the processing is in perfect compliance with GETP/GETSUB of XF, WNDLNK/WNDSUB of Wand, and READP/READSUB of MassMem – effectively it is RSUB/MRG of CR. (I never got accustomed to emulators throwing in ENDs here and there when reading RAW files, blithely disregarding decades of common usages.)

Emulators may optionally bundle several programs in one RAW file. But, by design, the CR can process only one 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. This makes it easy, in tandem with the standard CR behaviour, to keep from a bundle actually required routines only.

About reading program listings
Frankly, it's a pretty bad idea to convert program listings to a running phase. There are several ways less error-prone for transferring programs, e.g. mass memory, or magnetic cards for those with a CR, also RAW files if it's for simulators. Despite its imperfection reading program listings may produce a result concordant to 98% or even better. To check and correct this "first approach" could be faster than type out all from scratch.

How it works: input files are converted according the BOM (Byte Order Mark), possible are UTF-7, UTF-8, UTF-16 (LE), not possible are UTF-16 (BE), UTF-32 (BE and LE) and few more, not yet tested are UTF-7 and UTF-16 (LE). BOM-less files are assumed to be CP 1252 encoded. (It remains user's task to prepare useful input files.)

The conversion includes transliteration of some glyphs to their substitutes I used since NutEm under VM/CMS. Thus CL§ stands for CLΣ, x^2 for x↑2, x#y? for x≠y?, etc. This conversion may be too general in rare cases. Simple example:

                  PRP ""

 01•LBL "SIMSIM"
"H?"  PROMPT  "F(X)?"
PROMPT

 06•LBL 01
PROMPT  FC?C 22  GTO 09
4  *  +  PROMPT  FC?C 22
"N//2≠0"  ST+ X  +
GTO 01

 19•LBL 09
LASTX  2  /  -  *  3  /
END

C000F700 53494D53 494DF248 3F8EF546
2858293F 8E028EAB 16BA0014 42408EAB
16F64E2F 2F322330 927340B2 000A7612
43414213 43C0000F

For testing purposes NutEmPC.zip contains two .PRLst files, w/ and w/o BOM, one requires a [CREX] section in .CFG file while one does not, perielli.PRLst computes – half-axes in X and Y – the perimeter of an ellipse (by fast converging MAGM, modified arithmetic-geometric mean, based on Gauss); PBCIR.PRLst is from this thread about barcode printing via 82242A Infrared Printer Module.

 ↑ 

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.

Spot The Difference Contest
End of 2023 Thomas Fänge and Meindert Kuipers successfully reverse-engineered Blinky to a large extent thus capable now to emulate its essential operations. — My congratulations! — Consequently I should include their insights in NutEm/PC so to make TESTP check all works perfectly, similar as service ROM concludes « TIME IC  OK ». However I leave it as is, taking the TESTP result « BAD » as a distinguishing mark of the first successful Blinky simulation (except for TESTP).

In exchange I offer a contest (w/o reward): spot the difference! – Who is first to find a discrepancy in the print-out of simulated and real HP82242A? If there are deviations to note, no matter if substantial or minor only, please publish your results in forum.hp41.org.

• With Blinky the Wand Virtual Paper Keyboard will show four extra buttons:
  – TRACE/MAN/NORM, switching caption after hit,
  – ADV,
  – PRX/A, that is PRA in alpha mode, else PRX, and
  – RESETP.
• The function TESTP (Test Printer) returns « BAD » at once. Though looking imperfect it should not jeopardise other functions of simulated HP82242A.
• Since I discovered how to simulate Blinky I kept the related routines under cover, for no rational reason. 11/1/2023 I published it, also for no reasonable cause.

 ↑ 

Thermal Printer Simulations

External Thermal Printer Simulation

Because of the unidirectional connection, status and flags of the external printer simulation remain part of NutEm/PC. Consequently this applies also to the printer control panel with its main operating elements. Here 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 applies to the 82143A buffer only, 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:

if applicable, prints the buffer content right-justified, then (in any case) 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 involved.

Notes:

• When printing 'synthetics' the referenced register is transliterated, e.g. RCL [ is replaced by RCL M what parallels how the calculator displays such commands.
• Printer Service Module (tag SM-2B, item ET-11968) shows « ALL TESTS OK » – also the test output complies with figure 4-3 shown in Printer Service Manual if using HP-82240B version 1.18 (or younger) as external printing device.
• With SM-2B "plugged" the printer control panel shows an extra checkbox in order to simulate removing and inserting paper as requested during the test program.
• The internal, text-only printer simulation intentionally ignores all non-text elements, thus with it the service module test quits quite quick.

 ↑ 

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 mostly. 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 (for an exception see CAT 2 details below). 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, "Dev-IL", 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 collective table. Differing example (see screen shot): -VORANOGE 3, my Voyager Random Number Generator Version 3 is not listed in the overall XROM file yet. Hence the entry for page 7 (where I placed it on trial) can't be expanded, that is why it's not emphasised, despite it is not an executable function.

Not all ROMs > 4 k comprise an extra CAT-2 header for the 2^nd page. Then the virtual paper keyboard shows the corresponding ROM-ID in twin brackets, see PG D in the example, it is the upper 4 k of the PPC ROM.

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 currently offers no user exit to customise the content of this section.

Extra Features

• PPC ROM functions sorted: In CAT 2 functions of plug-in modules are typically shown sorted. Not so for PPC ROM, what is annoying when looking within a "strict illiterately sorted" list for one of its 122 functions. That is why NutEm/PC presents functions of PPC ROM sorted alphabetically.
• CAT 3 functions structured: The HP41 comes with many built-in functions, so picking one of those in virtual paper keyboard was a job of scrolling search. It was because CAT 3 functions are now grouped in sections +..B/C..F/G..P and so on. Therefore, to get the desired functions another click is needed but it avoids tiresome scrolling. This makes handling easier and faster.
• Atomic weights of elements: Solely and exclusively meant as a silly example for what a virtual paper keyboard may be used I was mad enough to include some 68 atomic weights.

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 for sure, 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 emerge. Likely it will take few unsuccessful attempts, so 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 (once only) three items in the .CFG file being used:
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) if not done yet for the a. m. Virtual Paper Keyboard insert a section [WAND] – see details here,
iii) there define the full path of the IrfanView executable (only this enables the start of the SDW with a right mouse click on the Virtual Paper Keyboard).
Furthermore – it's essential – ensure you do have 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:

• To capture barcodes only screen copy leaves cursor out, so no remnants of it may thwart the use of E or W as scan start. If in doubt use a. m. option S.
• 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

• "The internationalisation update" enables to display and print characters like Σ formerly shown substituted only
• 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
• retarding 41's display changes when NutEm/PC runs faster than role model (feature selectable in context menu)
• 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),
  furthermore (supplementing the role model)
  – RAW files (R/W), and some
  – HP41 related LIF file-types within LIF disk dumps (R/O)
  – new – program listings of different styles and encoding
• lists of LIF disk dumps show file types
• fast handling of long filelists 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 sufficient as input for XEQ option
• HP41 with 82143A printer – transliterating 'synthetics' to human readable, e.g. RCL M in place of RCL [
• 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
• oversized cursors will not jeopardise barcode scanning any longer

RAM tree view

• 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
• Voyager program listings may be imported and shared, even with another platform

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, fairly 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,
• not all source code published
  — the credo of a pretty much self complacent programmer I know is (or was?), "if someone likes to know more details than I documented, he may have a look at the source code." ´While this is possible for NutEm/PC it's not for the CR simulation (reason described in there) nor for the SDW. To my knowledge there are three more SDWs published, one with source code (I don't grasp), two without. Take me as strange, but this is the only reason I also keep mine undercover.
• 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 few – one thereof troubling serious as related to RXqueue – showed once only 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 disk directories.

 ↑ 

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

 ↑