PICBASIC PRO(TM) Compiler 2.50c README.TXT Copyright 2009 microEngineering Labs, Inc.

This software and accompanying documentation is copyright (c) microEngineering Labs, Inc. and Microchip Technology Inc. It may only be used by the licensee of the microEngineering Labs, Inc. PICBASIC PRO(TM) Compiler. Please contact microEngineering Labs, Inc. to license this software. Contact information is listed at the end of this file. The files on this disk should include: BS1DEFS.BAS BS2DEFS.BAS ICDDEFS*.BAS MODEDEFS.BAS MP.EXE MPLAB.TXT PBP.EXE PBPW.EXE able PBPL.EXE xecutable PBP*.LIB PBP*.MAC PBP*.RAM PM.EXE PM.TXT PROMPT.BAS README.TXT *EXT.BAS *.BAS *.BAL *.INC \INC\M*.INC \SAMPLES\*.BAS \USB\*.* \USB18\*.* PICBASIC PRO(TM) Compiler, long 32-bit Windows e PBP library files PBP macro files PBP library RAM files PM Assembler PM Assembler instruction file 18Fxx39 ProMPT motor control API This file External register definitions PBP BASIC include file for each device PBP BASIC include file for each device, long PBP include file for each device PM include file for each device PBP sample programs PIC16C7x5 USB files PIC18Fxxxx USB files BS1 RAM and pin definitions BS2 RAM and pin definitions ICD/ICD2 memory allocation Serial, Shift and X-10 mode definitions Mpasm launcher MPLAB installation/simulation instructions PICBASIC PRO(TM) Compiler PICBASIC PRO(TM) Compiler, 32-bit Windows execut

Version Information Version 2.5 of the PICBASIC PRO(TM) Compiler adds new long variable types for the PIC18Xxxx devices.

PIC18Xxxx Information The 16-bit core 18Xxxx PIC(R) MCUs may now be used with the PICBASIC PRO Compiler. MPASMWIN must be used as the assembler as PM does not support the PIC18Xxxx devices. See the file MPLAB.TXT for more information on how to install MPASMWIN and set it up. Then specify the assembler and device type on the command line using the -a and -p options: PBPW -ampasmwin -p18f452 filename Some MPASMWIN header files include a location labelled Debug. This label will collide with the labels used by the PICBASIC PRO Debug instruction.

To use the compilers Debug instructions on devices that yield a duplicate label error, remove the Debug line from the MPASMWIN header file for the device you are using. Early PIC18Xxxx devices do not include the LFSR assembler op-code. By default, PBP will not use the LFSR op-code but will use a longer method instead. If the PIC18Xxxx device does have the LFSR op-code, a Define may be added to the BASIC program to tell PBP to use it: Define USE_LFSR 1

PIC17Cxxx Information The 16-bit core 17Cxxx PIC(R) MCUs may now be used with the PICBASIC PRO Compiler. Simply specify the device type on the command line using the -p option: PBP -p17c752 filename There is no data direction (TRIS) register for PORTA. Therefore, commands that rely on the TRIS register for their operation, such as I2CRead and I2CWrite, may not be used on PORTA. The default Defines for the LCD are: Define Define Define Define Define Define Define Define LCD_DREG PORTB LCD_DBIT 0 LCD_RSREG PORTB LCD_RSBIT 4 LCD_EREG PORTB LCD_EBIT 5 LCD_BITS 4 LCD_LINES 2 ' ' ' ' ' ' ' ' LCD LCD LCD LCD LCD LCD LCD LCD data pin port data pin bit register select pin port register select pin bit enable pin port enable pin bit number of data bits number of lines

PIC12X5xx, 16X5xx Information On the PIC12X5xx and 16X5xx devices, pin GPIO.2 is forced to an input regardless of the setting of the TRIS register. To allow this pin to be used as a standard I/O pin, add the following line to the beginning of the program: OPTION_REG.5 = 0 The flash data space on these devices that have that feature is implemented differently than most of the other PIC MCUs. While Read and Write are still used to access the data space, a row must be erased using Erasecode before before it can be rewritten. Be sure to copy any other data that needs to be saved from the row before it is erased.

Files Information FILES should be set to at least 75 in your CONFIG.SYS file. It is also a good idea to set BUFFERS to at least 75.

Out of Memory Errors Compiling large PICBASIC PRO source code files can tax the memory of the PC running the compiler. If an Out of Memory error is issued and the FILES and BUFFERS are set as above, an alternate version of PBP can be used. PBPW.EXE has been compiled to make use of all of the memory available to Windows 95, 98, ME, NT, 2000, XP and Vista. You must, of course, be running in a DOS shell from one of those Windows environments or within Microchip's MPLAB or other Windows IDE. To execute the Windows version from the DOS command line, simply substitute PBPW for PBP. PBPW options filename

OPTION Register The actual name of the OPTION register for use by PICBASIC PRO is OPTION_REG. This is the Microchip compatible name so that it can be used within MPLAB. The names of the registers that PICBASIC PRO can use may be found in the files PIC12EXT.BAS, PIC14EXT.BAS, PIC17EXT.BAS and PIC18EXT.BAS.

GPIO, TRISIO Registers The actual name of the port and TRIS register for use by PICBASIC PRO for the PIC12C5xx, 12C67x and 12Fxxx parts is GPIO and TRISIO. These are the Microchip compatible names so that they can be used within MPLAB. The names of the registers that PICBASIC PRO can use may be found in the files PIC12EXT.BAS, PIC14EXT.BAS, PIC17EXT.BAS and PIC18EXT.BAS.

Shared SFR Register Names on PIC18FxxJ5x The addresses of some registers on the PIC18FxxJ5x devices are shared with other registers. The PICBASIC PRO Compiler can access these shared register addresses but the register name that must be used is different than the register name in the Microchip data sheet for the device. These different names allow the compiler to select the alternate address. The affected registers from the Microchip data sheet, followed by the register name that must be used in PBP are shown below: ANCON0 ANCON1 CVRCON MEMCON ODCON1 ODCON2 ODCON3 PADCFG1 ANCON0_ALT ANCON1_ALT CVRCON_ALT MEMCON_ALT ODCON1_ALT ODCON2_ALT ODCON3_ALT PADCFG1_ALT

An example of the usage of these register names in PBP: ANCON0_ALT = $ff ' Set all analog pins to digital

ANCON1_ALT = $ff

Aliases The PICBASIC PRO Compiler allows multiple variable names to point to the same RAM locations. These are generally called aliases. Aliases should only be applied to the originally created variable. There should be no aliases to an alias.

Loader Define A Define tells the compiler that a boot loader, like the melabs Loader, is going to be used to put the program into the PIC(R) MCU. This Define moves the compiler's library code out of the first 4 locations. Define LOADER_USED 1

OSCCAL Defines Some PIC MCUs, notably the PIC12C671, 672, 12CE673, 674, 12F629 and 675 have on-chip RC oscillators. These devices contain an oscillator calibration factor in the last location of code space. The on-chip oscillator may be fine-tuned by acquiring the data from this location and moving it into the OSCCAL register. Two Defines have been created to perform this task automatically each time the program starts. Define OSCCAL_1K 1 Define OSCCAL_2K 1 ' Set OSCCAL for 1K device ' Set OSCCAL for 2K device

Add one of these 2 Defines near the beginning of the PICBASIC PRO program to perform the setting of OSCCAL. These Defines are only for the PIC12X6xx devices. The PIC12C5xx devices set the OSSCAL without using a Define. If a UV erasable device has been erased, the value cannot be read from memory. If one of these Defines is used on an erased part, it will cause the program to loop endlessly. To set the OSCCAL register on an erased part, near the beginning of the program, add the line: OSCCAL = $a0 ' Set OSCCAL register to $a0

The $a0 is merely an example. The part would need to be read before it is erased to obtain the actual OSCCAL value for that particular device. Please see the Microchip data sheets for more information on OSCCAL.

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. The PM 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 PM Information PICBASIC PRO now uses PM Assembler version 4.00 or later to work with the 16-bit core PIC(R) MCUs. Do not use an earlier version of PM with version 2.2 or later of PBP.

Additional Interrupt Information Interrupts in Pro may be BASIC instruction and by On Interrupt instruction fair bit of overhead and accomplished in two manners: the On Interrupt using an assembler interrupt routine. The may be used with any PIC(R) MCU but can add a potential latency.

For 14-bit core parts, interrupts in assembler need to be treated differently depending on whether the device has more than 2K of code space or not. If the device has 2K of code space or less, registers the interrupt handler uses may be save and restored in the handler and the interrupt handler may appear anywhere in the program. If the device has more than 2K of code space, however, PCLATH must be set before jumping to the interrupt handler. This is because PCLATH may be pointing to a different code page than the interrupt handler is in, when an interrupt occurs. Before the PCLATH register can be changed, its current value, along with the current value of the W and STATUS registers must be saved. Once this has been accomplished, the interrupt handler may appear anywhere in the program, as above. There is a stub in the file PBPPIC14.LIB that will automatically set up PCLATH before the interrupt handler is jumped to. However, it needs memory allocated in the BASIC source file for storing the saved values. The following code fragment will allocate this memory. While the stub saves these values, your interrupt handler will need to restore them before exiting. The stub to save the registers is automatically inserted for devices with more that 2K of code space. If the device has 2K or less of code space, the interrupt handler will need to save, as well as, restore the registers. wsave 'wsave1 'wsave2 'wsave3 ssave psave var var var var var var byte $20 system byte $a0 system ' Necessary for devices with RAM in bank1 byte $120 system ' Necessary for devices with RAM in bank2 byte $1a0 system ' Necessary for devices with RAM in bank3 byte bank0 system byte bank0 system

The interrupt section in the manual has more information on interrupts in assembler and BASIC.

Reserved Words As stated in the manual, all of the PICBASIC PRO commands are reserved and may not be used as a program variable or label. Count is an example of this. Since Count is a PICBASIC PRO command, it may not be used as a variable or label. Additionally, the names of the PIC MCU(R) registers listed in the file PIC1*EXT.BAS are also predefined and may not be defined again as something else. Also reserved are the system variables listed in PBPPIC1*.RAM. On and Off are also reserved and may not be used as program variables or labels. If BS1DEFS.BAS, BS2DEFS.BAS or MODEDEFS.BAS are included in the program, all of their contents are now defined and cannot be redefined.

PicStic Information Micromint PicStic users must tell PBP which PicStic is the target so that it can include the proper library. The command line option "-p" should be followed by the name of the PicStic: pbp pbp pbp pbp -pps1 -pps2 -pps3 -pps4 filename filename filename filename

These files specify PIC16F84A as the device. A particular PicStic may contain either a PIC16C84, PIC16F84 or PIC16F84A. pbp pbp pbp pbp -pps1_2k -pps2_2k -pps3_2k -pps4_2k filename filename filename filename

These PicStic 2k files specify PIC16F628 as the device. pbp -pps5 filename This PicStic file specifies PIC16F876 as the device. The PicStic libraries only work with 14-bit core parts, not 12-bit core or 16-bit core PIC17Cxxx and PIC18Xxxx devices.

Temporary Variables PBP creates temporary variables to store intermediate results of expressions. These temporaries are always words and are only created when necessay. They can cause unexpected RAM usage. To see what variables are used, see the .ASM file created by PBP. Math operations are generally 16-bit integer operations. You can usually mix 8- and 16-bit operands with no ill effects. PBP will sort things out and usually give you the result you are looking for. However, certain situations can create problems. As an example, consider the following two code fragments:

Listing 1: addr var

byte

addr = 10 I2CWrite 0,1,$a0,addr,[addr * 2] Listing 2: addr var store var

byte byte

addr = 10 store = addr * 2 I2CWrite 0,1,$a0,addr,[store] These two listing seem as if they should yield the same result. But because of the 16-bit expression handling and word-sized temporary variables, they will do two different things. The program in Listing 2 will write the byte store (which is address * 2 or 20) to I2C address 10. The program in Listing 1 looks like it will do the same thing but in reality, it won't. Instead of writing a single byte 20 to I2C address 10, it will write a word 20 (two consecutive bytes, 0 then 20). This is because the result of the mathematical expression is a word. This problem does not affect very many commands, but it is safer to create your own intermediate variables of the desired size as in Listing 2, rather than to let PBP make all the decisions for you.

Current PIC(R) MCU support: 10F202, 10F206, 10F222: Limited support. 12C508(A), 12C509(A), 12CE518, 12CE519, 12F508, 12F509, 12F510, 12F519, 12F609, 12F615, 12HV609, 12HV615: Limited support. 12C671, 12C672, 12CE673, 12CE674, 12F629, 12F635, 12F675, 12F683: Supported. 14000: Supported. 16C432, 16C433: Supported. 16C505, 16C54(AC), 16C55(A), 16C56(A), 16C57(C), 16C58(B), 16F505, 16F506, 16F526, 16F54, 16F57, 16F59, 16HV540: Limited support. 16C554, 16C557, 16C558, 16C61, 16C62(AB), 16C620(A), 16C621(A), 16C622(A), 16C63(A), 16C64(A), 16C642, 16C65(AB), 16C66, 16C662, 16C67, 16C71, 16C710, 16C711, 16C712, 16C715, 16C716, 16C717, 16C72(A), 16C73(AB), 16C74(AB), 16C745, 16C76, 16C765, 16C77, 16C770, 16C771, 16C773, 16C774, 16C781, 16C782, 16C84, 16C923, 16C924, 16C925, 16C926, 16CE623, 16CE624, 16CE625, 16F610, 16F616, 16F627(A), 16F628(A), 16F630, 16F631, 16F636, 16F639, 16F648A, 16F676, 16F677, 16F684, 16F685, 16F687, 16F688, 16F689, 16F690, 16F716, 16F72, 16F722, 16F723, 16F724, 16F726, 16F727, 16F73, 16F737, 16F74, 16F747, 16F76, 16F767,

16F77, 16F777, 16F785, 16F818, 16F819, 16F83, 16F84(A), 16F87, 16F870, 16F871, 16F872, 16F873(A), 16F874(A), 16F876(A), 16F877(A), 16F88, 16F882, 16F883, 16F884, 16F886, 16F887, 16F913, 16F914, 16F916, 16F917, 16F946, 16HV610, 16HV616, 16HV785, 16LF722, 16LF723, 16LF724, 16LF726, 16LF727: Supported. 17C42A, 17C43, 17C44, 17C752, 17C756(A), 17C762, 17C766: Supported. 18C242, 18C252, 18C442, 18C452, 18C601, 18C658, 18C801, 18C858, 18F1220, 18F1230, 18F1231, 18F1320, 18F1330, 18F1331, 18F2220, 18F2221, 18F2320, 18F2321, 18F2331, 18F2410, 18F242, 18F2420, 18F2423, 18F2431, 18F2439, 18F2450, 18F2455, 18F2458, 18F248, 18F2480, 18F2510, 18F2515, 18F252, 18F2520, 18F2523, 18F2525, 18F2539, 18F2550, 18F2553, 18F258, 18F2580, 18F2585, 18F2610, 18F2620, 18F2680, 18F2682, 18F2685, 18F4220, 18F4221, 18F4320, 18F4321, 18F4331, 18F4410, 18F442, 18F4420, 18F4423, 18F4431, 18F4439, 18F4450, 18F4455, 18F4458, 18F448, 18F4480, 18F4510, 18F4515, 18F452, 18F4520, 18F4523, 18F4525, 18F4539, 18F4550, 18F4553, 18F458, 18F4580, 18F4585, 18F4610, 18F4620, 18F4680, 18F4682, 18F4685, 18F6310, 18F6390, 18F6393, 18F6410, 18F6490, 18F6493, 18F6520, 18F6525, 18F6527, 18F6585, 18F6620, 18F6621, 18F6622, 18F6627, 18F6628, 18F6680, 18F6720, 18F6722, 18F6723, 18F8310, 18F8390, 18F8393, 18F8410, 18F8490, 18F8493, 18F8520, 18F8525, 18F8527, 18F8585, 18F8620, 18F8621, 18F8622, 18F8627, 18F8628, 18F8680, 18F8720, 18F8722, 18F8723: Supported. 18F24J10, 18F25J10, 18F64J90, 18F65J10, 18F66J11, 18F66J15, 18F67J10, 18F67J11, 18F84J90, 18F85J10, 18F86J11, 18F86J15, 18F87J10, 18F87J11, Supported. 18F44J10, 18F65J11, 18F66J16, 18F67J50, 18F85J11, 18F86J16, 18F87J50, 18F45J10, 18F65J15, 18F66J50, 18F67J60, 18F85J15, 18F86J50, 18F87J60, 18F63J11, 18F65J50, 18F66J55, 18F83J11, 18F85J50, 18F86J55, 18F96J60, 18F63J90, 18F65J90, 18F66J60, 18F83J90, 18F85J90, 18F86J60, 18F96J65, 18F64J11, 18F66J10, 18F66J65, 18F84J11, 18F86J10, 18F86J65, 18F97J60:

18F23K20, 24K20, 25K20, 26K20, 43K20, 44K20, 45K20, 46K20: Supported. PicStic1, PicStic1 2k, PicStic2, PicStic2 2k, PicStic3, PicStic3 2k, PicStic4, PicStic4 2k, PicStic5: Supported. rfPIC12C509AF, rfPIC12C509AG: Limited support as base device PIC12C509A. rfPIC12F675F, rfPIC12F675H, rfPIC12F675K: Supported as base device PIC12F675.

PICBASIC PRO is a trademark of Microchip Technology Inc. in the U.S.A. and other countries. MPLAB and PIC are registered trademarks of Microchip Technology Inc. in the U.S.A. and other countries. microEngineering Labs, Inc. Box 60039 Colorado Springs CO 80960-0039 USA (719) 520-5323 (719) 520-1867 fax http://www.melabs.com email:support@melabs.com