Using PBP With MPLAB


With the latest releases of Microchip's MPLAB , the PicBasic and PicBasic Pro
Compiler can now be used within the IDE.

First, download the latest release of MPLAB, if you don't have it, from
Microchip's web site (www.microchip.com).  Install MPLAB and make sure it is
in your DOS path.  This last step is important, even if you are using
Windows.

You must alter the path statement in the DOS AUTOEXEC.BAT file to include the
path to the directory where MPLAB was installed.  You must also reboot after
this change to the path.  Not making this addition to the path leads to
unsuccessful builds as PicBasic Pro cannot find MPASM and its include files.

The PicBasic Pro Compiler should also have been installed into its own
subdirectories by this point.


Setup

Start MPLAB and select Install Language Tool under the Project menu.  Select
microEngineering Labs, Inc. as the Language Suite.  Select the appropriate
Tool Name (PicBasic Pro Compiler).  Use the browse button to select PBP.EXE
or PBPW.EXE within the subdirectory where it was installed as the Executable.
Select the Command-line radio button and click OK to finish up.

Installation of the compiler into MPLAB is now complete.  You can now write,
edit, simulate and program BASIC projects from within MPLAB.


Operation

To create a BASIC project within MPLAB, select New Project under the Project
menu.  Navigate to the subdirectory into which the PicBasic Pro Compiler was
installed.  The project and its associated files must exist in the compiler's
subdirectory in order for all of the include files to be found.  Enter a new
project name such as BLINK.PJT and click OK.  The Edit Project window should
pop up.

Select the desired processor type using the Change button next to Development
Mode.

Select microEngineering Labs, Inc. as the Language Tool Suite.

Click on the name of the project under Project Files and then click the Node
Properties button.  The Node Properties window should pop up.

Select the desired Language Tool for the project (PicBasic Pro Compiler). The
rest of the defaults should be OK so click OK to exit.

Click the Add Node button to add your BASIC source file to the project, or
click OK and File|New to begin a new source file.

That's all (!!!) there is to it.  You can now select Make or Build to compile
your program.



Additional Case Sensitivity Information

As the PicBasic Pro manual points out, the PicBasic Pro Compiler itself is
not case sensitive.  This means, for example, LOOP: would be the same label
as loop: or even LoOp:.

The assemblers that are launched by PBP, on the other hand, are of varying
degrees of case sensitivity.  PM, the PICmicro Macro Assembler, is also case
insensitive.

MPASM defaults to case sensitive.  Normally this will have no noticable
effect on programs, unless in-line assembly code is used.  PBP DEFINEs like
OSC and the LCD definitions must be in all upper-case as shown in the
examples in the manual.



Additional MPASM Information

MPASM may be used with PBP in two ways.  If the command line option "-ampasm"
is used, MPASM will be launched following compilation to complete the
process.  MPASM will display its own screen with its progress.

Alternatively, the command line option "-amp" will launch MPASM in quiet mode
and only display any errors.  However, the launcher consumes additional
memory that is therefore not available to MPASM.

For maximum memory availability to MPASM, the command line option "-ampasm"
or "-ampasmwin" should be used.

In any case, MPASM is not included with PBP and must be obtained from
Microchip.



Microchip ICD

PicBasic Pro may be used with Microchip's ICD (In-Circuit Debugger).  The ICD
requires certain resources from the target processor including access to 6
RAM registers and the first location of code space.

Several files have been created to allocate these locations to the ICD and
remove them from the resources the PicBasic Pro program has access to.  When
it is desired to use the ICD, simply include one of these files at the
beginning of the PicBasic Pro program.

For PIC16F876 and 877:
        Include "ICDDEFS.BAS"

For PIC16F873 and 874:
        Include "ICDDEFS1.BAS"

For PIC16F870, 16F871 and 872:
        Include "ICDDEFS2.BAS"



PicBasic Pro source level simulation and debugging with MPLAB 5.xx.

Create a new project (or edit a previous one) in MPLAB using PicBasic Pro as
the Language suite.  The executable must be set for PBPW.EXE in order for the
simulator or ICE to work properly.  If you haven't installed the compiler in
MPLAB, refer to the installation instructions elsewhere in this document or
online at melabs.com.

In the Edit Project window, change the Development Mode to indicate which
tool you want to use (SIM, ICE, or ICD). Click to highlight the [.hex] node,
and click Node Properties.  The language tool should be PicBasic Pro
Compiler.  Select MPASMWIN as the assembler, and add "-z" to the
"Additional command line parameters" field.

Compile or build as usual.  Open your source code in a window, and open the
absolute listing file in another window.  Click somewhere on the source code
window to set the focus (make the title bar on this window turn blue).

To start source level debugging press the "Step Over" icon or key F8.  You
should see the highlighted line move in both windows.  If you wish to step
through the assembly code, set the focus to the window that holds the listing
file.

Always use "Step Over" unless you wish to step into a Gosub or Call.  To step
into a Gosub or Call, use the "Step" icon or key F7.  Most PBP commands call
assembly language routines.  If you use Step (F7) instead of Step Over (F8),
the focus will change to the listing file and program execution will be
performed there.  This can be confusing at first.  If you wish only to step
through PicBasic code, only use Step at a Gosub or Call command.  Use Step
Over at all other times.

To run to a particular line, right click the mouse and choose "Run to Here".
Use this option in the PicBasic window when you want to return from the
assembly code to the PicBasic code.

To set a break point, go to the source line of interest and right click the
mouse.  Choose the Break Point menu item.  The line will change colors.
(Default: red).

Some instructions that make multiple calls will require multiple "Step Over"
clicks.  It will usually be one click for each command parameter.  You will
see the "pc" program counter at the info-bar at the bottom of MPLAB increment
for each item.  Since it is part of the same Basic command, the
"current line" will remain the same. Example: DEBUG "Hello" requires five
"Step Over" clicks.

Command's that may require multiple "Step Over" clicks:
DEBUG, DEBUGIN, DTMFOUT, FREQOUT, HSERIN, HSEROUT, I2CREAD, I2CWRITE, LCDIN,
LCDOUT, SERIN, SERIN2, SEROUT, SEROUT2, SHIFTIN, SHIFTOUT, SOUND, XIN, XOUT,
Complex expression like x = y * z / a that have library calls for multiply
and divide.


Notes:

MPLAB's "Animation" will move the source through at the assembly language
level mixed with the Basic source level since animation is fully based on
"Step".

Unfortunately, "Step Over" does not work in Microchip's ICD.  You will need
to use "Step".  As detailed above, some instructions will step in Basic using
"Step" and some will step in assembler.

In simulator mode certain timed functions like PAUSE and PAUSEUS do not
operate at their real-time speed but are simulated very slowly.  A
"PAUSE 250" may have to be modified to a PAUSE 2 while in simulation mode.
It should work properly with an ICE though.
