.. _sec-examples:

Examples
========

Now lets look at some examples on how to use the tools to build actual
modules. HP-41 modules come in many variants and Calypsi will
allow you to make virtually any kind of software module using RPN or
MCODE, allowing multi-page layouts, with or without page banking.


Hello world
-----------
.. index:: example;hello world

The first example is a very basic MCODE module that contains a simple
instruction ``HELLO`` that will display ``HELLO WORLD``. The purpose
is to put together minimal, but complete module, following the module
layout as described in :ref:`sec-module-layout`.

While this example is simple, it is useful for getting familiar with
the tools and how to use the resulting module on your HP-41 or HP-41
emulator.

The example can be found relative to the installation directory in
``example/HelloWorld``. In order to build it you will need to, *a*)
copy the example elsewhere; *b*) ensure that you have GNU Make
installed;  and *c*) have your path environment variable set up so
that GNU Make and the Calypsi can be found.

When properly set up, you should be able to build the example by just
saying ``make`` from the command line.

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


.. index:: MLDL, Clonix
.. _sec-trying-it-out:

Trying it out
^^^^^^^^^^^^^

The result will be a module file ``hello.mod`` that you need to plug in
to your HP-41 or load in your HP-41 emulator. If you are using a real
HP-41, you need either an MLDL,  Clonix module or something similar,
and some means to download the module to it. If you are using an
emulator, it needs to support the module file format to be able to load
the module.

Once installed in the HP-41, try the command ``HELLO`` which should
display ``HELLO WORLD``. You can also see the module in catalog 2
(using ``CAT 2``).


.. index:: example;games, example;rpn
.. _sec-games:

RPN games module
----------------

In this example we will start with a games module that makes use of a
couple of nice Poker and Roulette games written by Jean-Marc
Baillard. The intention here is to use them as an example how to make
a module (not document these programs in detail).

The example can be found in the ``example/games`` directory in the
Calypsi installation.

Originally, these programs were obtained from internet by using copy
and paste into a source file. Since they use features on the HP-41CX,
an ``.import`` directive stating this has been added at the beginning.
When importing source code, you should check which convention has been
used to represent append alpha strings, as there are many variants in
use. This is because there
is no natural way to do this in ASCII as the HP-41 uses character 127,
which is DEL in ASCII.

In the original sources for these programs, character code 126 is used
as append character. This is the tilde in ASCII, but actually Σ on the
HP-41. The RPN Compiler does not accept this and those strings need to
be changed, i.e. change ``"~NTH"`` to ``>"NTH"``.


The project
^^^^^^^^^^^

This example uses GNU Make which you need to have installed. The
Makefile contains the following:

.. literalinclude:: example/games/Makefile
   :language: makefile

As can be seen, it is fairly simple to add source files to the project
by adding files to the variables at the top. There are two RPN
source files, no raw RPN files and two assembly source files.


The assembly files
^^^^^^^^^^^^^^^^^^

The ``PokerSupport.s`` file contains some special MCODE routines used
by the poker program to speed it up. These routines are imported into
the ``poker.rpn`` program at the top:

.. literalinclude:: poker-extract.rpn
   :language: ca65


The second one is ``header.s`` which defines everything related to the
module layout:

.. literalinclude:: example/games/header.s
   :language: ca65

This file can be used as a starting point for other projects simply by
changing the XROM identity, the ROM header function and the module ID
at the end.

The size of the FAT is automatically calculated thanks to the
`.fatsize` relocation operator being used to point to the end marker
of the FAT.


Linker rules
^^^^^^^^^^^^

The linker rule file lists the order of the sections and ensures that
the ``TAIL`` section ends up at the proper starting position (hex
``FF4``):

.. literalinclude:: example/games/Plugin4K.scm
   :language: scheme

The ``TAIL`` section contains the poll vectors and  module identity which
shall go to the end of the module page.


Trying it out
^^^^^^^^^^^^^

The result will be a module file ``games.mod`` that you need to plugin
to your HP-41 or load in you HP-41 emulator as described in the
previous example, see :ref:`sec-trying-it-out`.

Once installed in the HP-41, you can try the games, but you are
probably best advised to go to
`Jean-Marc Baillard's web site <http://hp41programs.yolasite.com>`_
and read the instructions.


Modules on the internet
-----------------------

Here is a collection of real projects that use Calypsi.


Amateur astronomy
^^^^^^^^^^^^^^^^^

`Amateur astronomy ROM <https://github.com/isene/hp-41_AMASTRO.ROM>`_
contains a collection of telescope and observational utilities.


CLILUP
^^^^^^

`CLILUP <https://github.com/hth313/CLILUP>`_ is an update module for
HP-41CL using HP-IL. It is a mixed module using both MCODE and RPN.


Data and statistical analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

`Data and statistical analysis ROM <https://github.com/isene/hp-41_DSTAT.ROM>`_
is a comprehensive statistical analysis of data sets on the HP-41
calculator.


EquationLibrary
^^^^^^^^^^^^^^^

`EquationLibrary <https://github.com/mafleming/EquationLibrary>`_
implements an equation library on top of the Formula Evaluation
module. It is mostly written in RPN with some MCODE.


Geir ROM
^^^^^^^^

`Geir ROM <https://github.com/isene/hp-41_GEIR.ROM>`_ is a collection
of the most essential programs, utilities and tools as used by Geir
Isene.  This contains a mixture of useful RPN and MCODE programs.


Isene ROM
^^^^^^^^^

`Isene ROM <https://github.com/isene/hp-41_isene-rom>`_ contains the
most useful of Geir Isene's RPN programs.
Ultimate Alarm Clock, the PDA programs NOTES and REM as well as CRYPT
to encrypt and decrypt ASCII files and other neat stuff.
Makes use of HEPAX and XM files.


Ladybug
^^^^^^^

`Ladybug <https://github.com/hth313/ladybug>`_ is a banked module that
makes use of various techniques to switch banks on the fly. It
converts the HP-41 into an integer mode calculator, similar to the
HP-16C.


Lib41
^^^^^

`Lib41 <https://github.com/hth313/lib41>`_ is a library (not a module)
with routines that can be incorporated into your own module.

OS4
^^^

`OS4 <https://github.com/hth313/OS4>`_ is an HP-41 operating system
extension module that uses page 4.
