Embed Inc PIC Development Resources

This section of the Embed Inc web site contains general information and example source code for the Microchip PIC line of microcontrollers. 

Be sure to read the legal notice before using any software found on this web site. 

General Structure of PIC Firmware

Embed Inc is a custom embedded systems development company.  We have done many projects using the Microchip PIC line of microcontrollers and have converged on a structure and methodology for PIC projects that is suitable for the majority of cases.  This includes a set of standard macros, subroutines, modules, and host tools. 

When possible, we use our common framework for PIC firmware projects.  The framework has evolved over many projects, and will continue to evolve.  It consists of two master include files (STD_DEF.INS.ASPIC and STD.INS.ASPIC), a common naming scheme and structure for the modules of a project, and a few standard modules for capabilities required by most PIC projects. 

We use the naming convention PPP_MMM.ASPIC, where PPP is the project name and MMM is the name of the module within the project.  For example, "hal_intr.aspic" is the source file for the INTR module within the HAL project.  Many examples here use a three letter project name and 4 letter module name.  This is because MPLAB version 5 and earlier only allowed 8.3 "DOS" file name.  Fortunately this was changed in MPLAB version 6. 

So what's with this ASPIC stuff?  We use a preprocessor on all our PIC source code.  The .aspic file name suffix indicates to our build system that it is a PIC assembler module that must be run thru the preprocessor to create a .asm file.  The .asm file produced by the preprocessor is assembled directly by the MPASM PIC assembler. 

Below are the standard include files, and templates for the standard modules and additional include files.  The project name of the templates is "qqq".  The strings "qqq" and "QQQ" in the template files are intended to be replaced with the actual project name via global substitution in a text editor. 

std_def.ins.aspic

This is the first of the two mandatory include files used by all projects.  This file sets defaults that will be used in STD.INS.ASPIC.  The two files are separated so that the application can change the defaults before they are used. 

std.ins.aspic

This is the second of the two mandatory include files.  This is the file that does all the work, which is mostly defining a set of macros.  It relies on the configuration values originally set in STD_DEF.INS.ASPIC, which can be altered by the application before this file is included. 

qqqlib.ins.aspic

This is the top include file for the project and declares the PIC environment.  This include file references STD_DEF.INS.ASPIC, customizes specific values, then includes STD.INS.ASPIC.  Non-environment issues related to the operation of the project are in qqq.INS.ASPIC.  Standard library routines used by this project only use this include file and not qqq.INS.ASPIC.  Modules specific to the project include qqq.INS.ASPIC, which includes qqqLIB.INS.ASPIC. 

qqq.ins.aspic

Project-specific include file.  All project definitions except those relating to just the PIC environment go here. 

qqq_strt.aspic

Top executable module.  This module contains the reset vector and initializes each of the modules individually.  When done, it jumps to the INIT entry point in the INIT module. 

qqq_init.aspic

INIT in this module is jumped to after all the modules have been intialized individually.  This module performs system-level initialization and jumps to MAIN in the MAIN module. 

qqq_main.aspic

Main operating code.  Entry point MAIN is jumped to after initialization is complete. 

qqq_port.aspic

Low level I/O port handling.  The PORT_INIT routine initializes the I/O ports as defined by the /INBIT and /OUTBIT preprocessor directives in qqq.INS.ASPIC. 

This module also disables any analog inputs the chip might have, which are usually enabled on power up.  If used, these would be specifically enabled by the modules that handle them.  Initializing all analog inputs to off eliminates some common bugs in porting from a PIC without an analog peripheral to one that has an analog peripheral. 

qqq_intr.aspic, qqq_intr18.aspic

Interrupt handlers.  QQQ_INTR.ASPIC is for 16 family PICs and QQQ_INTR18.ASPIC for the 18 family.  QQQ_INTR18.ASPIC is configurable to single or multiple priority interrupts by setting the INTR_PRIORITIES constant at the top of the file to true or false. 

qqq_uart.aspic

Fully interrupt driven UART handler with software receive and transmit FIFOs. 

qqq_cmd.aspic

Host command interpreter.  The command interpreter runs as a separate thread.  It is run for a time slice from the main event loop when a UART input byte is availble (FLAG_SIN set). 

qqq_xxxx.aspic

Template for an arbitrary project module. 

In general, each module contains the qqq_INIT routine, which performs any module-specific initialization.  The qqq_INIT routines are called from the STRT module after a reset. 

HAL example project

This project follows the structure and naming conventions described above.  It is the PIC code for the SpookyEyes halloween device.  See the comments in HAL.INS.ASPIC for more details. 

HOS example project

Template project that acts on commands sent from a host or dumb terminal via RS-232. 

dsPIC Templates

std.ins.dspic

Standard include file.  Defines a few constants and general purpose macros. 

qqq_strt.dspic

Contains execution start point and defines static processor configuration. 

qqq_port.dspic

Initializes I/O ports according to the /INBIT and /OUTBIT directives in the project include file. 

qqq_task.dspic

Cooperative task manager. 

qqq_xxxx.dspic

Blank module template. 

Tools

We use wrapper programs around each of the Microchip build tools: MPASM, MPLIB, and MPLINK.  This is partly because the Microchip tools are too brain dead to return a bad program exit status when they fail.  Our build system, like most build systems, requires a tool to return something other than 0 program exit status when the build failed.  Our wrappers also deal with some file naming and other issues. 

In addition to plain wrappers for the Microchip executables, we have created a Microchip assembler preprocessor.  This allows us to add directives to the assembler source code that enable better programming practises than raw MPASM does.  See the doc file for details. 

Here is the list of some of the PIC development tools.  Click on a tool name to view its documentation file. 

PREPIC - PIC assembler preprocessor.  Required by ASMPIC if assembling .ASPIC files. 

ASMPIC - Wrapper around MPASMWIN.  Requires PREPIC if assembling .ASPIC files. 

LIBPIC - Wrapper around MPLIB. 

LINKPIC - Wrapper around MPLINK. 

ASPIC_FIX - Fixes formatting, removes tabs, etc, of an arbitrary PIC assembler file.  Same resulting format as used for all examples here. 

Eagle files

We use Eagle from Cadsoft as our primary electronics design software.  In the process of using it over many projects, we have developed a number of libraries, scripts, user language programs (ULPs), and other facilities.  Some of these are publicly available.  Among other things, this includes a library specifically for PICs.  These Eagle tools can be downloaded from the software downloads page.  Install and look around. 

Software Downloads

The build tools, source code, and other software are available for download.  Click on the heading above to see what is available. 

Documentation

Some of the documentation for the PIC development environment is viewable from this web page.  All the separate documentation files will be in the DOC subdirectory after the PIC development tools are installed.  The remaining details are documented in the source code itself.  This will be in the SOURCE subdirectory after installation.  See the software installation page for more details on the stucture of installed software. 

A combined document is available that contains much of the information in a single place.  This was produced by Jan-Erik Söderholm, and is available on his web site www.jescab.se/embedinc.  It is mostly a PDF file compilation of the documentation here, plus some additional information of his own.  Embed Inc takes no responsibility for this document. 



Last Updated 21 January 2006