13. Clonix tool

Clonix is a series of programmable modules for the HP-41. A Clonix module contains a PIC-18 micro controller inside a HP-41 module shell which can be programmed outside the calculator. When plugged into the HP-41, it works by interacting directly with the HP-41 CPU over its bus, just like any other plug-in module.

The Clonix tool is an optional way to assemble HP-41 module images into configurations and have source code generated suitable for generating a Clonix module firmware.

The Clonix tool is a command line tool named clonix. Running it from the command line with the ``–help`` option will give a sign-on message and display accepted options:

Calypsi clonix tool for Hewlett-Packard Nut version 5.16

Usage: clonix [--version] [--module CLONIX-MODULE] [--start-page NUMBER]
              [--lock-pages HEX-DIGITS] [--calypsi-source]
              [-o|--output-file OUTPUT-FILE] [--signature-file NAME]
              [--lowercase-romimg-pages] [FILE...]
  use 'clonix --help' for detailed help

Available options:
  --version                Display version number
  --module CLONIX-MODULE   Clonix module, one of 'Clonix-41', 'Clonix-D' or
                           'NoV-64' (defaults to 'Clonix-41')
  --start-page NUMBER      Page to start loading at (defaults to '8')
  --lock-pages HEX-DIGITS  Pages that are to be left available (string of
                           individual hex digits)
  --calypsi-source         Generate experimental single source output
  -o,--output-file OUTPUT-FILE
                           Name of output file (valid only for experimental
                           single source output)
  --signature-file NAME    Name of the signature file (defaults to
                           'sgnature.asm')
  --lowercase-romimg-pages Use lowercase page numbers (defaults to upper case)
  -h,--help                Show this help text

Documentation of Clonix modules together with source files and tools for Windows are available at the Clonix web size. If you are using Windows either directly, or by emulation, you will find everything you need here.

If you are on Linux or macOS, and you prefer to use your own platform, the Clonix tool is an option to the Windows tools.

In addition to the Clonix tool, you will need:

  • A physical Clonix module (obviously).

  • A suitable Clonix source file from the Clonix distribution, available from http://www.clonix41.org/.

  • HP-41 module file images. A good place to look for these are http://www.hp41.org/.

  • A PIC-18 assembler that is compatible with the Clonix source code. You can get MPLAB X from Microchip http://www.microchip.com/mplabx/ which contains mpasmx.

  • A PIC-18 programmer wired to an adapter which attaches to the physical module. Such adapter can be obtained from the same source as the Clonix modules. Depending on which programmer you use, it may need some customization to fit the module adapter to the programmer. (The PICKit-2 mentioned below will need customization.)

One programmer that has been successfully used on macOS is PICkit-2. To use PICkit-2 from macOS or Linux, you need to download and build the command line tool pk2cmd from http://ww1.microchip.com/downloads/en/DeviceDoc/pk2cmdv1.20LinuxMacSource.tar.gz.

13.1. Differences

Comparing the Clonix tools to the ClonixConfig provided in the Clonix distribution, you may find there are situations where you prefer one over the other.

A brief comparison between the two is that ClonixConfig runs on Windows only, provides a GUI and support all modules from the Clonix and NoV families. It is an all-in-one solution that also will start the programming software (support is provided for two programmers).

The Clonix tool on the other hand runs on multiple platforms and currently supports a more limited set of modules. It provides more flexibility in generating double configurations (Clonix-D and NoV-64). It is also more of a building block, which means you may want to write some kind of script or build file to tie it all together.

ClonixConfig loads ROM images (lose module pages) and requires you to put them in the desired location manually. The Clonix tool loads module files, and will do the page layout for you.

One can say that ClonixConfig is more user friendly out of the box, but forces you to do the page layout manually every time. The Clonix tool is more of a building block for your own module creating scripts. Once created, you have a very powerful and easy way to keep your Clonix module (or modules) up to date with whatever configurations you want to use.

13.2. Load process

To assemble modules into a Clonix module, the Clonix tools goes through a load process where one or several modules are processed. Basically, the module image files are loaded into a fictive memory system following the load constraints in the module file meta data.

There are several possible outcomes from loading modules. A success load process will output the page map:

$ clonix advantage.mod ppc.mod library4_Q.mod
4   Library#4 Rev.Q
8   Advantage Pac
9:1 Advantage Pac
9:2 Advantage Pac
a   PPC ROM
b   PPC ROM
(all Clonix pages filled up)

If you try to load too many module pages into you Clonix image, the Clonix tool will abort and tell you about it:

$ clonix smath44_3x3.mod library4_Q.mod
fatal error: trying to load too many module pages, Clonix-41 supports up to 6 ROM pages
Terminating due to errors

It is also possible that the load process went fine, but you are not happy with where the modules were loaded. There are a couple of parameters you can use to tune the load process. By default, loading will take place at page 8 (which is the first page available to any module plugged into the first port of the HP-41). Information in the module meta data may dictate that specific pages are to be used, or that it wants several pages allocated next to each other.

You can request load to start at another page using the --start-page option. You can further prevent pages from being used by specifying such pages to the --lock-pages option:

$ clonix --start-page=a --lock-pages e ppc.mod advantage.mod library4_Q.mod
4   Library#4 Rev.Q
a   PPC ROM
b   PPC ROM
c   Advantage Pac
d:1 Advantage Pac
d:2 Advantage Pac
(all Clonix pages filled up)

Here we start loading from page A (decimal 10) and ensure that we leave page E free (this is where a card reader would like to go). This went fine, but we realize that it would be good to leave page C free also so we can plug in a physical 4K application ROM there. As the PPC ROM wants two adjacent pages it will no longer fit, so we choose two 4K ROMs instead:

$ clonix --start-page=a --lock-pages cf advantage.mod tvm_1e.mod ccd-osx.mod library4_Q.mod
4   Library#4 Rev.Q
a   Advantage Pac
b:1 Advantage Pac
b:2 Advantage Pac
d   TIME VALUE of MONEY
e   CCD OS/X Module
(all Clonix pages filled up)

13.3. Building the image

The Clonix tool just emits various source files that need to be built together with the appropriate Clonix source file using mpasmx.

$ mpasmx ClonixLP.asm

If successful, you will now have a CLonixLP.HEX output file. You may also want to inspect the ClonixLP.ERR diagnostic file for any errors.

13.4. Programming a module

Programming a module requires a flash programmer. There are many possible choices, but one that has been tested on macOS is PICkit-2 from Microchip.

PICkit-2 uses USB, so just plug it in and try the following, assuming your output file is named ClonixLP.HEX and you have pk2cmd (and its device file) in the PATH:

$ pk2cmd -P -FClonixLP.HEX -A3.3 -M
Auto-Detect: Found part PIC18F252.

PICkit 2 Program Report
19-1-2016, 11:30:21
Device Type: PIC18F252

Program Succeeded.

13.5. Setting up a Makefile

If you want to simplify the process of maintaining your Clonix module (or even modules), you can set up a Makefile for building and maintaining a directory with your collection of HP-41 module images. If you later want to make minor changes to the list of modules, simply edit the commands in the Makefile accordingly:

MPASMX = /Applications/microchip/mplabx/v3.20/mpasmx/mpasmx
VPATH = /Users/me/modules41

# Build my Clonix-41 module
ClonixLP.HEX: ext-io.mod ttrkall.mod library4_Q.mod tvm_1e.mod ccd-osx.mod games.mod
        clonix --module clonix-41 --lock-pages cde $^
        $(MPASMX) ClonixLP.asm

clean:
        -rm -f ClonixLP.HEX ClonixLP.ERR ClonixLP.LST ClonixLP.O

programLP:
        pk2cmd -P -FClonixLP.HEX -A3.3 -M

As you add more modules to your growing collection and store them in your modules41 directory, they become available to the set of modules you can choose between.

The example above relies on GNU Make, which provides the very useful VPATH directive. It basically makes it possible to set up a search path for input files, making it possible to just list places where you have module files in a colon separated list of directories.