Using PBP With MPLAB The PICBASIC PRO(TM) 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 8.10 is Microchip's latest release. Install MPLAB and its components. The default installation directory for MPLAB is C:\Program Files\Microchip. MPASMWIN.EXE is located in the subdirectory C:\Program Files\Microchip\MPASM Suite. Install the PICBASIC PRO(TM) Compiler according to the instructions found in its readme file. Avoid long directory names or spaces in the installation path. 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) and then Executables. 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 under the Project menu. 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 included 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 uppercase 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

PICBASIC PRO programs may be analyzed using the MPLAB simulator, ICD or ICE at either the assembler or BASIC source level. The generated COD or COFF file contains the information necessary to do this. COD files are limited to a memory size of 64K bytes. If you want to debug on a device with more memory than this, such as the PIC16F6720 or 8720, you will need to select "Use Linker/COFF Debugging" under the project Build Options dialog. Note that this selection eliminates some of the code optimization the compiler performs so do not select this option unless necessary. A linker file is needed for the specific device you are using. An example linker file, 18F6720.LKR, is provided in the PBP directory. The steps required for source level debugging are: 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 PRO 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 include: 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.

PICBASIC PRO is a trademark of Microchip Technology Inc. in the U.S.A. and other countries. MPLAB, PIC and PICmicro are registered trademarks of Microchip Technology Inc. in the U.S.A. and other countries.