===========================================================================
Installing the FreeHC12 Library
===========================================================================

:Author: Colin D. Bennett <colin@gibibit.com>
:Date: 23 May 2008

.. contents::


Introduction
============

The FreeHC12 library consists of C header files and source files to make
programming for the HC12/HCS12 microcontrollers easier and more fun.  The
header files make I/O registers available to C programs and support setting
user functions as interrupt service routines.  Basic I/O operations such as
using the HC12 serial communications interface (the SCI module, which is a
UART) are made easier by driver modules.  The driver modules consist of a
header file and a C source file, which is compiled and linked into your
program.

In addition to the core HC12/HCS12 peripherals, there are several drivers for
peripherals on the `Dragon12-Plus`_ evaluation board.  Some of the
Dragon12-Plus peripherals supported by FreeHC12 drivers are the 4x4 matrix
keypad and the seven segment LED modules.  A number of examples are provided
to help get you started developing on the HC12 or HCS12.  These examples can
be compiled and downloaded directly to a Dragon12-Plus board via the serial
port.  FreeHC12 currently requires the D-Bug12 boot loader to function, but
support for standalone operation could be added [#standalonehc12]_.

You will need to first install the GNU HC12 toolchain before FreeHC12 can be
used.  See the `FreeHC12 documentation`_ page under *Installation* for
instructions on installing the toolchain.



Downloading FreeHC12
====================

Download the FreeHC12 library and examples from the `FreeHC12 downloads`_
page.


Installing the Library
======================

We will install the library in ``$HOME/bin/freehc12-0.5``::

	cd $HOME/bin
	tar -xzf /path/to/freehc12-0.5.tgz



Configure Environment
=====================

If you followed the instructions for building the GNU HC12 toolchain, you
created the file ``~/.m6812-env``, which is sources by your
``~/.bash_profile`` or ``~/.profile``.

Add the following lines to your ``~/.m6812-env`` file::

	export HC12INCLUDE="$HOME/bin/freehc12-0.5/include"
	export HC12DRIVERS="$HOME/bin/freehc12-0.5/drivers"

The makefiles for the example projects use these environment variables to
locate the FreeHC12 header files and driver source files.

Make sure you log out and log back in so the script will be sourced into your
shell.  (Alternatively, you can manually source the script by typing ``.
~/.m6812-env`` at the shell prompt.)



Programming: Getting Started
============================

YOU ARE NOW READY TO BUILD PROGRAMS FOR THE HC12!


Unpack and Build Examples
-------------------------

You can extract the FreeHC12 examples anywhere you like on your filesystem.
We will assume you are extracting the examples to
``~/freehc12-0.5-examples``::

	cd ~
	tar -xzf /path/to/freehc12-0.5-examples.tgz

Now you can build individual example programs by changing to the example's
source directory and running ``make`` in that example's subdirectory.  For
example, to build the seven segment LED display example ``7segment2``::

	cd ~/freehc12-0.5-examples/7segment2
	make

This will create a subdirectory called ``build`` and put the generated files
in it.  If you want to download the built program to the Dragon12-Plus board,
the ``.s19`` file is the one you are most interested in, called ``7seg.s19``.

You can also build all the examples with a single command by running ``make``
in the ``freehc12-0.5-examples`` directory itself. 

See `Uploading programs to the Dragon12-Plus`_ for instructions on uploading
and running the program on the Dragon12-Plus board.



Further Reading
---------------

Now that you have a working HC12 toolchain, you may want to read the documents
on the `FreeHC12 documentation`_ page under the *Programming* section.



.. [#standalonehc12] When running in EVB mode on the D-Bug12 boot loader, 
  the interrupt vector table used to install user interrupt handlers is at a
  different location in memory.  D-Bug12 actually chains the real interrupt
  handlers and calls the handlers from this other table.


.. _FreeHC12 downloads: http://freehc12.gibibit.com/Download

.. _FreeHC12 documentation: http://freehc12.gibibit.com/Docs

.. _Uploading programs to the Dragon12-Plus: 
  http://freehc12.gibibit.com/Uploading_Dragon12

.. _Dragon12-Plus: http://www.evbplus.com/hcs12.html