.. index:: Clonix tool

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.

.. running:: "Clonix tool" clonix
.. literalinclude:: gen/ClonixSignOn.text
   :language: none

Documentation of Clonix modules together with source files and tools
for Windows are available at
`the Clonix web size <http://www.clonix41.org/>`_.
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.


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.


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:

.. literalinclude:: gen/ClonixGood.text
   :language: none



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

.. literalinclude:: gen/ClonixOverflow.text
   :language: none


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:

.. literalinclude:: gen/ClonixGood2.text
   :language: none

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:

.. literalinclude:: gen/ClonixGood3.text
   :language: none



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``.

.. code-block:: none

  $ 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.


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``:

.. code-block:: none

  $ 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.


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:


.. code-block:: make

  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.
