Installing the FreeHC12 Library

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

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 [1].

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.

[1]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.