***************
Getting started
***************

.. running:: "Calypsi debugger" dbnut
.. literalinclude:: gen/dbnutSignOn.text
   :language: none

.. index:: HP-41 user interface, user interface, HP-41

User interface
==============

The debugger simulates an HP-41 calculator internally, but in order to
control the calculator we need to be able to push button and watch the
display. Rather than opening a traditional graphical user interface,
the debugger relies on web technologies and starts a web server.


HP-41 web application
---------------------

The web application, or HP-41 front end is included in the installation
under ``hp41-ui/hp41.html``. Simply open it in any web browser and it
will connect to the debugger.

The source code for the user interface project can also be found at
`dbnut-ui <https://github.com/hth313/dbnut-ui>`_.

.. note::
   You should only have one HP-41 web application front end open at
   any time. Having multiple ones will cause them to fight over which
   is the user interface as the debugger expects to talk to a
   single front end. If this happens a notification will be written to
   the debugger console output. Simply close one of the front ends if
   this occurs.


.. index:: web application, web server

Protocol
--------

The web server acts on simple JSON-RPC commands passed over a web
socket. Typically key presses are passed from the web application and
notifications about display updates are passed back. The user
interface is in other words quite dumb. All processing takes place in
the debugger.


.. index:: mainframe

Starting
========

The Calypsi debugger simulates the HP-41 Nut processor with an
attached HP-41 memory system. In order to do anything meaningful you
need to provide a mainframe (operating system) image. Such image
contains the internal ROMs of the HP-41 and is not included with this
product.

The minimal command line to start the Calypsi debugger in a
meaningful way is:

.. code-block:: sh

  $ dbnut --load-module 41cv.mod

Where ``41cv.mod`` is the mainframe as a module file. The Calypsi
debugger can also be started as an HP-41CX using an appropriate
module file.

.. note::

   Extended memory and the clock chip is currently supported, but the
   beeper is not.

You can plug in other modules as well, simply specify each one using the
``--load-module`` option:

.. code-block:: sh

  $ dbnut --load-module 41cx.mod --load-module ppc.mod --load-module zenrom.mod

To debug your own module at MCODE level you should build it using
the ``-g`` option to produce debugging information. The linker will
normally produce an ELF/DWARF executable image with the ``.elf`` extension
that can be loaded by the Calypsi debugger:

.. code-block:: sh

  $ dbnut --load-module 41cx.mod myimage.elf


.. index:: command line

Command line
------------

Once the Calypsi debugger is started it responds with:

.. code-block:: none

  $ dbnut --load-module 41cx.mod myimage
  Calypsi debugger for Nut
  listening for user interface connections on port 8080
  (dbnut)

The debugger announces its presence and opens a web server for the user
interface. The ``(dbnut)`` text is the command prompt indicating that
it is ready for commands.

At this point the debugger is ready to start a debug session with the
modules specified by ``--load-module`` options loaded. However, the
simulated process does not yet exist.

To start the program and create a process for it, simply run it with
the ``run`` (or just ``r``) command:

.. code-block:: sh

  (dbnut) r
  running

The debug process is created and execution starts, however it does not
get so far as the calculator starts in sleep. To wake it up, press
the ``ON`` button on the calculator user interface.

Note that after the ``running`` message, you will not get the prompt
back. This is because the calculator is active. To take control again
in the debugger, press ``Ctrl-c`` in debugger console window.

.. code-block:: sh

  (dbnut) r
  running
  ^C
  program received signal SIGINT, interrupt
  0x0000
  (dbnut)

The running program received an interrupt signal at address
``0x0000``. The debugger is now in control and is ready for more
commands as indicated by that the prompt is back.

To terminate the session and leave the debugger, use the ``quit``
command (or ``q`` for short).


More on running from the command line can be found in
:ref:`command-line`.

.. index:: MI, machine interface, console mode,
.. index:: mode; console, mode; MI

Machine interface
-----------------

The MI (Machine Interface) is intended for debugger front-ends like
Visual Studio Code. To start the Calypsi debugger in MI mode, add
the ``-i mi`` or ``--interpreter mi`` to the command line:

.. code-block:: sh

  $ dbnut --load-module 41cx.mod -i mi myimage

If you try it you will find that the MI mode is quite a bit less
friendly than the command console. However, it does provide additional
commands and some commands provide additional information that are not
given in the console mode. For a very experienced user it may
sometimes be desirable to issue an MI command, but that is better done
using the console command ``interpreter-exec MI "command"`` which
invokes an MI command from the console. This provides you with the
usual powerful console mode and allows occasional use of MI commands,
should the need arise.

.. note::

   Switching between console and MI modes once the debugger is started
   is not possible. However, both modes provide a command that allows
   a command to be issued in a specified command interpreter.
