Specifying configuration bit settings in PICBASIC PRO™ programs (for PBP 2.60C and earlier).

The following information is not applicable to PBP 3.0 and later.  For these newer versions, see the directives "#CONFIG"/"#ENDCONFIG" in the PBP user guide.

It is possible to add a line to your PICBASIC PRO™ program that will place configuration bit settings in the generated hex file.  The method used depends on the assembler that you are using in conjunction with PBP.

If you are compiling for 18C or 18F PICs, you must use the Microchip assembler, MPASMWIN.EXE.  Some Windows interface software will specify MPASMWIN as the default assembler for all the PICs.

The easiest way to know what assembler is in use is to do a compile.  If you see the MPASM window pop up momentarily and display a green progress bar, or if you see a black command window momentarily, you are using MPASMWIN and should follow the appropriate procedure below.  If no popup window appears, you are using PM.

If you add a configuration directive to your program file,  you are actually replacing the default configuration that the compiler would otherwise include.  The easiest way to determine the correct syntax is to get examples from the compiler and assembler's built-in resource files.  To that end, it's best to understand how the compiler determines the config defaults.

When PICBASIC PRO is invoked, whether through a Windows interface or DOS command line, it is given a set of parameters that tell it how to proceed.  To determine the configuration defaults, it needs to know which PICmicro^® is being used and which assembler to use.

The first thing the compiler looks for is a file in the PBP folder that matches the targeted PIC^®.  If you tell it to compile for a 16F84A, it reads the file "16F84A.INC".  The contents of this file are divided into 2 sections, one for each assembler.  An internal variable, "PM_USED", tells the compiler which section of the file to use.  In the following example, you will see that the top section ("ifdef" to "else") is meant for the PM assembler and the bottom section ("else" to "endif") is meant for the MPASM assembler.

ifdef PM_USED
        LIST
        include 'M16F8x.INC'    ; PM header
        device  pic16F84A, xt_osc, wdt_on, protect_off
        XALL
        NOLIST
    else
        LIST
        LIST p = 16F84A, r = dec, w = -302
        INCLUDE "P16F84A.INC"    ; MPASM  Header
        __config _XT_OSC & _WDT_ON & _CP_OFF
        NOLIST
    endif

For each assembler, PBP is given a header file and a set of defaults.  The header file is important because it holds the definitions of the labels used to set the configuration.  Keep in mind that the labels in MPASMWIN are case-sensitive, in PM they are not.

Procedure for MPASMWIN.EXE:

A note about deprecation of the __CONFIG directive

Let's look at an example using the 18F452 and setting the oscillator configuration to HS.  Assuming the compiler is installed at C:\PBP, we view the file C:\PBP\18F452.INC .  Only the critical settings are listed in the file.  Any bits not listed are left in their default states, which can be found in the Special Features section of the Microchip datasheet for the PICmicro.  Here we find that the MPASM configuration directive reads:

INCLUDE "P18F452.INC"   ; MPASM  Header
        __CONFIG    _CONFIG1H, _OSCS_OFF_1H & _XT_OSC_1H
        __CONFIG    _CONFIG2H, _WDT_ON_2H & _WDTPS_128_2H
        __CONFIG    _CONFIG4L, _LVP_OFF_4L

To find the correct labels that set the configuration bits as we need them, view the MPASM header file found in C:\Program Files\Microchip\MPASM Suite\P18F452.INC.  Here we find the label we need:

;Configuration Byte 1H Options
_OSCS_ON_1H        EQU  H'DF'	; Oscillator Switch enable
_OSCS_OFF_1H       EQU  H'FF'
_LP_OSC_1H         EQU  H'F8'	; Oscillator type
_XT_OSC_1H         EQU  H'F9'
_HS_OSC_1H         EQU  H'FA'
_RC_OSC_1H         EQU  H'FB'
_EC_OSC_1H         EQU  H'FC'	; External Clock w/OSC2 output divide by 4
_ECIO_OSC_1H       EQU  H'FD'	; w/OSC2 as an IO pin (RA6)
_HSPLL_OSC_1H      EQU  H'FE'	; HS PLL
_RCIO_OSC_1H       EQU  H'FF'	; RC w/OSC2 as an IO pin (RA6)

Replacing the appropriate labels and putting the "@" at the beginning of the line to signify inline assembly, the configuration line in our PICBASIC PRO source file becomes:

@        __CONFIG    _CONFIG1H, _OSCS_OFF_1H & _HS_OSC_1H

To avoid an error caused by multiple configuration lines, the original line must be commented in the file 18F452.INC.  A semicolon (;) is used for comments in Assembly language:

INCLUDE "P18F452.INC"   ; MPASM  Header
;        __CONFIG    _CONFIG1H, _OSCS_OFF_1H & _XT_OSC_1H
        __CONFIG    _CONFIG2H, _WDT_ON_2H & _WDTPS_128_2H
        __CONFIG    _CONFIG4L, _LVP_OFF_4L

Procedure for PM.EXE:

Let's go through an example.  Let's say we want to compile for the 16F877 using PM and we want to set the oscillator configuration to HS and enable code protection.  Assuming the compiler is installed at C:\PBP, we view the file C:\PBP\16F877.INC .  Only the critical settings are listed in the file.  Any bits not listed are left in their default states, which can be found in the Special Features section of the Microchip datasheet for the PICmicro.  Here we find that the PM configuration directive reads:

To find the correct labels that set the configuration bits as we need them, view the PM header file at C:\PBP\INC\M16F87x.INC.  Here we find the labels we need:

					; *** DEVICE Fuses Definitions
RC_OSC          equ     3FFC0003h       ; XX XXXX XXXX XX11
HS_OSC          equ     3FFC0002h       ; XX XXXX XXXX XX10
XT_OSC          equ     3FFC0001h       ; XX XXXX XXXX XX01
LP_OSC          equ     3FFC0000h       ; XX XXXX XXXX XX00
WDT_ON          equ     3FFB0004h       ; XX XXXX XXXX X1XX
WDT_OFF         equ     3FFB0000h       ; XX XXXX XXXX X0XX
PWRT_ON         equ     3FF70000h       ; XX XXXX XXXX 0XXX
PWRT_OFF        equ     3FF70008h       ; XX XXXX XXXX 1XXX
BOD_ON          equ     3FBF0040h       ; XX XXXX X1XX XXXX
BOD_OFF         equ     3FBF0000h       ; XX XXXX X0XX XXXX
LVP_ON          equ     3F7F0080h       ; XX XXXX 1XXX XXXX
LVP_OFF         equ     3F7F0000h       ; XX XXXX 0XXX XXXX
CPD_ON          equ     3EFF0000h       ; XX XXX0 XXXX XXXX
CPD_OFF         equ     3EFF0100h       ; XX XXX1 XXXX XXXX
WRT_ON          equ     3DFF0200h       ; XX XX1X XXXX XXXX
WRT_OFF         equ     3DFF0000h       ; XX XX0X XXXX XXXX
DEBUG_ON        equ     37FF0000h       ; XX 0XXX XXXX XXXX
DEBUG_OFF       equ     37FF0800h       ; XX 1XXX XXXX XXXX
PROTECT_ON      equ     0FCF0000h       ; 00 XXXX XX00 XXXX
PROTECT_OFF     equ     0FCF3030h       ; 11 XXXX XX11 XXXX

Replacing the appropriate labels and putting the "@" at the beginning of the line to signify inline assembly, the configuration line in our PICBASIC PRO source file becomes:

Some of the newer PIC16 MCUs have multiple configuration words.  An example is the PIC16F88.  When you open the .INC file for these devices, you will see a section of labels denoted with the "DEVICE2" heading:

		; *** DEVICE2 Fuses Definitions
FCMEN_OFF	equ     3FFE0000h       ; XX XXXX XXXX XXX0
FCMEN_ON	equ     3FFE0001h       ; XX XXXX XXXX XXX1
IESO_OFF	equ     3FFD0000h       ; XX XXXX XXXX XX0X
IESO_ON		equ     3FFD0002h       ; XX XXXX XXXX XX1X

When using configuration labels from this section, a special directive "device2" must be used, as follows:

PM will always take the configuration that is placed in the program source code.  There is no need to comment or remove the line in the .INC file.