Using PBP With MPLAB


The PicBasic Pro Compiler can be used within the MPLAB IDE.

First, download the latest release of MPLAB, if you don't have it, from
Microchip's web site (www.microchip.com).   As of this writing, version 6.40
is Microchip's latest release with support for our products.

Install MPLAB and its components.  The default installation directory for
MPLAB is C:\Program Files\MPLAB IDE.  MPASMWIN.EXE is located in the
subdirectory C:\Program Files\MPLAB IDE\Mchip_Tools.

Install the PicBasic Pro Compiler according to the instructions found in its
readme file.  Avoid long directory names in the installation path.  Some
versions will have problems if installed in C:\Program Files\PBP.  It is best
to install the PicBasic Pro Compiler in its default directory, C:\PBP.

The next step is to include both of the install directories within the
search path on your system.  The procedure differs depending on the version
of Windows running.  The melabs web site has details on setting the path for
each version of Windows. (http://melabs.com/support/mplab.htm)

Next, setup PicBasic Pro as a language tool within MPLAB.  Start MPLAB and
select Set Language Tool Locations under the Project menu.  Select the
appropriate Toolsuite Name (PicBasic Pro Compiler).  Use the browse button
to select PBPW.EXE within the subdirectory where it was installed (C:\PBP).

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

To create a BASIC project within MPLAB, run the Project Wizard.  Select 
the desired processor.  Select the appropriate microEngineering Labs, Inc.
Toolsuite (PicBasic Pro Compiler).  Name the project.  Choose the directory
where the source file exists.  Add the source file to the project.  Click
Next, then Finish.  You should now be able to edit the source and build the
project.

MPLAB is limited in the number of characters that are allowed in the path 
to your project. You may encounter problems if you store your project too
deeply within your directory structure.  If you are encountering unexplained 
errors, try storing your project files in a directory closer to the root of
your drive. 



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 and should be used this way.  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 MPASMWIN Information

MPASMWIN may be used with PBP outside of MPLAB.  You may have to edit your
system's path evironment variable as mentioned above.

If the PBP command line option "-ampasmwin" is used, MPASMWIN will be 
launched following compilation to complete the process.  MPASMWIN will 
display its own screen with its progress.

MPASMWIN is not included with PBP and must be obtained from Microchip.  It
can be downloaded as part of the MPLAB development environment.



Microchip ICD/ICD2

PicBasic Pro may be used with Microchip's ICD (In-Circuit Debugger) and
ICD2.  The ICDs require certain resources from the target processor
including access to RAM registers and, in some cases, 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(A) and 877(A):
        Include "ICDDEFS.BAS"

For PIC16F873(A) and 874(A):
        Include "ICDDEFS1.BAS"

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

For PIC18F242, 248, 442 and 448:
        Include "ICDDEFS3.BAS"

For PIC18F252, 258, 452 and 458:
        Include "ICDDEFS4.BAS"

For PIC18F6620, 6720, 8620 and 8720:
        Include "ICDDEFS5.BAS"

For PIC18F1220 and 1320:
        Include "ICDDEFS6.BAS"

For PIC18F2220, 2320, 4220 and 4320:
        Include "ICDDEFS7.BAS"

For PIC16F818 and 819:
        Include "ICDDEFS8.BAS"



PicBasic Pro source level simulation and debugging with MPLAB.

Create a new project (or open 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 Debugger menu, select the debugging tool that you want to use (SIM, 
ICE, or ICD). In the Build Options dialog box, click on the PicBasic Pro tab
and check both "Use MPASM Assembler" and "Source-level Debug".

Compile or build as usual.  Open your source code in a 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 the source window with each
"Step Over".

Always use "Step Over" when doing source-level debug.  If you "Step" (F7),
MPLAB will open the library or macro file from which the PBP command was
assembled.  If you accidentally modify a library file and save it, your PBP
installation will be corrupted.

To run to a particular line, click to place the cursor on the line, then 
right click the mouse and choose "Run to Cursor".  Use this option in the 
PicBasic source window if you accidentally step into the LIB file.

To set a break point, go to the source line of interest and right click the
mouse.  Choose the Break Point menu item.  A small symbol will appear to
the left of the line.

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".  The concerns voiced above apply here.  There is a chance of
corrupting your LIB file.

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.  It may be
desireable to modify a PAUSE 250 to a PAUSE 2 while in simulation mode.
It should work at full speed with an ICE.

