mikroElektronika

Development tools - Books - Compilers

www.mikroe.com

User’s manual PASCAL Compiler for Microchip PIC microcontrollers

mikroPASCAL
Making it simple

Develop your applications quickly and easily with the world's

mikro

most intuitive Pascal compiler for PIC Microcontrollers (families

ICD
IN-CIRCUIT
PIC12, PIC16, and PIC18).

Highly sophisticated IDE provides the power you need with the
simplicity of a Windows based point-and-click environment.
DEBUGGER
With useful implemented tools, many practical code examples,
broad set of built-in routines, and a comprehensive Help,
SUPPORTED mikroPascal makes a fast and reliable tool, which can satisfy
from V6.0 needs of experienced engineers and beginners alike.
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Reader’s note

DISCLAIMER:
mikroPascal and this manual are owned by mikroElektronika and are protected by copyright
law and international copyright treaty. Therefore, you should treat this manual like any other
copyrighted material (e.g., a book). The manual and the compiler may not be copied, par-
tially or as a whole without the written consent from the mikroElektronika. The PDF-edition
of the manual can be printed for private or local use, but not for distribution. Modifying the
manual or the compiler is strictly prohibited.

HIGH RISK ACTIVITIES

The mikroPascal compiler is not fault-tolerant and is not designed, manufactured or intended
for use or resale as on-line control equipment in hazardous environments requiring fail-safe
performance, such as in the operation of nuclear facilities, aircraft navigation or communica-
tion systems, air traffic control, direct life support machines, or weapons systems, in which
the failure of the Software could lead directly to death, personal injury, or severe physical or
environmental damage ("High Risk Activities"). mikroElektronika and its suppliers specifically
disclaim any express or implied warranty of fitness for High Risk Activities.

LICENSE AGREEMENT:
By using the mikroPascal compiler, you agree to the terms of this agreement. Only one
person may use licensed version of mikroPascal compiler at a time.
Copyright © mikroElektronika 2003 - 2006.

This manual covers mikroPascal version 6.0.2 and the related topics. New versions may
contain changes without prior notice.

COMPILER BUG REPORTS:

The compiler has been carefully tested and debugged. It is, however, not possible to
guarantee a 100% error free product. If you would like to report a bug, please contact us at
the address office@mikroe.com. Please include the following information in your bug report:
- Your operating system
- Version of mikroPascal
- Code sample
- Description of a bug

CONTACT US:
mikroElektronika
Voice: + 381 (11) 30 66 377, + 381 (11) 30 66 378
Fax: + 381 (11) 30 66 379
Web: www.mikroe.com
E-mail: office@mikroe.com

PIC, PICmicro and MPLAB is a Registered trademark of Microchip company. Windows is a

Registered trademark of Microsoft Corp. All other trade and/or services marks are the
property of the respective owners.

page

ii
mikroElektronika: Development tools - Books - Compilers
mikr oPascal User ’s manual

Table of Contents

CHAPTER 1 mikroPascal IDE

CHAPTER 2 Building Applications

CHAPTER 3 mikroPascal Reference

CHAPTER 4 mikroPascal Libraries

mikroElektronika: Development tools - Books - Compilers

 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CHAPTER 1: mikroPascal IDE 1

Quick Overview 1
Code Editor 3
Code Explorer 6
Debugger 7
Error Window 10
Statistics 11
Integrated Tools 14
Keyboard Shortcuts 17

CHAPTER 2: Building Applications 19

Projects 20
Source Files 21
Search Paths 21
Managing Source Files 21
Compilation 23
Output Files 23
Assembly View 23
Error Messages 24

CHAPTER 3: mikroPascal Language Reference 27

PIC Specifics 28
mikroPascal Specifics 30
Predefined Globals and Constants 30
Accessing Individual Bits 30
Interrupts 31
Linker Directives 32
Code Optimization 34
mikro ICD (In-Circuit Debugger) 35
mikro ICD Debugger Options 37
mikro ICD Debugger Example 38
mikro ICD Overview 42
Lexical Elements 44
Whitespace 44
Comments 45
Tokens 46

page

iv
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Literals 47
Integer Literals 47
Floating Point Literals 47
Character Literals 48
String Literals 48
Keywords 49
Identifiers 50
Punctuators 51
Program Organization 53
Scope and Visibility 56
Units 57
Uses Clause 57
Main Unit 58
Other Units 59
Variables 60
Constants 61
Labels 62
Functions and Procedures 63
Functions 63
Procedures 64
Types 66
Simple Types 67
Arrays 68
Multi-Dimnesional Arrays 69
Strings 70
Pointers 72
Records 73
Types Conversions 75
Implicit Conversion 75
Explicit Conversion 76
Arithmetic Conversion 77
Operators 78
Precedence and Associativity 78
Arithmetic Operators 79
Relational Operators 80
Bitwise Operators 81
Expressions 85
Statements 86
asm Statement 86
Migration from older versions 87
Assignment Statements 88
Compound Statements 88
Conditional Statements 89
Iteration Statements 91
Jump Statements 93

page
mikroElektronika: Development tools - Books - Compilers
v
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Compiler Directives 96

CHAPTER 4: mikroPascal Libraries 99

Built-in Routines 100

Library Routines 106
ADC Library 107
CAN Library 109
CAN Constants 115
CANSPI Library 121
Compact Flash Library 130
EEPROM Library 142
Ethernet Library 144
SPI Ethernet Library 156
Flash Memory Library 163
I2C Library 165
Keypad Library 170
LCD Library (4-bit interface) 174
LCD Library (8-bit interface) 180
Graphic LCD Library 184
T6963C Graphic LCD Library 194
Manchester Code Library 210
Multi Media Card Library 217
OneWire Library 230
PS/2 Library 234
PWM Library 237
RS-485 Library 241
Software I2C Library 247
Software SPI Library 251
Software UART Library 254
Sound Library 257
SPI Library 259
USART Library 263
USB HID Library 269
Util Library 274
Conversions Library 275
Delays Library 281
Math Library 283
String Library 290
Port Expander Library 298
SPI Graphic LCD Library 306
SPI LCD Library (4-bit interface) 317
SPI LCD Library (8-bit interface) 322
SPI T6963C Graphic LCD Library 327
Contact Us 343

page

vi
mikroElektronika: Development tools - Books - Compilers
 CHAPTER
1

mikroPascal IDE
QUICK OVERVIEW

mikroPascal is a powerful, feature rich development tool for PIC microcontrollers.

It is designed to provide the customer with the easiest possible solution for
developing applications for embedded systems, without compromising perform-
ance or control.

Highly advanced IDE, broad set of hardware libraries, comprehensive

documentation, and plenty of ready to run examples should be more than enough
to get you started in programming PIC microcontrollers.

MikroElektronika: Development tools - Books - Compilers

 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Watch
Window

Code
Explorer

Code
Editor

Error
Window
Code Breakpoints
Assistant Window

mikroPascal allows you to quickly develop and deploy complex applications:

- Write your Pascal source code using the highly advanced Code Editor

- Use the included mikroPascal libraries to dramatically speed up development:

data acquisition, memory, displays, conversions, communications…

- Generate commented, human-readable assembly, and standard HEX compatible

with all programmers.

- Inspect program flow and debug executable logic with the integrated Debugger.
Get detailed reports and graphs on code statistics, assembly listing, calling tree…

- We have provided plenty of examples for you to expand, develop, and use as
building bricks in your projects.

page

2
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CODE EDITOR
The Code Editor is advanced text editor fashioned to satisfy the needs of profes-
sionals. General code editing is same as working with any standard text-editor,
including familiar Copy, Paste, and Undo actions, common for Windows environ-
ment.

Advanced Editor features include:

- Adjustable Syntax Highlighting

- Code Assistant
- Parameter Assistant
- Code Templates
- Auto Correct for common typos
- Bookmarks and Goto Line

You can customize these options from te Editor Settings dialog. To access the
settings, click Tools > Options from the drop-down menu, or click the Tools icon.

Tools Icon.

page
mikroElektronika: Development tools - Books - Compilers
3
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Code Assistant [CTRL+SPACE]

If you type first few letter of a word and then press CTRL+SPACE, all valid iden-
tifiers matching the letters you typed will be prompted to you in a floating panel
(see the image). Now you can keep typing to narrow the choice, or you can select
one from the list using keyboard arrows and Enter.

Parameter Assistant [CTRL+SHIFT+SPACE]

The Parameter Assistant will be automatically invoked when you open a parenthe-
sis "(" or press CTRL+SHIFT+SPACE. If name of valid function or procedure
precedes the parenthesis, then the expected parameters will be prompted to you in
a floating panel. As you type the actual parameter, next expected parameter will
become bold.

Code Template [CTR+J]

You can insert the Code Template by typing the name of the template (for
instance, whileb), then press CTRL+J, and Editor will automatically generate
code. Or you can click button from Code toolbar and select template from the list.

You can add your own templates to the list. Just select Tools > Options from the
drop-down menu, or click the Tools Icon from the Settings Toolbar, and then
select the Auto Complete Tab. Here you can enter the appropriate keyword,
description, and code of your template.

page

4
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Auto Correct

The Auto Correct feature corrects common typing mistakes. To access the list of
recognized typos, select Tools > Options from the drop-down menu, or click the
Tools Icon from the Settings Toolbar, and then select the Auto Correct Tab. You
can also add your own preferences to the list.

Comment/Uncomment

Comment / The Code Editor allows you to comment or uncomment selected block of code by
Uncomment Icon.
a simple click of a mouse, using the Comment/Uncomment icons from the Code
Toolbar.

Bookmarks

Bookmarks make navigation through large code easier.

CTRL+<number> : Goto bookmark

CTRL+SHIFT+<number> : Set bookmark

Goto Line

Goto Line option makes navigation through large code easier. Select Search >
Goto Line from the drop-down menu, or use the shortcut CTRL+G.

page
mikroElektronika: Development tools - Books - Compilers
5
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CODE EXPLORER
Code Explorer is placed to the left of the main window by default, and gives clear
view of every declared item in the source code. You can jump to declaration of
any item by right clicking it, or by clicking the Find Declaration icon. To expand
or collapse treeview in the Code Explorer, use the Collapse/Expand All icon.

Also, two more tab windows are available in the Code Explorer. QHelp Tab lists
all the available built-in and library functions, for a quick reference. Double-click-
Collapse/Expand ing a routine in QHelp Tab opens the relevant Help topic. Keyboard Tab lists all
All Icon. available keyboard shortcuts in mikroPascal.

page

6
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

DEBUGGER
Source-level Debugger is an integral component of mikroPascal development
environment. It is designed to simulate operations of Microchip Technology's
PICmicros and to assist users in debugging software written for these devices.
Start Debugger.

Debugger simulates program flow and execution of instruction lines, but does not
fully emulate PIC device behavior: it does not update timers, interrupt flags, etc.

After you have successfully compiled your project, you can run Debugger by
selecting Run > Debug from the drop-down menu, or by clicking Debug Icon .
Starting the Debugger makes more options available: Step Into, Step Over, Run to
Cursor, etc. Line that is to be executed is color highlighted.

Debug [F9]
Start the Debugger.
Pause Debugger.
Run/Pause Debugger [F6]
Run or pause the Debugger.

Step Into [F7]

Execute the current Pascal (single– or multi–cycle) instruction, then halt. If the
Step Into.
instruction is a routine call, enter the routine and halt at the first instruction fol-
lowing the call.

Step Over [F8]

Execute the current Pascal (single– or multi–cycle) instruction, then halt. If the
Step Over.
instruction is a routine call, skip it and halt at the first instruction following the
call.

Step Out [Ctrl+F8]

Execute the current Pascal (single– or multi–cycle) instruction, then halt. If the
Step Out.
instruction is within a routine, execute the instruction and halt at the first instruc-
tion following the call.

Run to cursor [F4]

Executes all instructions between the current instruction and the cursor position.
Run to Cursor.

page
mikroElektronika: Development tools - Books - Compilers
7
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Jump to Interrupt [F2]

Jump to address $04 for PIC12/16 or to address $08 for PIC18 and execute the
Jump to Interrupt.
procedure located at that address.

Toggle Breakpoint [F5]

Toggle breakpoint at the current cursor position. To view all the breakpoints, select
Toggle
Run > View Breakpoints from the drop-down menu. Double clicking an item in
Breakpoint. window list locates the breakpoint.

Watch Window

Debugger Watch Window is the main Debugger window which allows you to
monitor program items while running your program. To show the Watch Window,
select View > Debug Windows > Watch Window from the drop-down menu.

The Watch Window displays variables and registers of PIC, with their addresses
and values. Values are updated as you go through the simulation. Use the drop-
down menu to add and remove the items that you want to monitor. Recently
changed items are colored red.

Double clicking an item opens the Edit Value window in which you can assign a
new value to the selected variable/register. Also, you can change view to binary,
hex, char, or decimal for the selected item.

page

8
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Stopwatch Window

Debugger Stopwatch Window is available from the drop-down menu,

View > Debug Windows > Stopwatch.

The Stopwatch Window displays the current count of cycles/time since the last
Debugger action. Stopwatch measures the execution time (number of cycles) from
the moment Debugger is started, and can be reset at any time. Delta represents the
number of cycles between the previous instruction line (line where the Debugger
action was performed) and the active instruction line (where the Debugger action
landed).

Note: You can change the clock in the Stopwatch Window; this will recalculate
values for the newly specified frequency. Changing the clock in the Stopwatch
Window does not affect the actual project settings – it only provides a simulation.

View RAM Window

Debugger View RAM Window is available from the drop-down menu,

View > Debug Windows > View RAM.

The View RAM Window displays the map of PIC’s RAM, with recently changed
items colored red. You can change value of any field by double-clicking it.

page
mikroElektronika: Development tools - Books - Compilers
9
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

ERROR WINDOW
In case that errors were encountered during compiling, compiler will report them
and won't generate a hex file. The Error Window will be prompted at the bottom
of the main window.

The Error Window is located under message tab, and displays location and type of
errors compiler has encountered. The compiler also reports warnings, but these do
not affect generating hex code. Only errors can interefere with generation of hex.

Double click the message line in the Error Window to highlight the line where the
error was encountered.

Consult the Error Messages for more information about errors recognized by the
compiler.

page

10
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

STATISTICS
After successful compilation, you can review statistics of your code. Select Project
> View Statistics from the drop-down menu, or click the Statistics icon. There are
Statistics Icon. six tab windows:

Memory Usage Window

Provides overview of RAM and ROM memory usage in form of histogram.

Procedures (Graph) Window

Displays functions in form of histogram, according to their memory allotment.

page
mikroElektronika: Development tools - Books - Compilers
11
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Procedures (Locations) Window

Displays how functions are distributd in microcontroller’s memory.

Procedures (Details) Window

Displays complete call tree, along with details for each procedure and function:

size, start and end address, calling frequency, return type, etc.

page

12
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

RAM Window
Summarizes all GPR and SFR registers and their addresses. It also displays sym-
bolic names of variables and their addresses.

ROM Window
Lists op-codes and their addresses in form of a human readable hex code.

page
mikroElektronika: Development tools - Books - Compilers
13
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

INTEGRATED TOOLS
USART Terminal
mikroPascal includes the USART (Universal Synchronous Asynchronous Receiver
Transmitter) communication terminal for RS232 communication. You can launch
it from the drop-down menu Tools > Terminal or by clicking the Terminal icon.

ASCII Chart
The ASCII Chart is a handy tool, particularly useful when working with LCD dis-
play. You can launch it from the drop-down menu Tools > ASCII chart.

page

14
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

7 Segment Display Decoder

The 7seg Display Decoder is a convenient visual panel which returns decimal/hex
value for any viable combination you would like to display on 7seg. Click on the
parts of 7 segment image to the left to get the desired value in the edit boxes. You
can launch it from the drop-down menu Tools > 7 Segment Display.

EEPROM Editor
EEPROM Editor allows you to easily manage EEPROM of PIC microcontroller.

page
mikroElektronika: Development tools - Books - Compilers
15
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

mikroBootloader

mikroBootloader can be used only with PICmicros that support flash write.

1. Load the PIC with the appropriate hex file using the conventional programming
techniques (e.g. for PIC16F877A use p16f877a.hex).
2. Start mikroBootloader from the drop-down menu Tools > Bootoader.
3. Click on Setup Port and select the COM port that will be used. Make sure that
BAUD is set to 9600 Kpbs.
4. Click on Open File and select the HEX file you would like to upload.
5. Since the bootcode in the PIC only gives the computer 4-5 sec to connect, you
should reset the PIC and then click on the Connect button within 4-5 seconds.
6. The last line in then history window should now read “Connected”.
7. To start the upload, just click on the Start Bootloader button.
8. Your program will written to the PIC flash. Bootloader will report an errors that
may occur.
9. Reset your PIC and start to execute.

The boot code gives the computer 5 seconds to get connected to it. If not, it starts
running the existing user code. If there is a new user code to be downloaded, the
boot code receives and writes the data into program memory.

The more common features a bootloader may have are listed below:

- Code at the Reset location.

- Code elsewhere in a small area of memory.
- Checks to see if the user wants new user code to be loaded.
- Starts execution of the user code if no new user code is to be loaded.
- Receives new user code via a communication channel if code is to be loaded.
- Programs the new user code into memory.

Integrating User Code and Boot Code

The boot code almost always uses the Reset location and some additional program
memory. It is a simple piece of code that does not need to use interrupts; therefore,
the user code can use the normal interrupt vector at 0x0004. The boot code must
avoid using the interrupt vector, so it should have a program branch in the address
range 0x0000 to 0x0003. The boot code must be programmed into memory using
conventional programming techniques, and the configuration bits must be pro-
grammed at this time. The boot code is unable to access the configuration bits,
since they are not mapped into the program memory space.

page

16
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

KEYBOARD SHORTCUTS
Below is the complete list of keyboard shortcuts available in mikroPascal IDE.
You can also view keyboard shortcuts in the Code Explorer, tab Keyboard.

IDE Shortcuts

F1 Help
CTRL+SHIFT+E Edit Project
Ctrl+N New Unit
Ctrl+O Open
SHIFT+F9 Build all
Ctrl+F9 Compile
F11 Program
F12 Options
CTRL+F11 Compile and program
Ctrl+Shift+F5 View breakpoints

Basic Editor shortcuts

F3 Find, Find Next

CTRL+A Select All
CTRL+C Copy
CTRL+F Find
CTRL+P Print
CTRL+R Replace
CTRL+S Save unit
CTRL+SHIFT+S Save As
CTRL+V Paste
CTRL+X Cut
CTRL+Y Redo
CTRL+Z Undo

page
mikroElektronika: Development tools - Books - Compilers
17
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Advanced Editor shortcuts

Ctrl+Space Code Assistant

Ctrl+Shift+Space Parameter Assistant
Ctrl+D Find declaration
CTRL+E Incremental search
Ctrl+G Goto line
Ctrl+J Insert Code Template
Ctrl+L Procedures list
CTRL+/ Toggle line comment
Ctrl+number Goto bookmark
Ctrl+Shift+number Set bookmark
Ctrl+Shift+I Indent selection
Ctrl+Shift+U Unindent selection
Alt+Select Select columns
Tab Indent selection
Shift+Tab Unindent selection
Ctrl+Alt+Select Select columns
Alt+F3 Find in files

Debugger Shortcuts

F4 Run to Cursor
F5 Toggle Breakpoint
F6 Run/Pause Debugger
F7 Step into
F8 Step over
Ctrl+F8 Step out
F9 Debug
F2 Jump to Interrupt
Ctrl+F2 Reset
Ctrl+F5 Add to watch

page

18
mikroElektronika: Development tools - Books - Compilers
 CHAPTER
2

Building
Applications
Creating applications in mikroPascal is easy and intuitive. Project Wizard allows
you to set up your project in just few clicks: name your application, select chip,
set flags, and get going.

mikroPascal allows you to distribute your projects in as many units as you find
appropriate. You can then share your mikroCompiled Libraries (.mcl files) with
other developers without disclosing the source code. The best part is that you can
use .mcl bundles created by mikroBasic or mikroC!

mikroElektronika: Development tools - Books - Compilers

 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

PROJECTS
mikroPascal organizes applications into projects, consisting of a single project file
(extension .ppp) and one or more source files (extension .ppas). You can com-
pile source files only if they are part of a project.

Project file carries the following information:

- project name and optional description

- target device
- device flags (config word) and device clock
- list of project source files with paths

New Project

New Project. The easiest way to create project is by means of New Project Wizard, drop-down
menu Project > New Project. Just fill the dialog with desired values (project name
and description, location, device, clock, config word) and mikroPascal will create
the appropriate project file.

Also, an empty source file named after the project will be created by default.
mikroPascal does not require you to have source file named same as the project,
it’s just a matter of convenience.

Editing Project

Edit Project. Later, you can change project settings from the drop-down menu Project > Edit.
You can add or remove source files from project, rename the project, modify its
description, change chip, clock, config word, etc.

To delete a project, simply delete the folder in which the project file is stored.

page

20
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SOURCE FILES
Source files containing Pascal code should have the extension .ppas. List of
source files relevant for the application is stored in project file with extension
.ppp, along with other project information. You can compile source files only if
they are part of a project.

Search Paths

You can specify your own custom search paths. This can be configured by select-
ing Tools > Options from the drop-down menu and Compiler > Search Paths.

When including source files with the uses clause, mikroPascal will look for the
file in following locations, in this particular order:

1. mikroPascal installation folder > “defs” folder

2. mikroPascal installation folder > “uses” folder
3. your custom search paths
4. the project folder (folder which contains the project file .ppp)

Managing Source Files

Creating a new source file

New File. To create a new source file, do the following:

Select File > New from the drop-down menu, or press CTRL+N, or click the New
File icon. A new tab will open, named “Untitled1”. This is your new source file.
Select File > Save As from the drop-down menu to name it the way you want.

If you have used New Project Wizard, an empty source file, named after the proj-
ect with extension .ppas, is created automatically. mikroPascal does not require
you to have source file named same as the project, it’s just a matter of conven-
ience.

page
mikroElektronika: Development tools - Books - Compilers
21
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Opening an Existing File

Open File. Select File > Open from the drop-down menu, or press CTRL+O, or click the
Open File icon. The Select Input File dialog opens. In the dialog, browse to the
location of the file you want to open and select it. Click the Open button.
The selected file is displayed in its own tab. If the selected file is already open, its
current Editor tab will become active.

Printing an Open File

Print File.
Make sure that window containing the file you want to print is the active window.
Select File > Print from the drop-down menu, or press CTRL+P, or click the Print
icon. In the Print Preview Window, set the desired layout of the document and
click the OK button. The file will be printed on the selected printer.

Saving File

Save File.
Make sure that window containing the file you want to save is the active window.
Select File > Save from the drop-down menu, or press CTRL+S, or click the Save
icon. The file will be saved under the name on its window.

Saving File Under a Different Name

Save File As. Make sure that window containing the file you want to save is the active window.
Select File > Save As from the drop-down menu, or press SHIFT+CTRL+S. The
New File Name dialog will be displayed. In the dialog, browse to the folder where
you want to save the file. In the File Name field, modify the name of the file you
want to save. Click the Save button.

Closing a File

Close File. Make sure that tab containing the file you want to close is the active tab. Select
File > Close from the drop-down menu, or right click the tab of the file you want
to close in Code Editor. If the file has been changed since it was last saved, you
will be prompted to save your changes.

page

22
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

COMPILATION
When you have created the project and written the source code, you will want to
compile it. Select Project > Build from the drop-down menu, or click the Build
Build Icon. Icon, or simply hit CTRL+F9.

Progress bar will appear to inform you about the status of compiling. If there are
errors, you will be notified in the Error Window. If no errors are encountered,
mikroPascal will generate output files.

Output Files

Upon successful compilation, mikroPascal will generate output files in the project
folder (folder which contains the project file .ppp). Output files are summarized
below:

Intel HEX file (.hex)

Intel style hex records. Use this file to program PIC MCU.

Binary mikro Compiled Library (.mcl)

Binary distribution of application that can be included in other projects.

List File (.lst)

Overview of PIC memory allotment: instruction addresses, registers, routines, etc.

Assembler File (.asm)

Human readable assembly with symbolic names, extracted from the List File.

Assembly View

After compiling your program in mikroPascal, you can click the View Assembly
Icon or select Project > View Assembly from the drop-down menu to review gen-
View Assembly erated assembly code (.asm file) in a new tab window. The assembler is human
Icon. readable with symbolic names. All physical addresses and other information can
be found in Statistics or in list file (.lst).

If the program is not compiled and there is no assembly file, starting this option
will compile your code and then display assembly.

page
mikroElektronika: Development tools - Books - Compilers
23
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

ERROR MESSAGES
Error Messages

Message Message Number

Error: "%s" is not a valid identifier 1

Error: Unknown type "%s" 2

Error: Identifier "%s" was not declared 3

Error: Expected "%s" but "%s" found 4

Error: Argument is out of range 5

Error: Syntax error in additive expression 6

Error: File "%s" not found 7

Error: Invalid command "%s" 8

Error: Not enough parameters 9

Error: Too many parameters 10

Error: Too many characters 11

Error: Actual and formal parameters must be identical 12

Error: Invalid ASM instruction: "%s" 13

Error: Identifier "%s" has been already declared 14

Error: Syntax error in multiplicative expression 15

Error: Definition file for "%s" is corrupted 16

page

24
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hint and Warning Messages

Message Message Number

Hint: Variable "%s" has been declared, but was not used 1

Warning: Variable "%s" is not initialized 2

Warning: Return value of the function "%s" is not defined 3

Hint: Constant "%s" has been declared, but was not used 4

Warning: Identifier "%s" overrides declaration in unit "%s" 5

page
mikroElektronika: Development tools - Books - Compilers
25
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

page

26
mikroElektronika: Development tools - Books - Compilers
 CHAPTER
3

mikroPascal
Language Reference
Why Pascal in the first place? The answer is simple: it is legible, easy-to-learn,
structured programming language, with sufficient power and flexibility needed for
programming microcontrollers. Whether you had any previous programming expe-
rience, you will find that writing programs in mikroPascal is very easy. This chap-
ter will help you learn or recollect Pascal syntax, along with the specifics of pro-
gramming PIC microcontrollers.

mikroElektronika: Development tools - Books - Compilers

 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

PIC SPECIFICS
In order to get the most from your mikroPascal compiler, you should be familiar
with certain aspects of PIC MCU. This knowledge is not essential, but it can pro-
vide you a better understanding of PICs’ capabilities and limitations, and their
impact on the code writing.

Types Efficiency

First of all, you should know that PIC’s ALU, which performs arithmetic opera-
tions, is optimized for working with bytes. Although mikroPascal is capable of
handling very complex data types, PIC may choke on them, especially if you are
working on some of the older models. This can dramatically increase the time
needed for performing even simple operations. Universal advice is to use the
smallest possible type in every situation. It applies to all programming in general,
and doubly so with microcontrollers.

When it comes down to calculus, not all PICmicros are of equal performance. For
example, PIC16 family lacks hardware resources to multiply two bytes, so it is
compensated by a software algorithm. On the other hand, PIC18 family has HW
multiplier, and as a result, multiplication works considerably faster.

Nested Calls Limitations

Nested call represents a function call within function body, either to itself (recur-
sive calls) or to another function. Recursive calls, as form of cross-calling, are
unsupported by mikroPascal due to the PIC’s stack and memory limitations.

mikroPascal limits the number of non-recursive nested calls to:

- 8 calls for PIC12 family,

- 8 calls for PIC16 family,
- 31 calls for PIC18 family.

The number of allowed nested calls decreases by one if you use any of the follow-
ing operators in the code: * / %. It further decreases by one if you use interrupt
in the program. If the allowed number of nested calls is exceeded, compiler will
report stack overflow error.

page

28
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

PIC16 Only Specifics

Breaking Through Pages

In applications targeted at PIC16, no single routine should exceed one page (2,000
instructions). If routine does not fit within one page, linker will report an error.
When confront with this problem, maybe you should rethink the design of your
application – try breaking the particular routine into several chunks, etc.

Limits of Indirect Approach Through FSR

Pointers with PIC16 are “near”: they carry only the lower 8 bits of the address.
Compiler will automatically clear the 9th bit upon startup, so that pointers will
refer to banks 0 and 1. To access the objects in banks 3 or 4 via pointer, user
should manually set the IRP, and restore it to zero after the operation.

Note: It is very important to take care of the IRP properly, if you plan to follow
this approach. If you find this method to be inappropriate with too many variables,
you might consider upgrading to PIC18.

Note: If you have many variables in the code, try rearranging them with linker
directive absolute. Variables that are approached only directly should be moved
to banks 3 and 4 for increased efficiency.

page
mikroElektronika: Development tools - Books - Compilers
29
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

mikroPascal SPECIFICS
Predefined Globals and Constants

To facilitate programming, mikroPascal implements a number of predefined glob-

als and constants.

All PIC SFR registers are implicitly declared as global variables of byte type, and
are visible in the entire project. When creating a project, mikroPascal will include
an appropriate .def file, containing declarations of available SFR and constants
(such as PORTB, TMR1, etc). Identifiers are all in uppercase, identical to nomen-
clature in Microchip datasheets. For the complete set of predefined globals and
constants, look for “Defs” in your mikroPascal installation folder, or probe the
Code Assistant for specific letters (CTRL+SPACE in Editor).

Accessing Individual Bits

mikroPascal allows you to access individual bits of variables. Simply use the dot
(.) with a variable, followed by a number. For example:

var myvar : longint;

// range of applicable bits is myvar.0 .. myvar.31
//...
// If RB0 is set, set the 28th bit of myvar:
if PORTB.0 = 1 then myvar.27 := 1;

There is no need for any special declarations; this kind of selective access is an
intrinsic feature of mikroPascal and can be used anywhere in the code. Provided
you are familiar with the particular chip, you can access bits by their name (e.g.
INTCON.TMR0F).

page

30
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Interrupts

Interrupts can be easily handled by means of reserved word interrupt.

mikroPascal implictly declares procedure interrupt which cannot be redeclared.

Write your own procedure body to handle interrupts in your application.

mikroPascal saves the following SFR on stack when entering interrupt and pops
them back upon return:

PIC12 family: W, STATUS, FSR, PCLATH

PIC16 family: W, STATUS, FSR, PCLATH
PIC18 family: FSR (fast context is used to save WREG, STATUS, BSR)

Note: mikroPascal does not support low priority interrupts; for PIC18 family,
interrupts must be of high priority.

Routine Calls from Interrupt

Calling functions and procedures from within the interrupt routine is now possible.
The compiler takes care about the registers being used, both in "interrupt" and in
"begin" thread, and performs "smart" context-switching between the two, saving
only the registers that have been used in both threads.

The functions and procedures that don't have their own frame (no arguments and
local variables) can be called both from the interrupt and the "begin" thread.

Here is a simple example of handling the interrupts from TMR0 (if no other inter-
rupts are allowed):

procedure interrupt;
begin
counter := counter + 1;
TMR0 := 96;
INTCON := $20;
end;

page
mikroElektronika: Development tools - Books - Compilers
31
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Linker Directives

mikroPascal uses internal algorithm to distribute objects within memory. If you

need to have variable or routine at specific predefined address, use linker direc-
tives absolute and org.

Directive absolute

Directive absolute specifies the starting address in RAM for variable. If variable
is multi-byte, higher bytes are stored at consecutive locations.

Directive absolute is appended to the declaration of variable:

var x : byte; absolute $22;

// Variable x will occupy 1 byte at address $22

y : word; absolute $23;

// Variable y will occupy 2 bytes at addresses $23 and $24

Be careful when using absolute directive, as you may overlap two variables by
mistake. For example:

var i : byte; absolute $33;

// Variable i will occupy 1 byte at address $33;

jjjj : longint; absolute $30;

// Variable will occupy 4 bytes at $30, $31, $32, $33; thus,
// changing i changes jjjj highest byte at the same time

Directive org

Directive org specifies the starting address of routine in ROM. It is appended to

the declaration of routine. For example:

procedure proc(par : byte); org $200;

begin // Procedure will start at address $200
...
end;

Note: Directive org can be applied to any routine except the interrupt procedure.
Interrupt will always be located at address $4 (or $8 for P18), Page0.

page

32
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Directive volatile

Directive volatile gives variable possibilty to change without intervention from

code.

Typical volatile variables are: STATUS, TIMER0, TIMER1, PORTA, PORTB etc.

var MyVar: byte; absolute $123; register; volatile;

page
mikroElektronika: Development tools - Books - Compilers
33
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Code Optimization

Optimizer has been added to extend the compiler usability, cuts down the amount
of code generated and speed-up its execution. Main features are:

Constant folding
All expressions that can be evaluated in the compile time (i.e. are constant) are
being replaced by their result. (3 + 5 -> 8);

Constant propagation
When a constant value is being assigned to certain variable, the compiler recog-
nizes this and replaces the use of the variable in the code that follows by constant,
as long as variable's value remains unchanged.

Copy propagation
The compiler recognizes that two variables have same value and eliminates one of
them in the further code.

Value numbering
The compiler "recognize" if the two expressions yield the same result, and can
therefore eliminate the entire computation for one of them.

"Dead code" ellimination

The code snippets that are not being used elsewhere in the programme do not
affect the final result of the application. They are automatically being removed.

Stack allocation
Temporary registers ("Stacks") are being used more rationally, allowing for VERY
complex expressions to be evaluated with minimum stack consumption.

Local vars optimization

No local variables are being used if their result does not affect some of the global
or volatile variables.

Better code generation and local optimization

Code generation is more consistent, and much attention has been made to imple-
ment specific solutions for the code "building bricks" that further reduce output
code size.

page

34
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

mikro ICD (In-Circuit Debugger)

mikro ICD is highly effective tool for Real-Time debugging on hardware level.
ICD debugger enables you to execute a mikroPascal program on a host PIC micro-
controller and view variable values, Special Function Registers (SFR), memory
and EEPROM as the program is running.

If you have appropriate hardware and software for using mikro ICD then you have
to upon completion of writing your program to choose between Release build
Type or ICD Debug build type.

After you choose ICD Debug build type it's time to compile your project. After
you have successfully compiled your project you must program PIC using F11
shortcut. After successful PIC programming you have to select mikro ICD by
selecting Debugger › Select Debugger › mikro ICD Debugger from the drop-
down menu.

page
mikroElektronika: Development tools - Books - Compilers
35
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

You can run the mikro ICD by selecting Run › Debug from the drop-down menu,
or by clicking Debug Icon . Starting the Debugger makes more options available:
Step Into, Step Over, Run to Cursor, etc. Line that is to be executed is color high-
lighted (blue by default). There is also notification about program execution and it
can be found on Watch Window (yellow status bar). Note that some functions take
time to execute, so running of program is indicated on Watch Window.

page

36
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

mikro ICD Debugger Options

Name Description Function Key

Debug Starts Debugger. [F9]

Run/ Pause
Debugger
Run or pause Debugger. [F6]

Toggle breakpoint at the current cursor posi-

tion. To view all the breakpoints, select Run ›
Toggle
Breakpoints
View Breakpoints from the drop-down menu. [F5]
Double clicking an item in window list
locates the breakpoint.

Execute all instructions between the current

Run to cursor [F4]
instruction and the cursor position.
Execute the current C (single– or
multi–cycle) instruction, then halt. If the
Step Into instruction is a routine call, enter the routine [F7]
and halt at the first instruction following the
call.
Execute the current C (single– or
multi–cycle) instruction, then halt. If the
Step Over [F8]
instruction is a routine call, skip it and halt at
the first instruction following the call.
Flushes current PIC RAM. All variable val-
Flush RAM ues will be changed according to values from N/A
watch window.

page
mikroElektronika: Development tools - Books - Compilers
37
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

mikro ICD Debugger Example

Here is a step by step mikro ICD Debugger Example. First you have to write a
program. We will show how mikro ICD works using this example:

program LCD_demo;
var text : string[21];
i : byte;
begin
PORTD := $00;
TRISD := $00;
text := 'mikroElektronika';

Lcd_Init(PORTD);
Lcd_Cmd(LCD_CLEAR);
Lcd_Cmd(LCD_CURSOR_OFF);

for i:=1 to 17 do
Lcd_Chr(1,i,text[i-1]);
end.

After successful compilation and PIC programming press F9

for starting mikro ICD. After mikro ICD initialization blue active line should
appear.

page

38
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

We will debug program line by line. Pressing F8 we are executing code line by
line. It is recommended that user does not use Step Into [F7] and Step Over [F8]
over Delays routines and routines containing delays. Instead use Run to cursor
[F4] and Breakpoints functions.

All changes are read from PIC and loaded into Watch Window. Note that TRISD
changed its value from 255 to 0.

page
mikroElektronika: Development tools - Books - Compilers
39
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Step Into [F7] and Step Over [F8] are mikro ICD debugger functions that are used
in stepping mode. There is also Real-Time mode supported by mikro ICD.
Functions that are used in Real-Time mode are Run/ Pause Debugger [F6] and
Run to cursor [F4]. Pressing F4 goes to line selected by user. User just have to
select line with cursor and press F4, and code will be executed until selected line
is reached.

Run(Pause) Debugger [F6] and Toggle Breakpoints [F5] are mikro ICD debugger
functions that are used in Real-Time mode. Pressing F5 marks line selected by
user for breakpoint. F6 executes code until breakpoint is reached. After reaching
breakpoint Debugger halts. Here at our example we will use breakpoints for writ-
ing "mikroElektronika" on LCD char by char. Breakpoint is set on LCD_Chr and
program will stop everytime this function is reached. After reaching breakpoint we
must press F6 again for continuing program execution.

page

40
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Breakpoints has been separated into two groups. There are hardware and software
break points. Hardware breakpoints are placed in PIC and they provide fastest
debug. Number of hardware breakpoints is limited (1 for P16 and 1 or 3 for P18).
If all hardware brekpoints are used, next breakpoints that will be used are software
breakpoint. Those breakpoints are placed inside mikro ICD, and they simulate
hardware breakpoints. Software breakpoints are much slower than hardware break-
points. This differences between hardware and software differences are not visible
in mikro ICD software but their different timings are quite notable, so it is impor-
tant to know that there is two types of breakpoints.

page
mikroElektronika: Development tools - Books - Compilers
41
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

mikro ICD (In-Circuit Debugger) Overview

Watch Window

Debugger Watch Window is the main Debugger window which allows you to
monitor program items while running your program. To show the Watch Window,
select View › Debug Windows › Watch Window from the drop-down menu.

The Watch Window displays variables and registers of PIC, with their addresses
and values. Values are updated as you go through the simulation. Use the drop-
down menu to add and remove the items that you want to monitor. Recently
changed items are colored red.

Double clicking an item opens the Edit Value window in which you can assign a
new value to the selected variable/register. Also, you can change view to binary,
hex, char, or decimal for the selected item.

page

42
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

View RAM Window

Debugger View RAM Window is available from the drop-down menu, View ›
Debug Windows › View RAM.

The View RAM Window displays the map of PIC’s RAM, with recently changed
items colored red.

Common Errors

- Trying to program PIC while mikro ICD is active.

- Trying to debug Release build Type version of program.
- Trying to debug changed program code which hasn't been compiled and pro-
grammed into PIC.
- Trying to select line that is empty for Run to cursor [F4] and Toggle Breakpoints
[F5] functions.

page
mikroElektronika: Development tools - Books - Compilers
43
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

LEXICAL ELEMENTS
These topics provide a formal definition of the mikroPascal lexical elements. They
describe the different categories of word-like units (tokens) recognized by a lan-
guage.

In the tokenizing phase of compilation, the source code file is parsed (that is, bro-
ken down) into tokens and whitespace. The tokens in mikroPascal are derived
from a series of operations performed on your programs by the compiler.

A mikroPascal program starts as a sequence of ASCII characters representing the

source code, created by keystrokes using a suitable text editor (such as the
mikroPascal Code Editor). The basic program unit in mikroPascal is the file. This
usually corresponds to a named file located in RAM or on disk and having the
extension .ppas.

Whitespace

Whitespace is the collective name given to spaces (blanks), horizontal and vertical
tabs, newline characters, and comments. Whitespace serves to indicate where
tokens start and end, but beyond this function, any surplus whitespace is discard-
ed.

For example, the two sequences

var i : char;
j : word;

and

var
i : char;

j : word;

are lexically equivalent and parse identically.

page

44
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Whitespace in Strings

The ASCII characters representing whitespace can occur within string literals, in
which case they are protected from the normal parsing process (they remain as
part of the string). For example, statement

some_string := 'mikro foo';

parses to four tokens, including the single string literal token:

some_string
:=
'mikro foo'
;

Comments

Comments are pieces of text used to annotate a program, and are technically
another form of whitespace. Comments are for the programmer’s use only; they
are stripped from the source text before parsing.

There are two ways to create comments in mikroPascal. You can use multi-line
comments:

{ All text between a left brace and a right brace

constitutes a comment. May span multiple lines. }

or single-line comments:

// Any text between a double-slash and the end of the

// line constitutes a comment. May span one line only.

page
mikroElektronika: Development tools - Books - Compilers
45
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

TOKENS
Token is the smallest element of a Pascal program that is meaningful to the com-
piler. The parser separates tokens from the input stream by creating the longest
token possible using the input characters in a left–to–right scan.

mikroPascal recognizes these kinds of tokens:

- keywords
- identifiers
- constants
- operators
- punctuators (also known as separators)

Token Extraction Example

Here is an example of token extraction. Let’s have the following code sequence:

end_flag := 0;

The compiler would parse it as the following four tokens:

end_flag // variable identifier

:= // assignment operator
0 // literal
; // statement terminator

Note that end_flag would be parsed as a single identifier, rather than as the key-
word end followed by the identifier _flag.

page

46
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

LITERALS
Literals are tokens representing fixed numeric or character values.

The data type of a constant is deduced by the compiler using such clues as numer-
ic value and the format used in the source code.

Integer Literals

Integral values can be represented in decimal, hexadecimal, or binary notation.

In decimal notation, numerals are represented as a sequence of digits (without

commas, spaces, or dots), with optional prefix + or - operator to indicate the sign.
Values default to positive (6258 is equivalent to +6258).

The dollar-sign prefix ($) or the prefix 0x indicates a hexadecimal numeral (for
example, $8F or 0x8F).

The percent-sign prefix (%) indicates a binary numeral (for example, %0101).

The allowed range of values is imposed by the largest data type in mikroPascal –
longint. Compiler will report an error if the literal exceeds 2147483647
($7FFFFFFF).

Floating Point Literals

A floating-point value consists of:

- Decimal integer
- Decimal point
- Decimal fraction
- e or E and a signed integer exponent (optional)

You can omit either the decimal integer or the decimal fraction (but not both).
Negative floating constants are taken as positive constants with the unary operator
minus (-) prefixed.

page
mikroElektronika: Development tools - Books - Compilers
47
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

mikroPascal limits floating-point constants to range

±1.17549435082E38 .. ±6.80564774407E38.

Here are some examples:

0. // = 0.0
2e-5 // = 2.0 * 10^-5
-.09E34 // = -0.09 * 10^34

Character Literals

Character literal is one character from the extended ASCII character set, enclosed
with apostrophes. Character literal can be assigned to variables of byte and char
type (variable of byte will be assigned the ASCII value of the character). Also,
you can assign character literal to a string variable.

Note: Quotes ("") have no special meaning in mikroPascal.

String Literals

String literal is a sequence of up to 255 characters from the extended ASCII char-
acter set, enclosed with apostrophes. Whitespace is preserved in string literals, i.e.
parser does not “go into” strings but treats them as single tokens.

Length of string literal is the number of characters it consists of. String is stored
internally as the given sequence of characters plus a final null character (ASCII
zero). This appended “stamp” does not count against string’s total length. String
literal with nothing in between the apostrophes (null string) is stored as a single
null character. You can assign a string literal to a string variable or to an array of
char.

Here are several string literals:

'Hello world!' // message, 12 chars long

' ' // two spaces, 2 chars long
'C' // letter, 1 char long
'' // null string, 0 chars long

Apostrophe itself cannot be a part of the string literal, i.e. there is no escape
sequence. You could use the built-in function Chr to print an apostrophe:
Chr(39). Also, see Strings and String Splicing.

page

48
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

KEYWORDS
Keywords are words reserved for special purposes and must not be used as normal
identifier names.

Beside standard Pascal keywords, all relevant SFR are defined as global variables
and represent reserved words that cannot be redefined (for example: TMR0, PCL,
etc). Probe the Code Assistant for specific letters (CTRL+SPACE in Editor) or
refer to Predefined Globals and Constants.

Here is the alphabetical listing of keywords in mikroPascal:

absolute function read

and goto record
array if repeat
asm implementation shl
begin interrupt shr
boolean in step
break is string
case label then
char mod to
continue not type
const or unit
div org until
do otherwise uses
downto print var
else procedure while
end program with
for real xor

Also, mikroPascal includes a number of predefined identifiers used in libraries.

You could replace these by your own definitions, if you plan to develop your own
libraries. For more information, see mikroPascal Libraries.

page
mikroElektronika: Development tools - Books - Compilers
49
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

IDENTIFIERS
Identifiers are arbitrary names of any length given to functions, variables, symbol-
ic constants, user-defined data types, and labels. All these program elements will
be referred to as objects throughout the help (not to be confused with the meaning
of object in object-oriented programming).

Identifiers can contain the letters a to z and A to Z, the underscore character '_',
and the digits 0 to 9. The only restriction is that the first character must be a letter
or an underscore.

Case Sensitivity

Pascal is not case sensitive, so Sum, sum, and suM represent an equivalent
identifier.

Uniqueness and Scope

Although identifier names are arbitrary (within the rules stated), errors result if the
same name is used for more than one identifier within the same scope and sharing
the same name space. Duplicate names are legal for different name spaces regard-
less of scope rules. For more information on scope, refer to Scope and Visibility.

Identifier Examples

Here are some valid identifiers:

temperature_V1
Pressure
no_hit
dat2string
SUM3
_vtext

page

50
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

PUNCTUATORS
The mikroPascal punctuators (also known as separators) include brackets, paren-
theses, comma, semicolon, colon, and dot.

Brackets

Brackets [ ] indicate single and multidimensional array subscripts:

var alphabet : array[1..30] of byte;

// ...
alphabet[3] := 'c';

For more information, refer to Arrays.

Parentheses

Parentheses ( ) are used to group expressions, isolate conditional expressions,

and indicate function calls and function declarations:

d := c * (a + b); // Override normal precedence

if (d = z) then ... // Useful with conditional statements
func(); // Function call, no args
function func2(n : word); // Function declaration w/ parameters

For more information, refer to Operators Precedence and Associativity,

Expressions, or Functions and Procedures.

Comma

The comma (,) separates the arguments in function calls:

Lcd_Out(1, 1, txt);

Further, the comma separates identifiers in declarations:

var i, j, k : byte;

page
mikroElektronika: Development tools - Books - Compilers
51
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

The comma also separates elements of array in initialization lists:

const MONTHS : array[1..12] of byte =

(31,28,31,30,31,30,31,31,30,31,30,31);

Semicolon

The semicolon (;) is a statement terminator. Every statement in Pascal must be

terminated by a semicolon. The only exception is the last (outer most) end state-
ment in program which is terminated by dot.

For more information, see Statements.

Colon

Colon (:) is used in declarations to separate identifier list from type identifier. For
example:

var
i, j : byte;
k : word;

In the program, use the colon to indicate a labeled statement:

start: nop;
...
goto start;

Dot

Dot (.) indicates access to a field of a record. For example:

person.surname := 'Smith';

For more information, refer to Records.

Dot is also a necessary part of floating point literals. Also, dot can be used for
accessing individual bits of registers in mikroPascal.

page

52
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

PROGRAM ORGANIZATION
mikroPascal imposes strict program organization. Below you can find models for
writing legible and organized source files. For more information on file inclusion
and scope, refer to Units and to Scope and Visibility.

Organization of Main Unit

Basically, main source file has two sections: declaration and program body.
Declarations should be in their proper place in the code, organized in an orderly
manner. Otherwise, compiler may not be able to comprehend the program
correctly.

When writing code, follow the model presented in the following page.

Organization of Other Units

Units other than main start with the keyword unit; implementation section starts
with the keyword implementation. Follow the models presented in the follow-
ing two pages.

page
mikroElektronika: Development tools - Books - Compilers
53
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Main unit should look like this:

program { program name }
uses { include other units }

//********************************************************
//* Declarations (globals):
//********************************************************

{ constants declarations }
const ...

{ variables declarations }
var ...

{ labels declarations }
label ...

{ procedures declarations }
procedure procedure_name
{ local declarations }
begin
...
end;

{ functions declarations }
function function_name
{ local declarations }
begin
...
end;

//********************************************************
//* Program body:
//********************************************************

begin
{ write your code here }
end.

page

54
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Other units should look like this:

unit { unit name }

uses { include other units }

//********************************************************
//* Interface (globals):
//********************************************************
{ constants declarations }
const ...

{ variables declarations }
var ...

{ procedures prototypes }
procedure procedure_name(...);

{ functions prototypes }
function function_name(...);

//********************************************************
//* Implementation:
//********************************************************
implementation

{ constants declarations }
const ...

{ variables declarations }
var ...

{ labels declarations }
label ...

{ procedures declarations }
procedure procedure_name
{ local declarations }
begin
...
end;

{ functions declarations }
function function_name
{ local declarations }
begin
...
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
55
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

SCOPE AND VISIBILITY

Scope

The scope of identifier is the part of the program in which the identifier can be
used to access its object. There are different categories of scope which depend on
how and where identifiers are declared:

If identifier is declared in the declaration section of a main unit, out of any func-
tion or procedure, scope extends from the point where it is declared to the end of
the current file, including all routines enclosed within that scope. These identifiers
have a file scope, and are referred to as globals.

If identifier is declared in the function or procedure, scope extends from the point
where it is declared to the end of the current routine. These identifiers are referred
to as locals.

If identifier is declared in the interface section of a unit, scope extends the inter-
face section of a unit from the point where it is declared to the end of the unit, and
to any other unit or program that uses that unit.

If identifier is declared in the implementation section of a unit, but not within any
function or procedure, scope extends from the point where it is declared to the end
of the unit. The identifier is available to any function or procedure in the unit.

Visibility

The visibility of an identifier is that region of the program source code from which
legal access can be made to the identifier’s associated object.

Scope and visibility usually coincide, though there are circumstances under which
an object becomes temporarily hidden by the appearance of a duplicate identifier:
the object still exists but the original identifier cannot be used to access it until the
scope of the duplicate identifier is ended.

Technically, visibility cannot exceed scope, but scope can exceed visibility.

page

56
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

UNITS
In mikroPascal, each project consists of a single project file, and one or more unit
files. Project file, with extension .ppp contains information about the project,
while units, with extension .ppas, contain the actual source code.

Units allow you to:

- break large programs into encapsulated units that can be edited separately,
- create libraries that can be used in different projects,
- distribute libraries to other developers without disclosing the source code.

Each unit is stored in its own file and compiled separately; compiled units are
linked to create an application. To build a project, the compiler needs either a
source file or a compiled unit file for each unit.

Uses Clause

mikroPascal includes units by means of uses clause. It consists of the reserved

word uses, followed by one or more comma-delimited unit names, followed by a
semicolon. Extension of the file should not be included. There can be at most one
uses clause in each source file, and it must appear immediately after the program
(or unit) name.

Here’s an example:

uses utils, strings, Unit2, MyUnit;

page
mikroElektronika: Development tools - Books - Compilers
57
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Given a unit name, compiler will check for the presence of .mcl and .ppas files,
in order specified by the search paths.

- If both .ppas and .mcl files are found, compiler will check their dates and
include the newer one in the project. If the .ppas file is newer than the .mcl, new
library will be written over the old one;

- If only .ppas file is found, compiler will create the .mcl file and include it in
the project;

- If only .mcl file is present, i.e. no source code is available, compiler will
include it as found;

- If none found, compiler will issue a “File not found” warning.

Main Unit

Every project in mikroPascal requires single main unit file. Main unit is identified
by the keyword program at the beginning; it instructs the compiler where to
“start”.

After you have successfully created an empty project with Project Wizard, Code
Editor will display a new main unit. It contains the bare-bones of a program:

program MyProject;

{ main procedure }
begin
{ Place program code here }
end.

Other than comments, nothing should precede the keyword program. After the
program name, you can optionally place the uses clause.

Place all global declarations (constants, variables, labels, routines) before the key-
word begin.

Note: In mikroPascal, the end. statement (the closing statement of every

program) acts as an endless loop.

page

58
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Other Units

Modules other than main start with the keyword unit. Newly created blank unit
contains the bare-bones:

unit MyUnit;

implementation

end.

Other than comments, nothing should precede the keyword unit. After the unit
name, you can optionally place the uses clause.

Interface Section

Part of the unit above the keyword implementation is referred to as interface

section. Here, you can place global declarations (constants, variables, and labels)
for the project.

You do not define routines in the interface section. Instead, state the prototypes of
routines (from implementation section) that you want to be visible outside the unit.
Prototypes must match the declarations exactly.

Implementation Section

Implementation section hides all the irrelevant innards from other units, allowing
encapsulation of code.

Everything declared below the keyword implementation is private, i.e. has its
scope limited to the file. When you declare an identifier in the implementation
section of a unit, you cannot use it outside the unit, but you can use it in any block
or routine defined within the unit.

By placing the prototype in the interface section of the unit (above the imple-
mentation) you can make the routine public, i.e. visible outside of unit.
Prototypes must match the declarations exactly.

page
mikroElektronika: Development tools - Books - Compilers
59
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

VARIABLES
Variable is object whose value can be changed during the runtime. Every variable
is declared under unique name which must be a valid identifier. This name is used
for accessing the memory location occupied by the variable.

Variables are declared in the declaration part of the file or routine — each variable
needs to be declared before it can be used. Global variables (those that do not
belong to any enclosing block) are declared below the uses statement, above the
keyword begin.

Specifying a data type for each variable is mandatory. Basic syntax for variable
declaration is:

var identifier_list : type;

The identifier_list is a comma-delimited list of valid identifiers and type

can be any data type.

For more details refer to Types and Types Conversions. For more information on
variables’ scope refer to the chapter Scope and Visibility.

Pascal allows shorthand syntax with only one keyword var followed by multiple
variable declarations. For example:

var i, j, k : byte;
samples : array[100] of word;

Variables and PIC

Every declared variable consumes part of RAM memory. Data type of variable
determines not only the allowed range of values, but also the space variable occu-
pies in RAM memory. Bear in mind that operations using different types of vari-
ables take different time to be completed. mikroPascal recycles local variable
memory space – local variables declared in different functions and procedures
share same memory space, if possible. There is no need to declare SFR explicitly,
as mikroPascal automatically declares relevant registers as global variables of
byte. For example: T0IE, INTF, etc.

page

60
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CONSTANTS
Constant is data whose value cannot be changed during the runtime. Using a con-
stant in a program consumes no RAM memory. Constants can be used in any
expression, but cannot be assigned a new value.

Constants are declared in the declaration part of program or routine. Declare a

constant like this:

const constant_name [: type] = value;

Every constant is declared under unique constant_name which must be a valid

identifier. It is a tradition to write constant names in uppercase. Constant requires
you to specify value, which is a literal appropriate for the given type. The type is
optional; in the absence of type, compiler assumes the “smallest” type that can
accommodate value.

Note: You cannot omit type if declaring a constant array.

Pascal allows shorthand syntax with only one keyword const followed by multi-
ple constant declarations. Here’s an example:

const
MAX : longint = 10000;
MIN = 1000; // compiler will assume word type
SWITCH = 'n'; // compiler will assume char type
MSG = 'Hello'; // compiler will assume string type
MONTHS : array[1..12] of byte =
(31,28,31,30,31,30,31,31,30,31,30,31);

page
mikroElektronika: Development tools - Books - Compilers
61
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

LABELS
Labels serve as targets for goto statements. Mark the desired statement with label
and a colon like this:

label_identifier : statement

Before marking a statement, you must first declare the label. Labels are declared
in declaration part of unit or routine, similar to variables and constants. Declare
labels using the keyword label:

label label1, ..., labeln;

Name of the label needs to be a valid identifier. The label declaration, marked
statement, and goto statement must belong to the same block. Hence it is not pos-
sible to jump into or out of a procedure or function. Do not mark more than one
statement in a block with the same label.

Here is an example of an infinite loop that calls the Beep procedure repeatedly:

label loop;
...
loop: Beep;
goto loop;

page

62
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

FUNCTIONS AND PROCEDURES

Functions and procedures, collectively referred to as routines, are subprograms
(self-contained statement blocks) which perform a certain task based on a number
of input parameters. Function returns a value when executed, and procedure does
not. Note: mikroPascal does not support inline routines.

Functions

Function is declared like this:

function function_name(parameter_list) : return_type;

{ local declarations }
begin
{ function body }
end;

The function_name represents a function’s name and can be any valid identifier.
The return_type is the type of return value and can be any simple type. Within
parentheses, parameter_list is a formal parameter list similar to variable dec-
laration. In mikroPascal, parameters are always passed to function by value; to
pass argument by the address, add the keyword var ahead of identifier.

Local declarations are optional declarations of variables and/or constants,

local for the given function. Function body is a sequence of statements to be
executed upon calling the function.

A function is called by its name, with actual arguments placed in the same
sequence as their matching formal parameters. The compiler is able to coerce mis-
matching arguments to the proper type according to implicit conversion rules.
Upon function call, all formal parameters are created as local objects initialized by
values of actual arguments. Upon return from a function, temporary object is cre-
ated in the place of the call, and it is initialized by the expression of return state-
ment. This means that function call as an operand in complex expression is treated
as the function result.

In standard Pascal, function name is automatically created local variable that can
be used for returning a value of a function. Also, mikroPascal allows you to use
the automatically created local variable result to assign the return value of a
function if you find function name to be too ponderous.

page
mikroElektronika: Development tools - Books - Compilers
63
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Function calls are considered to be primary expressions, and can be used in situa-
tions where expression is expected. Function call can also be a self-contained
statement, in which case the return value is discarded.

Here’s a simple function which calculates xn based on input parameters x and n

(n > 0):

function power(x, n : byte) : longint;

var i : byte;
begin
i := 0; result := 1;
if n > 0 then
for i := 1 to n do result := result*x;
end;

Now we could call it to calculate, say, 312:

tmp := power(3, 12);

Procedures

Procedure is declared like this:

procedure procedure_name(parameter_list);
{ local declarations }
begin
{ procedure body }
end;

The procedure_name represents a procedure’s name and can be any valid identi-
fier. Within parentheses, parameter_list is a formal parameter list similar to
variable declaration. In mikroPascal, parameters are always passed to procedure
by value; to pass argument by the address, add the keyword var ahead of
identifier.

Local declarations are optional declaration of variables and/or constants,

local for the given procedure. Procedure body is a sequence of statements to be
executed upon calling the procedure.

page

64
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

A procedure is called by its name, with actual arguments placed in the same
sequence as their matching formal parameters. The compiler is able to coerce mis-
matching arguments to the proper type according to implicit conversion rules.
Upon procedure call, all formal parameters are created as local objects initialized
by values of actual arguments.

Procedure call is a self-contained statement.

Here’s an example procedure which transforms its input time parameters, prepar-
ing them for output on LCD:

procedure time_prep(var sec, min, hr : byte);

begin
sec := ((sec and $F0) shr 4)*10 + (sec and $0F);
min := ((min and $F0) shr 4)*10 + (min and $0F);
hr := ((hr and $F0) shr 4)*10 + (hr and $0F);
end;

page
mikroElektronika: Development tools - Books - Compilers
65
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

TYPES
Pascal is a strictly typed language, which means that every variable and constant
need to have a strictly defined type, known at the time of compilation.

The type serves:

- to determine the correct memory allocation required,

- to interpret the bit patterns found in the object during subsequent accesses,
- in many type-checking situations, to ensure that illegal assignments are trapped.

mikroPascal supports many standard (predefined) and user-defined data types,

including signed and unsigned integers of various sizes, arrays, strings, pointers,
and records.

In mikroPascal from v5.xx, you can define your own types.Types can be built
from other types by the type declaration.

Example:

Type MyType1 = array[10] of byte;

MyType2 = integer;
MyType3 = ^word;
MyType4 = ^MyType1;

var mynumber : MyType2;

Type Categories

Types can be divided into:

- simple types
- arrays
- strings
- pointers
- records (user defined types)

page

66
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SIMPLE TYPES
Simple types represent types that cannot be divided into more basic elements, and
are the model for representing elementary data on machine level.

Here is an overview of simple types in mikroPascal:

Type Size Range

byte 8-bit 0 .. 255

char* 8-bit 0 .. 255

word 16-bit 0 .. 65535

short 8-bit - 128 .. 127

integer 16-bit -32768 .. 32767

longint 32-bit -2147483648 .. 2147483647

±1.17549435082 * 10-38 ..
real 32-bit
±6.80564774407 * 1038

* char type can be treated as byte type in every aspect

You can assign signed to unsigned or vice versa only using the explicit conversion.
Refer to Types Conversions for more information.

page
mikroElektronika: Development tools - Books - Compilers
67
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

ARRAYS
An array represents an indexed collection of elements of the same type (called the
base type). Because each element has a unique index, arrays, unlike sets, can
meaningfully contain the same value more than once.

Array types are denoted by constructions of the form:

array[index_start .. index_end] of type

Each of the elements of an array is numbered from index_start through the

index_end. Specifier index_start can be omitted along with dots, in which
case it defaults to zero. Every element of an array is of type and can be accessed
by specifying array name followed by element’s index within brackets.

Here are a few examples of array declaration:

var
weekdays : array[1..7] of byte;
samples : array[50] of word;

begin
// Now we can access elements of array variables, for example:
samples[0] := 1;
if samples[37] = 0 then ...

Constant Arrays

Constant array is initialized by assigning it a comma-delimited sequence of values

within parentheses. For example:

// Declare a constant array which holds no. of days in each month:

const MONTHS : array[1..12] of byte
= (31,28,31,30,31,30,31,31,30,31,30,31);
// Declare a constant numbers:
const NUMBERS : byte[4][4] = ((0, 1, 2, 3), (5, 6, 7, 8), (9, 10,
11,12), (13,14, 15, 16));

The number of assigned values must not exceed the specified length. Vice versa is
possible, when the trailing “excess” elements will be assigned zeroes.

For more information on arrays of char, refer to Strings.

page

68
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Multi-dimensional Arrays
An array is one-dimensional if it is of scalar type. One-dimensional arrays are
sometimes referred to as vectors.

Multidimensional arrays are constructed by declaring arrays of array type. These

arrays are stored in memory in such way that the right most subscript changes
fastest, i.e. arrays are stored “in rows”. Here is a sample 2-dimensional array:

m: array[50] of array[20] of byte; //2-dimensional array of size 50x20

Variable m is an array of 50 elements, which in turn are arrays of 20 bytes each.

Thus, we have a matrix of 50x20 elements: first element is m[0][0], last one is
m[49][19]. First element of the 5th row would be m[0][5].

If you are not initializing the array in the declaration, you can omit the first dimen-
sion of multi-dimensional array. In that case, array is located elsewhere, e.g. in
another file. This is a commonly used technique when passing arrays as function
parameters:

procedure example(var m: array[50] of array[20] of byte); // we can omit first

dimension
begin
...
inc(m[1][1]);
end;

var
m: array[50] of array[20] of byte; // 2-dimensional array of size 50x20
n: array[4] of array[2] of array[7] of byte; // 3-dimensional array of size 4x2x7
begin
...
func(m);
end.

page
mikroElektronika: Development tools - Books - Compilers
69
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

STRINGS
A string represents a sequence of characters, and is an equivalent to an array of
char. It is declared like:

string_name string[length]

Specifier length is the number of characters string consists of. String is stored
internally as the given sequence of characters plus a final null character (zero).
This appended “stamp” does not count against string’s total length.

A null string ('') is stored as a single null character.

You can assign string literals or other strings to string variables. String on the right
side of an assignment operator has to be the shorter of the two, or of equal length.
For example:

var
msg1 : string[20];
msg2 : string[19];

begin
msg1 := 'This is some message';
msg2 := 'Yet another message';
msg1 := msg2; // this is ok, but vice versa would be illegal

Alternately, you can handle strings element–by–element. For example:

var s : string[5];
//...
s := 'mik';
{
s[0] is char literal 'm'
s[1] is char literal 'i'
s[2] is char literal 'k'
s[3] is zero
s[4] is undefined
s[5] is undefined
}

Be careful when handling strings in this way, since overwriting the end of a string
can cause access violations.

page

70
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

String Splicing

mikroPascal allows you to splice strings by means of plus character. This kind of
concatenation is applicable to string variables/literals and character variables/liter-
als. For control characters, use the non-quoted hash sign and a numeral (e.g. #13
for CR).

The result of splicing is of string type, naturally. See also Strcat function.

Here is an example:

var msg : string[100];

res_txt : string[5];
res, channel : word;

begin

//...

// Get result of ADC

res := Adc_Read(channel);

// Create string out of numeric result

WordToStr(res, res_txt);

// Prepare message for output

msg := 'Result is' + // Text "Result is"
#13#10 + // Append CR/LF sequence
res_txt + // Result of ADC
'.'; // Append a dot

//...

Note: mikroPascal includes a String Library which automatizes string related

tasks.

page
mikroElektronika: Development tools - Books - Compilers
71
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

POINTERS
A pointer is a data type which holds a memory address. While a variable accesses
that memory address directly, a pointer can be thought of as a reference to that
memory address.

To declare a pointer data type, add a carat prefix (^) before type. For example, if
you are creating a pointer to an integer, you would write:

^integer;

To access the data at the pointer’s memory location, you add a carat after the vari-
able name. For example, let’s declare variable p which points to a word, and then
assign the pointed memory location value 5:

var p : ^word;
...
p^ := 5;

A pointer can be assigned to another pointer. However, note that only the address,
not the value, is copied. Once you modify the data located at one pointer, the other
pointer, when dereferenced, also yields modified data.

@ Operator

The @ operator returns the address of a variable or routine; that is, @ constructs a
pointer to its operand. The following rules apply to @:

- If X is a variable, @X returns the address of X.

- If F is a routine (a function or procedure), @F returns F’s entry point (result is of
longint).

page

72
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

RECORDS
A record (analogous to a structure in some languages) represents a heterogeneous
set of elements. Each element is called field; the declaration of a record type speci-
fies a name and type for each field. The syntax of a record type declaration is

type recordTypeName = record

fieldList1 : type1;
...
fieldListn : typen;
end;

where recordTypeName is a valid identifier, each type denotes a type, and each
fieldList is a valid identifier or a comma-delimited list of identifiers. The scope
of a field identifier is limited to the record in which it occurs, so you don’t need to
worry about naming conflicts between field identifiers and other variables.

Note: In mikroPascal, you cannot use the record construction directly in variable
declarations, i.e. without type.

For example, the following declaration creates a record type called TDot:

type
TDot = record
x, y : real;
end;

Each TDot contains two fields: x and y coordinates; memory is allocated when
you instantiate the record, like this:

var m, n: TDot;

This variable declaration creates two instances of TDot, called m and n.

A field can be of previously defined record type. For example:

// Structure defining a circle:

type
TCircle = record
radius : real;
center : TDot;
end;

page
mikroElektronika: Development tools - Books - Compilers
73
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Accessing Fields

You can access the fields of a record by means of dot (.) as a direct field selector.
If we declare variables circle1 and circle2 of previously defined type
TCircle:

var circle1, circle2 : TCircle;

we could access their individual fields like this:

circle1.radius := 3.7;
circle1.center.x := 0;
circle1.center.y := 0;

You cannot commit assignments between complex variables. See MemCpy for
more info.

page

74
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

TYPES CONVERSIONS
Conversion of object of one type is changing it to the same object of another type
(i.e. applying another type to a given object). mikroPascal supports both implicit
and explicit conversions for built-in types.

Implicit Conversion

Compiler will provide an automatic implicit conversion in the following

situations:

- statement requires an expression of particular type (according to language

definition), and we use an expression of different type,
- operator requires an operand of particular type, and we use an operand of
different type,
- function requires a formal parameter of particular type, and we pass it an object
of different type,
- result does not match the declared function return type.

Promotion

When operands are of different types, implicit conversion promotes the less
complex to more complex type taking the following steps:

byte/char -> word

short -> integer
short -> longint
integer -> longint
integral -> real

Higher bytes of extended unsigned operand are filled with zeroes. Higher bytes of
extended signed operand are filled with bit sign (if number is negative, fill higher
bytes with one, otherwise with zeroes).

page
mikroElektronika: Development tools - Books - Compilers
75
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Clipping

In assignments, and statements that require an expression of particular type,

destination will store the correct value only if it can properly represent the result
of expression (that is, if the result fits in destination range).

If expression evaluates to more complex type than expected, excess data will be
simply clipped (higher bytes are lost).

var i : byte; j : word;

...
j := $FF0F;
i := j; // i becomes $0F, higher byte $FF is lost

Explicit Conversion

Explicit conversion can be executed at any point by inserting type keyword (byte,
word, short, integer, or longint) ahead of the expression to be converted.
The expression must be enclosed in parentheses. Explicit conversion can be
performed only on the operand left of the assignment operator.

Special case is conversion between signed and unsigned types. Explicit conversion
between signed and unsigned data does not change binary representation of data; it
merely allows copying of source to destination.

For example:

var a : byte; b : short;

...
b := -1;
a := byte(b); // a is 255, not 1

// This is because binary representation remains

// 11111111; it's just interpreted differently now

You cannot execute explicit conversion on the operand left of the assignment
operator.

page

76
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Arithmetic Conversions

When you use an arithmetic expression, such as a + b, where a and b are of differ-
ent arithmetic types, mikroPascal performs implicit type conversions before the
expression is evaluated. These standard conversions include promotions of
“lower” types to “higher” types in the interests of accuracy and consistency.

Assigning a signed character object (such as a variable) to an integral object

results in automatic sign extension. Objects of type short always use sign exten-
sion; objects of type byte always set the high byte to zero when converted to int.

Converting a longer integral type to a shorter type truncates the higher order bits
and leaves low-order bits unchanged. Converting a shorter integral type to a longer
type either sign-extends or zero-fills the extra bits of the new value, depending on
whether the shorter type is signed or unsigned, respectively.

Note: Conversion of floating point data into integral value (in assignments or via
explicit typecast) produces correct results only if the float value does not exceed
the scope of destination integral type.

In details:
Here are the steps mikroPascal uses to convert the operands in an arithmetic
expression:

First, any small integral types are converted according to the following rules:

byte converts to integer

short converts to integer, with the same value
short converts to integer, with the same value, sign-extended
byte converts to integer, with the same value, zero-filled
The result of the expression is the same type as that of the two operands.

Here are several examples of implicit conversion:

2 + 3.1 /* -> 2. + 3.1 -> 5.1 */

5 / 4 * 3. /* -> (5/4)*3. -> 1*3. -> 1.*3. -> 3. */
3. * 5 / 4 /* -> (3.*5)/4 -> (3.*5.)/4 -> 15./4 -> 15./4. -> 3.75 */

page
mikroElektronika: Development tools - Books - Compilers
77
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

OPERATORS
Operators are tokens that trigger some computation when applied to variables and
other objects in an expression.

There are four types of operators in mikroPascal:

- Arithmetic Operators
- Bitwise Operators
- Boolean Operators
- Relational Operators

Operators Precedence and Associativity

There are 4 precedence categories in mikroPascal. Operators in the same category

have equal precedence with each other.

Each category has an associativity rule: left-to-right, or right-to-left. In the absence

of parentheses, these rules resolve the grouping of expressions with operators of
equal precedence.

Precedence Operands Operators Associativity

4 1 @ not + - right-to-left

* /
3 2 div mod and shl shr
left-to-right

2 2 + - or xor left-to-right

1 2 = <> < > <= >= left-to-right

page

78
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Arithmetic Operators

Arithmetic operators are used to perform mathematical computations. They have

numerical operands and return numerical results. As char operators are
technically bytes, they can be also used as unsigned operands in arithmetic
operations. Operands need to be either both signed or both unsigned.

All arithmetic operators associate from left to right.

Operator Operation Precedence

+ addition 2

- subtraction 2

* multiplication 3

/ division 3

div division, rounds down to nearest integer 3

returns the remainder of integer division (can-

mod 3
not be used with floating points)

Operator - can be used as a prefix unary operator to change sign of a signed

value. Unary prefix operator + can be used, but it doesn’t affect the data.

For example: b := -a

Division by Zero

If 0 (zero) is used explicitly as the second operand (i.e. x div 0), compiler will
report an error and will not generate code. But in case of implicit division by zero:
x div y , where y is 0 (zero), result will be the maximum value for the appropri-
ate type (for example, if x and y are words, the result will be $FFFF).

page
mikroElektronika: Development tools - Books - Compilers
79
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Relational Operators

Use relational operators to test equality or inequality of expressions. All relational

operators return TRUE or FALSE.

All relational operators associate from left to right.

Operator Operation Precedence

= equal 1

<> not equal 1

> greater than 1

< less than 1

>= greater than or equal 1

<= less than or equal 1

Relational Operators in Expressions

Precedence of arithmetic and relational operators was designated in such a way to

allow complex expressions without parentheses to have expected meaning:

a + 5 >= c - 1.0 / e // -> (a + 5) >= (c - (1.0 / e))

page

80
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Bitwise Operators

Use the bitwise operators to modify the individual bits of numerical operands.
Operands need to be either both signed or both unsigned.

Bitwise operators associate from left to right. The only exception is the bitwise
complement operator not which associates from right to left.

Operator Operation Precedence

bitwise AND; returns 1 if both bits are 1, oth-

and 3
erwise returns 0
bitwise (inclusive) OR; returns 1 if either or
or 2
both bits are 1, otherwise returns 0
bitwise exclusive OR (XOR); returns 1 if the
xor 2
bits are complementary, otherwise 0

not bitwise complement (unary); inverts each bit 4

bitwise shift left; moves the bits to the left,

shl 3
see below
bitwise shift right; moves the bits to the right,
shr 3
see below

Bitwise operators and, or, and xor perform logical operations on appropriate
pairs of bits of their operands. Operator not complements each bit of its operand.
For example:

$1234 and $5678 // equals $1230

{ because ..

$1234 : 0001 0010 0011 0100

$5678 : 0101 0110 0111 1000
----------------------------
and : 0001 0010 0011 0000

.. that is, $1230 }

page
mikroElektronika: Development tools - Books - Compilers
81
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Similarly:

$1234 or $5678 // equals $567C

$1234 xor $5678 // equals $444C
not $1234 // equals $EDCB

Unsigned and Conversions

If number is converted from less complex to more complex data type, upper bytes
are filled with zeroes. If number is converted from more complex to less complex
data type, data is simply truncated (upper bytes are lost).

For example:

var a : byte; b : word;

...
a := $AA;
b := $F0F0;
b := b and a;
{ a is extended with zeroes; b becomes $00A0 }

Signed and Conversions

If number is converted from less complex data type to more complex, upper bytes
are filled with ones if sign bit is 1 (number is negative); upper bytes are filled with
zeroes if sign bit is 0 (number is positive). If number is converted from more com-
plex data type to less complex, data is simply truncated (upper bytes are lost).

For example:

var a : byte; b : word;

...
a := -12;
b := $70FF;
b := b and a;

{ a is sign extended, with the upper byte equal to $FF;

b becomes $70F4 }

page

82
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Bitwise Shift Operators

Binary operators shl and shr move the bits of the left operand for a number of
positions specified by the right operand, to the left or right, respectively. Right
operand has to be positive and less than 255.

With shift left (shl), left most bits are discarded, and “new” bits on the right are
assigned zeroes. Thus, shifting unsigned operand to the left by n positions is
equivalent to multiplying it by 2n if all the discarded bits are zero. This is also true
for signed operands if all the discarded bits are equal to sign bit.

With shift right (shr), right most bits are discarded, and the “freed” bits on the left
are assigned zeroes (in case of unsigned operand) or the value of the sign bit (in
case of signed operand). Shifting operand to the right by n positions is equivalent
to dividing it by 2n.

page
mikroElektronika: Development tools - Books - Compilers
83
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

page

84
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

EXPRESSIONS
An expression is a sequence of operators, operands, and punctuators that returns a
value.

The primary expressions include: literals, variables, and function calls. From
these, using operators, more complex expressions can be created. Formally,
expressions are defined recursively: subexpressions can be nested up to the limits
of memory.

Expressions are evaluated according to certain conversion, grouping, associativity,

and precedence rules that depend on the operators used, the presence of parenthe-
ses, and the data types of the operands. The precedence and associativity of the
operators are summarized in Operator Precedence and Associativity. The way
operands and subexpressions are grouped does not necessarily specify the actual
order in which they are evaluated by mikroPascal.

You cannot mix signed and unsigned data types in assignment expressions or in
expressions with arithmetic or logical operators. You can use explicit conversion
though.

page
mikroElektronika: Development tools - Books - Compilers
85
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

STATEMENTS
Statements define algorithmic actions within a program. Each statement needs to
be terminated by a semicolon (;). In the absence of specific jump and selection
statements, statements are executed sequentially in the order of appearance in the
source code.

The simplest statements include assignments, routine calls, and jump statements.
These can be combined to form loops, branches, and other structured statements.

Statements can be roughly divided into:

- asm Statement
- Assignment Statements
- Compound Statements (Blocks)
- Conditional Statements
- Iteration Statements (Loops)
- Jump Statements

asm Statement

mikroPascal allows embedding assembly in the source code by means of asm

statement. Note that you cannot use numerals as absolute addresses for register
variables in assembly instructions. You may use symbolic names instead (listing
will display these names as well as addresses). You can group assembly
instructions with the asm keyword:

asm
block of assembly instructions
end;

Pascal comments are not allowed in embedded assembly code. Instead, you may
use one-line assembly comments starting with semicolon. If you plan to use a cer-
tain Pascal variable in embedded assembly only, be sure to at least initialize it
(assign it initial value) in Pascal code; otherwise, linker will issue an error. This
does not apply to predefined globals such as PORTB.

Note: mikroPascal will not check if the banks are set appropriately for your vari-
able. You need to set the banks manually in assembly code.

page

86
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Migration from older compiler versions

The syntax that is being used in the asm blocks is somewhat different than it has
been in vesion 3. The differences are:

For example, for variable named :

- _myVar, if it is global.
- FARG_+XX, if it is local (this is myVar's actual position in the local function
frame.
- _myVar_L0(+XX), if it is a local static variable (+XX to access further individ-
ual bytes).

The only types whose name remains the same in asm as it is in Pascal are con-
stants, e.g. INTCON, PORTB, WREG, GIE, etc.

Accessing individual bytes is different as well. For example, if you have a global
variable "g_var", that is of type long (i.e. 4 bytes), you are to access it like this:

MOVF _g_var+0, 0 ;puts least-significant byte of g_var in W

register
MOVF _g_var+1, 0 ;second byte of _g_var; corresponds to
Hi(g_var)
MOVF _g_var+2, 0 ;Higher(g_var)
MOVF _g_var+3, 0 ;Highest(g_var)
... etc.

Syntax for retrieving address of an object is different. For objects located in flash
ROM:

MOVLW #_g_var ;first byte of address

MOVLW @#_g_var ;second byte of address
MOVLW @@#_g_var ;third byte of address
... and so on.

For objects located in RAM:

MOVLW CONST1 ;first byte of address

MOVLW @CONST1 ;second byte of address
... and so on.

page
mikroElektronika: Development tools - Books - Compilers
87
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Assignment Statements

Assignment statements have the form:

variable := expression;

The statement evaluates the expression and assigns its value to the variable.
All rules of the implicit conversion apply. Variable can be any declared variable
or array element, and expression can be any expression.

Do not confuse the assignment with relational operator = which tests for equality.

Compound Statements

A compound statement, or block, is a list of statements enclosed by keywords

begin and end:

begin
statements
end;

Syntactically, a block is considered to be a single statement which allows using it

when Pascal syntax requires a single statement. Blocks can be nested up to the
limits of memory.

For example, while loop expects one statement in its body, so we can pass it a
compound statement:

while i < n do
begin
temp := a[i];
a[i] := b[i];
b[i] := temp;
n := n + 1;
end;

end.

Note: In mikroPascal, the end. statement (the closing statement of every

program) acts as an endless loop.

page

88
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Conditional Statements

Conditional or selection statements select from alternative courses of action by

testing certain values. There are two types of selection statements in mikroPascal:
if and case.

If Statement

Use if to implement a conditional statement. Syntax of if statement has the

form:

if expression then statement1 [else statement2]

When expression evaluates to true, statement1 executes. If expression is

false, statement2 executes. The expression must convert to a boolean type
(true or false); otherwise, the condition is ill-formed. The else keyword with an
alternate statement ( statement2) is optional. There should never be a semicolon
before the keyword else.

Nested if statements require additional attention. General rule is that the nested
conditionals are parsed starting from the innermost conditional, with each else
bound to the nearest available if on its left.

page
mikroElektronika: Development tools - Books - Compilers
89
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Case Statement

Use the case statement to pass control to a specific program branch, based on a
certain condition. The case statement consists of a selector expression (a condi-
tion) and a list of possible values. Syntax of case statement is:

case selector of
value_1 : statement_1
...
value_n : statement_n
[else default_statement]
end;

The selector is an expression which should evaluate as integral value. The

values can be literals, constants, or expressions, and statements can be any
statements. The else clause is optional. If using the else branch, note that there
should never be a semicolon before the keyword else.

First, the selector expression (condition) is evaluated. The case statement then
compares it against all the available values. If the match is found, the state-
ment following the match evaluates, and case statement terminates. In case there
are multiple matches, the first matching statement will be executed. If none of the
values matches the selector, then the default_statement in the else
clause (if there is one) is executed.

Here’s a simple example of case statement::

case operator of
'*' : result := n1 * n2;
'+' : result := n1 + n2;
'-' : result := n1 - n2
else result := 0;
end;

Also, you can group values together for a match. Simply separate the items by
commas:

case reg of
1,2,3,4: opmode := 1;
5,6,7: opmode := 2;
end;

Note that case statements can be nested – values are then assigned to the inner-
most enclosing case statement.

page

90
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Iteration Statements (Loops)

Iteration statements let you loop a set of statements. There are three forms of itera-
tion statements in mikroPascal: for, while, and repeat.

You can use the statements break and continue to control the flow of a loop
statement. The break terminates the statement in which it occurs, while
continue begins executing the next iteration of the sequence.

For Statement

The for statement implements an iterative loop and requires you to specify the
number of iterations. Syntax of for statement is:

for counter := initial_value to final_value do statement

// or
for counter := initial_value downto final_value do statement

The counter is a variable which increments (or decrements if you use downto)
with each iteration of the loop. Before the first iteration, counter is set to the
initial_value and will increment (or decrement) until it reaches the
final_value. With each iteration, statement will be executed.

The initial_value and final_value should be expressions compatible with

the counter; statement can be any statement that does not change the value of
counter.

Here is an example of calculating scalar product of two vectors, a and b, of length

n, using for statement:

s := 0;
for i := 0 to n do s := s + a[i] * b[i];

The for statement results in an endless loop if the final_value equals or

exceeds the range of counter’s type. More legible way to create an endless loop
in Pascal is to use the statement while TRUE do.

page
mikroElektronika: Development tools - Books - Compilers
91
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

While Statement

Use the while keyword to conditionally iterate a statement. Syntax of while

statement is:

while expression do statement

The statement is executed repeatedly as long as the expression evaluates

true. The test takes place before the statement is executed. Thus, if expres-
sion evaluates false on the first pass, the loop does not execute.

Here is an example of calculating scalar product of two vectors, using the while
statement:

s := 0; i := 0;
while i < n do
begin
s := s + a[i] * b[i];
i := i + 1;
end;

Repeat Statement

The repeat statement executes until the condition becomes false. Syntax of
repeat statement is:

repeat statement until expression

The statement is executed repeatedly until the expression evaluates true. The
expression is evaluated after each iteration, so the loop will execute state-
ment at least once.

Here is an example of calculating scalar product of two vectors, using the repeat
statement:

s := 0; i := 0;
repeat
begin
s := s + a[i] * b[i];
i := i + 1;
end;
until i = n;

page

92
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Jump Statements

A jump statement, when executed, transfers control unconditionally. There are

three such statements in mikroPascal: break, continue, and goto.

Break Statement

Sometimes, you might need to stop the loop from within its body. Use the break
statement within loops to pass control to the first statement following the inner-
most loop (for, while, or repeat block).

For example:

// Wait for CF card to be plugged; refresh every second

while TRUE do
begin
Lcd_Out(1, 1, "No card inserted");
if Cf_Detect() = 1 then break;
Delay_ms(1000);
end;

// Now we can work with CF card ...

Lcd_Out(1, 1, "Card detected ");

Continue Statement

You can use the continue statement within loops to “skip the cycle”:

- continue statement in for loop moves program counter to the line with the
keyword for; it does not change the loop counter,
- continue statement in while loop moves program counter to the line with loop
condition (top of the loop),
- continue statement in repeat loop moves program counter to the line with
loop condition (bottom of the loop).

page
mikroElektronika: Development tools - Books - Compilers
93
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Goto Statement

Use the goto statement to unconditionally jump to a local label — for more infor-
mation, refer to Labels. Syntax of goto statement is:

goto label_name;

This will transfer control to the location of a local label specified by label_name.
The goto line can come before or after the label.

The label declaration, marked statement, and goto statement must belong to the
same block. Hence it is not possible to jump into or out of a procedure or function.

You can use goto to break out from any level of nested control structures. Never
jump into a loop or other structured statement, since this can have unpredictable
effects.

Use of goto statement is generally discouraged as practically every algorithm can

be realized without it, resulting in legible structured programs. One possible appli-
cation of goto statement is breaking out from deeply nested control structures:

for (...) do
begin
for (...) do
begin
...
if (disaster) then goto Error;
...
end;
end;
.
.
.
Error: // error handling code

page

94
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Exit Statement

The exit statement allows you to break out of a routine (function or procedure).
It passes the control to the first statement following the routine call.

Here is a simple example:

procedure Proc1();
var error: byte;
begin
... // we're doing something here
if error = TRUE then exit;
... // some code, which won't be executed if error is true
end;

Note: If breaking out of a function, return value will be the value of the local
variable result at the moment of exit.

page
mikroElektronika: Development tools - Books - Compilers
95
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

COMPILER DIRECTIVES
mikroPascal treats comments beginning with a “$” immediately following the
opening brace as a compiler directive; for example, {$ELSE}. Compiler directives
are not case sensitive.

You can use conditional compilation to select particular sections of code to com-
pile while excluding other sections. All compiler directives must be completed in
the source file in which they begun.

Supported compiler directives are:

$DEFINE
$UNDEFINE
$IFDEF
$ELSE
$ENDIF

Directives $DEFINE and $UNDEFINE

Use directive $DEFINE to define a conditional compiler constant (“flag”). You can
use any identifier for a flag, with no limitations. No conflicts with program identi-
fiers are possible, as flags have a separate name space. Only one flag can be set
per directive.

For example:

{$DEFINE Extended_format}

Use $UNDEFINE to undefine (“clear”) previously defined flag.

Note: Pascal does not support macros; directives $DEFINE and $UNDEFINE do
not create/destroy macros; they only provide flags for directive $IFDEF to check
against.

page

96
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Directives $IFDEF..$ELSE

Conditional compilation is carried out by $IFDEF directive. The $IFDEF tests

whether a flag is currently defined or not; that is, whether a previous $DEFINE
directive has been processed for that flag and is still in force.

Directive $IFDEF is terminated by the $ENDIF directive, and can have an optional
$ELSE clause:

{$IFDEF flag}
<block of code>
{$ELSE}
<alternate block of code>
{$ENDIF}

First, $IFDEF checks if flag is defined by means of $DEFINE. If so, only <block
of code> will be compiled. Otherwise, <alternate block of code> will be
compiled. The $ENDIF ends the conditional sequence. The result of the preceding
scenario is that only one section of code (possibly empty) is passed on for further
processing.

The processed section can contain further conditional clauses, nested to any depth;
each $IFDEF must be matched with a closing $ENDIF.

Here is an example:

// Uncomment the appropriate flag for your application:

//{$DEFINE resolution10}
//{$DEFINE resolution12}

{$IFDEF resolution10}
// <code specific to 10-bit resolution>
{$ELSE}
{$IFDEF resolution12}
// <code specific to 12-bit resolution>
{$ELSE}
// <default code>
{$ENDIF}
{$ENDIF}

page
mikroElektronika: Development tools - Books - Compilers
97
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

$I is compiler directive for inserting content of given file into place where this
directive is called.

Here is an example:

{$I filename.txt}

Predefined Flags

mikroPascal has several predefined flags for configuring hardware. These can be
found in definition files (“defs” folder), specifying hardware settings for individual
chips. SFR are sorted under categories: ___SFR (umbrella for all registers),
___CONFIG_OSC (oscillator), ___CONFIG_WDT (Watchdog timer), and ___CON-
FIG_BORPOR (brown–out reset and power–on–timer).

page

98
mikroElektronika: Development tools - Books - Compilers
 CHAPTER
4

mikroPascal
Libraries
mikroPascal provides a number of built-in and library routines which help you
develop your application faster and easier. Libraries for ADC, CAN, USART, SPI,
I2C, 1-Wire, LCD, PWM, RS485, Serial Ethernet, Toshiba GLCD, Port Expander,
Serial GLCD, numeric formatting, bit manipulation, and many other are included
along with practical, ready-to-use code examples.

mikroElektronika: Development tools - Books - Compilers

 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

BUILT-IN ROUTINES
mikroPascal compiler provides a set of useful built-in utility functions. Built-in
routines can be used in any part of the project.

Currently, mikroPascal includes the following built-in functions:

Inc
Dec
Chr
Ord
SetBit
ClearBit
TestBit
Lo
Hi
Higher
Highest
SizeOf
Swap
Clock_Khz
Clock_Mhz
Reset
ClrWdt

page

100
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Inc
Prototype function Inc(var par : longint) : longint;

Description Increases parameter par by 1. Note that the function may be called as a self-contained
statement. Function returns the value of increased parameter. This is an “inline” routine;
code is generated in the place of the call, so the call doesn’t count against the nested call
limit.

Dec
Prototype function Dec(var par : longint) : longint;

Description Decreases parameter par by 1. Note that the function may be called as a self-contained
statement. Function returns the value of decreased parameter. This is an “inline” routine;
code is generated in the place of the call, so the call doesn’t count against the nested call
limit.

Chr
Prototype function Chr(code : byte) : char;

Returns Returns a character associated with the specified character code.

Description Function returns a character associated with the specified character code. Numbers
from 0 to 31 are the standard nonprintable ASCII codes. This is an “inline” routine; code
is generated in the place of the call, so the call doesn’t count against the nested call
limit.

Example c := Chr(10); // returns a linefeed character

Ord
Prototype function Ord(character : char) : byte;

Returns ASCII code of the character.

Description Function returns ASCII code of the character. This is an “inline” routine; code is gener-
ated in the place of the call, so the call doesn’t count against the nested call limit.

Example c := Ord('A'); // returns 65

page
mikroElektronika: Development tools - Books - Compilers
101
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

SetBit

Prototype procedure SetBit(var register : byte; rbit : byte);

Description Function sets the bit rbit of register. Parameter rbit needs to be a variable or liter-
al with value 0..7. See Predefined globals and constants for more information on register
identifiers. This is an “inline” routine; code is generated in the place of the call, so the
call doesn’t count against the nested call limit.

Example SetBit(PORTB, 2); // Set RB2

ClearBit

Prototype procedure ClearBit(var register : byte; rbit : byte);

Description Function clears the bit rbit of register. Parameter rbit needs to be a variable or lit-
eral with value 0..7. See Predefined globals and constants for more information on regis-
ter identifiers. This is an “inline” routine; code is generated in the place of the call, so
the call doesn’t count against the nested call limit.

Example ClearBit(PORTC, 7); // Clear RC7

TestBit

Prototype function TestBit(register, rbit : byte) : byte;

Returns If bit is set, returns 1, otherwise returns 0.

Description Function tests if the bit rbit of register is set. If set, function returns 1, otherwise
returns 0. Parameter rbit needs to be a variable or literal with value 0..7. See
Predefined globals and constants for more information on register identifiers. This is an
“inline” routine; code is generated in the place of the call, so the call doesn’t count
against the nested call limit.

Example flag := TestBit(PORTE, 2); // 1 if RE2 is set, otherwise 0

page

102
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Lo

Prototype function Lo(number : byte..longint) : byte;

Returns Returns the lowest 8 bits (byte) of number, bits 0..7.

Description Function returns the lowest byte of number. Function does not interpret bit patterns of
number – it merely returns 8 bits as found in register.

Example a := Lo($1AC30F4); // Equals $F4

Hi

Prototype function Hi(number : word..longint) : byte;

Returns Returns byte next to the lowest byte of number, bits 8..15.

Description Function returns byte next to the lowest byte of number. Function does not interpret bit
patterns of number – it merely returns 8 bits as found in register.

Example a := Hi($1AC30F4); // Equals $30

Higher

Prototype function Higher(number : longint) : byte;

Returns Returns byte next to the highest byte of number, bits 16..23.

Description Function returns byte next to the highest byte of number. Function does not interpret bit
patterns of number – it merely returns 8 bits as found in register.

Example a := Higher($1AC30F4); // Equals $AC

page
mikroElektronika: Development tools - Books - Compilers
103
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Highest
Prototype function Highest(number : longint) : byte;

Returns Returns the highest byte of number, bits 24..31.

Description Function returns the highest byte of number. Function does not interpret bit patterns of
number – it merely returns 8 bits as found in register.

Example a := Highest($1AC30F4); // Equals $01

SizeOf
Prototype function SizeOf( variable_name : string[100]): word

Returns Returns size in bytes of a variable.

Description This function gives the size in bytes of how much memory space is used by its operand.

Example program onewire_test;

type TRec = record

FieldA : byte; // 1 byte
FieldB : word; // 2 bytes
end; // total 3 bytes

var SomeVar : TRec;

SomeOtherVar : word;
begin
someOtherVar := SizeOf(SomeVar); // SomeOtherVar := 3
end.

Swap

Prototype function Swap(var arg : byte) : byte;

Returns Returns byte consisting of swapped nibbles.

Description Swaps higher nibble (bits <7..4>) and lower nibble (bits <3..0>) of arg.

Example PORTB := $F0;

PORTA := Swap(PORTB); // PORTA = PORTB = $0F

page

104
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Clock_Khz

Prototype function Clock_Khz : word;

Returns Device clock in KHz.

Description Returns device clock in KHz, rounded to the nearest integer.

Example clk := Clock_Khz;

Clock_Mhz

Prototype function Clock_Mhz : byte;

Returns Device clock in MHz.

Description Returns device clock in MHz, rounded to the nearest integer.

Example clk := Clock_Mhz;

Reset

Prototype procedure Reset;

Description This procedure is equal to assembler instruction reset. This procedure works only for
P18.
Example Reset; //Resets the PIC MCU

ClrWdt

Prototype procedure ClrWdt;

Description This procedure is equal to assembler instruction clrwdt.

Example ClrWdt; //Clears PIC's WDT

page
mikroElektronika: Development tools - Books - Compilers
105
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

LIBRARY ROUTINES
mikroPascal provides a set of libraries which simplifies the initialization and use
of PIC MCU and its units. Library functions do not require any header files to be
included; you can use them anywhere in your projects. Currently available
libraries include:

- ADC Library - Delays Library

- CAN Library - Math Library
- CANSPI Library - String Library
- Compact Flash Library
- EEPROM Library
- Ethernet Library
- SPI Ethernet Library
- Flash Memory Library
- Graphic LCD Library
- T6963C Graphic LCD Library
- I²C Library
- Keypad Library
- LCD Library
- LCD8 Library
- Manchester Code Library
- Multi Media Card Library
- OneWire Library
- PS/2 Library
- PWM Library
- RS-485 Library
- Software I²C Library
- Software SPI Library
- Software UART Library
- Sound Library
- SPI Library
- USART Library
- USB HID Library
- Util Library
- Port Expander Library
- SPI GLCD Library
- SPI LCD Library
- SPI LCD8 Library
- SPI T6963C Graphic LCD Library
- Conversions Library

page

106
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

ADC Library
ADC (Analog to Digital Converter) unit is available with a number of PIC MCU
models. Library function Acd_Read is included to provide you comfortable work
with the unit.

Adc_Read

Prototype function Adc_Read(channel : byte) : word;

Returns 10-bit unsigned value read from the specified ADC channel.

Description Initializes PIC’s internal ADC unit to work with RC clock. Clock determines the time
period necessary for performing AD conversion (min 12TAD). RC sources typically
have Tad 4uS.

Parameter channel represents the channel from which the analog value is to be
acquired. For channel-to-pin mapping please refer to documentation for the appropriate
PIC MCU.

Requires PIC MCU with built-in ADC unit. You should consult the Datasheet documentation for
specific device (most devices from PIC16/18 families have it).

Before using the function, be sure to configure the appropriate TRISA bits to designate
the pins as input. Also, configure the desired pin as analog input, and set Vref (voltage
reference value).

Example tmp = Adc_Read(1); // Read analog value from channel 1

page
mikroElektronika: Development tools - Books - Compilers
107
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

This code snippet reads analog value from channel 2 and displays it on PORTD (lower 8 bits) and
PORTB (2 most significant bits).
program Adc_Test;
var temp_res : word;

begin
ADCON1 := $80; // Configure analog inputs and Vref
TRISA := $FF; // PORTA is input
TRISB := $3F; // Pins RB7 and RB6 are output
TRISD := $0; // PORTD is output
while TRUE do
begin
temp_res := Adc_Read(2);
PORTD := temp_res; // Send lower 8 bits to PORTD
PORTB := word(temp_res shr 2); // Send 2 most significant bits to PORTB
end;
end.

Hardware Connection

330 LD0
VCC 40
RB7
39
RB6
38 330 LD1
RB5
4 37
RA2 RB4
36 330 LD2
RB3
PIC18F452

35
RB2
34 330 LD3
RB1
33
RB0
330 LD4
VCC
11 330 LD5
VCC
12
GND
13
OSC1
330 LD6
14
OSC2
330 LD7

VCC
10K

Reset 8MHz

page

108
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CAN Library
mikroPascal provides a library (driver) for working with the CAN unit.

CAN is a very robust protocol that has error detection and signalling, self–check-
ing and fault confinement. Faulty CAN data and remote frames are re-transmitted
automatically, similar to the Ethernet.

Data transfer rates vary from up to 1 Mbit/s at network lengths below 40m to 250
Kbit/s at 250m cables, and can go even lower at greater network distances, down
to 200Kbit/s, which is the minimum bitrate defined by the standard. Cables used
are shielded twisted pairs, and maximum cable length is 1000m.

CAN supports two message formats:

Standard format, with 11 identifier bits, and

Extended format, with 29 identifier bits

Note: CAN routines are currently supported only by P18XXX8 PICmicros.

Microcontroller must be connected to CAN transceiver (MCP2551 or similar)
which is connected to CAN bus.

Note: Be sure to check CAN constants necessary for using some of the functions.
See page 99.

Library Routines

CANSetOperationMode
CANGetOperationMode
CANInitialize
CANSetBaudRate
CANSetMask
CANSetFilter
CANRead
CANWrite

Following routines are for the internal use by compiler only:

RegsToCANID
CANIDToRegs

page
mikroElektronika: Development tools - Books - Compilers
109
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CANSetOperationMode

Prototype procedure CANSetOperationMode(mode : byte, wait_flag : byte);

Description Sets CAN to requested mode, i.e. copies mode to CANSTAT. Parameter mode needs to
be one of CAN_OP_MODE constants (see CAN constants).

Parameter wait_flag needs to be either 0 or $FF:

If set to $FF, this is a blocking call – the function won’t “return” until the requested
mode is set. If 0, this is a non-blocking call. It does not verify if CAN unit is switched
to requested mode or not. Caller must use function CANGetOperationMode to verify
correct operation mode before performing mode specific operation.

Requires CAN routines are currently supported only by P18XXX8 PICmicros. Microcontroller
must be connected to CAN transceiver (MCP2551 or similar) which is connected to
CAN bus.

Example CANSetOperationMode(CAN_MODE_CONFIG, $FF);

CANGetOperationMode

Prototype function CANGetOperationMode : byte;

Returns Current opmode.

Description Function returns current operational mode of CAN unit.

Requires CAN routines are currently supported only by P18XXX8 PICmicros. Microcontroller
must be connected to CAN transceiver (MCP2551 or similar) which is connected to
CAN bus.

Example if CANGetOperationMode = CAN_MODE_NORMAL then ...

page

110
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CANInitialize

Prototype procedure CANInitialize(SJW, BRP, PHSEG1, PHSEG2, PROPSEG,

CAN_CONFIG_FLAGS : byte);

Description Initializes CAN. All pending transmissions are aborted. Sets all mask registers to 0 to
allow all messages.

Filter registers are set according to flag value:

if (CAN_CONFIG_FLAGS and CAN_CONFIG_VALID_XTD_MSG) <> 0

// Set all filters to XTD_MSG
else if (config and CONFIG_VALID_STD_MSG) <> 0
// Set all filters to STD_MSG
else
// Set half of the filters to STD, and the rest to XTD_MSG.

Parameters:

SJW as defined in 18XXX8 datasheet (1–4)

BRP as defined in 18XXX8 datasheet (1–64)
PHSEG1 as defined in 18XXX8 datasheet (1–8)
PHSEG2 as defined in 18XXX8 datasheet (1–8)
PROPSEG as defined in 18XXX8 datasheet (1–8)
CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants).

Requires CAN must be in Config mode; otherwise the function will be ignored.

Example init:= CAN_CONFIG_SAMPLE_THRICE and

CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and
CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG and
CAN_CONFIG_LINE_FILTER_OFF;
//...
CANInitialize(1, 1, 3, 3, 1, init); // Initialize CAN

page
mikroElektronika: Development tools - Books - Compilers
111
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CANSetBaudRate

Prototype procedure CANSetBaudRate(SJW, BRP, PHSEG1, PHSEG2, PROPSEG,

CAN_CONFIG_FLAGS : byte);

Description Sets CAN baud rate. Due to complexity of CAN protocol, you cannot simply force a bps
value. Instead, use this function when CAN is in Config mode. Refer to datasheet for
details.

Parameters:

SJW as defined in 18XXX8 datasheet (1–4)

BRP as defined in 18XXX8 datasheet (1–64)
PHSEG1 as defined in 18XXX8 datasheet (1–8)
PHSEG2 as defined in 18XXX8 datasheet (1–8)
PROPSEG as defined in 18XXX8 datasheet (1–8)
CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants)

Requires CAN must be in Config mode; otherwise the function will be ignored.

Example init := CAN_CONFIG_SAMPLE_THRICE and

CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and
CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG and
CAN_CONFIG_LINE_FILTER_OFF;
//...
CANSetBaudRate(1, 1, 3, 3, 1, init);

page

112
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CANSetMask

Prototype procedure CANSetMask(CAN_MASK : byte; value : longint;

CAN_CONFIG_FLAGS : byte);

Description Function sets mask for advanced filtering of messages. Given value is bit adjusted to
appropriate buffer mask registers.

Parameters: CAN_MASK is one of predefined constant values (see CAN constants);

value is the mask register value; CAN_CONFIG_FLAGS selects type of message to filter,
either CAN_CONFIG_XTD_MSG or CAN_CONFIG_STD_MSG.

Requires CAN must be in Config mode; otherwise the function will be ignored.

Example // Set all mask bits to 1, i.e. all filtered bits are relevant:
CANSetMask(CAN_MASK_B1, -1, CAN_CONFIG_XTD_MSG);

{ Note that -1 is just a cheaper way to write $FFFFFFFF.

Complement will do the trick and fill it up with ones. }

CANSetFilter

Prototype procedure CANSetFilter(CAN_FILTER : byte; value : longint;

CAN_CONFIG_FLAGS : byte);

Description Function sets mask for advanced filtering of messages. Given value is bit adjusted to
appropriate buffer mask registers.

Parameters: CAN_MASK is one of predefined constant values (see CAN constants);

value is the filter register value; CAN_CONFIG_FLAGS selects type of message to filter,
either CAN_CONFIG_XTD_MSG or CAN_CONFIG_STD_MSG.

Requires CAN must be in Config mode; otherwise the function will be ignored.

Example // Set id of filter B1_F1 to 3:

CANSetFilter(CAN_FILTER_B1_F1, 3, CAN_CONFIG_XTD_MSG);

page
mikroElektronika: Development tools - Books - Compilers
113
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CANRead

Prototype function CANRead(var id : longint; var data : array[8] of byte;

var datalen: byte; var CAN_RX_MSG_FLAGS : byte) : byte;

Returns Message from receive buffer or zero if no message found.

Description Function reads message from receive buffer. If at least one full receive buffer is found, it
is extracted and returned. If none found, function returns zero.

Parameters: id is message identifier; data is an array of bytes up to 8 bytes in length;

datalen is data length, from 1–8; CAN_RX_MSG_FLAGS is value formed from constants
(see CAN constants).

Requires CAN must be in mode in which receiving is possible.

Example rcv := CANRead(id, data, len, 0);

CANWrite

Prototype function CANWrite(id : longint; var data : array[8] of byte;

datalen, CAN_TX_MSG_FLAGS : byte) : byte;

Returns Returns zero if message cannot be queued (buffer full).

Description If at least one empty transmit buffer is found, function sends message on queue for
transmission. If buffer is full, function returns 0.

Parameters: id is CAN message identifier. Only 11 or 29 bits may be used depending

on message type (standard or extended); data is array of bytes up to 8 bytes in length;
datalen is data length from 1–8; CAN_TX_MSG_FLAGS is value formed from constants
(see CAN constants).

Requires CAN must be in Normal mode.

Example tx = CAN_TX_PRIORITY_0 and CAN_TX_XTD_FRAME;

CANWrite(id, data, 2, tx);

page

114
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CAN Constants
There is a number of constants predefined in CAN library. To be able to use the
library effectively, you need to be familiar with these. You might want to check
the example at the end of the chapter.

CAN_OP_MODE

CAN_OP_MODE constants define CAN operation mode. Function

CANSetOperationMode expects one of these as its argument:

const CAN_MODE_BITS = $E0; // Use it to access mode bits

const CAN_MODE_NORMAL = 0;
const CAN_MODE_SLEEP = $20;
const CAN_MODE_LOOP = $40;
const CAN_MODE_LISTEN = $60;
const CAN_MODE_CONFIG = $80;

CAN_CONFIG_FLAGS

CAN_CONFIG_FLAGS constants define flags related to CAN unit configuration.

Functions CANInitialize and CANSetBaudRate expect one of these (or a bitwise
combination) as their argument:
const CAN_CONFIG_DEFAULT = $FF; // 11111111

const CAN_CONFIG_PHSEG2_PRG_BIT = $01;

const CAN_CONFIG_PHSEG2_PRG_ON = $FF; // XXXXXXX1
const CAN_CONFIG_PHSEG2_PRG_OFF = $FE; // XXXXXXX0

const CAN_CONFIG_LINE_FILTER_BIT = $02;

const CAN_CONFIG_LINE_FILTER_ON = $FF; // XXXXXX1X
const CAN_CONFIG_LINE_FILTER_OFF = $FD; // XXXXXX0X

const CAN_CONFIG_SAMPLE_BIT = $04;

const CAN_CONFIG_SAMPLE_ONCE = $FF; // XXXXX1XX
const CAN_CONFIG_SAMPLE_THRICE = $FB; // XXXXX0XX

const CAN_CONFIG_MSG_TYPE_BIT = $08;

const CAN_CONFIG_STD_MSG = $FF; // XXXX1XXX
const CAN_CONFIG_XTD_MSG = $F7; // XXXX0XXX

// continues..

page
mikroElektronika: Development tools - Books - Compilers
115
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

// ..continued

const CAN_CONFIG_DBL_BUFFER_BIT = $10;

const CAN_CONFIG_DBL_BUFFER_ON = $FF; // XXX1XXXX
const CAN_CONFIG_DBL_BUFFER_OFF = $EF; // XXX0XXXX

const CAN_CONFIG_MSG_BITS = $60;

const CAN_CONFIG_ALL_MSG = $FF; // X11XXXXX
const CAN_CONFIG_VALID_XTD_MSG = $DF; // X10XXXXX
const CAN_CONFIG_VALID_STD_MSG = $BF; // X01XXXXX
const CAN_CONFIG_ALL_VALID_MSG = $9F; // X00XXXXX

You may use bitwise AND to form config byte out of these values. For example:
init := CAN_CONFIG_SAMPLE_THRICE and CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG and CAN_CONFIG_LINE_FILTER_OFF;
//...
CANInitialize(1, 1, 3, 3, 1, init); // initialize CAN

CAN_TX_MSG_FLAGS

CAN_TX_MSG_FLAGS are flags related to transmission of a CAN message:

const CAN_TX_PRIORITY_BITS = $03;
const CAN_TX_PRIORITY_0 = $FC; // XXXXXX00
const CAN_TX_PRIORITY_1 = $FD; // XXXXXX01
const CAN_TX_PRIORITY_2 = $FE; // XXXXXX10
const CAN_TX_PRIORITY_3 = $FF; // XXXXXX11

const CAN_TX_FRAME_BIT = $08;

const CAN_TX_STD_FRAME = $FF; // XXXXX1XX
const CAN_TX_XTD_FRAME = $F7; // XXXXX0XX

const CAN_TX_RTR_BIT = $40;

const CAN_TX_NO_RTR_FRAME = $FF; // X1XXXXXX
const CAN_TX_RTR_FRAME = $BF; // X0XXXXXX

You may use bitwise AND to adjust the appropriate flags. For example:
// form value to be used with CANSendMessage:
send_config := CAN_TX_PRIORITY_0 and CAN_TX_XTD_FRAME and
CAN_TX_NO_RTR_FRAME;
//...
CANSendMessage(id, data, 1, send_config);

page

116
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CAN_RX_MSG_FLAGS

CAN_RX_MSG_FLAGS are flags related to reception of CAN message. If a particular

bit is set; corresponding meaning is TRUE or else it will be FALSE.

const CAN_RX_FILTER_BITS = $07; // Use it to access filter bits

const CAN_RX_FILTER_1 = $00;
const CAN_RX_FILTER_2 = $01;
const CAN_RX_FILTER_3 = $02;
const CAN_RX_FILTER_4 = $03;
const CAN_RX_FILTER_5 = $04;
const CAN_RX_FILTER_6 = $05;
const CAN_RX_OVERFLOW = $08; // Set if Overflowed; else clear
const CAN_RX_INVALID_MSG = $10; // Set if invalid; else clear
const CAN_RX_XTD_FRAME = $20; // Set if XTD msg; else clear
const CAN_RX_RTR_FRAME = $40; // Set if RTR msg; else clear
const CAN_RX_DBL_BUFFERED = $80; // Set if msg was
// hardware double-buffered

You may use bitwise AND to adjust the appropriate flags. For example:

if MsgFlag and CAN_RX_OVERFLOW = 0 then

... // Receiver overflow has occurred; previous message is lost.

CAN_MASK

CAN_MASK constants define mask codes. Function CANSetMask expects one of these
as its argument:

const CAN_MASK_B1 = 0;
const CAN_MASK_B2 = 1;

CAN_FILTER

CAN_FILTER constants define filter codes. Function CANSetFilter expects one of

these as its argument:

const CAN_FILTER_B1_F1 = 0;
const CAN_FILTER_B1_F2 = 1;
const CAN_FILTER_B2_F1 = 2;
const CAN_FILTER_B2_F2 = 3;
const CAN_FILTER_B2_F3 = 4;
const CAN_FILTER_B2_F4 = 5;

page
mikroElektronika: Development tools - Books - Compilers
117
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The example demonstrates CAN protocol. It is a simple data exchange between 2 PIC’s, where
data is incremented upon each bounce. Data is printed on PORTC (lower byte) and PORTD (high-
er byte) for a visual check. Note that the data exchange doesn’t start until you press a button;
check the code below.
program CAN_test;

var aa,aa1,len,aa2 : byte;

data : array[8] of byte;
id : longint;
zr, cont, oldstate: byte;

function TestButton : byte;

begin
result := true;
if Button(PORTB, 0, 1, 0) = true then oldstate:= 255;
if (oldstate and Button(PORTB, 0, 1, 1)) then
begin
result := false;
oldstate := 0;
end;
end;

begin
SetBit(TRISB,0); // pin RB0 is input
PORTC := 0;
TRISC := 0;
PORTD := 0;
TRISD := 0;
aa := 0; aa1 := 0; aa2 := 0;

// Form value to be used with CANSendMessage

aa1 := CAN_TX_PRIORITY_0 and
CAN_TX_XTD_FRAME and
CAN_TX_NO_RTR_FRAME;

// Form value to be used with CANInitialize

aa := CAN_CONFIG_SAMPLE_THRICE and
CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and
CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG and
CAN_CONFIG_LINE_FILTER_OFF;

// continues ..

page

118
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

// .. continued

cont := true;
while (cont) do cont := TestButton;

data[0] := 0;

// Initialize CAN
CANInitialize(1,1,3,3,1,aa);

// Set CONFIG mode

CANSetOperationMode(CAN_MODE_CONFIG,TRUE);

ID := -1;

// Set all mask1 bits to ones

CANSetMask(CAN_MASK_B1,ID,CAN_CONFIG_XTD_MSG);

// Set all mask2 bits to ones

CANSetMask(CAN_MASK_B2,ID,CAN_CONFIG_XTD_MSG);

// Set id of filter B1_F1 to 3

CANSetFilter(CAN_FILTER_B1_F1,3,CAN_CONFIG_XTD_MSG);

// Set NORMAL mode

CANSetOperationMode(CAN_MODE_NORMAL,TRUE);

PORTD := $FF;
id := 12111;

// Send message via CAN

CANSendMessage(id,data,1,aa1);

while true do
begin
oldstate := 0;
zr := CANReceiveMessage(id , Data , len, aa2);
if (id = 3) and zr then
begin
PORTD := $AA;
PORTC := data[0]; // Output data at PORTC
data[0] := data[0]+1;
id := 12111;
CANSendMessage(id,data,1,aa1); // Send incremented data back
if len = 2 then // If message contains two data bytes
PORTD := data[1]; // send second byte to PORTD
end;
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
119
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection

CAN TX of MCU

CAN RX of MCU

10

1 8
TX-CAN RS
2 7
GND CANH
3 6
VCC VCC CANL
4 5
RXD Vref

MCP2551

Shielded pair
no longer than 300m

page

120
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CANSPI Library
SPI unit is available with a number of PICmicros. mikroPascal provides a library
(driver) for working with the external CAN units (such as MCP2515 or
MCP2510) via SPI.

In mikroPascal, each routine of CAN library has its CANSPI counterpart with
identical syntax. For more information on the Controller Area Network, consult
the CAN Library. Note that the effective communication speed depends on the
SPI, and is certainly slower than the “real” CAN.

Note: CANSPI functions are supported by any PIC MCU that has SPI interface on
PORTC. Also, CS pin of MCP2510 or MCP2515 must be connected to RC0.
Example of HW connection is given at the end of the chapter.

Note: Be sure to check CAN constants necessary for using some of the functions.
See CAN Constants.

Note: SPI_Init; must be called before initializing CANSPI.

Library Routines

CANSPISetOperationMode
CANSPIGetOperationMode
CANSPIInitialize
CANSPISetBaudRate
CANSPISetMask
CANSPISetFilter
CANSPIRead
CANSPIWrite

Following routines are for the internal use by compiler only:

RegsToCANSPIID
CANSPIIDToRegs

page
mikroElektronika: Development tools - Books - Compilers
121
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CANSPISetOperationMode

Prototype procedure CANSPISetOperationMode(mode : byte, wait_flag : byte);

Description Sets CAN to requested mode, i.e. copies mode to CANSTAT. Parameter mode needs to
be one of CAN_OP_MODE constants (see CAN constants, page 141).

Parameter wait_flag needs to be either 0 or 0xFF: If set to 0xFF, this is a blocking

call – the function won’t “return” until the requested mode is set. If 0, this is a non-
blocking call. It does not verify if CAN unit is switched to requested mode or not. Caller
must use function CANSPIGetOperationMode to verify correct operation mode before
performing mode specific operation.

Requires CANSPI functions are supported by any PIC MCU that has SPI interface on PORTC.
Also, CS pin of MCP2510 or MCP2515 must be connected to RC0.

Example CANSPISetOperationMode(CAN_MODE_CONFIG, $FF);

CANSPIGetOperationMode

Prototype function CANSPIGetOperationMode : byte;

Returns Current opmode.

Description Function returns current operational mode of CAN unit.

Example if (CANSPIGetOperationMode = CAN_MODE_CONFIG) then ...

page

122
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CANSPIInitialize

Prototype procedure CANSPIInitialize(SJW, BRP, PHSEG1, PHSEG2, PROPSEG,

CAN_CONFIG_FLAGS : byte);

Description Initializes CANSPI. All pending transmissions are aborted. Sets all mask registers to 0
to allow all messages.

Filter registers are set according to flag value:

if ((CAN_CONFIG_FLAGS and CAN_CONFIG_VALID_XTD_MSG) = 0) then

// Set all filters to XTD_MSG
else if ((config and CONFIG_VALID_STD_MSG) = 0) then
// Set all filters to STD_MSG
else
// Set half the filters to STD, and the rest to XTD_MSG

Parameters:

SJW as defined in 18XXX8 datasheet (1–4)

BRP as defined in 18XXX8 datasheet (1–64)
PHSEG1 as defined in 18XXX8 datasheet (1–8)
PHSEG2 as defined in 18XXX8 datasheet (1–8)
PROPSEG as defined in 18XXX8 datasheet (1–8)
CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants, page
99).

Requires SPI_Init; must be called before initializing CANSPI.

CANSPI must be in Config mode; otherwise the function will be ignored.

Example init := CAN_CONFIG_SAMPLE_THRICE and

CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and
CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG and
CAN_CONFIG_LINE_FILTER_OFF;
...
CANSPIInitialize(1, 1, 3, 3, 1, init); // Initialize CANSPI

page
mikroElektronika: Development tools - Books - Compilers
123
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CANSPISetBaudRate

Prototype procedure CANSPISetBaudRate(SJW, BRP, PHSEG1, PHSEG2, PROPSEG,

CAN_CONFIG_FLAGS : byte);

Description Sets CANSPI baud rate. Due to complexity of CANSPI protocol, you cannot simply
force a bps value. Instead, use this function when CANSPI is in Config mode. Refer to
datasheet for details.

Parameters:

SJW as defined in 18XXX8 datasheet (1–4)

BRP as defined in 18XXX8 datasheet (1–64)
PHSEG1 as defined in 18XXX8 datasheet (1–8)
PHSEG2 as defined in 18XXX8 datasheet (1–8)
PROPSEG as defined in 18XXX8 datasheet (1–8)
CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants)

Requires CANSPI must be in Config mode; otherwise the function will be ignored.

Example init := CAN_CONFIG_SAMPLE_THRICE and

CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and
CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG and
CAN_CONFIG_LINE_FILTER_OFF
...
CANSPISetBaudRate(1, 1, 3, 3, 1, init);

page

124
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

CANSPISetMask

Prototype procedure CANSPISetMask(CAN_MASK : byte; value : longint;

CAN_CONFIG_FLAGS : byte);

Description Function sets mask for advanced filtering of messages. Given value is bit adjusted to
appropriate buffer mask registers.

Parameters: CAN_MASK is one of predefined constant values (see CAN constants);

value is the mask register value; CAN_CONFIG_FLAGS selects type of message to filter,
either CAN_CONFIG_XTD_MSG or CAN_CONFIG_STD_MSG.

Requires CANSPI must be in Config mode; otherwise the function will be ignored.

Example // Set all mask bits to 1, i.e. all filtered bits are relevant:
CANSPISetMask(CAN_MASK_B1, -1, CAN_CONFIG_XTD_MSG);

{ Note that -1 is just a cheaper way to write $FFFFFFFF.

Complement will do the trick and fill it up with ones }

CANSPISetFilter

Prototype procedure CANSPISetFilter(CAN_FILTER : byte; val : longint;

CAN_CONFIG_FLAGS : byte);

Description Function sets mask for advanced filtering of messages. Given value is bit adjusted to
appropriate buffer mask registers.

Parameters: CAN_MASK is one of predefined constant values (see CAN constants);

value is the filter register value; CAN_CONFIG_FLAGS selects type of message to filter,
either CAN_CONFIG_XTD_MSG or CAN_CONFIG_STD_MSG.

Requires CANSPI must be in Config mode; otherwise the function will be ignored.

Example // Set id of filter B1_F1 to 3:

CANSPISetFilter(CAN_FILTER_B1_F1, 3, CAN_CONFIG_XTD_MSG);

page
mikroElektronika: Development tools - Books - Compilers
125
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

CANSPIRead

Prototype function CANSPIRead(var id : longint; var Data : array[8] of

byte; var DataLen: byte; var CAN_RX_MSG_FLAGS : byte) : byte;

Returns Message from receive buffer or zero if no message found.

Description Function reads message from receive buffer. If at least one full receive buffer is found, it
is extracted and returned. If none found, function returns zero.

Parameters: id is message identifier; data is an array of bytes up to 8 bytes in length;

datalen is data length, from 1–8; CAN_RX_MSG_FLAGS is value formed from constants
(see CAN constants).

Requires CANSPI must be in mode in which receiving is possible.

Example rcv := CANSPIRead(id, data, len, rx);

CANSPIWrite

Prototype function CANSPIwrite(id : longint; var data : array[8] of byte;

datalen, CAN_TX_MSG_FLAGS : byte) : byte;

Returns Returns zero if message cannot be queued (buffer full).

Description If at least one empty transmit buffer is found, function sends message on queue for
transmission. If buffer is full, function returns 0.

Parameters: id is CANSPI message identifier. Only 11 or 29 bits may be used depend-

ing on message type (standard or extended); data is array of bytes up to 8 bytes in
length; datalen is data length from 1–8; CAN_TX_MSG_FLAGS is value formed from
constants (see CAN constants).

Requires CANSPI must be in Normal mode.

Example tx := CAN_TX_PRIORITY_0 and CAN_TX_XTD_FRAME;

CANSPIWrite(id, data, 2, tx);

page

126
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example

The example demonstrates CANSPI protocol. It is a simple data exchange between 2 PIC’s, where
data is incremented upon each bounce. Data is printed on PORTC (lower byte) and PORTD (high-
er byte) for a visual check.

program CANSPI_test;

var
aa, aa1, len, aa2 : byte;
data : array[8] of byte;
id : longint;
zr : byte;

begin
TRISB := 0;
Spi_Init; // Must be performed before any other activity
ClearBit(TRISC,2); // This pin is connected to Reset pin of MCP2510
ClearBit(portc,2); // Keep MCP2510 in reset state
SetBit(PORTC,0); // Make sure that MCP2510 is not selected
ClearBit(TRISC,0); // Make RC0 output
PORTD := 0;
TRISD := 0; // PORTD is output
aa := 0;
aa1 := 0;
aa2 := 0;

// Prepare flags for CANSPIinitialize procedure

aa := CAN_CONFIG_SAMPLE_THRICE and
CAN_CONFIG_PHSEG2_PRG_ON and
CAN_CONFIG_STD_MSG and
CAN_CONFIG_DBL_BUFFER_ON and
CAN_CONFIG_VALID_XTD_MSG;

// Activate MCP2510 chip

SetBit(PORTC,2);

// continues ..

page
mikroElektronika: Development tools - Books - Compilers
127
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

// .. continued

Spi_init; // Initialize SPI

// Prepare flags for CANSPIwrite function

aa1 := CAN_TX_PRIORITY_BITS and
CAN_TX_FRAME_BIT and
CAN_TX_RTR_BIT;

// Initialize MCP2510
CANSPIInitialize(1,2,3,3,1,aa);

// Set CONFIG mode

CANSPISetOperationMode(CAN_MODE_CONFIG,true);

ID := -1;

// Set all mask1 bits to ones

CANSPISetMask(CAN_MASK_B1,id,CAN_CONFIG_XTD_MSG);

// Set all mask2 bits to ones

CANSPISetMask(CAN_MASK_B2,0,CAN_CONFIG_XTD_MSG);

// Set filter_b1_f1 id to 12111

CANSPISetFilter(CAN_FILTER_B1_F1,12111,CAN_CONFIG_XTD_MSG);

// Get back to NORMAL mode

CANSPISetOperationMode(CAN_MODE_NORMAL,true);

while true do
begin
zr := CANSPIRead(id, Data, len, aa2);
if (id = 12111) and zr then
begin
PORTD := $AA;
PORTB := data[0];
data[0]:=data[0]+1;
id := 3;
Delay_ms(10);
CANSPIWrite(id,data,1,aa1);
if len = 2 then PORTD := data[1];
end;
end;
end.

page

128
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

VCC

100K VCC

1 18
TX Vdd
2 17
RX RST

PIC18F452
3 16
CLKO CS
4 15
TX0 SO 33
5 14 RB0
TX1 SI
6 13 VCC
TX2 SCK
7 12 11
OSC2 INT VCC
8 11 12
OSC1 RX0B GND
13
9 10 OSC1
Vss RX1B 14
8 MhZ OSC2
15
MCP2510 RC0

8 MhZ 24
RC5
18 23
RC3 RC4
10

1 8
TX-CAN RS
2 7
GND CANH
3 6
VCC VCC CANL
4 5
RXD Vref

MCP2551

Shielded pair
no longer than 300m

page
mikroElektronika: Development tools - Books - Compilers
129
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Compact Flash Library

Compact Flash Library provides routines for accessing data on Compact Flash
card (abbrev. CF further in text). CF cards are widely used memory elements,
commonly found in digital cameras. Great capacity (8MB ~ 2GB, and more) and
excellent access time of typically few microseconds make them very attractive for
microcontroller applications.

In CF card, data is divided into sectors, one sector usually comprising 512 bytes
(few older models have sectors of 256B). Read and write operations are not per-
formed directly, but successively through 512B buffer. Following routines can be
used for CF with FAT16, and FAT32 file system. Note that routines for file han-
dling can be used only with FAT16 file system.

Important! Before write operation, make sure you don’t overwrite boot or FAT
sector as it could make your card on PC or digital cam unreadable. Drive mapping
tools, such as Winhex, can be of a great assistance.

Library Routines

Cf_Init
Cf_Detect
Cf_Read_Init
Cf_Read_Byte
Cf_Write_Init
Cf_Write_Byte
Cf_Write_Sector
Cf_Read_Sector

Cf_Fat_Init
Cf_Fat_Assign
Cf_Fat_Reset
Cf_Fat_Read
Cf_Fat_Rewrite
Cf_Fat_Append
Cf_Fat_Delete
Cf_Fat_Write
Cf_Fat_Set_File_Date
Cf_Fat_Get_File_Date
Cf_Fat_Get_File_Size
Cf_Fat_Get_Swap_File

Function Cf_Set_Reg_Adr is for compiler internal purpose only.

page

130
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Cf_Init

Prototype procedure Cf_Init(var ctrlport, dataport : byte);

Description Initializes ports appropriately for communication with CF card. Specify two different
ports: ctrlport and dataport.

Example Cf_Init(PORTB, PORTD);

Cf_Detect

Prototype function Cf_Detect : byte;

Returns Returns 1 if CF is present, otherwise returns 0.

Description Checks for presence of CF card on ctrlport.

Example // Wait until CF card is inserted:

repeat
nop;
until Cf_Detect = 1;

Cf_Read_Init

Prototype procedure Cf_Read_Init(address : longint; sectcnt : byte);

Description Initializes CF card for reading. Parameter address specifies sector address from where
data will be read, and sectcnt is total number of sectors prepared for read operation.

Requires Ports must be initialized. See Cf_Init.

Example Cf_Read_Init(590, 1);

page
mikroElektronika: Development tools - Books - Compilers
131
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Cf_Read_Byte

Prototype function Cf_Read_Byte : byte;

Returns Returns byte from CF.

Description Reads one byte from CF.

Requires CF must be initialized for read operation. See Cf_Read_Init.

Example PORTC := Cf_Read_Byte;

Cf_Write_Init

Prototype procedure Cf_Write_Init(address : longint; sectcnt : byte);

Description Initializes CF card for writing. Parameter address specifies sector address where data
will be stored, and sectcnt is total number of sectors prepared for write operation.

Requires Ports must be initialized. See Cf_Init.

Example Cf_Write_Init(590, 1);

Cf_Write_Byte

Prototype procedure Cf_Write_Byte(data : byte);

Description Writes one byte (data) to CF. All 512 bytes are transferred to a buffer.

Requires CF must be initialized for write operation. See Cf_Write_Init.

Example Cf_Write_Byte(100);

page

132
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Cf_Write_Sector
Prototype function Cf_Write_Sector(sector : longint; var data : array[512]
of byte) : byte;

Returns Returns 0 if write was successful; returns 1 if there was an error in sending write com-
mand; returns 2 if there was an error in writing.
Description Function writes 512 bytes of data to CF card at sector address sector. Function returns 0
if write was successful, or 1 if there was an error in sending write command, or 2 if
there was an error in writing.
Requires Ports must be initialized. See Cf_Init.
Example error := Cf_Write_Sector(sector, data);

Cf_Read_Sector
Prototype function Cf_Read_Sector(sector : longint; var data : array[512]
of byte) : byte;

Returns Returns 0 if read was successful, or 1 if an error occurred.

Description Function reads one sector (512 bytes) from CF card at sector address sector. Read data
is stored in the array data. Function returns 0 if read was successful, or 1 if an error
occurred.
Requires Ports must be initialized. See Cf_Init.
Example error := Cf_Read_Sector(sector, data);

Cf_Fat_Init

Prototype function Cf_Fat_Init(var ctrlPort : byte; var dataPort : byte) :

byte;

Returns Returns 0 if initialization is successful, 1 if boot sector was not found and 255 if card
was not detected.
Description Initializes ports appropriately for FAT operations with CF card. Specify two different
ports: ctrlport and dataport.

Requires Nothing.

Example CF_Fat_Init(PORTD,PORTC);

page
mikroElektronika: Development tools - Books - Compilers
133
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Cf_Fat_Assign

Prototype function Cf_Fat_Assign(var filename : array[12] of char;

create_file : byte): byte;

Returns "1" is file is present (or file isn't present but new file is created), or "0" if file isn't pres-
ent and no new file is created.
Description Assigns file for FAT operations. If file isn't present, function creates new file with given
filename. filename parameter is name of file (filename must be in format 8.3 UPPER-
CASE). create_file is a parameter for creating new files. if create_file if different from 0
then new file is created (if there is no file with given filename).

Requires Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

Example Cf_Fat_Assign('MIKROELE.TXT',1);

Cf_Fat_Reset

Prototype procedure Cf_Fat_Reset(var size : longint);

Returns Size of file in bytes. Size is stored on address of input variable.

Description Opens assigned file for reading.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

Example Cf_Fat_Reset(size);

page

134
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Cf_Fat_Read

Prototype procedure Cf_Fat_Read(var bdata : byte);

Returns Nothing.

Description Reads data from file. bdata is data read from file.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

File must be open for reading.

See Cf_Fat_Reset.

Example Cf_Fat_Read(character);

Cf_Fat_Rewrite

Prototype procedure Cf_Fat_Rewrite;

Returns Nothing.

Description Rewrites assigned file.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

Example Cf_Fat_Rewrite;

page
mikroElektronika: Development tools - Books - Compilers
135
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Cf_Fat_Append

Prototype procedure Cf_Fat_Append;

Returns Nothing.

Description Opens file for writing. This procedure continues writing from the last byte in file.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

Example Cf_Fat_Append;

Cf_Fat_Delete

Prototype procedure Cf_Fat_Delete;

Returns Nothing.

Description Deletes file from CF.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

Example Cf_Fat_Delete;

page

136
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Cf_Fat_Write

Prototype procedure Cf_Fat_Write(var fdata : array[512] of byte; data_len :

word);

Returns Nothing.

Description Writes data to CF.fdata parameter is data written to CF. data_len number of bytes that is
written to CF.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

File must be open for reading.

See Cf_Fat_Reset.

Example Cf_Fat_Write(file_contents, 42); // write data to the assigned

file

Cf_Fat_Set_File_Date

Prototype procedure Cf_Fat_Set_File_Date(year : word; month, day, hours,

mins, seconds : byte);

Returns Nothing.

Description Sets time attributes of file.You can set file year, month, day. hours, mins, seconds.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

File must be open for writing.

See Cf_Fat_Rewrite or Cf_Fat_Append.

Example Cf_Fat_Set_File_Date(2005,9,30,17,41,0);

page
mikroElektronika: Development tools - Books - Compilers
137
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Cf_Fat_Get_File_Date

Prototype procedure Cf_Fat_Get_File_Date(var year : word; var month : byte;

var day : byte; var hours : byte; var mins : byte);

Returns Nothing.

Description Reads time attributes of file.You can read file year, month, day. hours, mins.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

Example Cf_Fat_Get_File_Date(year, month, day, hours, mins);

Cf_Fat_Get_File_Size

Prototype function Cf_Fat_Get_File_Size: longint;

Returns Size of file in bytes.

Description This function returns size of file in bytes.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

File must be assigned.

See Cf_Fat_Assign.

Example Cf_Fat_Get_File_Size;

page

138
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Cf_Fat_Get_Swap_File

Prototype function Cf_Fat_Get_Swap_File(sectors_cnt : longint): longint

Returns No. of start sector for the newly created swap file, if swap file was created; otherwise,
the function returns zero.

Description This function is used to create a swap file on the CF media. It accepts as sectors_cnt
argument the number of consecutive sectors that user wants the swap file to have.
During its execution, the function searches for the available consecutive sectors, their
number being specified by the sectors_cnt argument. If there is such space on the media,
the swap file named MIKROSWP.SYS is created, and that space is designated (in FAT
tables) to it. The attributes of this file are: system, archive and hidden, in order to dis-
tinct it from other files. If a file named MIKROSWP.SYS already exists on the media,
this function deletes it upon creating the new one.

The purpose of the swap file is to make reading and writing to CF media as fast as pos-
sible, without potentially damaging the FAT system. Swap file can be considered as a
"window" on the media where user can freely write/read the data, in any way (s)he
wants to. Its main purpose in mikroPascal library is to be used for fast data acquisition;
when the time-critical acquisition has finished, the data can be re-written into a "nor-
mal" file, and formatted in the most suitable way.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

Example //-------------- Tries to create a swap file, whose size will be

//at least 100 sectors.
//If it succeeds, it sends the No. of start sector over USART
procedure C_Create_Swap_File;
begin
size := Cf_Fat_Get_Swap_File(100);
if (size) then
begin
Usart_Write($AA);
Usart_Write(Lo(size));
Usart_Write(Hi(size));
Usart_Write(Higher(size));
Usart_Write(Highest(size));
Usart_Write($AA);
end;
end;

page
mikroElektronika: Development tools - Books - Compilers
139
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The following example writes 512 bytes at sector no.590, and then reads the data and prints on
PORTC for a visual check.

program Cf_example;
var i : word;

begin
TRISC := 0; // PORTC is output
Cf_Init(PORTB, PORTD); // Initialize ports

repeat nop;
until Cf_Detect(); // Wait until CF card is inserted

Delay_ms(500);
Cf_Write_Init(590, 1); // Initialize write at sector address 590
// of 1 sector (512 bytes)
for i := 0 to 511 do // Write 512 bytes to sector (590)
Cf_Write_Byte(i + 11);

PORTC := $FF;
Delay_ms(1000);
Cf_Read_Init(590, 1); // Initialize write at sector address 590
// of 1 sector (512 bytes)
for i := 0 to 511 do // Read 512 bytes from sector (590)
begin
PORTC := Cf_Read_Byte; // Read byte and display on PORTC
Delay_ms(1000);
end;
end.

page

140
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

HW Connection

40
RB7
39
RB6
38
RB5
37
RB4
36
RB3

PIC18F452
35
RB2
34
RB1
33
RB0

VCC
11 30
VCC RD7
12 29
GND RD6
13 28
OSC1 RD5
14 27
OSC2 RD4
15
RC0

8 MhZ

19 22
RD0 RD3
20 21
RD1 RD2

VCC

RD7
RD6
RD5
50
25
RD4 49
24
48
RD3 23
47
22
RD2 46
21
45
RD1 44
20
19
RD0 43
42
18 Compact Flash
17
41
16 Card
40
15
39
14
38
13
37
12
36
11
35
10
RB7 34
9
33
RB6 8
32
7
RB5 31
6
30
5
RB4 29
4
28
RB3 3
27
2
RB2 26
1
RB1
RB0

R25 VCC
10K

page
mikroElektronika: Development tools - Books - Compilers
141
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

EEPROM Library
EEPROM data memory is available with a number of PICmicros. mikroPascal
includes library for comfortable work with EEPROM.

Library Routines

Eeprom_Read
Eeprom_Write

Eeprom_Read

Prototype function EEprom_read(Address: word): byte;

Returns Returns byte from specified address.

Description Reads data from specified address. Parameter address is of byte type, which means it
can address only 256 locations. For PIC18 micros with more EEPROM data locations, it
is programmer’s responsibility to set EEADRH register appropriately.

Requires Requires EEPROM unit.

Ensure minimum 20ms delay between successive use of routines Eeprom_Write and
Eeprom_Read. Although PIC will write the correct value, Eeprom_Read might return
an undefined result.

Example tmp := Eeprom_Read($3F);

page

142
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Eeprom_Write

Prototype procedure EEprom_write(Address : word; Data: byte);

Description Writes data to specified address. Parameter address is of byte type, which means it can
address only 256 locations. For PIC18 micros with more EEPROM data locations, it is
programmer’s responsibility to set EEADRH register appropriately.

Be aware that all interrupts will be disabled during execution of Eeprom_Write routine
(GIE bit of INTCON register will be cleared). Routine will set this bit on exit.

Requires Requires EEPROM unit.

Ensure minimum 20ms delay between successive use of routines Eeprom_Write and
Eeprom_Read. Although PIC will write the correct value, Eeprom_Read might return
an undefined result.

Example Eeprom_Write($32);

Library Example

The example writes values at 20 successive locations of EEPROM. Then, it reads the written data
and prints on PORTB for a visual check.

program Eeprom_Test;
var i, j : byte;

begin
TRISB := 0;
for i := 0 to 20 do
Eeprom_Write(i, i + 6);

for i := 0 to 20 do
begin
PORTB := Eeprom_Read(i);
for j := 0 to 200 do
Delay_us(500);
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
143
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Ethernet Library
This library is designed to simplify handling of the underlying hardware
(RTL8019AS). However, certain level of knowledge about the Ethernet and
Ethernet-based protocols (ARP, IP, TCP/IP, UDP/IP, ICMP/IP) is expected from
the user. The Ethernet is a high–speed and versatile protocol, but it is not a simple
one. Once you get used to it, however, you will make your favorite PIC available
to a much broader audience than you could do with the RS232/485 or CAN.

Library Routines
Eth_Init
Eth_Set_Ip_Address
Eth_Inport
Eth_Scan_For_Event
Eth_Get_Ip_Hdr_Len
Eth_Load_Ip_Packet
Eth_Get_Hdr_Chksum
Eth_Get_Source_Ip_Address
Eth_Get_Dest_Ip_Address
Eth_Arp_Response
Eth_Get_Icmp_Info
Eth_Ping_Response
Eth_Get_Udp_Source_Port
Eth_Get_Udp_Dest_Port
Eth_Get_Udp_Port
Eth_Set_Udp_Port
Eth_Send_Udp
Eth_Load_Tcp_Header
Eth_Get_Tcp_Hdr_Offset
Eth_Get_Tcp_Flags
Eth_Set_Tcp_Data
Eth_Tcp_Response

page

144
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Eth_Init

Prototype procedure Eth_Init(var addrP, dataP, ctrlP : byte; pinReset,

pinIOW, pinIOR : byte);

Description Performs initialization of Ethernet card and library. This includes:

- Setting of control and data ports;
- Initialization of the Ethernet card (also called the Network Interface Card, or NIC);
- Retrieval and local storage of the NIC’s hardware (MAC) address;
- Putting the NIC into the LISTEN mode.

Parameter addrP is a pointer to address port, which handles the addressing lines.
Parameter dataP is pointer to data port. Parameter ctrlP is the control port. Parameter
pinReset is the reset/enable pin for the ethernet card chip (on control port). Parameter
pinIOW is the I/O Write request control pin. Parameter pinIOR is the I/O read request
control pin.

Requires As specified for the entire library.

Example Eth_Init(PORTB, PORTD, PORTE, 2, 1, 0);

Eth_Set_Ip_Address

Prototype procedure Eth_Set_Ip_Address(ip1, ip2, ip3, ip4 : byte);

Description Sets the IP address of the connected and initialized Ethernet network card. The
arguments are the IP address numbers, in IPv4 format (e.g. 127.0.0.1).

Requires This procedure should be called immediately after the NIC initialization (see
Eth_Init). You can change your IP address at any time, anywhere in the code.

Example // Set IP address 192.168.20.25

Eth_Set_Ip_Address(192, 168, 20, 25);

page
mikroElektronika: Development tools - Books - Compilers
145
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Eth_Set_Inport

Prototype function Eth_Inport(address : byte) : byte;

Returns One byte from the specified address.

Description Retrieves a byte from the specified address of the Ethernet card chip.

Requires The card (NIC) must be properly initialized. See Eth_Init.

Example udp_length := udp_length or Eth_Inport(NIC_DATA);

Eth_Scan_For_Event

Prototype function Eth_Scan_For_Event(var next_ptr : byte) : word;

Returns Type of the ethernet packet received. Two types are distinguished: ARP (MAC-IP
address data request) and IP (Internet Protocol).

Description Retrieves sender’s MAC (hardware) address and type of the packet received. The
function argument is an (internal) pointer to the next data packet in RTL8019’s buffer,
and is of no particular importance to the end user.

Requires The card (NIC) must be properly initialized. See Eth_Init. Also, the function must be
called in a proper sequence, i.e. right after the card init and IP address/UDP port init.

Example // Main block of the Ethernet example

while TRUE do
begin
event_type := Eth_Scan_For_Event(next_ptr); // Scan for event
if event_type <> 0 then
begin
case event_type of // Call an appropriate event handler
ARP: Arp_Event(); IP : Ip_Event();
end;
Eth_Outport(CR, $22); Eth_Outport(BNDRY, next_ptr);
end;
end;

page

146
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Eth_Get_Ip_Hdr_Len

Prototype function Eth_Get_Ip_Hdr_Len() : byte;

Returns Header length of the received IP packet.

Description Function returns header length of the received IP packet. Before other data based upon
the IP protocol (TCP, UDP, ICMP) can be analyzed, the sub-protocol data must be prop-
erly loaded from the received IP packet.

Requires The card (NIC) must be properly initialized. See Eth_Init. The function must be
called in a proper sequence, i.e. immediately after determining that the packet received
is the IP packet.

Example // Receive IP Header

opt_len := Eth_Get_Ip_Hdr_Len() - 20;

Eth_Load_Ip_Packet

Prototype procedure Eth_Load_Ip_Packet();

Description Loads various IP packet data into PIC’s Ethernet variables.

Requires The card (NIC) must be properly initialized. See Eth_Init. Also, a proper sequence of
calls must be obeyed (see the Ip_Event function in the supplied Ethernet example).

Example Eth_Load_Ip_Packet();

page
mikroElektronika: Development tools - Books - Compilers
147
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Eth_Get_Hdr_Chksum

Prototype procedure Eth_Get_Hdr_Chksum();

Description Loads and returns the header checksum of the received IP packet.

Requires The card (NIC) must be properly initialized. See Eth_Init. Also, a proper sequence of
calls must be obeyed (see the Ip_Event function in the supplied Ethernet example).

Example Eth_Get_Hdr_Chksum();

Eth_Get_Source_Ip_Address

Prototype procedure Eth_Get_Source_Ip_Address();

Description Loads and returns the IP address of the sender of the received IP packet.

Requires The card (NIC) must be properly initialized. See Eth_Init. Also, a proper sequence of
calls must be obeyed (see the Ip_Event function in the supplied Ethernet example).

Example Eth_Get_Source_Ip_Address();

Eth_Get_Dest_Ip_Address

Prototype procedure Eth_Get_Dest_Ip_Address();

Description Loads the IP address of the received IP packet for which the packet is designated.

Requires The card (NIC) must be properly initialized. See Eth_Init. Also, a proper sequence of
calls must be obeyed (see the Ip_Event function in the supplied Ethernet example).

Example Eth_Get_Dest_Ip_Address();

page

148
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Eth_Arp_Response

Prototype procedure Eth_Arp_Response();

Description An automated ARP response. User should simply call this function once he detects the
ARP event on the NIC.

Requires As specified for the entire library.

Example Eth_Arp_Response();

Eth_Get_Icmp_Info

Prototype procedure Eth_Get_Icmp_Info();

Description Loads ICMP protocol information (from the header of the received ICMP packet) and
stores it to the PIC’s Ethernet variables.

Requires The card (NIC) must be properly initialized. See Eth_Init. Also, this function must be
called in a proper sequence, and before the Eth_Ping_Response.

Example Eth_Get_Icmp_Info();

Eth_Ping_Response

Prototype procedure Eth_Ping_Response();

Description An automated ICMP (Ping) response. User should call this function when answerring to
an ICMP/IP event.

Requires As specified for the entire library.

Example Eth_Ping_Response();

page
mikroElektronika: Development tools - Books - Compilers
149
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Eth_Get_Udp_Source_Port

Prototype function Eth_Get_Udp_Source_Port() : word;

Returns Returns the source port (socket) of the received UDP packet.

Description The function returns the source port (socket) of the received UDP packet. After the
reception of valid IP packet is detected and its type is determined to be UDP, the UDP
packet header must be interpreted. UDP source port is the first data in the UDP header.

Requires This function must be called in a proper sequence, i.e. immediately after interpretation
of the IP packet header (at the very beginning of UDP packet header retrieval).

Example udp_source_port := Eth_Get_Udp_Source_Port();

Eth_Get_Udp_Dest_Port

Prototype function Eth_Get_Udp_Dest_Port() : word;

Returns Returns the destination port of the received UDP packet.

Description The function returns the destination port of the received UDP packet. The second
information contained in the UDP packet header is the destination port (socket) to which
the packet is targeted.

Requires This function must be called in a proper sequence, i.e. immediately after calling the
Eth_Get_Udp_Source_Port function.

Example udp_dest_port := Eth_Get_Udp_Dest_Port();

page

150
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Eth_Get_Udp_Port

Prototype function Eth_Get_Udp_Port() : byte;

Returns Returns the UDP port (socket) number that is set for the PIC’s Ethernet card.

Description The function returns the UDP port (socket) number that is set for the PIC's Ethernet
card. After the UDP port is set at the beginning of the session (Eth_Set_Udp_Port), its
number is later used to test whether the received UDP packet is targeted at the port we
are using.

Requires The network card must be properly initialized (see Eth_Init), and the UDP port
propely set (see Eth_Set_Udp_Port). This library currently supports working with
only one UDP port (socket) at a time.

Example if udp_dest_port = Eth_Get_Udp_Port() then

... // Respond to action

Eth_Set_Udp_Port

Prototype procedure Eth_Set_Udp_Port(udp_port : word);

Description Sets up the default UDP port, which will handle user requests. The user can decide,
upon receiving the UDP packet, which port was this packet sent to, and whether it will
be handled or rejected.

Requires As specified for the entire library.

Example Eth_Set_Udp_Port(10001);

page
mikroElektronika: Development tools - Books - Compilers
151
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Eth_Send_Udp

Prototype procedure Eth_Send_Udp(msg : string[16]);

Description Sends the prepared UDP message (msg), of up to 16 bytes (characters).

Unlike ICMP and TCP, the UDP packets are generally not generated as a response to the
client request. UDP provides no guarantees for message delivery and sender retains no
state on UDP messages once sent onto the network. This is why UDP packets are simply
sent, instead of being a response to someone’s request.

Requires As specified for the entire library. Also, the message to be sent must be formatted as a
null-terminated string. The message length, including the trailing “0”, must not exceed
16 characters.

Example Eth_Send_Udp(udp_tx_message);

Eth_Load_Tcp_Header

Prototype procedure Eth_Load_Tcp_Header();

Description Loads various TCP Header data into PIC’s Ethernet variables.

Requires This function must be called in a proper sequence, i.e. immediately after retrieving the
source and destination port (socket) of the TCP message.

Example tcp_source_port := Eth_Inport(NIC_DATA) shl 8; // get src port

tcp_source_port := tcp_source_port or Eth_Inport(NIC_DATA);
tcp_dest_port := Eth_Inport(NIC_DATA) shl 8; // get dest. port
tcp_dest_port := tcp_dest_port or Eth_Inport(NIC_DATA);

// We only respond to port 80 (HTML requests)

if tcp_dest_port = 80 then
begin
// retrieve TCP Header data (most of it)
Eth_Load_Tcp_Header();
//...
end;

page

152
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Eth_Get_Tcp_Hdr_Offset

Prototype function Eth_Get_Tcp_Hdr_Offset() : byte;

Returns Returns the length (or offset) of the TCP packet header in bytes.

Description The function returns the length (or offset) of the TCP packet header in bytes. Upon
receiving a valid TCP packet, its header is to be analyzed in order to respond properly
(e.g. respond to other's request, merge several packets into the message, etc.). The head-
er length is important to know in order to be able to extract the information contained in
it.

Requires This function must be called after the Eth_Load_Tcp_Header, since it initializes the
private variables used for this function.

Example // calculate offset (TCP header length)

tcp_options := Eth_Get_Tcp_Hdr_Offset() - 20;

Eth_Get_Tcp_Flags

Prototype function Eth_Get_Tcp_Flags() : byte;

Returns Returns the flags data from the header of the received TCP packet.

Description The function returns the flags data from the header of the received TCP packet. TCP
flags show various information, e.g. SYN (syncronize request), ACK (acknowledge
receipt), and similar. It is upon these flags that, for example, a proper HTTP communi-
cation is established.

Requires This function must be called after the Eth_Load_Tcp_Header, since it initializes the
private variables used for this function.

Example flags := Eth_Get_Tcp_Flags();

page
mikroElektronika: Development tools - Books - Compilers
153
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Eth_Set_Tcp_Data

Prototype procedure Eth_Set_Tcp_Data(const data : ^byte);

Description Prepares data to be sent on HTTP request. This library can handle only HTTP requests,
so sending other TCP-based protocols, such as FTP, will cause an error. Note that
TCP/IP was not designed with 8-bit MCU’s in mind, so be gentle with your HTTP
requests.

Requires As specified for the entire library.

Example // Let's prepare a simple HTML page in our string:

const httpPage1 =
'HTTP/1.0 200 OK' + #13 + #10 +
'Content-type: text/html' + #13 + #10 +
'<html>' + #10 + '<body>' + #10 +
'<h1>Hello world!</h1>' + #10 +
'</body>' + #10 + '</html>';
//...
Eth_Set_Tcp_Data(@httpPage1);

Eth_Tcp_Response

Prototype procedure Eth_Tcp_Response();

Description Performs user response to TCP/IP event. User specifies data to be sent, depending on the
request received (HTTP, HTTPD, FTP, etc). This is performed by the function
Eth_Set_Tcp_Data.

Requires Hardware requirements are as specified for the entire library. Prior to using this proce-
dure, user must prepare the data to be sent through TCP; see Eth_Set_Tcp_Data.

Example Eth_Tcp_Response();

page

154
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example

Check the supplied Ethernet example in the Examples folder.

HW Connection

200 8
+5V 1K T1 : FL1012 7
6

RJ45
5
1K 8 9 4
3
1K 7 10 2
1
6 11
0.1u
+5V 3 14 J2
0.1u +5V 2 15
0.1u 1 16
0.1u 0.1u 0.1u
2KV 2KV
80
79
78
77
76
75
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
20MHz
Vdd
BA18
BD4
BD5

BD7

BA14

BA16
BA17

BA19
BA20

JP
AUI

LED1

LEDBNC
TPIN+

Vdd

RX-
CD+

GND
EECS
BD6

BCSB

BA15

BA21

LED2

LED0

TPIN-

RX+

CD-

OSCO

81
BD3 OSCI
50 RD7
82 49
BD2 TX+
83
GND TX- 48 RD6
84 47
BD1 Vdd
0.1u 85 BD0 LD 46 RD5
86 45
GND HD
+5V 87
SD15 GND
44 RD4
88 43
SD14 SD7
RD3
RTL8019AS
89 42
Vdd SD6
90 41
SD13 SD5
91
SD12 U5 SD4
40 RD2
92 39
SD11 SD3
93
94
SD10 SD2 38
37
RD1
SD9 SD1
95 36
96
SD8 SD0
35
RD0
IOCS16B IOCHRDY
97 34
INT7 AEN
98 33
99
INT6 RSTDRV
32
+5V
INT5 SMEMWB
100 31
INT4 SMEMRB
IOWB
SA13
SA14

SA16

SA18
SA19

IORB
SA10

SA12

SA15

SA17
AS11
GND

GND
INT3
INT2

INT0
INT1

SA5
SA6
SA1

SA3
SA4

SA7

SA9
SA0

SA2

SA8

Vdd
Vdd

+5V
1K
29
30
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

RES
IOW
IOR
0.1u
+5V
RB0
RB1
RB2
RB3
RB4

page
mikroElektronika: Development tools - Books - Compilers
155
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

SPI Ethernet Library

The ENC28J60 is a stand-alone Ethernet controller with an industry standard
Serial Peripheral Interface (SPI™). It is designed to serve as an Ethernet network
interface for any controller equipped with SPI.

The ENC28J60 meets all of the IEEE 802.3 specifications. It incorporates a num-
ber of packet filtering schemes to limit incoming packets. It also provides an inter-
nal DMA module for fast data throughput and hardware assisted IP checksum cal-
culations. Communication with the host controller is implemented via two inter-
rupt pins and the SPI, with data rates of up to 10 Mb/s. Two dedicated pins are
used for LED link and network activity indication.

This library is designed to simplify handling of the underlying hardware

(ENC28J60). It works with any PIC with integrated SPI and more than 4 Kb ROM
memory. 38 to 40 MHz clock is recommended to get from 8 to 10 Mhz SPI clock,
otherwise PIC should be clocked by ENC clock output due to ENC silicon bug in
SPI hardware. if you try lower PIC clock speed, there might be board hang or miss
some requests. This library is tested with PIC16F877A@10Mhz,
PIC18F452@40Mhz.

Note: For advanced users there is a header in Uses\P16 and Uses\P18 folder
("enc28j60_libprivate.pas") with detailed description of all functions which are
implemented in SPI Ethernet Library.

Note: SPI_Init; must be called before initializing SPI Ethernet.

Library Routines

SPI_Ethernet_Init
SPI_Ethernet_doPacket
SPI_Ethernet_putByte
SPI_Ethernet_getByte
SPI_Ethernet_UserTCP
SPI_Ethernet_UserUDP

page

156
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SPI_Ethernet_Init

Prototype procedure SPI_Ethernet_Init(var resetPort : byte; resetBit :

byte; var CSportPtr : byte; CSbit : byte; var mac : array[6] of
byte; var ip : array[4] of byte; fullDuplex : byte);

Returns Nothing.

Description Initialize ENC controller. This function is splited into 2 parts to help linker when com-
ing short of memory.

resetPort - pointer to reset pin port

resetBit - reset bit number on resetPort
CSport - pointer to CS pin port
CSbit - CS bit number on CSport
mac - pointer to array of 6 char with MAC address
ip - pointer to array of 4 char with IP address
fullDuplex - either SPI_Ethernet_HALFDUPLEX for half duplex or
SPI_Ethernet_FULLDUPLEX for full duplex

Requires SPI_Init; must be called before initializing SPI Ethernet.

Example SPI_Ethernet_Init(PORTC, 0, PORTC, 1, myMacAddr, myIpAddr,

SPI_Ethernet_FULLDUPLEX);

SPI_Ethernet_doPacket

Prototype procedure SPI_Ethernet_doPacket;

Returns Nothing.

Description Process one incoming packet if available. This function is public.

Requires SPI_Ethernet_init must have been called before using this function. This function
must be called as often as possible by user.

Example SPI_Ethernet_doPacket;

page
mikroElektronika: Development tools - Books - Compilers
157
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

SPI_Ethernet_putByte

Prototype procedure SPI_Ethernet_putByte(v : byte);

Returns Nothing.

Description v - value to store

Store one byte to current EWRPT ENC location.

Requires SPI_Ethernet_init must have been called before calling this function.

Example SPI_Ethernet_putByte(0xa0);

SPI_Ethernet_getByte

Prototype function SPI_Ethernet_getByte : byte;

Returns Value of byte @ addr.

Description Get next byte from current ERDPT ENC location.

Requires SPI_Ethernet_init must have been called before calling this function.

Example b := SPI_Ethernet_getByte;

page

158
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SPI_Ethernet_UserTCP

Prototype function SPI_Ethernet_UserTCP(var remoteHost : array[4] of byte;

remotePort, localPort, reqLength : word) : word;

Returns Returns the length in bytes of the HTTP reply, or 0 if nothing to transmit.

Description This function is called by the library. The user accesses to the HTTP request by succes-
sive calls to SPI_Ethernet_getByte the user puts data in the transmit buffer by succes-
sive calls to SPI_Ethernet_putByte the function must return the length in bytes of the
HTTP reply, or 0 if nothing to transmit. If you don't need to reply to HTTP requests, just
define this function with a return(0) as single statement.

Requires SPI_Ethernet_init must have been called before calling this function.

Example

SPI_Ethernet_UserUDP

Prototype function SPI_Ethernet_UserUDP(var remoteHost : array[4] of byte;

remotePort, destPort, reqLength : word) : word;

Returns Returns the length in bytes of the UDP reply, or 0 if nothing to transmit.

Description This function is called by the library. The user accesses to the UDP request by succes-
sive calls to SPI_Ethernet_getByte. The user puts data in the transmit buffer by succes-
sive calls to SPI_Ethernet_putByte. The function must return the length in bytes of the
UDP reply, or 0 if nothing to transmit. If you don't need to reply to UDP requests,just
define this function with a return(0) as single statement.

Requires SPI_Ethernet_init must have been called before calling this function.

Example

page
mikroElektronika: Development tools - Books - Compilers
159
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The following example is a simple demonstration of the SPI Ethernet Library. PIC
is assigned an IP address of 192.168.20.60, and will respond to ping if connected
to a local area network.
program enc_ethernet;

uses enc_eth;

{***********************************
* RAM variables
*}
var myMacAddr : array[6] of byte {= (0x00, 0x14, 0xA5, 0x76, 0x19, 0x3f)} ;
// my MAC address
myIpAddr : array[4] of byte {= (192, 168, 20, 60)} ;
// my IP address

begin
ADCON1 := 0x00 ; // ADC convertors will be used

PORTA := 0 ;
TRISA := 0xff ; // set PORTA as input for ADC

PORTB := 0 ;
TRISB := 0xff ; // set PORTB as input for buttons

PORTD := 0 ;
TRISD := 0 ; // set PORTD as output

httpCounter := 0;

myMacAddr[0] := 0x00;
myMacAddr[1] := 0x14;
myMacAddr[2] := 0xA5;
myMacAddr[3] := 0x76;
myMacAddr[4] := 0x19;
myMacAddr[5] := 0x3F;

myIpAddr[0] := 192;
myIpAddr[1] := 168;
myIpAddr[2] := 20;
myIpAddr[3] := 60;

// continues ...

page

160
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

// continued ...

{*
* starts ENC28J60 with :
* reset bit on RC0
* CS bit on RC1
* my MAC & IP address
* full duplex
*}

SPI_Ethernet_Init(PORTC, 0, PORTC, 1, myMacAddr, myIpAddr, SPI_Ethernet_FULLDUPLEX);

while true do // do forever

begin
SPI_Ethernet_doPacket() ; // process incoming Ethernet packets

{*
* add your stuff here if needed
* SPI_Ethernet_doPacket() must be called as often as possible
* otherwise packets could be lost
*}
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
161
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

HW Connection

PIC18F452
VCC

11
VCC
12
GND
13
OSC1
14
OSC2
15
RC0
8 Mhz 16
RC1
24
RC5
18 23
RC3 RC4

LD2 LD3
VCC LED LED

VCC3
E3 R2 R3
10uF
ENC28J60
500 500
1 28
VCAP VCC
2 27
1 14 GND LEDA
1A VCC 3 26
74HCT08N

2 13 CLKOUT LEDB
1B 4B 4 25
3 12 INT OSC-VCC
1Y 4A 5 24
4 11 WOL OSC2
2A 4Y 3B 6 23
5 10 SO OSC1
2B 3B RC5 7 22
6 9 SI OSCGND
2Y 3A RC3 8 21 25 MHz
7 8 RC4 SCK PLL-GND
GND 3Y RC1 9 20
CS PLL-VCC
RC0 10 19
RESET RX-VCC
11 18
GND-RX TX-GND R4
12 17
TPIN- TPOUT+ 51
13 16
TPIN+ TPOUT- R5
14 15
RBIAS TX-VCC 51

R1
2K
VCC3

R6
L1 51
FERRITE
BEAD R7
RJ45 51
12 11
K2 A2 1
TD+
3
CT
2
TD-
7
RD+
6
CT
8
RD-
K1 A1
C4 C3
10 9
100nF 10nF

page

162
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Flash Memory Library

This library provides routines for accessing microcontroller Flash memory. Note
that prototypes differ for PIC16 and PIC18 families.
Note: Due to P16 family flash specifics, flash library is MCU dependent. There
are three kinds of MCU's that support flash memory operations:
1. Only flash Read operation supported. For this group of MCU's only Flash_Read
function is implemented.
2. Read and Write operations are supported (write is executed as erase-and-write).
For this group of MCU's read and write functions are implemented.
3. Read, Write and Erase operations supported. For this group of MCU's read,
write and erase functions are implemented. Further more, flash memory block has
to be erased prior to writting (write operation is not executed as erase_and_write).
Note: Please refer to datasheet before using flash library.
Library Routines
Flash_Read Flash_Write Flash_Erase

Flash_Read
Prototype function Flash_Read(address : word) : byte; // PIC16
function Flash_Read(address : longint) : byte; // PIC18

Returns Returns data byte from Flash memory.

Description Reads data from the specified address in Flash memory.

Example tmp := Flash_Read($0D00);

Flash_Write
Prototype procedure Flash_Write(Address : word; var Data : array[4] of
word); // PIC16
procedure Flash_Write(Address : longint; var Data : array[64] of
word); // PIC18

Description Writes chunk of data to Flash memory. With PIC18, data needs to be exactly 64 bytes in
size. The function erases target memory before writing data to it. This means that if
write was unsuccessful, previous data will be lost.
Example // Write consecutive values in 64 consecutive locations
for i := 0 to 63 do
toWrite[i] := i;

// Write contents of the array to the address $0D00:

Flash_Write($0D00, toWrite);

page
mikroElektronika: Development tools - Books - Compilers
163
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Flash_Erase
Prototype procedure Flash_Erase(address : word);

Description Erases 32 bytes memory block starting from a given address. Implemented only for
those MCU's whose flash memory does not support erase-and-write operations (refer to
datasheet for details).

Example //Erase 32 byte memory memory block, starting from address $0D00:

Flash_Erase($0D00);

Library Example
The example writes 64 consecutive values to 64 consecutive locations in flash memory. Then, it
verifies the written data, with error indication on PORTB.
// For PIC18
program flash_pic18;

var i : byte ;
addr : longint;
dataRd : byte;
dataWr : array[64] of byte ;

begin
PORTB := 0;
TRISB := 0;

for i := 0 to 63 do
dataWr[i] := i;

addr := 0x00000A30; // valid for P18F452

Flash_Write(addr, dataWr);

addr := 0x00000A30;
for i := 0 to 63 do
begin
dataRd := Flash_Read(addr);
PORTB := dataRd;
addr := addr + 1;
Delay_ms(200);
end;
end.

page

164
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

I2C Library
I²C full master MSSP unit is available with a number of PIC MCU models.
mikroPascal provides I2C library which supports the master I²C mode.

Note: Certain PICmicros with two I²C modules, such as P18F8722, require you to
specify the module you want to use. Simply append the number 1 or 2 to a I2C.
For example, I2C2_Wr; Also, for the sake of backward compabitility with previ-
ous compiler versions and easier code management, MCU's with multiple I2C
modules have I²C library which is identical to I2C1 (i.e. you can use I2C_Init;
instead of I2C1_Init; for I²C operations).

Library Routines
I2C_Init
I2C_Start
I2C_Repeated_Start
I2C_Is_Idle
I2C_Rd
I2C_Wr
I2C_Stop

I2C_Init

Prototype procedure I2C_Init(const clock : longint);

Description Initializes I²C with desired clock (refer to device data sheet for correct values in
respect with Fosc). Needs to be called before using other functions of I2C Library.

Requires Library requires MSSP unit on PORTB or PORTC.

Example I2C_Init(100000);

page
mikroElektronika: Development tools - Books - Compilers
165
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

I2C_Start

Prototype function I2C_Start : byte;

Returns If there is no error, function returns 0.

Description Determines if I²C bus is free and issues START signal.

Requires I²C must be configured before using this function. See I2C_Init.

Example if I2C_Start = 0 then

...

I2C_Repeated_Start

Prototype procedure I2C_Repeated_Start;

Description Issues repeated START signal.

Requires I²C must be configured before using this function. See I2C_Init.

Example I2C_Repeated_Start();

I2C_Is_Idle

Prototype function I2C_Is_Idle : byte;

Returns Returns 1 if I²C bus is free, otherwise returns 0.

Description Tests if I²C bus is free.

Requires I²C must be configured before using this function. See I2C_Init.

Example if I2C_Is_Idle then

...

page

166
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

I2C_Rd

Prototype function I2C_Rd(ack : byte) : byte;

Returns Returns one byte from the slave.

Description Reads one byte from the slave, and sends not acknowledge signal if parameter ack is 0,
otherwise it sends acknowledge.

Requires START signal needs to be issued in order to use this function. See I2C_Start.

Example tmp := I2C_Rd(0); // Read data and send not acknowledge signal

I2C_Wr

Prototype function I2C_Wr(data : byte) : byte;

Returns Returns 0 if there were no errors.

Description Sends data byte (parameter data) via I²C bus.

Requires START signal needs to be issued in order to use this function. See I2C_Start.

Example I2C_Write($A3);

I2C_Stop

Prototype procedure I2C_Stop;

Description Issues STOP signal.

Requires I²C must be configured before using this function. See I2C_Init.

page
mikroElektronika: Development tools - Books - Compilers
167
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

This code demonstrates use of I2C Library procedures and functions. PIC MCU is connected (pins
SCL, SDA) to 24c02 EEPROM. Program sends data to EEPROM (data is written at address 2).
Then, we read data via I2C from EEPROM and send its value to PORTD, to check if the cycle
was successful (figure on the following page shows how to interface 24c02 to PIC).

program Eeprom_Test;

var EE_adr, EE_data, k : byte;

jj : word;

begin
I2C_Init(100000); // Initialize full master mode
TRISD := 0; // PORTD is output
PORTD := $FF; // Initialize PORTD
I2C_Start; // Issue I2C start signal
I2C_Wr($A2); // Send byte via I2C(command to 24cO2)
EE_adr := 2;
I2C_Wr(EE_adr); // Send byte(address for EEPROM)
EE_data := $AA;
I2C_Wr(EE_data); // Send data(data that will be written)
I2C_Stop; // Issue I2C stop signal

// Pause while EEPROM writes data

for jj := 0 to 65500 do nop;

I2C_Start; // Issue I2C start signal

I2C_Wr($A2); // Send byte via I2C
EE_adr := 2;
I2C_Wr(EE_adr); // Send byte(address for EEPROM)
I2C_Repeated_Start; // Issue I2C signal repeated start
I2C_Wr($A3); // Send byte (request data from EEPROM)
k := I2C_Rd(1); // Read the data
I2C_Stop; // Issue I2C stop signal
PORTD := k; // Show data on PORTD

// Endless loop
while true do nop;

end.

page

168
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

HW Connection

VCC VCC

1 8
A0 Vcc
2 7
PIC18F452
A1 WP
VCC 3 6
NC SCL
4 5
GND SDA

24C02
10K

10K
11
VCC
12
GND
13
OSC1
14
OSC2

18 23
RC3 RC4

8 Mhz

page
mikroElektronika: Development tools - Books - Compilers
169
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Keypad Library
mikroPascal provides library for working with 4x4 keypad; routines can also be
used with 4x1, 4x2, or 4x3 keypad. Check the connection scheme at the end of the
topic.

Library Routines

Keypad_Init
Keypad_Read
Keypad_Released

Keypad_Init

Prototype procedure Keypad_Init(var port : word);

Description Initializes port to work with keypad. The procedure needs to be called before using other
routines from Keypad library.

Example Keypad_Init(PORTB);

Keypad_Read

Prototype function Keypad_Read : word;

Returns 1..16, depending on the key pressed, or 0 if no key is pressed.

Description Checks if any key is pressed. Function returns 1 to 16, depending on the key pressed, or
0 if no key is pressed.

Requires Port needs to be appropriately initialized; see Keypad_Init.

Example kp := Keypad_Read();

page

170
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Keypad_Released

Prototype function Keypad_Released : word;

Returns 1..16, depending on the key.

Description Call to Keypad_Released is a blocking call: function waits until any key is pressed
and released. When released, function returns 1 to 16, depending on the key.

Requires Port needs to be appropriately initialized; see Keypad_Init.

Example kp := Keypad_Released();

page
mikroElektronika: Development tools - Books - Compilers
171
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The following code can be used for testing the keypad. It supports keypads with 1 to 4 rows and 1
to 4 columns. The code returned by the keypad functions (1..16) is transformed into ASCII codes
[0..9,A..F]. In addition, a small single-byte counter displays the total number of keys pressed in
the second LCD row.
program keypad_test;

var kp, cnt : byte;

txt : string[5];

begin
cnt := 0;
Keypad_Init(PORTC);
Lcd_Init(PORTB); // Initialize LCD on PORTC
Lcd_Cmd(LCD_CLEAR); // Clear display
Lcd_Cmd(LCD_CURSOR_OFF); // Cursor off
Lcd_Out(1, 1, 'Key :');
Lcd_Out(2, 1, 'Times:');

repeat
begin
kp := 0;

//--- Wait for key to be pressed

while kp = 0 do
begin
//--- un-comment one of the keypad reading functions
kp := Keypad_Released();
//kp := Keypad_Read();
end;

Inc(cnt);

//--- prepare value for output

if kp > 10 then
kp := kp + 54
else
kp := kp + 47;

//--- print it on LCD

Lcd_Chr(1, 10, kp);
WordToStr(cnt, txt);
Lcd_Out(2, 10, txt);
end;
until FALSE;
end.

page

172
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

HW Connection

40
RB7
39
RB6 1 2 3 A
38
RB5
37
RB4
36 4 5 6 B
RB3
PIC18F452

35
VCC RB2
34
RB1
7 8 9 C
33
RB0

0 # D
*
11
VCC
12
GND
13 KEYPAD
OSC1 4X4
14
OSC2

R-SIL 8/9
10K

8 Mhz

page
mikroElektronika: Development tools - Books - Compilers
173
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

LCD Library (4-bit interface)

mikroPascal provides a library for communicating with commonly used LCD (4-
bit interface). Figures showing HW connection of PIC and LCD are given at the
end of the chapter.

Library Routines

Lcd_Config
Lcd_Init
Lcd_Out
Lcd_Out_Cp
Lcd_Chr
Lcd_Chr_Cp
Lcd_Cmd

Lcd_Config

Prototype procedure Lcd_Config(var data_port:byte; D7, D6, D5, D4:byte;var

ctrl_port:byte; RS, WR, EN:byte);

Description Initializes LCD data port and control port with pin settings you specify.

Example Lcd_Config(PORTD,3,2,1,0,PORTB,2,3,4);

page

174
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Lcd_Init

Prototype procedure Lcd_Init(var port : byte);

Description Initializes LCD at port with default pin settings (see the connection scheme at the end of
the chapter): D7 -> PORT.7, D6 -> PORT.6, D5 -> PORT.5, D4 -> PORT.4,
E -> PORT.3, RS -> PORT.2.

Example Lcd_Init(PORTB);

Lcd_Out

Prototype procedure Lcd_Out(row, col : byte; var text : array[255] of

char);

Description Prints text on LCD at specified row and column (parameter row and col). Both string
variables and literals can be passed as text.

Requires Port with LCD must be initialized. See Lcd_Config or Lcd_Init.

Example Lcd_Out(1, 3, 'Hello!'); // Print "Hello!" at line 1, char 3

Lcd_Out_Cp

Prototype procedure Lcd_Out_Cp(var text : array[255] of char);

Description Prints text on LCD at current cursor position. Both string variables and literals can be
passed as text.

Requires Port with LCD must be initialized. See Lcd_Config or Lcd_Init.

Example Lcd_Out_Cp('Here!'); // Print "Here!" at current cursor position

page
mikroElektronika: Development tools - Books - Compilers
175
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Lcd_Chr

Prototype procedure Lcd_Chr(row, col, character : byte);

Description Prints character on LCD at specified row and column (parameters row and col).
Both variables and literals can be passed as character.

Requires Port with LCD must be initialized. See Lcd_Config or Lcd_Init.

Example Lcd_Chr(2, 3, 'i'); // Print "i" at line 2, char 3

Lcd_Chr_Cp

Prototype procedure Lcd_Chr_Cp(character : byte);

Description Prints character on LCD at current cursor position. Both variables and literals can be
passed as character.

Requires Port with LCD must be initialized. See Lcd_Config or Lcd_Init.

Example Lcd_Chr_Cp('e'); // Print "e" at current cursor position

Lcd_Cmd

Prototype procedure Lcd_Cmd(command : byte);

Description Sends command to LCD. You can pass one of the predefined constants to the function.
The complete list of available commands is shown on the page 140.

Requires Port with LCD must be initialized. See Lcd_Config or Lcd_Init.

Example Lcd_Cmd(LCD_Clear); // Clear LCD display

page

176
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

LCD Commands

LCD Command Purpose

LCD_FIRST_ROW Move cursor to 1st row

LCD_SECOND_ROW Move cursor to 2nd row

LCD_THIRD_ROW Move cursor to 3rd row

LCD_FOURTH_ROW Move cursor to 4th row

LCD_CLEAR Clear display

Return cursor to home position, returns a shifted display to original posi-

LCD_RETURN_HOME
tion. Display data RAM is unaffected.

LCD_CURSOR_OFF Turn off cursor

LCD_UNDERLINE_ON Underline cursor on

LCD_BLINK_CURSOR_ON Blink cursor on

LCD_MOVE_CURSOR_LEFT Move cursor left without changing display data RAM

Lcd_Move_Cursor_Right Move cursor right without changing display data RAM

LCD_TURN_ON Turn LCD display on

LCD_TURN_OFF Turn LCD display off

LCD_SHIFT_LEFT Shift display left without changing display data RAM

LCD_SHIFT_RIGHT Shift display right without changing display data RAM

page
mikroElektronika: Development tools - Books - Compilers
177
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example (default pin settings)

program Lcd_default_test;
var text: array[20] of char;

begin
TRISB := 0; // PORTB is output
Lcd_Init(PORTB); // Initialize LCD on PORTB
Lcd_Cmd(Lcd_CURSOR_OFF); // Turn off cursor
text := 'mikroElektronika';
Lcd_Out(1, 1, text); // Print text at LCD
end.

page

178
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

VCC
RB1
RB2

RB0

RD2
RB7

RD7

RC7
RB3

RD3
VDD
RB6

RD6

RC6
RB5

RD5

RC5
RB4

RD4

RC4
VSS
PICxxxx
MCLR

OSC1
OSC2
VDD
VSS

RD1
RA0

RA1
RA2
RA3
RA4
RA5

RC0
RC1

RC3
RD0
RE2

RC2
RE0
RE1

8 MhZ
14

D7
D6
D5
D4
D3
D2
D1
D0
E
R/W
RS
VEE
VCC
GND
Adjustment

1
Contrast
VCC

5K
P4

page
mikroElektronika: Development tools - Books - Compilers
179
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

LCD Library (8-bit interface)

mikroPascal provides a library for communicating with commonly used 8-bit
interface LCD (with Hitachi HD44780 controller). Figures showing HW connec-
tion of PIC and LCD are given at the end of the chapter.

Library Routines

Lcd8_Init
Lcd8_Out
Lcd8_Out_Cp
Lcd8_Chr
Lcd8_Chr_Cp
Lcd8_Cmd

Lcd8_Init

Prototype procedure Lcd8_Init(var ctrlport, dataport : byte);

Description Initializes LCD at Control port (ctrlport) and Data port (dataport) with default pin set-
tings (see the connection scheme at the end of the chapter):

E -> ctrlport.3, RS -> ctrlport.2, R/W -> ctrlport.0, D7 -> dataport.7, D6 -> dataport.6,
D5 -> dataport.5, D4 -> dataport.4, D3 -> dataport.3, D2 -> dataport.2, D1 -> dataport.1,
D0 -> dataport.0

Example Lcd8_Init(PORTB, PORTC);

page

180
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Lcd8_Out

Prototype procedure Lcd8_Out(row, col : byte; var text : array[255] of

char);

Description Prints text on LCD at specified row and column (parameter row and col). Both string
variables and literals can be passed as text.

Requires Ports with LCD must be initialized. See Lcd8_Config or Lcd8_Init.

Example Lcd8_Out(1, 3, 'Hello!'); // Print "Hello!" at line 1, char 3

Lcd8_Out_Cp

Prototype procedure Lcd8_Out_Cp(var text : array[255] of char);

Description Prints text on LCD at current cursor position. Both string variables and literals can be
passed as text.

Requires Ports with LCD must be initialized. See Lcd8_Config or Lcd8_Init.

Example Lcd8_Out_Cp('Here!'); // Print "Here!" at current cursor position

page
mikroElektronika: Development tools - Books - Compilers
181
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Lcd8_Chr

Prototype procedure Lcd8_Chr(row, col, character : byte);

Description Prints character on LCD at specified row and column (parameters row and col).
Both variables and literals can be passed as character.

Requires Ports with LCD must be initialized. See Lcd8_Config or Lcd8_Init.

Example Lcd8_Out(2, 3, 'i'); // Print "i" at line 2, char 3

Lcd8_Chr_Cp

Prototype procedure Lcd8_Chr_Cp(character : byte);

Description Prints character on LCD at current cursor position. Both variables and literals can be
passed as character.

Requires Ports with LCD must be initialized. See Lcd8_Config or Lcd8_Init.

Example Lcd8_Chr_Cp('e'); // Print "e" at current cursor position

Lcd8_Cmd

Prototype procedure Lcd8_Cmd(command : byte);

Description Sends command to LCD. You can pass one of the predefined constants to the function.
The complete list of available commands is on the page 140.

Requires Ports with LCD must be initialized. See Lcd8_Config or Lcd8_Init.

Example Lcd8_Cmd(LCD_Clear); // Clear LCD display

page

182
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example (default pin settings)

program Lcd8_default_test;
var text: array[20] of char;

begin
TRISB := 0; // PORTB is output
TRISC := 0; // PORTC is output
Lcd8_Init(PORTB, PORTC); // Initialize LCD at PORTB and PORTC
Lcd8_Cmd(Lcd_CURSOR_OFF); // Turn off cursor
text := 'mikroElektronika';
Lcd8_Out(1, 1, text); // Print text at LCD
end.

Hardware Connection

MCLR RB7
RA0 RB6 E
R/W
RA1 RB5
RS
RA2 RB4
RA3 RB3
VCC RA4 RB2
VCC
PICxxxx
RA5 RB1
RE0 RB0
RE1 VDD
Contrast
RE2 VSS
P3 Adjustment D7
5K VDD RD7
D6
VSS RD6
D5
OSC1 RD5
D4
OSC2 RD4

1 14 RC0 RC7
GND
VCC
VEE
R/W

8 MhZ
D1
RS

D0
D2
D3

D7
D6
D5
D4
E

RC1 RC6
RC2 RC5
RC3 RC4
D0 D3
RD0 RD3
D1 D2
RD1 RD2

page
mikroElektronika: Development tools - Books - Compilers
183
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

GLCD Library
mikroPascal provides a library for drawing and writing on Graphic LCD. These
routines work with commonly used GLCD 128x64, and work only with the PIC18
family.

Library Routines

Basic routines:

Glcd_Init
Glcd_Set_Side
Glcd_Set_Page
Glcd_Set_X
Glcd_Read_Data
Glcd_Write_Data

Advanced routines:

Glcd_Fill
Glcd_Dot
Glcd_Line
Glcd_V_Line
Glcd_H_Line
Glcd_Rectangle
Glcd_Box
Glcd_Circle
Glcd_Set_Font
Glcd_Write_Char
Glcd_Write_Text
Glcd_Image

page

184
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Glcd_Init

Prototype procedure Glcd_Init(var ctrlport : byte; cs1, cs2, rs, rw, rst,
en : byte; var dataport : byte);

Description Initializes GLCD at lower byte of data_port with pin settings you specify. Parameters
cs1, cs2, rs, rw, rst, and en can be pins of any available port.

This procedure needs to be called befored using other routines of GLCD library.

Example Glcd_Init(PORTB, 2, 0, 3, 5, 7, 1, PORTC);

Glcd_Set_Side

Prototype procedure Glcd_Set_Side(x : byte);

Description Selects side of GLCD, left or right. Parameter x specifies the side: values from 0 to 63
specify the left side, and values higher than 64 specify the right side. Use the functions
Glcd_Set_Side, Glcd_Set_X, and Glcd_Set_Page to specify an exact position on
GLCD. Then, you can use Glcd_Write_Data or Glcd_Read_Data on that location.

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Set_Side(0);

page
mikroElektronika: Development tools - Books - Compilers
185
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Glcd_Set_Page

Prototype procedure Glcd_Set_Page(page : byte);

Description Selects page of GLCD, technically a line on display; parameter page can be 0..7.

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Set_Page(5);

Glcd_Set_X

Prototype procedure Glcd_Set_X(x : byte);

Description Positions to x dots from the left border of GLCD within the given page.

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Set_X(25);

Glcd_Read_Data

Prototype function Glcd_Read_Data : byte;

Returns One word from the GLCD memory.

Description Reads data from from the current location of GLCD memory. Use the functions
Glcd_Set_Side, Glcd_Set_X, and Glcd_Set_Page to specify an exact position on
GLCD. Then, you can use Glcd_Write_Data or Glcd_Read_Data on that location.

Requires Reads data from from the current location of GLCD memory.

Example tmp := Glcd_Read_Data();

page

186
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Glcd_Write_Data

Prototype procedure Glcd_Write_Data(data : byte);

Description Writes data to the current location in GLCD memory and moves to the next location.

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Write_Data(data);

Glcd_Fill

Prototype procedure Glcd_Fill(pattern : byte);

Description Fills the GLCD memory with byte pattern. To clear the GLCD screen, use
Glcd_Fill(0); to fill the screen completely, use Glcd_Fill($FF).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Fill(0); // Clear screen

Glcd_Dot

Prototype procedure Glcd_Dot(x, y, color : byte);

Description Draws a dot on the GLCD at coordinates (x, y). Parameter color determines the dot
state: 0 clears dot, 1 puts a dot, and 2 inverts dot state.

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Dot(0, 0, 2); // Invert the dot in the upper left corner

page
mikroElektronika: Development tools - Books - Compilers
187
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Glcd_Line

Prototype procedure Glcd_Line(x1, y1, x2, y2, color : byte);

Description Draws a line on the GLCD from (x1, y1) to (x2, y2). Parameter color determines
the dot state: 0 draws an empty line (clear dots), 1 draws a full line (put dots), and 2
draws a “smart” line (invert each dot).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Line(0, 63, 50, 0, 2);

Glcd_V_Line

Prototype procedure Glcd_V_Line(y1, y2, x, color : byte);

Description Similar to Glcd_Line, draws a vertical line on the GLCD from (x, y1) to
(x, y2).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_V_Line(0, 63, 0, 1);

Glcd_H_Line

Prototype procedure Glcd_H_Line(x1, x2, y, color : byte);

Description Similar to Glcd_Line, draws a horizontal line on the GLCD from (x1, y) to
(x2, y).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_H_Line(0, 127, 0, 1);

page

188
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Glcd_Rectangle

Prototype procedure Glcd_Rectangle(x1, y1, x2, y2, color : byte);

Description Draws a rectangle on the GLCD. Parameters (x1, y1) set the upper left corner,
(x2, y2) set the bottom right corner. Parameter color defines the border: 0 draws an
empty border (clear dots), 1 draws a solid border (put dots), and 2 draws a “smart” bor-
der (invert each dot).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Rectangle(10, 0, 30, 35, 1);

Glcd_Box

Prototype procedure Glcd_Box(x1, y1, x2, y2, color : byte);

Description Draws a box on the GLCD. Parameters (x1, y1) set the upper left corner, (x2, y2)
set the bottom right corner. Parameter color defines the fill: 0 draws a white box (clear
dots), 1 draws a full box (put dots), and 2 draws an inverted box (invert each dot).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Box(10, 0, 30, 35, 1);

Glcd_Circle

Prototype procedure Glcd_Circle(x, y, radius, color : integer);

Description Draws a circle on the GLCD, centered at (x, y) with radius. Parameter color defines the
circle line: 0 draws an empty line (clear dots), 1 draws a solid line (put dots), and 2
draws a “smart” line (invert each dot).

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Circle(63, 31, 25, 1);

page
mikroElektronika: Development tools - Books - Compilers
189
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Glcd_Set_Font

Prototype procedure Glcd_Set_Font(font_address : longint; font_width,

font_height : byte; font_offset : word);

Description Sets the font for text display routines, Glcd_Write_Char and Glcd_Write_Text.
Font needs to be formatted as an array of byte. Parameter font_address specifies the
address of the font; you can pass a font name with the @ operator. Parameters
font_width and font_height specify the width and height of characters in dots. Font
width should not exceed 128 dots, and font height should not exceed 8 dots. Parameter
font_offset determines the ASCII character from which the supplied font starts.
Demo fonts supplied with the library have an offset of 32, which means that they start
with space.

If no font is specified, Glcd_Write_Char and Glcd_Write_Text will use the default

5x8 font supplied with the library. You can create your own fonts by following the
guidelines given in the file “GLCD_Fonts.ppas”. This file contains the default fonts for
GLCD, and is located in your installation folder, “Extra Examples” > “GLCD”.

Requires GLCD needs to be initialized. See Glcd_Init.

Example // Use the custom 5x7 font "myfont" which starts with space (32):
Glcd_Set_Font(@myfont, 5, 7, 32);

Glcd_Write_Char

Prototype procedure Glcd_Write_Char(character, x, page, color : byte);

Description Prints character at page (one of 8 GLCD lines, 0..7), x dots away from the left bor-
der of display. Parameter color defines the “fill”: 0 writes a “white” letter (clear dots),
1 writes a solid letter (put dots), and 2 writes a “smart” letter (invert each dot).

Use routine Glcd_Set_Font to specify font, or the default 5x7 font (included with the
library) will be used.

Requires GLCD needs to be initialized, see Glcd_Init. Use the Glcd_Set_Font to specify the
font for display; if no font is specified, the default 5x8 font supplied with the library will
be used.

Example Glcd_Write_Char('C', 0, 0, 1);

page

190
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Glcd_Write_Text

Prototype procedure Glcd_Write_Text(text : string[20]; x, page,

color : byte);

Description Prints text at page (one of 8 GLCD lines, 0..7), x dots away from the left border of
display. Parameter color defines the “fill”: 0 prints a “white” letters (clear dots), 1
prints solid letters (put dots), and 2 prints “smart” letters (invert each dot).

Use routine Glcd_Set_Font to specify font, or the default 5x7 font (included with the
library) will be used.

Requires GLCD needs to be initialized, see Glcd_Init. Use the Glcd_Set_Font to specify the
font for display; if no font is specified, the default 5x8 font supplied with the library will
be used.

Example Glcd_Write_Text('Hello world!', 0, 0, 1);

Glcd_Image

Prototype procedure Glcd_Image(image : array[0..1023] of byte);

Description Displays bitmap image on the GLCD. Parameter image should be formatted as an array
of 1024 bytes. Use the mikroPascal’s integrated Bitmap-to-LCD editor (menu option
Tools > Graphic LCD Editor) to convert image to a constant array suitable for display
on GLCD.

Requires GLCD needs to be initialized. See Glcd_Init.

Example Glcd_Image(my_image);

page
mikroElektronika: Development tools - Books - Compilers
191
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The following drawing demo tests advanced routines of GLCD library.

program Glcd_Test;
var j, k : byte;

begin

Glcd_Init(PORTB, 2, 0, 3, 5, 7, 1, PORTD);

// Set font for displaying text

Glcd_Set_Font(@FontSystem5x8, 5, 8, 32);

repeat
begin

// Draw circles
Glcd_Fill(0); // Clear screen
Glcd_Write_Text('Circles', 0, 0, 1);
j := 4;
while j < 31 do
begin
Glcd_Circle(63, 31, j, 2);
j := j + 4;
end;
Delay_ms(4000);

// Draw boxes
Glcd_Fill(0); // Clear screen
Glcd_Write_Text('Rectangles', 0, 0, 1);
j := 0;
while j < 31 do
begin
Glcd_Box(j, 0, j + 20, j + 25, 2);
j := j + 4;
end;
Delay_ms(4000);

end
until FALSE;

end.

page

192
mikroElektronika: Development tools - Books - Compilers
 mikroPASCAL
making it simple...

RST
Hardware Connection

Vee MCLR RB7

RA0 E
RB6
R/W
RA1 RB5
RS
RA2 RB4
CS2
Contrast RA3 RB3
Adjustment VCC VCC CS1
RA4 RB2
P3 VCC
Vo RA5 RB1
5K
RE0 RB0
RE1 VDD
RE2 VSS
VDD D7
RD7
1 20 D6
VSS RD6

E
D1

Vo
D0
D2
D3
D7
D6
D5
D4

RS
D5

Vee

CS1
CS2
R/W
RST

VCC
GND
LED-
OSC1 RD5

LED+
D4
OSC2 RD4
PICxxxx

mikroElektronika: Development tools - Books - Compilers

RC0 RC7

8 MhZ RC1 RC6

mikroElektronika RC2 RC5
RC3 RC4
D0 D3
Compilers
RD0 RD3
D1 D2
RD1 RD2
Tools
Books

page

193
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

T6963C Graphic LCD Library

mikroPascal provides a library for drawing and writing on Toshiba T6963C
Graphic LCD (changeable size).

Library Routines

T6963C_Init
T6963C_writeData
T6963C_writeCommand
T6963C_setPtr
T6963C_waitReady
T6963C_fill
T6963C_dot
T6963C_write_char
T6963C_write_text
T6963C_line
T6963C_rectangle
T6963C_box
T6963C_circle
T6963C_image
T6963C_sprite
T6963C_set_cursor
T6963C_clearBit
T6963C_setBit
T6963C_negBit
T6963C_displayGrPanel
T6963C_displayTxtPanel
T6963C_setGrPanel
T6963C_setTxtPanel
T6963C_panelFill
T6963C_grFill
T6963C_txtFill
T6963C_cursor_height
T6963C_graphics
T6963C_text
T6963C_cursor
T6963C_cursor_blink
T6963C_Init_240x128
T6963C_Init_240x64

page

194
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

T6963C_init
Prototype procedure T6963C_init(width, height, fntW : word; var data :
word; var cntrl : word; wr, rd, cd, rst : word);

Description Initalizes the Graphic Lcd controller. This function must be called before all T6963C
Library Routines.
width - Number of horizontal (x) pixels in the display.
height - Number of vertical (y) pixels in the display.
fntW - Font width, number of pixels in a text character, must be set accordingly to the
hardware.
data - Address of the port on which the Data Bus is connected.
cntrl - Address of the port on which the Control Bus is connected.
wr - !WR line bit number in the *cntrl port.
rd - !RD line bit number in the *cntrl port.
cd - !CD line bit number in the *cntrl port.
rst - !RST line bit number in the *cntrl port.

Display RAM :
The library doesn't know the amount of available RAM.
The library cuts the RAM into panels : a complete panel is one graphics panel followed
by a text panel, The programer has to know his hardware to know how much panel he
has.

Requires Nothing.

Example T6963C_init(240, 128, 8, PORTD, PORTB, 3, 2, 1, 5);

{
* init display for 240 pixel width and 128 pixel height
* 8 bits character width
* data bus on PORTD
* control bus on PORTB
* bit 3 is !WR
* bit 2 is !RD
* bit 1 is !CD
* bit 5 is RST
*}

page
mikroElektronika: Development tools - Books - Compilers
195
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

T6963C_writeData
Prototype procedure T6963C_writeData(data : byte);

Description Routine that writes data to T6963C controller.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_writeData(AddrL);

T6963C_writeCommand
Prototype procedure T6963C_writeCommand(data : byte);

Description Routine that writes command to T6963C controller.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_writeCommand(T6963C_CURSOR_POINTER_SET);

T6963C_setPtr
Prototype procedure T6963C_setPtr(p : word; c : byte);

Description This routine sets the memory pointer p for command c.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_setPtr(T6963C_grHomeAddr + start,

T6963C_ADDRESS_POINTER_SET);

T6963C_waitReady
Prototype procedure T6963C_waitReady;

Description This routine pools the status byte, and loops until ready.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_waitReady;

page

196
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

T6963C_fill
Prototype procedure T6963C_fill(v : byte; start, len : word);

Description This routine fills length with bytes to controller memory from start address.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_fill(0x33,0x00FF,0x000F);

T6963C_dot
Prototype procedure T6963C_dot(x, y : integer; color : byte);

Description This sets current text work panel. It writes string str row x line y. mode =
T6963C_ROM_MODE_[OR|EXOR|AND].

Requires Ports must be initialized. See T6963C_init.

Example T6963C_dot(x0, y0, pcolor);

T6963C_write_char
Prototype procedure T6963C_write_char(c, x, y, mode : byte);

Description This routine sets current text work panel.

It writes char c row x line y.
mode = T6963C_ROM_MODE_[OR|EXOR|AND]

Requires Ports must be initialized. See T6963C_init.

Example T6963C_write_char('A',22,23,AND);

T6963C_write_text
Prototype procedure T6963C_write_text(var str : array[10] of byte; x, y,
mode : byte);

Description This sets current text work panel.

It writes string str row x line y.
mode = T6963C_ROM_MODE_[OR|EXOR|AND]
Requires Ports must be initialized. See T6963C_init.

Example T6963C_write_text("GLCD LIBRARY DEMO, WELCOME !", 0, 0,

T6963C_ROM_MODE_XOR);

page
mikroElektronika: Development tools - Books - Compilers
197
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

T6963C_line
Prototype procedure T6963C_line(x0, y0, x1, y1 : integer; pcolor : byte);

Description This routine current graphic work panel.

It's draw a line from (x0, y0) to (x1, y1).
pcolor = T6963C_[WHITE[BLACK]
Requires Ports must be initialized. See T6963C_init.

Example T6963C_line(0, 0, 239, 127, T6963C_WHITE);

T6963C_rectangle
Prototype procedure T6963C_rectangle(x0, y0, x1, y1 : integer; pcolor :
byte);

Description It sets current graphic work panel.

It draws the border of the rectangle (x0, y0)-(x1, y1).
pcolor = T6963C_[WHITE[BLACK].
Requires Ports must be initialized. See T6963C_init.

Example T6963C_rectangle(20, 20, 219, 107, T6963C_WHITE);

T6963C_box

Prototype procedure T6963C_box(x0, y0, x1, y1 : integer; pcolor : byte);

Description This routine sets current graphic work panel.

It draws a solid box in the rectangle (x0, y0)-(x1, y1).
pcolor = T6963C_[WHITE[BLACK].
Requires Ports must be initialized. See T6963C_init.

Example T6963C_box(0, 119, 239, 127, T6963C_WHITE);

page

198
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

T6963C_circle
Prototype procedure T6963C_circle(x, y : integer; r : longint; pcolor :
word);

Description This routine sets current graphic work panel.

It draws a circle, center is (x, y), diameter is r.
pcolor = T6963C_[WHITE[BLACK]
Requires Ports must be initialized. See T6963C_init.

Example T6963C_circle(120, 64, 110, T6963C_WHITE);

T6963C_image
Prototype procedure T6963C_image(const pic : ^byte);

Description This routine sets current graphic work panel :

It fills graphic area with picture pointer by MCU.
MCU must fit the display geometry.
For example : for a 240x128 display, MCU must be an array of (240/8)*128 = 3840
bytes .
Requires Ports must be initialized. See T6963C_init.

Example T6963C_image(my_image);

T6963C_sprite
Prototype procedure T6963C_sprite(px, py : byte; const pic : ^byte; sx, sy
: byte);

Description This routine sets current graphic work panel.

It fills graphic rectangle area (px, py)-(px + sx, py + sy) witch picture pointed by MCU.
Sx and sy must be the size of the picture.
MCU must be an array of sx*sy bytes.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_sprite(76, 4, einstein, 88, 119); // draw a sprite

page
mikroElektronika: Development tools - Books - Compilers
199
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

T6963C_set_cursor
Prototype procedure T6963C_set_cursor(x, y : byte);

Description This routine sets cursor row x line y.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_set_cursor(cposx, cposy);

T6963C_clearBit
Prototype procedure T6963C_clearBit(b : byte);

Description Clear control bit.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_clearBit(b);

T6963C_setBit
Prototype procedure T6963C_setBit(b : byte);

Description Set control bit.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_setBit(b);

T6963C_negBit
Prototype procedure T6963C_negBit(b : byte);

Description Neg control bit.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_negBit(b);

page

200
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

T6963C_displayGrPanel
Prototype procedure T6963C_displayGrPanel(n : word);

Description Display graphic panel number n.

Requires GLCD needs to be initialized, see T6963C_init.

Example T6963C_displayGrPanel(n);

T6963C_displayTxtPanel
Prototype procedure T6963C_displayTxtPanel(n : word);

Description Display text panel number n.

Requires GLCD needs to be initialized, see T6963C_init.

Example T6963C_displayTxtPanel(n);

T6963C_setGrPanel
Prototype procedure T6963C_setGrPanel(n : word);

Description Compute graphic start address for panel number n.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_setGrPanel(n);

T6963C_setTxtPanel
Prototype procedure T6963C_setTxtPanel(n : word);

Description Compute text start address for panel number n.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_setTxtPanel(n);

page
mikroElektronika: Development tools - Books - Compilers
201
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

T6963C_panelFill
Prototype procedure T6963C_panelFill(v : word);

Description Fill full #n panel with v bitmap (0 to clear).

Requires Ports must be initialized. See T6963C_init.

Example T6963C_panelFill(v);

T6963C_grFill
Prototype procedure T6963C_grFill(v: word);

Description Fill graphic #n panel with v bitmap (0 to clear).

Requires Ports must be initialized. See T6963C_init.

Example T6963C_grFill(v);

T6963C_txtFill
Prototype procedure T6963C_txtFill(v : word);

Description Fill text #n panel with char v + 32 (0 to clear).

Requires Ports must be initialized. See T6963C_init.

Example T6963C_txtFill(v);

T6963C_cursor_height
Prototype procedure T6963C_cursor_height(n: word);

Description Set cursor size.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_cursor_height(n);

page

202
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

T6963C_graphics
Prototype procedure T6963C_graphics(n : word);

Description Set graphics on/off.

Requires GLCD needs to be initialized, see T6963C_init.

Example T6963C_graphics(1);

T6963C_text
Prototype procedure T6963C_text(n : word);

Description Set text on/off.

Requires GLCD needs to be initialized, see T6963C_init.

Example T6963C_text(1);

T6963C_cursor
Prototype procedure T6963C_cursor(n : word);

Description Set cursor on/off.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_cursor(1);

T6963C_cursor_blink
Prototype procedure T6963C_cursor_blink(n : word);

Description Set cursor blink on/off.

Requires Ports must be initialized. See T6963C_init.

Example T6963C_cursor_blink(0);

page
mikroElektronika: Development tools - Books - Compilers
203
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

T6963C_Init_240x128
Prototype procedure T6963C_Init_240x128;

Description Initialize T6963C based GLCD (240x128 pixels) with default settings for mE GLCD's.

Example T6963C_Init_240x128;

T6963C_Init_240x64
Prototype procedure T6963C_Init_240x64;

Description Initialize T6963C based GLCD (240x64 pixels) with default settings for mE GLCD's.

Example T6963C_Init_240x64;

Library Example
The following drawing demo tests advanced routines of T6963C GLCD library.
program T6963C;
uses bitmap, bitmap2;
var panel : byte; // current panel
i : word; // general purpose register
curs : byte; // cursor visibility
cposx,
cposy : word; // cursor x-y position
begin
TRISC := 0xFFFF;
TRISB := 0x0000;
PORTD := 0 ;
TRISD := 0 ;
{* init display for 240 pixel width and 128 pixel height
* 8 bits character width
* data bus on PORTD
* control bus on PORTB
* bit 3 is !WR
* bit 2 is !RD
* bit 1 is !CD
* bit 5 is RST}
T6963C_init(240, 128, 8, PORTD, PORTB, 3, 2, 1, 5) ;
// enable both graphics and text display at the same time
T6963C_graphics(1) ;
T6963C_text(1) ;

//continues...

page

204
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

//continues...

panel := 0;
i := 0;
curs := 0;
cposy := 0;
cposx := 0;

{*
* text messages
*}
T6963C_write_text(' GLCD LIBRARY DEMO, WELCOME !', 0, 0,
T6963C_ROM_MODE_XOR) ;
T6963C_write_text(' EINSTEIN WOULD HAVE LIKED mC', 0, 15,
T6963C_ROM_MODE_XOR) ;

{*
* cursor
*}
T6963C_cursor_height(8); // 8 pixel height
T6963C_set_cursor(0, 0); // move cursor to top left
T6963C_cursor(0) ; // cursor off

{*
* draw rectangles
*}
T6963C_rectangle(0, 0, 239, 127, T6963C_WHITE) ;
T6963C_rectangle(20, 20, 219, 107, T6963C_WHITE) ;
T6963C_rectangle(40, 40, 199, 87, T6963C_WHITE) ;
T6963C_rectangle(60, 60, 179, 67, T6963C_WHITE) ;

{*
* draw a cross
*}
T6963C_line(0, 0, 239, 127, T6963C_WHITE) ;
T6963C_line(0, 127, 239, 0, T6963C_WHITE) ;

{*
* draw solid boxes
*}
T6963C_box(0, 0, 239, 8, T6963C_WHITE) ;
T6963C_box(0, 119, 239, 127, T6963C_WHITE) ;

//continued...

page
mikroElektronika: Development tools - Books - Compilers
205
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

{*
* draw circles
*}
T6963C_circle(120, 64, 10, T6963C_WHITE) ;
T6963C_circle(120, 64, 30, T6963C_WHITE) ;
T6963C_circle(120, 64, 50, T6963C_WHITE) ;
T6963C_circle(120, 64, 70, T6963C_WHITE) ;
T6963C_circle(120, 64, 90, T6963C_WHITE) ;
T6963C_circle(120, 64, 110, T6963C_WHITE) ;
T6963C_circle(120, 64, 130, T6963C_WHITE) ;

T6963C_sprite(76, 4, einstein, 88, 119) ; // draw a sprite

T6963C_setGrPanel(1) ; // select other graphic panel

T6963C_image(mikroPascal_logo_glcd_bmp);
// fill the graphic screen with a picture

while true do
begin
{*
* if RC0 is pressed, toggle the display between positive
and negative mode
*}
if(PORTC.0 <> 0) then
begin
//PORTC.1 := PORTC.1 xor 1;
Delay_ms(300) ;
end

{*
* if RC1 is pressed, toggle the display between graphic
panel 0 and graphic 1
*}
else
if(PORTC.1 <> 0) then
begin
panel := panel + 1;
panel := panel and 1 ;
T6963C_displayGrPanel(panel) ;
Delay_ms(300) ;
end

page

206
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

{*
* if RC2 is pressed, display only graphic panel
*}
else
if(PORTC.2 <> 0) then
begin
T6963C_graphics(1) ;
T6963C_text(0) ;
Delay_ms(300) ;
end

{*
* if RC3 is pressed, display only text panel
*}
else
if(PORTC.3 <> 0) then
begin
T6963C_graphics(0) ;
T6963C_text(1) ;
Delay_ms(300) ;
end

{*
* if RC4 is pressed, display text and graphic panels
*}
else
if(PORTC.4 <> 0) then
begin
T6963C_graphics(1) ;
T6963C_text(1) ;
Delay_ms(300) ;
end

page
mikroElektronika: Development tools - Books - Compilers
207
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

{*
* if RC5 is pressed, change cursor
*}
else
if(PORTC.5 <> 0) then
begin
curs := curs + 1;
if(curs = 3) then
curs := 0 ;
case curs of
0:
T6963C_cursor(0) ;

1:
begin
T6963C_cursor(1) ;
T6963C_cursor_blink(1) ;
end;

2:
begin
T6963C_cursor(1) ;
T6963C_cursor_blink(0) ;
end;
end;
Delay_ms(300) ;
end;
{*
* move cursor, even if not visible
*}
cposx := cposx + 1;
if(cposx = T6963C_txtCols) then
begin
cposx := 0 ;
cposy := cposy + 1;
if(cposy = (T6963C_grHeight div T6963C_CHARACTER_HEIGHT)) then
cposy := 0 ;
end;
T6963C_set_cursor(cposx, cposy) ;
Delay_ms(100) ;
end;
end.

page

208
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

PIC18F452
VCC

11 30 D7
VCC RD7
12 29 D6
GND RD6
13 28 D5
OSC1 RD5
14 27 D4
OSC2 RD4

8 Mhz RS 16
RC1
R/W 17 24 RST
RC2 RC5
E 18
RC3
D0 19 22 D3
RD0 RD3
D1 20 21 D2
RD1 RD2

Contrast
Adjustment
P1
10K

VCC

VCC
R1
50

1 20
VDD

LED+
VSS

RST
VEE
R/W

MD
CE
RS

D0

D5
D7
D1
D3
D2
D4
D6

FS
Vo

mikroE
EasyPIC3
Dev. tool

Toshiba T6963C Graphic LCD (240x128)

page
mikroElektronika: Development tools - Books - Compilers
209
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Manchester Code Library

mikroPascal provides a library for handling Manchester coded signals. Manchester
code is a code in which data and clock signals are combined to form a single self-
synchronizing data stream; each encoded bit contains a transition at the midpoint
of a bit period, the direction of transition determines whether the bit is a 0 or a 1;
second half is the true bit value and the first half is the complement of the true bit
value (as shown in the figure below).

Manchester RF_Send_Byte format

St1 St2 Ctr B7 B6 B5 B4 B3 B2 B1 B0

Bi-phase coding

1 0
2.4ms Example of transmission

1 1 0 0 01 0 0 01 1

Notes: Manchester receive routines are blocking calls (Man_Receive_Config,

Man_Receive_Init, Man_Receive). This means that PIC will wait until the
task is performed (e.g. byte is received, synchronization achieved, etc). Routines
for receiving are limited to a baud rate scope from 340 ~ 560 bps.

Library Routines

Man_Receive_Config
Man_Receive_Init
Man_Receive
Man_Send_Config
Man_Send_Init
Man_Send
Man_Synchro

page

210
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Man_Receive_Config

Prototype procedure Man_Receive_Config(var port : byte; rxpin : byte);

Description The procedure prepares PIC for receiving signal. You need to specify the port and
rxpin (0–7) of input signal. In case of multiple errors on reception, you should call
Man_Receive_Init once again to enable synchronization.

Example Man_Receive_Config(PORTD, 6);

Man_Receive_Init

Prototype procedure Man_Receive_Init(var port : byte);

Description The procedure prepares PIC for receiving signal. You need to specify the port; rxpin
is pin 6 by default. In case of multiple errors on reception, you should call
Man_Receive_Init once again to enable synchronization.

Example Man_Receive_Init(PORTD);

Man_Receive

Prototype function Man_Receive(var error : byte) : byte;

Returns Returns one byte from signal.

Description procedure extracts one byte from signal. If signal format does not match the expected,
error flag will be set to 255.

Requires To use this function, you must first prepare the PIC for receiving. See
Man_Receive_Config or Man_Receive_Init.

Example temp := Man_Receive(error);

if error then ... // error handling

page
mikroElektronika: Development tools - Books - Compilers
211
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Man_Send_Config

Prototype procedure Man_Send_Config(var port : byte; txpin : byte);

Description The function prepares PIC for sending signal. You need to specify port and txpin
(0–7) for outgoing signal. Baud rate is const 500 bps.

Example Man_Send_Config(PORTD, 0);

Man_Send_Init

Prototype procedure Man_Send_Init(var port : byte);

Description The function prepares PIC for sending signal. You need to specify port for outgoing
signal; txpin is pin 0 by default. Baud rate is const 500 bps.

Example Man_Send_Init(PORTD);

Man_Send

Prototype procedure Man_Send(data : byte);

Description Sends one byte (data).

Requires To use this function, you must first prepare the PIC for sending. See
Man_Send_Config or Man_Send_Init.

Example Man_Send(msg);

page

212
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Man_Synchro

Prototype function Man_Synchro : byte;

Returns Half of the manchester bit length, given in multiples of 10us.

Description This function returns half of the manchester bit length. The length is given in multiples
of 10us. It is assumed that one bit lasts no more than 255*10us = 2550 us.

Requires To use this function, you must first prepare the PIC for sending. See
Man_Send_Config or Man_Send_Init.

Example man_len := Man_Synchro();

Library Example

The following example transmits message in Manchester code. Message is delimited by markers
$0B and $0E.

program RF_TX;
var i : byte;
var msg : string[20];
begin
msg := 'mikroElektronika';
PORTB := 0; // Initialize port
TRISB := %00001110;
ClearBit(INTCON, GIE); // Disable interrupts
Man_Send_Init(PORTB); // Initialize Manchester sender
while TRUE do
begin
Man_Send($0B); // Send start marker
Delay_ms(100); // Wait for a while
for i := 1 to Strlen(msg) do
begin
Man_Send(msg[i]); // Send char
Delay_ms(90);
end;
Man_Send($0E); // Send end marker
Delay_ms(1000);
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
213
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

The following code receives messages sent by the previous example, and prints it on LCD. Each
error in the received string will be indicated by a quotation mark.
program RRX;
var error, ErrorCount, temp : byte;

begin
ErrorCount := 0;
TRISB := 0;
CMCON := 7;
// VRCON = 0; // Uncomment the line for PIC16
Lcd_Init(PORTB); // Initialize LCD on PORTB
Lcd_Cmd(Lcd_CLEAR);
Man_Receive_Config(PORTA,3); // Configure and synchronize receiver

while true do
Lcd_Cmd(Lcd_FIRST_ROW);

while true do // Wait for the start marker

begin
temp := Man_Receive(error);
if temp = $0B then break; // We got the starting sequence
if error then break; // Exit so we do not loop forever
end;

repeat
begin
temp = Man_Receive(error); // Attempt byte receive
if error = true then
begin
Lcd_Chr_Cp(63); // ASCII for "?"
Inc(ErrorCount);
if ErrorCount > 20 then
begin
Man_Receive_Init(PORTA);
// alternative:
// temp := Man_Synchro;
ErrorCount := 0;
end;
else
if temp <> $0E then // Don't write the end marker on LCD
Lcd_Chr_Cp(temp);
Delay_ms(20);
end;
end;
until temp = $0E; // Wait for the end marker

end;
end.

page

214
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

Transmitter RF
module

PIC18F452
VCC

Antenna
11
VCC VCC
12
GND
13
OSC1
14
OSC2

8 Mhz

VCC

19
A RT4 In RD0

GND

page
mikroElektronika: Development tools - Books - Compilers
215
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Receiver RF
module

Antenna

PIC18F452
VCC

11
VCC
12
GND
RR4 13
14
OSC1
OSC2
Receiver RF
8 Mhz
module

20
RD1

VCC

page

216
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Multi Media Card Library

The Multi Media Card (MMC) is a flash memory memory card standard. MMC
cards are currently available in sizes up to and including 1 GB, and are used in
cell phones, mp3 players, digital cameras, and PDAs.

mikroPascal provides a library for accessing data on Multi Media Card via SPI
communication.

Note: Multi Media Card Library works only with PIC18 family.

Note: Spi_Init_Advanced(MASTER_OSC_DIV16, DATA_SAMPLE_MIDDLE,

CLK_IDLE_LOW, LOW_2_HIGH); must be called before initializing Mmc_Init
and Mmc_Fat_Init.

Library Routines

Mmc_Init
Mmc_Read_Sector
Mmc_Write_Sector
Mmc_Read_Cid
Mmc_Read_Csd

Mmc_Fat_Init
Mmc_Fat_Assign
Mmc_Fat_Reset
Mmc_Fat_Rewrite
Mmc_Fat_Append
Mmc_Fat_Read
Mmc_Fat_Write
Mmc_Fat_Set_File_Date
Mmc_Fat_Get_File_Date
Mmc_Fat_Get_File_Size
Mmc_Fat_Get_Swap_File

page
mikroElektronika: Development tools - Books - Compilers
217
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Mmc_Init

Prototype function Mmc_Init(var port : byte; pin : byte): byte;

Returns Returns 0 if MMC card is present and successfully initialized, otherwise returns 1.

Description Initializes hardware SPI communication; parameters port and pin designate the CS line
used in the communication (parameter pin should be 0..7). The function returns 0 if
MMC card is present and successfully initialized, otherwise returns 1. Mmc_Init needs
to be called before using other functions of this library.
Requires Spi_Init_Advanced(MASTER_OSC_DIV16, DATA_SAMPLE_MIDDLE,
CLK_IDLE_LOW, LOW_2_HIGH); must be called before initializing Mmc_Init.

Example error := Mmc_Init(PORTC, 2); // Init with CS line at RC2

Mmc_Read_Sector

Prototype function Mmc_Read_Sector(sector : longint; var data : array[512]

of byte) : byte;

Returns Returns 0 if read was successful, or 1 if an error occurred.

Description Function reads one sector (512 bytes) from MMC card at sector address sector. Read
data is stored in the array data. Function returns 0 if read was successful, or 1 if an
error occurred.

Requires Library needs to be initialized, see Mmc_Init.

Example error := Mmc_Read_Sector(sector, data);

page

218
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Mmc_Write_Sector

Prototype function Mmc_Write_Sector(sector : longint; var data : array[512]

of byte) : byte;

Returns Returns 0 if write was successful; returns 1 if there was an error in sending write com-
mand; returns 2 if there was an error in writing.

Description Function writes 512 bytes of data to MMC card at sector address sector. Function
returns 0 if write was successful, or 1 if there was an error in sending write command,
or 2 if there was an error in writing.

Requires Library needs to be initialized, see Mmc_Init.

Example error := Mmc_Write_Sector(sector, data);

Mmc_Read_Cid

Prototype function Mmc_Read_Cid(var data_for_registers : array[512] of

byte) : byte;

Returns Returns 0 if read was successful, or 1 if an error occurred.

Description Function reads CID register and returns 16 bytes of content into
data_for_registers.

Requires Library needs to be initialized, see Mmc_Init.

Example error := Mmc_Read_Cid(data);

page
mikroElektronika: Development tools - Books - Compilers
219
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Mmc_Read_Csd

Prototype function Mmc_Read_Csd(var data_for_registers : array[512] of

byte) : byte;

Returns Returns 0 if read was successful, or 1 if an error occurred.

Description Function reads CSD register and returns 16 bytes of content into
data_for_registers.

Requires Library needs to be initialized, see Mmc_Init.

Example error := Mmc_Read_Csd(data);

Mmc_Fat_Init

Prototype function Mmc_Fat_Init(var mmcport : byte; mmcpin : byte) : byte;

Returns Returns 0 if initialization is successful, 1 if boot sector was not found and 255 if card
was not detected.

Description Initializes hardware SPI communication; designated CS line for communication is given
by parameters mmcport and mmcpin. The function returns a non-zero value if MMC
card is present and successfully initialized, otherwise it returns 0.

This function needs to be called before using other functions of MMC FAT library.

Requires Spi_Init_Advanced(MASTER_OSC_DIV16, DATA_SAMPLE_MIDDLE,

CLK_IDLE_LOW, LOW_2_HIGH); must be called before initializing Mmc_Fat_Init.

Example success := Mmc_Fat_Init(PORTC, 2);

page

220
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Mmc_Fat_Assign

Prototype function Mmc_Fat_Assign(var filename : array[11] of char,

create_file : byte) : byte;

Returns If the card is successfully initialized returns 0, otherwise returns 1.

Description This function designates (“assigns”) the file we’ll be working with. The function looks
for the file specified by the filename in the root directory. If the file is found, routine
will initialize it by getting its start sector, size, etc. If the file is not found, an empty file
will be created with the given name, if allowed.

Whether the new file will be created or not is controlled by the parameter
create_file - setting it to zero will prevent creation of new file, while giving it any
non-zero value will do the opposite.

The filename must be 8 + 3 characters in uppercase.

Requires Library needs to be initialized; see Mmc_Fat_Init.

Example // Assign the file "EXAMPLE1.TXT" in the root directory of MMC.

// If the file is not found, routine will create one.
// In this case, function return value will allways be non-zero
Mmc_Fat_Assign('EXAMPLE1TXT', 1);

// Assign the file "EXAMPLE2.TXT" in the root directory of MMC.

// If the file is not found, routine will NOT create new one.
file_found := Mmc_Fat_Assign('EXAMPLE2TXT', 0);

page
mikroElektronika: Development tools - Books - Compilers
221
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Mmc_Fat_Reset

Prototype procedure Mmc_Fat_Reset(var size : longint);

Description Procedure resets the file pointer (moves it to the start of the file) of the assigned file, so
that the file can be read. Parameter size stores the size of the assigned file, in bytes.

Requires The file must be assigned, see Mmc_Fat_Assign.

Example Mmc_Fat_Reset(size);

Mmc_Fat_Rewrite

Prototype procedure Mmc_Fat_Rewrite;

Description Procedure resets the file pointer and clears the assigned file, so that new data can be
written into the file.

Requires The file must be assigned, see Mmc_Fat_Assign.

Example Mmc_Fat_Rewrite();

Mmc_Fat_Append

Prototype procedure Mmc_Fat_Append;

Description The procedure moves the file pointer to the end of the assigned file, so that data can be
appended to the file.

Requires The file must be assigned, see Mmc_Fat_Assign.

Example Mmc_Fat_Append();

page

222
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Mmc_Fat_Read

Prototype procedure Mmc_Fat_Read(var data : byte);

Description Procedure reads the byte at which the file pointer points to and stores data into parame-
ter data. The file pointer automatically increments with each call of Mmc_Fat_Read.

Requires The file must be assigned, see Mmc_Fat_Assign. Also, file pointer must be initialized;
see Mmc_Fat_Reset.

Example Mmc_Fat_Read(mydata);

Mmc_Fat_Write

Prototype procedure Mmc_Fat_Write(var fdata : array[256] of char);

Description Procedure writes a chunk of bytes (fdata) to the currently assigned file, at the position
of the file pointer.

Requires The file must be assigned, see Mmc_Fat_Assign. Also, file pointer must be initialized;
see Mmc_Fat_Append or Mmc_Fat_Rewrite.

Example Mmc_Fat_Write(txt);
Mmc_Fat_Write('Hello' + #13 + 'world');

Mmc_Fat_Set_File_Date

Prototype procedure Mmc_Set_File_Date(year : word; month, day, hours, min,

sec : byte);

Description Writes system timestamp to a file. Use this routine before each writing to file; other-
wise, the file will be appended an unknown timestamp.

Requires File pointer must be initialized; see Mmc_Fat_Assign and Mmc_Fat_Reset.

Example // April 1st 2005, 18:07:00

Mmc_Set_File_Date(2005, 4, 1, 18, 7, 0);

page
mikroElektronika: Development tools - Books - Compilers
223
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Mmc_Fat_Get_File_Date

Prototype procedure Mmc_Fat_Get_File_Date(var year : word; var month, day,

hours, min, sec : byte);

Description Retrieves date and time for the currently selected file. Seconds are not being retrieved
since they are written in 2-sec increments.

Requires The file must be assigned, see Mmc_Fat_Assign.

Example // get Date/time of file

var
yr: word;
mnth, dat, hrs, mins: byte;
...
file_Name := "MYFILEABTXT";
Mmc_Fat_Assign(file_Name);
Mmc_Fat_Get_File_Date(yr, mnth, dat, hrs, mins);

Mmc_Fat_Get_File_Size

Prototype function Mmc_Fat_Get_File_Size : longint;

Returns The size of active file (in bytes).

Description Retrieves size for currently selected file.

Requires The file must be assigned, see Mmc_Fat_Assign.

Example // get file size

var
yr: word;
mnth, dat, hrs, mins: byte;
...
file_name := "MYFILEXXTXT";
Mmc_Fat_Assign(file_name);
cf_size := Mmc_Fat_Get_File_Size();

page

224
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Mmc_Fat_Get_File_Size

Prototype function Mmc_Fat_Get_Swap_File(sectors_cnt : longint): longint

Returns No. of start sector for the newly created swap file, if swap file was created; otherwise,
the function returns zero.

Description This function is used to create a swap file on the MMC/SD media. It accepts as sec-
tors_cnt argument the number of consecutive sectors that user wants the swap file to
have. During its execution, the function searches for the available consecutive sectors,
their number being specified by the sectors_cnt argument. If there is such space on the
media, the swap file named MIKROSWP.SYS is created, and that space is designated
(in FAT tables) to it. The attributes of this file are: system, archive and hidden, in order
to distinct it from other files. If a file named MIKROSWP.SYS already exists on the
media, this function deletes it upon creating the new one.

The purpose of the swap file is to make reading and writing to MMC/SD media as fast
as possible, without potentially damaging the FAT system. Swap file can be considered
as a "window" on the media where user can freely write/read the data, in any way (s)he
wants to. Its main purpose in mikroPascal library is to be used for fast data acquisition;
when the time-critical acquisition has finished, the data can be re-written into a "nor-
mal" file, and formatted in the most suitable way.

Requires Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

Example //-------------- Tries to create a swap file, whose size will be

//at least 1000 sectors.
//If it succeeds, it sends the No. of start sector over USART
procedure M_Create_Swap_File;
begin
size := Mmc_Fat_Get_Swap_File(1000);
if (size) then
begin
Usart_Write($AA);
Usart_Write(Lo(size));
Usart_Write(Hi(size));
Usart_Write(Higher(size));
Usart_Write(Highest(size));
Usart_Write($AA);
end;
end;

page
mikroElektronika: Development tools - Books - Compilers
225
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The following code tests MMC library routines. First, we fill the buffer with 512 “M” characters
and write it to sector 56; then, we repeat the sequence with character “E” at sector 56. Finally, we
read the sectors 55 and 56 to check if the write was successful.
program mmc_test;
var tmp : byte;
i : word;
data : array[512] of byte;
begin
Usart_Init(9600);

// Initialize SPI
Spi_Init_Advanced(MASTER_OSC_DIV16, DATA_SAMPLE_MIDDLE, CLK_IDLE_LOW,
LOW_2_HIGH);

// Initialize ports
tmp := Mmc_Init(PORTC, 2);

// Fill the buffer with the 'M' character

for i := 0 to 512 do data[i] := 'M';

// Write it to MMC card, sector 55

tmp := Mmc_Write_Sector(55, data);

// Fill the buffer with the 'E' character

for i := 0 to 512 do data[i] := 'E';

// Write it to MMC card, sector 56

tmp := Mmc_Write_Sector(56, data);

//** Verify: **

// Read from sector 55

tmp := Mmc_Read_Sector(55, data);

// Send 512 bytes from buffer to USART

if tmp = 0 then
for i := 0 to 512 do Usart_Write(data[i]);

// Read from sector 56

tmp := Mmc_Read_Sector(56, data);

// Send 512 bytes from buffer to USART

if tmp = 0 then
for i := 0 to 512 do Usart_Write(data[i]);
end.

page

226
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example

The next program tests MMC FAT routines. First, we create 5 different files in the root of MMC
card, and fill with some information. Then, we read the files and send them via USART for a
check.

program MMC_FAT_Test;

const FAT_ERROR : string[20] = 'FAT16 not found';

var filename : string[14];
tmp, character, loop : byte;
size, i : longint;
aux : string[5];
msg : string[100];

begin
Usart_Init(19200); // Set up USART for reading of files
// Initialize SPI

Spi_Init_Advanced(MASTER_OSC_DIV16, DATA_SAMPLE_MIDDLE, CLK_IDLE_LOW,

LOW_2_HIGH);

tmp := Mmc_Fat_Init(PORTC, 2); // Try to locate the FAT

if tmp <> 0 then

for tmp := 0 to Strlen(FAT_ERROR) - 1 do
Usart_Write(FAT_ERROR[tmp]);

loop := 1;

//** Write test, 5 files **//

for loop := 1 to 5 do // We want 5 files on our MMC
begin
filename := 'MYFILE0xTXT'; // File names, e.g. "MYFILE01.TXT"
filename[7] := loop + 48; // Set number 1, 2, 3, 4, or 5

Mmc_Fat_Assign(filename, 1); // Create the file, if not found

Mmc_Fat_Rewrite(); // Clear the file, prepare for writing

// Form the text to be written

aux := ' ';
aux[0] := loop + 48;
msg := 'This is a test file, no.' + aux;

Mmc_Fat_Write(msg); // Write data to the assigned file

end;

// continues ..

page
mikroElektronika: Development tools - Books - Compilers
227
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

// .. continued

//** Append test **//

// Now let's add more data to the same files

for loop := 1 to 5 do
begin
filename := 'MYFILE0xTXT';
filename[7] := loop + 48;

Mmc_Fat_Assign(filename, 1); // Find the file and "assign" it

Mmc_Fat_Append(); // Prepare for appending

// Form the text to be written

aux := ' ';
aux[0] := loop + 48;
msg := 'Append test, try ' + aux;

Mmc_Set_File_Date(2005,5,loop,12,47,12); // Test the date function

Mmc_Fat_Write(msg); // Write data to the assigned file

//** Read test **//

Mmc_Fat_Reset(size); // Take the size of the file

// Send the whole file to USART, char by char

for i := 1 to size do
begin
Mmc_Fat_Read(character);
Usart_Write(character);
end;
end;

end.

page

228
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

REG2

MC33269 VCC
VCC3 VCC DT-3.3

3
GND VIN
C20 C19
PIC18F452 100nF 100nF 1 2 VOUT
VCC3

E15
VCC 10uF
SPI-MISO

MMC-CS#

11 SPI-MOSI
VCC
12 SPI-SCK
GND
13 VCC3
OSC1 R13 R15 R17
14 2K2 2K2 2K2
8 Mhz OSC2
1
CS
2
Din
3
GND
4
17 24 +3.3V
RC2 RC5 5
18 23 6
SCK
GND MMC/SD
RC3 RC4
R14 R16 R18
7
Dout CARD
3K3 3K3 3K3

1 2 3 4 5 6 7

MMC

Back view

page
mikroElektronika: Development tools - Books - Compilers
229
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

OneWire Library
OneWire library provides routines for communication via OneWire bus, for exam-
ple with DS1820 digital thermometer. This is a Master/Slave protocol, and all the
cabling required is a single wire. Because of the hardware configuration it uses
(single pullup and open collector drivers), it allows for the slaves even to get their
power supply from that line.

Some basic characteristics of this protocol are:

- single master system,

- low cost,
- low transfer rates (up to 16 kbps),
- fairly long distances (up to 300 meters),
- small data transfer packages.

Each OneWire device also has a unique 64-bit registration number (8-bit device
type, 48-bit serial number and 8-bit CRC), so multiple slaves can co-exist on the
same bus.

Note that oscillator frequency Fosc needs to be at least 4MHz in order to use the
routines with Dallas digital thermometers.

Library Routines

Ow_Reset
Ow_Read
Ow_Write

page

230
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Ow_Reset

Prototype function Ow_Reset(var port : byte; pin : byte) : byte;

Returns Returns 0 if DS1820 is present, 1 if not present.

Description Issues OneWire reset signal for DS1820. Parameters port and pin specify the location
of DS1820.

Requires Works with Dallas DS1820 temperature sensor only.

Example Ow_Reset(PORTA, 5); // reset DS1820 connected to the RA5 pin

Ow_Read

Prototype function Ow_Read(var port : byte; pin : byte) : byte;

Returns Data read from an external device over the OneWire bus.

Description Reads one byte of data via the OneWire bus.

Example tmp := Ow_Read(PORTA, 5);

Ow_Write

Prototype procedure Ow_Write(var port : byte; pin, par : byte);

Description Writes one byte of data (argument par) via OneWire bus.

Example Ow_Write(PORTA, 5, $CC);

page
mikroElektronika: Development tools - Books - Compilers
231
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example
The example reads the temperature from DS1820 sensor connected to RA5. Temperature value is
continually displayed on LCD.
program onewire;
var i, j1, j2 : byte;
text : array[10] of char;
tmp_sign : byte;
begin
text := 'Temp:';
ADCON1 := 6; // configure PORTA as digital I/O
PORTA := 255; // initialize porte to 255
PORTD := 0; // initialize portb to 255
TRISA := 255; // designate porta as input
TRISD := 0; // designate portb as output
Lcd_Init(PORTD);
Lcd_Cmd(LCD_CURSOR_OFF);
Lcd_Out(1, 1, text);
Lcd_Chr(2, 12, 223); // 'degree' character
Lcd_Chr(2, 13, 'C');
repeat
Ow_Reset(PORTA, 5); // onewire reset signal
Ow_Write(PORTA, 5, $CC); // issue SKIP ROM command to DS1820
Ow_Write(PORTA, 5, $44); // issue CONVERT T command to DS1820
Delay_us(120);
i := Ow_Reset(PORTA, 5);
Ow_Write(PORTA,5, $CC); // issue SKIP ROM command to DS1820
Ow_Write(PORTA,5, $BE); // issue READ SCRATCHPAD command to DS1820
j1 := Ow_Read(PORTA, 5); // get result
j2 := Ow_Read(PORTA, 5); // get result
if j2 = $FF then
begin
tmp_sign := '-'; // temperature sign
j1 := j1 or $FF; // complement of two
j1 := j1 + $01;
end
else
tmp_sign := '+';
j2 := (j1 and $01)*5; // get decimal value
j1 := j1 shr 1; // get temp value
ByteToStr(j1, text); // whole number
Lcd_Chr(2, 7, tmp_sign);
Lcd_Chr(2, 8, text[1]);
Lcd_Chr(2, 9, text[2]);
Lcd_Chr(2, 10, '.');
ByteToStr(j2, text); // decimal
Lcd_Chr(2, 11, text[2]);
Delay_ms(500);
until false; // endless loop
end.

page

232
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

125 C

PIC18F452
DS1820 -50 C VCC 7
RA5
VCC
R10
VCC
10K
VCC
11
VCC
DQ 12
GND
13
OSC1
14
OSC2

8 Mhz

page
mikroElektronika: Development tools - Books - Compilers
233
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

PS/2 Library
mikroPascal provides a library for communicating with common PS/2 keyboard.
The library does not utilize interrupts for data retrieval, and requires oscillator
clock to be 6MHz and above.

Please note:

- The pins to which a PS/2 keyboard is attached should be connected to pull-up

resistors.
- Although PS/2 is a two-way communication bus, this library does not provide
PIC-to-keyboard communication; e.g. the Caps Lock LED will not turn on if you
press the Caps Lock key.

Library Routines

Ps2_Init
Ps2_Key_Read

Ps2_Init

Prototype procedure Ps2_Init(var port : byte; clock, data : byte);

Description Initializes port for work with PS/2 keyboard, with custom pin settings. Parameters
data and clock specify pins of port for Data line and Clock line, respectively. Data
and clock need to be in range 0..7 and cannot point at the same pin. You need to call
Ps2_Init before using other routines of PS/2 library.

Requires Both Data and Clock lines need to be in pull-up mode.

Example Ps2_Init(PORTB, 3, 2);

page

234
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Ps2_Key_Read

Prototype function Ps2_Key_Read(var value, special, pressed : byte) : byte;

Returns Returns 1 if reading of a key from the keyboard was successful, otherwise 0.

Description The procedure retrieves information about key pressed.

Parameter value holds the value of the key pressed. For characters, numerals, punctua-
tion marks, and space, value will store the appropriate ASCII value. Procedure “recog-
nizes” the function of Shift and Caps Lock, and behaves appropriately.

Parameter special is a flag for special function keys (F1, Enter, Esc, etc). If key
pressed is one of these, special will be set to 1, otherwise 0.

Parameter pressed is set to 1 if the key is pressed, and 0 if released.

Requires PS/2 keyboard needs to be initialized; see Ps2_Init.

Example // Press Enter to continue:

repeat
if Ps2_Key_Read(val, spec, press) = 1 then
if (val = 13) and (spec = 1) then break;
until FALSE;

page
mikroElektronika: Development tools - Books - Compilers
235
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example
This simple example reads values of keys pressed on PS/2 keyboard and sends them via USART.

program ps2_test;
var keydata, special, down : byte;

begin
CMCON := $07; // Disable analog comparators (comment this for P18)
INTCON := 0; // Disable all interrupts
Ps2_Init(PORTA, 1, 0); // Init PS/2 Keyboard on PORTA
Delay_ms(100); // Wait for keyboard to finish

repeat
begin
if Ps2_Key_Read(keydata, special, down) = 1 then
begin
if (down = 1) and (keydata = 16) then // Backspace
// ...do something with a backspace...
else if (down = 1) and (keydata = 13) then // Enter
Usart_Write(13);
else if (down = 1) and (special = 0) and (keydata <> 0) then
Usart_Write(keydata);
end;
Delay_ms(10); // debounce
end;
until FALSE;
end.

page

236
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

PWM Library
CCP unit is available with a number of PICmicros. mikroPascal provides library
which simplifies using PWM HW Module.

Note: Certain PICmicros with two or more CCP modules, such as P18F8520,
require you to specify the module you want to use. Simply append the number 1
or 2 to a Pwm. For example, Pwm2_Start; Also, for the sake of backward com-
pabitility with previous compiler versions and easier code management, MCU's
with multiple PWM modules have PWM library which is identical to PWM1 (i.e.
you can use PWM_Init instead of PWM1_Init to initialize CCP1).

Library Routines

Pwm_Init
Pwm_Change_Duty
Pwm_Start
Pwm_Stop

Pwm_Init

Prototype procedure Pwm_Init(const freq);

Description Initializes the PWM unit with duty ratio 0. Parameter freq is a desired PWM frequency
in Hz (refer to device data sheet for correct values in respect with Fosc).

PWM_Init needs to be called before using other functions from PWM Library.

Requires You need a CCP module in order to use this library. Check mikroC installation folder,
subfolder “Examples”, for alternate solutions.

Example Pwm_Init(5000); // Initialize PWM unit at 5KHz

page
mikroElektronika: Development tools - Books - Compilers
237
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Pwm_Change_Duty

Prototype procedure Pwm_Change_Duty(duty_ratio : byte);

Description Changes PWM duty ratio. Parameter duty_ratio takes values from 0 to 255, where 0
is 0%, 127 is 50%, and 255 is 100% duty ratio. Other specific values for duty ratio can
be calculated as (Percent*255)/100.

Requires You need a CCP unit on PORTC to use this library. To use this function, unit needs to be
initalized – see Pwm_Init.

Example Pwm_Change_Duty(192); // Set duty ratio to 75%

Pwm_Start

Prototype procedure Pwm_Start;

Description Starts PWM.

Requires You need a CCP unit on PORTC to use this library. To use this function, unit needs to be
initalized – see Pwm_Init.

Example Pwm_Start();

Pwm_Stop

Prototype procedure Pwm_Stop;

Description Stops PWM.

Requires You need a CCP unit on PORTC to use this library. To use this function, unit needs to be
initalized – see Pwm_Init.

Example Pwm_Stop();

page

238
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example
The example changes PWM duty ratio on port C continually. If LED is connected to RC2, you can
observe the gradual change of emitted light.
program Pwm_Test;
var i, j : byte;
begin
i := 0; j := 0;
PORTC := $FF; // Initialize PORTC
Pwm_Init(5000); // Initialize PWM unit, freq = 5kHz.
Pwm_Start; // Start PWM
while true do
begin
for i := 0 to 20 do Delay_us(500);
j := j + 1;
Pwm_Change_Duty(j); // Change duty ratio
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
239
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection

PIC18F452
VCC

11
VCC
12
GND
13
OSC1
14
8 Mhz OSC2

17
RC2

300R

page

240
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

RS-485 Library
RS-485 is a multipoint communication which allows multiple devices to be con-
nected to a single signal cable. mikroPascal provides a set of library routines to
provide you comfortable work with RS-485 system using Master/Slave architec-
ture. Master and Slave devices interchange packets of information, each of these
packets containing synchronization bytes, CRC byte, address byte, and the data.
Each Slave has its unique address and receives only the packets addressed to it.
Slave can never initiate communication. It is programmer’s responsibility to
ensure that only one device transmits via 485 bus at a time.

RS-485 routines require USART unit on PORTC. Pins of USART need to be

attached to RS-485 interface transceiver, such as LTC485 or similar. Pins of trans-
ceiver (Receiver Output Enable and Driver Outputs Enable) should be connected
to PORTC, pin 2 (check the figure at end of the chapter).

Note: Address 50 is the common address for all Slaves (packets containing
address 50 will be received by all Slaves). The only exceptions are Slaves with
addresses 150 and 169, which require their particular address to be specified in the
packet.

Note: Usart_init(); must be called before initializing RS485.

Library Routines

RS485Master_Init
RS485Master_Receive
RS485Master_Send
RS485Slave_Init
RS485Slave_Receive
RS485Slave_Send

page
mikroElektronika: Development tools - Books - Compilers
241
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

RS485Master_Init

Prototype procedure RS485Master_Init(var port:byte; pin:byte);

Description Initializes PIC MCU as Master in RS-485 communication.

Requires USART HW unit needs to be initialized. See USART_Init.

Example RS485Master_Init(PORTC, 2, 160);

RS485Master_Receive

Prototype procedure RS485Master_Receive(var data : array[5] of byte);

Description Receives any message sent by Slaves. Messages are multi-byte, so this procedure must
be called for each byte received (see the example at the end of the chapter). Upon
receiving a message, buffer is filled with the following values:

data[0..2] is the message,

data[3] is number of message bytes received, 1–3,
data[4] is set to 255 when message is received,
data[5] is set to 255 if error has occurred,
data[6] is the address of the Slave which sent the message.

Function automatically adjusts data[4] and data[5] upon every received message.
These flags need to be cleared from the program.

Requires MCU must be initialized as Master in RS-485 communication in order to be assigned an

address. See RS485Master_Init.

Example RS485Master_Receive(msg);

page

242
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

RS485Master_Send

Prototype procedure RS485Master_Send(var data : array[2] of byte; datalen,

address : byte);

Description Sends data from buffer to Slave(s) specified by address via RS-485; datalen is a
number of bytes in message (1 <= datalen <= 3).

Requires MCU must be initialized as Master in RS-485 communication in order to be assigned an

address. See RS485Master_Init.

It is programmer’s responsibility to ensure (by protocol) that only one device sends data
via 485 bus at a time.

Example RS485Master_Send(msg, 3, $12);

RS485Slave_Init

Prototype procedure Rs485slave_Init(var port : byte; pin, address : byte);

Description Initializes MCU as Slave with a specified address in RS-485 communication. Slave
address can take any value between 0 and 255, except 50, which is common address
for all slaves.

Requires USART HW unit needs to be initialized. See Usart_Init.

Example RS485Slave_Init(PORTC, 2, 160); // Initialize MCU as Slave with

address 160

page
mikroElektronika: Development tools - Books - Compilers
243
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

RS485Slave_Receive

Prototype procedure RS485Slave_Receive(var data : array[5] of byte);

Description Receives message addressed to it. Messages are multi-byte, so this procedure must be
called for each byte received (see the example at the end of the chapter). Upon receiving
a message, buffer is filled with the following values:

data[0..2] is the message,

data[3] is number of message bytes received, 1–3,
data[4] is set to 255 when message is received,
data[5] is set to 255 if error has occurred,
data[6] is the address of the Slave which sent the message.

Function automatically adjusts data[4] and data[5] upon every received message.
These flags need to be cleared from the program.

Requires MCU must be initialized as Slave in RS-485 communication in order to be assigned an

address. See RS485Slave_Init.

Example RS485Slave_Read(msg);

RS485Slave_Send

Prototype procedure RS485Slave_Write(var data : array[2] of byte; datalen :

byte);

Description Sends data from buffer to Master via RS-485; datalen is the number of bytes in mes-
sage (1 <= datalen <= 3).

Requires MCU must be initialized as Slave in RS-485 communication in order to be assigned an

address. See RS485Slave_Init.

It is programmer’s responsibility to ensure (by protocol) that only one device sends data
via 485 bus at a time.

Example RS485Slave_Send(msg, 2);

page

244
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example
The example demonstrates working with PIC as Slave nod in RS-485 communication. PIC
receives only packets addressed to it (address 160 in our example), and general messsages with
target address 50. The received data is forwarded to PORTB, and sent back to Master.

program rs485_test;
var dat : array[8] of byte; // Message buffer
i, j : byte;

procedure interrupt;
begin
if TestBit(RCSTA, OERR) = 1 then PORTD := $81;
RS485Slave_Read(dat);
end;

begin
TRISB := 0;
TRISD := 0;
USART_init(9600); // Initialize USART unit
RS485Slave_Init(PORTC, 2, 160);// Initialize MCU as Slave, address 160
SetBit(PIE1, RCIE); // Enable interrupt on byte received
SetBit(INTCON, PEIE); // via USART (RS485)
ClearBit(PIE2, TXIE);
SetBit(INTCON, GIE);
PORTB := 0;
PORTD := 0;
dat[4] := 0; // Clear "message received" flag
dat[5] := 0; // Clear error flag

while true do
begin
// If there is an error, set PORTD to $AA
if dat[5] = TRUE then PORTD := $AA;
// If message received:
if dat[4] = TRUE then
begin
dat[4] := 0; // Clear message received flag
j := dat[3]; // Number of data bytes received
for i := 1 to j do
PORTB := dat[i - 1]; // Output received data bytes
dat[0] := dat[0] + 1; // Increment received dat[0]
RS485Slave_Write(dat, 1); // Send it back to Master
end;
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
245
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection

Shielded pair
no longer than 300m

PIC18F452
VCC

11
VCC
12
GND
VCC 13
OSC1
14
OSC2
26
RC7
1 8 25
R0 Vcc 8 Mhz RC6
17
2 7 RC2
RE B
3 6
DE A
4 5
DI GND

LTC485

VCC
620R
1 8
R0 Vcc
2 7
RE B
3 6
DE A
4 5
DI GND
620R
LTC485

4.7uF +

C1+ Vcc
MAX232

4.7uF
V+ GND
+
C1- T1 OUT
C2+ R1IN
+
PC
C2- R1out
V- T1in
4.7uF
T2out T2in
R2in R2out

RTS
+
4.7uF GND

TX
RX

page

246
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Software I2C Library

mikroPascal provides routines which implement software I²C. These routines are
hardware independent and can be used with any MCU. Software I2C enables you
to use MCU as Master in I2C communication. Multi-master mode is not support-
ed.

Note: This library implements time-based activities, so interrupts need to be dis-

abled when using Soft I²C.

Library Routines

Soft_I2C_Config
Soft_I2C_Start
Soft_I2C_Read
Soft_I2C_Write
Soft_I2C_Stop

Soft_I2C_Config

Prototype procedure Soft_I2C_Config(var port : byte; SDA, SCL : byte);

Description Configures software I²C. Parameter port specifies port of MCU on which SDA and SCL
pins are located. Parameters SCL and SDA need to be in range 0–7 and cannot point at
the same pin.

Soft_I2C_Config needs to be called before using other functions from Soft I2C
Library.

Example Soft_I2C_Config(PORTB, 1, 2);

page
mikroElektronika: Development tools - Books - Compilers
247
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Soft_I2C_Start

Prototype procedure Soft_I2C_Start;

Description Issues START signal. Needs to be called prior to sending and receiving data.

Requires Soft I²C must be configured before using this function. See Soft_I2C_Config.

Example Soft_I2C_Start;

Soft_I2C_Read

Prototype function Soft_I2C_Read(ack : byte) : byte;

Returns Returns one byte from the slave.

Description Reads one byte from the slave, and sends not acknowledge signal if parameter ack is 0,
otherwise it sends acknowledge.

Requires START signal needs to be issued in order to use this function. See Soft_I2C_Start.

Example tmp := Soft_I2C_Read(0);

page

248
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Soft_I2C_Write

Prototype function Soft_I2C_Write(data : byte) : byte;

Returns Returns 0 if there were no errors.

Description Sends data byte (parameter data) via I²C bus.

Requires START signal needs to be issued in order to use this function. See Soft_I2C_Start.

Example Soft_I2C_Write($A3);

Soft_I2C_Stop

Prototype procedure Soft_I2C_Stop;

Description Issues STOP signal.

Requires START signal needs to be issued in order to use this function. See Soft_I2C_Start.

Example Soft_I2C_Stop;

page
mikroElektronika: Development tools - Books - Compilers
249
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The example demonstrates use of Software I²C Library. PIC MCU is connected (SCL, SDA pins)
to 24C02 EEPROM. Program sends data to EEPROM (data is written at address 2). Then, we read
data via I²C from EEPROM and send its value to PORTC, to check if the cycle was successful.
Check the hardware connection scheme at hardware I2C Library.

program soft_i2c_test;

var ee_adr, ee_data : byte;

jj : word;

begin
Soft_I2C_Config(PORTD, 3, 4); // Initialize full master mode
TRISC := 0; // PORTC is output
PORTC := $FF; // Initialize PORTC
Soft_I2C_Start(); // Issue I2C start signal
Soft_I2C_Write($A2); // Send byte via I2C(command to 24cO2)
ee_adr := 2;
Soft_I2C_Write(ee_adr); // Send byte(address for EEPROM)
ee_data := $AA;
Soft_I2C_Write(ee_data); // Send data(data that will be written)
Soft_I2C_Stop(); // Issue I2C stop signal

for jj := 0 to 65500 do // Pause while EEPROM writes data

nop;

Soft_I2C_Start(); // Issue I2C start signal

Soft_I2C_Write($A2); // Send byte via I2C
ee_adr := 2;
Soft_I2C_Write(ee_adr); // Send byte(address for EEPROM)
Soft_I2C_Start(); // Issue I2Csignal repeated start
Soft_I2C_Write($A3); // Send byte(request data from EEPROM)
ee_data := Soft_I2C_Read(0); // Read the data
Soft_I2C_Stop(); // Issue I2C_stop signal
PORTC := ee_data; // Display data on PORTC

while TRUE do nop;

end.

page

250
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Software SPI Library

mikroPascal provides library which implement software SPI. These routines are
hardware independent and can be used with any MCU. You can easily communi-
cate with other devices via SPI: A/D converters, D/A converters, MAX7219,
LTC1290, etc.

The library configures SPI to master mode, clock = 50kHz, data sampled at the
middle of interval, clock idle state low and data transmitted at low to high edge.

Note: These functions implement time-based activities, so interrupts need to be

disabled when using the library.

Library Routines

Soft_Spi_Config
Soft_Spi_Read
Soft_Spi_Write

Soft_Spi_Config

Prototype procedure Soft_Spi_Config(var port : byte; SDI, SD0, SCK : byte);

Description Configures and initializes software SPI. Parameter port specifies port of MCU on which
SDI, SDO, and SCK pins will be located. Parameters SDI, SDO, and SCK need to be in
range 0–7 and cannot point at the same pin.

Soft_Spi_Config needs to be called before using other functions from Soft SPI
Library.

Example This will set SPI to master mode, clock = 50kHz, data sampled at the middle of interval,
clock idle state low and data transmitted at low to high edge. SDI pin is RB1, SDO pin
is RB2 and SCK pin is RB3:

Soft_Spi_Config(PORTB, 1, 2, 3);

page
mikroElektronika: Development tools - Books - Compilers
251
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Soft_Spi_Read

Prototype function Soft_Spi_Read(buffer : byte) : byte;

Returns Returns the received data.

Description Provides clock by sending buffer and receives data.

Requires Soft SPI must be initialized and communication established before using this function.
See Soft_Spi_Config.

Example tmp := Soft_Spi_Read(buffer);

Soft_Spi_Write

Prototype procedure Soft_Spi_Write(data : byte);

Description Immediately transmits data.

Requires Soft SPI must be initialized and communication established before using this function.
See Soft_Spi_Config.

Example Soft_Spi_Write(1);

page

252
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example
The example demonstrates using Software SPI library. Assumed HW configuration is: max7219
(chip select pin) is connected to RD1, and SDO, SDI, SCK pins are connected to corresponding
pins of max7219. Hardware connection is given on page 186.

program Soft_Spi_test;
uses m7219;

var i : byte;

begin
Soft_Spi_Config(PORTD, 4, 5, 3); // Standard configuration
TRISC := TRISC and $FD;
max7219_init; // Initialize max7219
SetBit(PORTD, 1); // Select max7219
Soft_Spi_Write(1); // Send address (1) to max7219
Soft_Spi_Write(7); // Send data (7) to max7219
ClearBit(PORTD, 1); // Deselect max7219
end.

page
mikroElektronika: Development tools - Books - Compilers
253
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Software UART Library

mikroPascal provides library which implements software UART. These routines
are hardware independent and can be used with any MCU. You can easily commu-
nicate with other devices via RS232 protocol – simply use the functions listed
below.

Note: This library implements time-based activities, so interrupts need to be dis-

abled when using Soft UART.

Library Routines

Soft_Uart_Init
Soft_Uart_Read
Soft_Uart_Write

Soft_Uart_Init

Prototype procedure Soft_Uart_Init(var port : byte; const rx, tx,

baud_rate, inverted : byte);

Description Initalizes software UART. Parameter port specifies port of MCU on which RX and TX
pins are located; parameters rx and tx need to be in range 0–7 and cannot point at the
same pin; baud_rate is the desired baud rate. Maximum baud rate depends on PIC’s
clock and working conditions.

Parameter inverted, if set to non-zero value, indicates inverted logic on output.

Soft_Uart_Init needs to be called before using other functions from Soft UART
Library.

Example This will initialize software UART and establish the communication at 9600 bps:

Soft_Uart_Init(PORTB, 1, 2, 9600, 0);

page

254
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Soft_Uart_Read

Prototype function Soft_Uart_Read(var error : byte) : byte;

Returns Returns a received byte.

Description Function receives a byte via software UART. Parameter error will be zero if the
transfer was successful. This is a non-blocking function call, so you should test the
error manually (check the example below).

Requires Soft UART must be initialized and communication established before using this func-
tion. See Soft_Uart_Init.

Example // Here's a loop which holds until data is received:

error := 1;
repeat
data := Soft_Uart_Read(error);
until error = 0;

Soft_Uart_Write

Prototype procedure Soft_Uart_Write(data : byte);

Description Function transmits a byte (data) via UART.

Requires Soft UART must be initialized and communication established before using this func-
tion. See Soft_Uart_Init.

Be aware that during transmission, software UART is incapable of receiving data – data
transfer protocol must be set in such a way to prevent loss of information.

Example Soft_Uart_Write($0A);

page
mikroElektronika: Development tools - Books - Compilers
255
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The example demonstrates simple data exchange via software UART. When PIC MCU receives
data, it immediately sends the same data back. If PIC is connected to the PC (see the figure
below), you can test the example from mikroPascal terminal for RS232 communication, menu
choice Tools > Terminal.

program soft_uart_test;

var received_byte, er : byte;

begin
Soft_Uart_Init(PORTB, 1, 2, 2400, 0); // Initialize soft UART
er := 1;
while true do
begin
repeat
received_byte := Soft_Uart_Read(er); // Read received data
until er = 0;
Soft_Uart_Write(received_byte); // Send data via UART
end;
end.

page

256
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Sound Library
mikroPascal provides a Sound Library which allows you to use sound signaliza-
tion in your applications. You need a simple piezo speaker (or other hardware) on
designated port.

Library Routines

Sound_Init
Sound_Play

Sound_Init

Prototype procedure Sound_Init(var port: byte; pin: byte);

Description Prepares hardware for output at specified port and pin. Parameter pin needs to be
within range 0–7.

Example Sound_Init(PORTB, 2); // Initialize sound at RB2

Sound_Play

Prototype procedure Sound_Play(period_div_10: byte; num_of_periods: word);

Description Plays the sound at the specified port and pin (see Sound_Init). Parameter
period_div_10 is a sound period given in MCU cycles divided by ten, and generated
sound lasts for a specified number of periods (num_of_periods).

Requires To hear the sound, you need a piezo speaker (or other hardware) on designated port.
Also, you must call Sound_Init to prepare hardware for output.

Example To play sound of 1KHz: T = 1/f = 1ms = 1000 cycles @ 4MHz. This gives us our first
parameter: 1000/10 = 100. Play 150 periods like this:

Sound_Play(100, 150);

page
mikroElektronika: Development tools - Books - Compilers
257
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The example is a simple demonstration of how to use sound library for playing tones on a piezo
speaker. The code can be used with any MCU that has PORTB and ADC on PORTA. Sound fre-
quencies in this example are generated by reading the value from ADC and using the lower byte of
the result as base for T (f = 1/T).

program Sound_test;
var adc_value : word;

begin
PORTB = 0; // Clear PORTB
TRISB = 0; // PORTB is output
INTCON = 0; // Disable all interrupts
ADCON1 = $82; // Configure VDD as Vref, and analog channels
TRISA = $FF; // PORTA is input
Sound_Init(PORTB, 2); // Initialize sound at RB2

while TRUE do
begin
adc_value = Adc_Read(2); // Get lower byte from ADC
Sound_Play(adc_value, 200); // Play the sound
end;
end.

page

258
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SPI Library
SPI unit is available with a number of PIC MCU models. mikroPascal provides a
library for initializing Slave mode and comfortable work with Master mode. PIC
can easily communicate with other devices via SPI: A/D converters, D/A convert-
ers, MAX7219, LTC1290, etc. You need PIC MCU with hardware integrated SPI
(for example, PIC16F877).

Note: Certain PICmicros with two SPI modules, such as P18F8722, require you to
specify the module you want to use. Simply append the number 1 or 2 to a Spi.
For example, Spi2_Write; Also, for the sake of backward compabitility with previ-
ous compiler versions and easier code management, MCU's with multiple SPI
modules have SPI library which is identical to SPI1 (i.e. you can use SPI_Init;
instead of SPI1_Init; for SPI operations).

Library Routines

Spi_Init
Spi_Init_Advanced
Spi_Read
Spi_Write

Spi_Init

Prototype procedure Spi_Init();

Description Configures and initializes SPI with default settings. Spi_Init_Advanced or

Spi_Init needs to be called before using other functions from SPI Library.

Default settings are: Master mode, clock Fosc/4, clock idle state low, data transmitted on
low to high edge, and input data sampled at the middle of interval.

For custom configuration, use Spi_Init_Advanced.

Requires You need PIC MCU with hardware integrated SPI.

Example Spi_Init;

page
mikroElektronika: Development tools - Books - Compilers
259
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_Init_Advanced

Prototype procedure Spi_Init_Advanced(master, data_sample, clock_idle,

transmit_edge : byte);

Description Configures and initializes SPI. Spi_Init_Advanced or Spi_Init needs to be called

before using other functions of SPI Library.

Parameter mast_slav determines the work mode for SPI; can have the values:

MASTER_OSC_DIV4 // Master clock=Fosc/4

MASTER_OSC_DIV16 // Master clock=Fosc/16
MASTER_OSC_DIV64 // Master clock=Fosc/64
MASTER_TMR2 // Master clock source TMR2
SLAVE_SS_ENABLE // Master Slave select enabled
SLAVE_SS_DIS // Master Slave select disabled

The data_sample determines when data is sampled; can have the values:

DATA_SAMPLE_MIDDLE // Input data sampled in middle of interval

DATA_SAMPLE_END // Input data sampled at the end of interval

Parameter clock_idle determines idle state for clock; can have the following values:

CLK_IDLE_HIGH // Clock idle HIGH

CLK_IDLE_LOW // Clock idle LOW

Parameter transmit_edge can have the following values:

LOW_2_HIGH // Data transmit on low to high edge

HIGH_2_LOW // Data transmit on high to low edge

Requires You need PIC MCU with hardware integrated SPI.

Example This will set SPI to master mode, clock = Fosc/4, data sampled at the middle of interval,
clock idle state low and data transmitted at low to high edge:

Spi_Init_Advanced(MASTER_OSC_DIV4, DATA_SAMPLE_MIDDLE,
CLK_IDLE_LOW, LOW_2_HIGH);

page

260
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Read

Prototype function Spi_Read(buffer : byte) : byte;

Returns Returns the received data.

Description Provides clock by sending buffer and receives data at the end of period.

Requires SPI must be initialized and communication established before using this function. See
Spi_Init_Advanced or Spi_Init.

Example take := Spi_Read(buffer);

Spi_Write

Prototype procedure Spi_Write(data : byte) : byte;

Description Writes byte data to SSPBUF, and immediately starts the transmission.

Requires SPI must be initialized and communication established before using this function. See
Spi_Init_Advanced or Spi_Init.

Example Spi_Write(1);

page
mikroElektronika: Development tools - Books - Compilers
261
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The code demonstrates how to use SPI library procedures and functions. Assumed configuration
is: max7219 (chip select pin) connected to RC1, and SDO, SDI, SCK pins are connected to corre-
sponding pins of max7219.

program Spi_test;
uses m7219;

begin
Spi_Init; // Standard configuration
TRISC := TRISC and $FD;
max7219_init; // Initialize max7219
ClearBit(PORTC, 1); // Select max7219
Spi_Write(1); // Send address (1) to max7219
Spi_Write(7); // Send data (7) to max7219
SetBit(PORTC, 1); // Deselect max7219
end.

page

262
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

USART Library
USART hardware unit is available with a number of PICmicros. mikroPascal
USART Library provides comfortable work with the Asynchronous (full duplex)
mode.You can easily communicate with other devices via RS232 protocol (for
example with PC, see the figure at the end of the topic – RS232 HW connection).
You need a PIC MCU with hardware integrated USART, for example PIC16F877.
Then, simply use the functions listed below.

Library Routines

Usart_Init Usart_Read_Text
Usart_Data_Ready Usart_Write_Text
Usart_Read
Usart_Write

Note: Certain PICmicros with two USART modules, such as P18F8520, require
you to specify the module you want to use. Simply append the number 1 or 2 to a
function name. For example, Usart_Write2(9600); Also, for the sake of backward
compabitility with previous compiler versions and easier code management,
MCU's with multiple USART modules have USART library which is identical to
USART1 (i.e. you can use Usart_Init(9600); instead of Usart_Init1(9600); for
Usart operations).

Usart_Init

Prototype procedure Usart_Init(const baud_rate : longint);

Description Initializes hardware USART unit with the desired baud rate. Refer to the device data
sheet for baud rates allowed for specific Fosc. If you specify the unsupported baud rate,
compiler will report an error.

Usart_Init needs to be called before using other functions from USART Library.

Requires You need PIC MCU with hardware USART.

Example Usart_Init(2400); // Establish communication at 2400 bps

page
mikroElektronika: Development tools - Books - Compilers
263
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Usart_Data_Ready

Prototype function Usart_Data_Ready : byte;

Returns Function returns 1 if data is ready or 0 if there is no data.

Description Use the function to test if data in receive buffer is ready for reading.
Requires USART HW unit must be initialized and communication established before using this
function. See Usart_Init.

Example // If data is ready, read it:

if Usart_Data_Ready() = 1 then receive := Usart_Read;

Usart_Read

Prototype function Usart_Read : byte;

Returns Returns the received byte. If byte is not received, returns 0.

Description Function receives a byte via USART. Use the function Usart_Data_Ready to test if
data is ready first.
Requires USART HW unit must be initialized and communication established before using this
function. See Usart_Init.
Example // If data is ready, read it:
if Usart_Data_Ready() = 1 then receive := Usart_Read;

page

264
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Usart_Write

Prototype procedure Usart_Write(data : byte);

Description Function transmits a byte (data) via USART.

Requires USART HW unit must be initialized and communication established before using this
function. See Usart_Init.

Example Usart_Write($1E) // send chunk via USART

Usart_Read_Text

Prototype procedure Usart_Read_Text(var output, delimiter : string[20]);

Description Reads characters received via USART until the delimiter sequence is detected. The read
sequence is stored in the parameter output; delimiter sequence is stored in the parameter
delimiter.

This is a blocking call: the delimiter sequence is expected, otherwise the procedure exits
after 20 recieved characters.
Requires USART HW unit must be initialized and communication established before using this
function. See Usart_Init.
Example Read text until the sequence “OK” is received, and send back what’s been received:

Usart_Init(9600);
delim := 'OK';
while TRUE do
begin
if Usart_Data_Ready() = 1 then
begin
Usart_Read_Text(txt, delim);
Usart_Write_Text(txt);
end;
end;

page
mikroElektronika: Development tools - Books - Compilers
265
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Usart_Write_Text

Prototype procedure Usart_Write_Text(var uart_text : string[20]);

Description Sends text (parameter uart_text) via USART. Text should be zero terminated.

Requires USART HW unit must be initialized and communication established before using this
function. See Usart_Init.

Example Read text until the sequence “OK” is received, and send back what’s been received:

Usart_Init(9600);
delim := 'OK';
while TRUE do
begin
if Usart_Data_Ready() = 1 then
begin
Usart_Read_Text(txt, delim);
Usart_Write_Text(txt);
end;
end;

page

266
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example
The example demonstrates simple data exchange via USART. When PIC receives the data, it
immediately sends it back. If PIC is connected to the PC (see the figure below), you can test the
example from mikroPascal terminal for RS232 communication, menu choice Tools > Terminal.

program rs232_com_test;
var received_byte : byte;

begin
Usart_Init(2400); // Initialize USART unit
while true do
begin
if Usart_Data_Ready = 1 then // If data is received
begin
received_byte := Usart_Read; // Read received data
Usart_Write(received_byte); // Send data via USART
end;
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
267
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection

PC
6 9
RS-232 CN3
CON SUB-D 9p
1 5

CONNECT Receive
MCU TO PC data (Rx)

SERIAL
CABLE

CONNECT
PC TO MCU Send
Data (Tx)

6 9
RS-232 CN3
SUB-D 9p
CON 1 5
1

2
7
3
8

9
6

5
4

VCC

C18
100nF
PIC18F452

VCC

U6 11
12
VCC
13 12 GND
R1 IN R1 OUT Rx 13
OSC1
MAX232

8 9 14
R2 IN R2 OUT OSC2
11 14 8 Mhz 26
T1 IN T1 OUT RC7
25
10 7 RC6
T2 IN T2 OUT
1 4
E9 C1+ C2+
3 5 E11
10uF C1- 10uF
C2-
6 2
E10 V- V+
15 16 E12
10uF 10uF
GND VCC

VCC Tx

page

268
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

USB HID Library

Universal Serial Bus (USB) provides a serial bus standard for connecting a wide
variety of devices, including computers, cell phones, game consoles, PDAs, etc.

mikroPascal includes a library for working with human interface devices via
Universal Serial Bus. A human interface device or HID is a type of computer
device that interacts directly with and takes input from humans, such as the key-
board, mouse, graphics tablet, and the like.

Each project based on the USB HID library should include a descriptor source file
which contains vendor id and name, product id and name, report length, and other
relevant information. To create a descriptor file, use the integrated USB HID ter-
minal of mikroPascal (Tools > USB HID Terminal). The default name for descrip-
tor file is USBdsc.ppas, but you may rename it. The provided code in the
“Examples” folder works at 48MHz, and the flags should not be modified without
consulting the appropriate datasheet first.

Library Routines

Hid_Enable
Hid_Read
Hid_Write
Hid_Disable

Hid_Enable

Prototype procedure Hid_Enable(readbuff, writebuff : word);

Description Enables USB HID communication. Parameters readbuff and writebuff are the addresses
of Read Buffer and the Write Buffer, respectively, which are used for HID communica-
tion. You can pass buffer names with the @ operator.

This function needs to be called before using other routines of USB HID Library.

Example Hid_Enable(@rd, @wr);

page
mikroElektronika: Development tools - Books - Compilers
269
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hid_Read

Prototype function Hid_Read() : byte;

Returns Number of characters in Read Buffer received from Host.

Description Receives message from host and stores it in the Read Buffer. Function returns the num-
ber of characters received in Read Buffer.

Requires USB HID needs to be enabled before using this function. See Hid_Enable.

Example length := Hid_Read();

Hid_Write

Prototype procedure Hid_Write(writebuff : word, len : byte);

Description Function sends data from Write Buffer writebuff to host. Write Buffer is the address
of the parameter used in initialization; see Hid_Enable. You can pass a buffer name
with the @ operator. Parameter len should specify a length of the data to be
transmitted.

Requires USB HID needs to be enabled before using this function. See Hid_Enable.

Example Hid_Write(@wr, len);

Hid_Disable

Prototype procedure Hid_Disable();

Description Disables USB HID communication.

Example Hid_Disable();

page

270
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Library Example

The following example continually sends sequence of numbers 0..255 to the PC via Universal
Serial Bus.

program hid_test;
var k : byte;
userRD_buffer : array[64] of byte;
userWR_buffer : array[64] of byte;

procedure interrupt;
begin
asm
CALL _Hid_InterruptProc
nop
end;
end;

procedure Init_Main;
begin
// Disable GIE, PEIE, TMR0IE, INT0IE, RBIE
INTCON := 0;
INTCON2 := $F5;
INTCON3 := $C0;
RCON.IPEN := 0;
PIE1 := 0;
PIE2 := 0;
PIR1 := 0;
PIR2 := 0;

// Configure all ports with analog function as digital

ADCON1 := ADCON1 or $0F;

TRISA := 0;
TRISB := 0;
TRISC := $FF;
TRISD := $FF;
TRISE := $07;

LATA := 0;
LATB := 0;
LATC := 0;
LATD := 0;
LATE := 0;

// continues ..

page
mikroElektronika: Development tools - Books - Compilers
271
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

// .. continued

// Clear user RAM

// Banks [00 .. 07] ( 8 x 256 = 2048 Bytes )
asm
LFSR FSR0, $000
MOVLW $08
CLRF POSTINC0, 0
CPFSEQ FSR0H, 0
BRA $ - 2
end;

// Timer 0
T0CON := $07;
TMR0H := (65536-156) shr 8;
TMR0L := (65536-156) and $FF;
INTCON.T0IE := 1; // Enable T0IE
T0CON.TMR0ON := 1;
end;

//** Main Program **/

begin
Init_Main();
Hid_Enable(@userRD_buffer, @userWR_buffer);

repeat
begin
for k := 0 to 255 do
begin
// Prepare send buffer
userWR_buffer[0] := k;

// Send the number via USB

Hid_Write(@userWR_buffer, 1);
end;
end;
until FALSE;

Hid_Disable;
end.

page

272
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

HW Connection

MCLR RB7
RA0 RB6
RA1 RB5
RA2 RB4
RA3
PIC18F4550 RB3
RA4 RB2
RA5 RB1
RE0 RB0
RE1 VDD
VCC
RE2 VSS
11
VDD RD7
12
VSS RD6
13
OSC1 RD5
14 VCC
8 Mhz OSC2 RD4
RC0 RC7
RC1 RC6 VCC
RC2 RC5 D-
Vusb RC4 D+ USB
100nF 100nF
RD0 RD3 GND
RD1 RD2

page
mikroElektronika: Development tools - Books - Compilers
273
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Util Library
Util library contains miscellaneous routines useful for project development.

Button

Prototype function Button(var port : byte; pin, time, active_state : byte)

: byte;

Returns Returns 0 or 255.

Description Function eliminates the influence of contact flickering upon pressing a button (debounc-
ing).

Parameter port specifies the location of the button; parameter pin is the pin number on
designated port and goes from 0..7; parameter time is a debounce period in millisec-
onds; parameter active_state can be either 0 or 1, and it determines if the button is
active upon logical zero or logical one.

Example Example reads RB0, to which the button is connected; on transition from 1 to 0 (release
of button), PORTD is inverted:

while true do
begin
if Button(PORTB, 0, 1, 1) then oldstate := 255;
if oldstate and Button(PORTB, 0, 1, 0) then
begin
PORTD := not(PORTD);
oldstate := 0;
end;
end;

page

274
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Conversions Library
mikroPascal Conversions Library provides routines for converting numerals to
strings, and routines for BCD/decimal conversions.

Library Routines

You can get text representation of numerical value by passing it to one of the fol-
lowing routines:

ByteToStr
WordToStr
IntToStr
LongintToStr
WordToHex
FloatToStr
StrToInt
StrToWord

The following functions convert decimal values to BCD (Binary Coded Decimal)
and vice versa:

Bcd2Dec
Dec2Bcd
Bcd2Dec16
Dec2Bcd16

ByteToStr

Prototype procedure ByteToStr(number : byte; var output : string[3]);

Description Procedure creates an output string out of a small unsigned number (numerical value
less than $100). Output string has fixed width of 3 characters; remaining positions on
the left (if any) are filled with blanks.

Example var t : word; txt : string[3];

//...
t := 24;
ByteToStr(t, txt); // txt is ' 24' (one blank here)

page
mikroElektronika: Development tools - Books - Compilers
275
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

ShortToStr

Prototype procedure ShortToStr(number : short; var output : string[4]);

Description Procedure creates an output string out of a small signed number (numerical value less
than $100). Output string has fixed width of 4 characters; remaining positions on the left
(if any) are filled with blanks.

Example var t : short; txt : string[4];

//...
t := -24;
ShortToStr(t, txt); // txt is ' -24' (one blank here)

WordToStr

Prototype procedure WordToStr(number : word; var output : string[5]);

Description Procedure creates an output string out of an unsigned number (numerical value of
word type). Output string has fixed width of 5 characters; remaining positions on the
left (if any) are filled with blanks.

Example var t : short; txt : string[4];

//...
t := -24;
ShortToStr(t, txt); // txt is ' -24' (one blank here)

WordToStrWithZeros

Prototype procedure WordToStrWithZeros(number : word; var output :

string[5]);

Description Procedure creates an output string out of an unsigned number (numerical value of
word type). Output string has fixed width of 5 characters; remaining positions on the
left (if any) are filled with zeros.

Example var t : short; txt : string[4];

//...
t := 437;
WordToStrWithZeros(t, txt); // txt is '00437' (two zeros here)

page

276
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

IntToStr

Prototype procedure IntToStr(number : integer; var output : string[6]);

Description Procedure creates an output string out of a signed number (numerical value of
integer type). Output string has fixed width of 6 characters; remaining positions on
the left (if any) are filled with blanks.

Example var j : integer; txt : string[6];

//...
j := -4220;
IntToStr(j, txt); // txt is ' -4220' (one blank here)

LongintToStr

Prototype procedure LongintToStr(number: longint; var output : string[11]);

Description Procedure creates an output string out of a large signed number (numerical value of
longint type). Output string has fixed width of 11 characters; remaining positions on
the left (if any) are filled with blanks.

Example var jj : longint; txt : string[11];

//...
jj := -3700000;
LongintToStr(jj, txt);// txt is ' -3700000' (three blanks here)

page
mikroElektronika: Development tools - Books - Compilers
277
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

FloatToStr

Prototype procedure FloatToStr(input : real; var output : string[17]);

Description Procedure creates string out of the input parameter, which should be a floating point
number in the longint range (±2147483648). Parameter output accepts the created
string. The result is given in format "integer.fraction", left aligned.

Note: Procedure won’t return the correct result if input exceeds the longint range!
You’ll need to create a custom routine if you want to handle such large numbers.

The integer part has flexible width of up to 11 characters (10 digits + sign). If the
actual integer part is shorter than that, string will wrap to the integer’s length. The
fraction part is always 5 characters long. If the actual fraction is shorter than 5 digits,
remaining chars on the right will be filled with zeroes; if the fraction exceeds 5 digits,
the fraction part will be trimmed.

Requires If you want to use the FloatToStr for printing on LCD, ensure that your program
clears/refreshes the display with each printing of a string. Otherwise, LCD will display
the remnants (rightmost digits) of the previous string, if it was longer than the presently
displayed one.

Example Here’s an example which prints value of a real variable on LCD:

var input : real; output : string[17];

begin
input := -3.1415;
FloatToStr(input, output);
Lcd_Out_Cp(output); // Print '-3.14150' on LCD

Bcd2Dec

Prototype function Bcd2Dec(bcdnum : byte) : byte;

Returns Returns converted decimal value.

Description Converts 8-bit BCD numeral bcdnum to its decimal equivalent.

Example var a, b : byte;

a := $52;
b := Bcd2Dec(a); // b equals 52

page

278
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Dec2Bcd

Prototype function Dec2Bcd(decnum : byte) : byte;

Returns Returns converted BCD value.

Description Converts 8-bit decimal value decnum to BCD.

Example var a, b : byte;

a := 52;
b := Dec2Bcd(a); // b equals $52

Bcd2Dec16

Prototype function Bcd2Dec16(bcdnum : byte) : byte;

Returns Returns converted decimal value.

Description Converts 16-bit BCD numeral bcdnum to its decimal equivalent.

Example var a, b : word;

a := 1234;
b := Bcd2Dec16(a); // b equals 4660

Dec2Bcd16

Prototype function Dec2Bcd16(decnum : byte) : byte;

Returns Returns converted BCD value.

Description Converts 16-bit decimal value decnum to BCD.

Example var a, b : word;

a := 4660;
b := Dec2Bcd16(a); // b equals 1234

page
mikroElektronika: Development tools - Books - Compilers
279
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

StrToInt

Prototype function StrToInt(var input: string[6]): integer;

Returns Integer variable.

Description Converts a string to integer.

Requires The string is assumed to be a correct representation of a number.

Example
var ii: integer;

begin
ii:= StrToInt('-1234');
end.

StrToWord
Prototype function StrToWord(var input: string[5]): word;

Returns Word variable.

Description Converts a string to word.

Requires input string with length of max 5 chars.

The string is assumed to be a correct representation of a number.

Example
var ww: word;

begin
ww:= StrToword('65432');
end.

page

280
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Delays Library
mikroPascal provides a basic utility routines for creating software delay. You can
create more advanced and flexible versions based on this library.

Note: Routines do not provide an entirely accurate delay as it depends on clock

specified in Project settings.

Delay_us

Prototype procedure Delay_us(const time_in_us : word);

Description Creates a software delay in duration of time_in_us microseconds (a constant). Range

of applicable constants depends on the oscillator frequency.

Example Delay_us(10); // Ten microseconds pause

Delay_ms

Prototype procedure Delay_ms(const time_in_ms : word);

Description Creates a software delay in duration of time_in_ms milliseconds (a constant). Range of

applicable constants depends on the oscillator frequency.

Example Delay_ms(1000); // One second pause

page
mikroElektronika: Development tools - Books - Compilers
281
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Vdelay_ms

Prototype procedure Vdelay_ms(time_in_ms : word);

Description Creates a software delay in duration of time_in_ms milliseconds (a variable).

Generated delay is not as precise as the delay created by Delay_ms.

Example pause := 1000;

// ...
Vdelay_ms(pause); // ~ one second pause

Delay_Cyc

Prototype procedure Delay_Cyc(cycles_div_by_10 : byte);

Description Creates a delay based on MCU clock. Delay lasts for 10 times the input parameter in
MCU cycles. Input parameter needs to be in range 3 .. 255.

Note that Delay_Cyc is library function rather than a built-in routine; it is presented in
this topic for the sake of convenience.

Example Delay_Cyc(10); // Hundred MCU cycles pause

page

282
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Math Library
Math Library implements a number of common mathematical functions.

Library Routines

Acos
Asin
Atan
Atan2
Ceil
Cos
CosE3
Cosh
Exp
Fabs
Floor
Frexp
Fmod
Ldexp
Log
Log10
Modf
Pow
Sin
SinE3
Sinh
Sqrt
Tan
Tanh

page
mikroElektronika: Development tools - Books - Compilers
283
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Acos

Prototype function Acos(x : real) : real;

Description Function returns the arc cosine of parameter x; that is, the value whose cosine is x.
Input parameter x must be between -1 and 1 (inclusive). The return value is in radians,
between 0 and pi (inclusive).

Asin

Prototype function Asin(x : real) : real;

Description Function returns the arc sine of parameter x; that is, the value whose sine is x. Input
parameter x must be between -1 and 1 (inclusive). The return value is in radians,
between -pi/2 and pi/2 (inclusive).

Atan

Prototype function Atan(x : real) : real;

Description Function computes the arc tangent of parameter x; that is, the value whose tangent is x.
The return value is in radians, between -pi/2 and pi/2 (inclusive).

Atan2

Prototype function Atan2(x, y : real) : real;

Description This is the two argument arc tangent function. It is similar to computing the arc tangent
of y/x, except that the signs of both arguments are used to determine the quadrant of
the result, and x is permitted to be zero. The return value is in radians, between -pi and
pi (inclusive).

page

284
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Ceil

Prototype function Ceil(x : real) : real;

Description Function returns value of parameter x rounded up to the next whole number.

Cos

Prototype function Cos(x : real) : real;

Description Function returns the cosine of x in radians. The return value is from -1 to 1.

CosE3

Prototype function CosE3(x : word) : integer;

Description Function takes parameter x which represents angle in degrees, and returns its cosine
multiplied by 1000 and rounded up to the nearest integer:

result := round_up(cos(x)*1000)

The function is implemented as a lookup table; maximum error obtained is ±1.

Cosh

Prototype function Cosh(x : real) : real;

Description Function returns the hyperbolic cosine of x, defined mathematically as (ex+e-x)/2. If

the value of x is too large (if overflow occurs), the function fails.

page
mikroElektronika: Development tools - Books - Compilers
285
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Exp

Prototype function Exp(x : real) : real;

Description Function returns the value of e — the base of natural logarithms — raised to the power
of x (i.e. ex).

Fabs

Prototype function Fabs(x : real) : real;

Description Function returns the absolute (i.e. positive) value of x.

Floor

Prototype function Floor(x : real) : real;

Description Function returns value of parameter x rounded down to the nearest integer.

Fmod

Prototype function Fmod(x, y : real) : real;

Description Function computes the floating point remainder of x/y. Function returns the value
x - i * y for some integer i such that, if y is nonzero, the result has the same sign as
x and magnitude less then the magnitude of y. If v is zero, the fmod function returns
zero.

page

286
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Frexp

Prototype function Frexp(num : real; n : ^integer) : real;

Description Function splits a floating-point value num into a normalized fraction and an integral
power of 2. Return value is the normalized fraction, and the integer exponent is stored in
the object pointed to by n.

Ldexp

Prototype function Ldexp(num : real; n : integer) : real;

Description Function returns the result of multiplying the floating-point number num by 2 raised to
the power n (i.e. returns x * 2n).

Log

Prototype function Log(x : real) : real;

Description Function returns the natural logarithm of x (i.e. loge(x)).

Log10

Prototype function Log10(x : real) : real;

Description Function returns the base-10 logarithm of x (i.e. log10(x)).

page
mikroElektronika: Development tools - Books - Compilers
287
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Modf

Prototype function Modf(num : real; whole : ^real) : real;

Description Function returns the signed fractional component of num, placing its whole number
component into the variable pointed to by whole.

Pow

Prototype function Pow(x, y: real) : real;

Description Function returns the value of x raised to the power of y (i.e. xy). If the x is negative,
function will automatically cast the y into longint.

Sin

Prototype function Sin(x : real) : real;

Description Function returns the sine of x in radians. The return value is from -1 to 1.

SinE3

Prototype function SinE3(x : word) : integer;

Description Function takes parameter x which represents angle in degrees, and returns its sine multi-
plied by 1000 and rounded up to the nearest integer:

result := round_up(sin(x)*1000)

The function is implemented as a lookup table; maximum error obtained is ±1.

page

288
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Sinh

Prototype function Sinh(x : real) : real;

Description Function returns the hyperbolic sine of x, defined mathematically as (ex-e-x)/2. If the
value of x is too large (if overflow occurs), the function fails.

Sqrt

Prototype function Sqrt(x : real) : real;

Description Function returns the non negative square root of num.

Tan

Prototype function Tan(x : real) : real;

Description Function returns the tangent of x in radians. The return value spans the allowed range of
floating point in mikroPascal.

Tanh

Prototype function Tanh(x : real) : real;

Description Function returns the hyperbolic tangent of x, defined mathematically as

sinh(x)/cosh(x).

page
mikroElektronika: Development tools - Books - Compilers
289
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

String Library
The String Library provides a number of routines for string handling.

Library Routines

Memchr
Memcmp
Memcpy
Memmove
Memset
Strcat
Strchr
Strcmp
Strcpy
Strcspn
Strlen
Strncat
Strncmp
Strncpy
Strpbrk
Strrchr
Strspn
Strstr
strAppendSuf
strAppendPre

page

290
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Memchr

Prototype function Memchr(p : word; ch : char; n : word) : word;

Description Function locates the first occurrence of byte ch in the initial n bytes of memory area
starting at the address p. Function returns the offset of this occurrence from the memory
address p or $FFFF if the character was not found.

For parameter p you can use either a numerical value (literal/variable/constant) indicat-
ing memory address or a dereferenced value of an object, for example @mystring or
@PORTB.

Memcmp

Prototype function Memcmp(p1, p2, n : word) : integer;

Description Function returns a positive, negative, or zero value indicating the relationship of first n
bytes of memory areas starting at addresses p1 and p2.

The Memcmp function compares two memory areas starting at addresses p1 and p2 for n
bytes and returns a value indicating their relationship as follows:

Value Meaning
<0 p1 "less than" p2
=0 p1 "equal to" p2
>0 p1 "greater than" p2

The value returned by function is determined by the difference between the values of the
first pair of bytes that differ in the strings being compared.

For parameters p1 and p2 you can use either a numerical value (literal/variable/con-
stant) indicating memory address or a dereferenced value of an object, for example
@mystring or @PORTB.

page
mikroElektronika: Development tools - Books - Compilers
291
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Memcpy

Prototype procedure Memcpy(p1, p2, n : word);

Description Function copies n bytes from the memory area starting at the address p2 to the memory
area starting at p1. If these memory buffers overlap, the memcpy function cannot guar-
antee that bytes are copied before being overwritten. If these buffers do overlap, use the
Memmove function.

For parameters p1 and p2 you can use either a numerical value (literal/variable/con-
stant) indicating memory address or a dereferenced value of an object, for example
@mystring or @PORTB.

Memmove

Prototype procedure Memmove(p1, p2, n : word);

Description Function copies n bytes from the memory area starting at the address p2 to the memory
area starting at p1. If these memory buffers overlap, the Memmove function ensures that
bytes in p2 are copied to p1 before being overwritten.

For parameters p1 and p2 you can use either a numerical value (literal/variable/con-
stant) indicating memory address or a dereferenced value of an object, for example
@mystring or @PORTB.

Memset

Prototype procedure Memset(p : word; ch : char; n : word);

Description Function fills the first n bytes in the memory area starting at the address p with the
value of byte ch.

For parameter p you can use either a numerical value (literal/variable/constant) indicat-
ing memory address or a dereferenced value of an object, for example @mystring or
@PORTB.

page

292
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Strcat

Prototype procedure Strcat(var s1, s2 : string[100]);

Description Function appends the value of string s2 to string s1 and terminates s1 with a null char-
acter.

Strchr

Prototype function Strchr(var s : string[100]; ch : char) : byte;

Description Function searches the string s for the first occurrence of the character ch. The null char-
acter terminating s is not included in the search.

Function returns the position (index) of the first character ch found in s; if no matching
character was found, function returns $FF.

Strcmp

Prototype function Strcmp(var s1, s2 : string[100]) : integer;

Description Function lexicographically compares the contents of strings s1 and s2 and returns a
value indicating their relationship:

Value Meaning
<0 s1 "less than" s2
=0 s1 "equal to" s2
>0 s1 "greater than" s2

The value returned by function is determined by the difference between the values of the
first pair of bytes that differ in the strings being compared.

page
mikroElektronika: Development tools - Books - Compilers
293
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Strcpy

Prototype procedure Strcpy(var s1, s2 : string[100]);

Description Function copies the value of string s2 to the string s1 and appends a null character to
the end of s1.

Strcspn

Prototype function Strcspn(var s1, s2 : string[100]) : byte;

Description The strcspn function computes the length of the maximum initial segment of the string
pointed to by s1 which consists entirely of characters not from the string pointed to by
s2. Function returns the length of the segment.

Strlen

Prototype function Strlen(var s : string[100]) : byte;

Description Function returns the length, in bytes, of the string s. The length does not include the null
terminating character.

page

294
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Strncat

Prototype procedure Strncat(var s1, s2 : string[100]; n : byte);

Description Function appends at most n characters from the string s2 to the string s1 and terminates
s1 with a null character. If s2 is shorter than n characters, s2 is copied up to and
including the null terminating character.

Strncmp

Prototype function Strncmp(var s1, s2 : string[100]; n : byte) : integer;

Description Function lexicographically compares the first n bytes of the strings s1 and s2 and
returns a value indicating their relationship:

Value Meaning
<0 s1 "less than" s2
=0 s1 "equal to" s2
>0 s1 "greater than" s2

The value returned by function is determined by the difference between the values of the
first pair of bytes that differ in the strings being compared (within first n bytes).

Strncpy

Prototype procedure Strncpy(var s1, s2 : string[100]; n : byte);

Description Function copies at most n characters from the string s2 to the string s1. If s2 contains
fewer characters than n, s1 is padded out with null characters up to the total length of n
characters.

page
mikroElektronika: Development tools - Books - Compilers
295
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Strpbrk

Prototype procedure Strpbrk(var s1, s2 : string[100]);

Description Function searches s1 for the first occurrence of any character from the string s2. The
null terminator is not included in the search. Function returns an index of the matching
character in s1. If s1 contains no characters from s2, function returns $FF.

Strrchr

Prototype procedure Strrchr(var s : string[100]; ch : byte);

Description Function searches the string s for the last occurrence of character ch. The null character
terminating s is not included in the search. Function returns an index of the last
ch found in s; if no matching character was found, function returns $FF.

Strspn

Prototype function Strspn(var s1, s2 : string[100]) : byte;

Description The strspn function computes the length of the maximum initial segment of the string
pointed to by s1 which consists entirely of the characters from the string pointed to by
s2. Function returns the length of the segment.

page

296
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Strstr

Prototype function Strstr(var s1, s2 : string[100]) : byte;

Description Function locates the first occurrence of the string s2 in the string s1 (excluding the ter-
minating null character). Function returns a number indicating the position of the first
occurrence of s2 in s1; if no string was found, function returns $FF. If s2 is a null
string, the function returns 0.

strAppendSuf

Prototype procedure strAppendSuf(var s1: string[100]; letter: char);

Description Adds suffix(letter) to string (s1).

Example txt:= '123';

strAppendSuf(txt,'4');
// txt = '1234'

strAppendPre

Prototype procedure strAppendPre(letter: char; var s1: string[100]);

Description Adds preffix(letter) to string (s1).

Example txt:= '123';

strAppendPre('0',txt);
// txt = '0123'

page
mikroElektronika: Development tools - Books - Compilers
297
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Port Expander Library

The SPI Expander Library facilitates working with MCP23S17, Microchip’s SPI
port expander. The chip connects to the PIC according to the scheme presented
below.
Note: PIC need to have a hardware SPI module.
Note: SPI_Init; must be called before initializing Port Expander.

Library Routines

Expander_Init
PortExpanderSelect
PortExpanderUnSelect
Expander_Read_Byte
Expander_Write_Byte
Expander_Set_Mode
Expander_Read_Array
Expander_Write_Array
Expander_Read_PortA
Expander_Read_PortB
Expander_Read_ArrayPortA
Expander_Read_ArrayPortB
Expander_Write_PortA
Expander_Write_PortB
Expander_Set_DirectionPortA
Expander_Set_DirectionPortB
Expander_Set_PullUpsPortA
Expander_Set_PullUpsPortB

Expander_Init

Prototype procedure Expander_Init(var RstPort : byte; RstPin : byte; var

CSPort : byte; CSPin, ModuleAddress : byte);

Description Establishes SPI communication with the expander and initializes the expander. RstPort
and RstPin - Sets pin connected on reset pin of spi expander. CSPort and CSPin - Sets
pin connected on CS pin of spi expander. moduleaddress - address of spi expander
(hardware setting of A0, A1 and A2 pins (connected on VCC or GND) on spi expander).

Requires This procedure needs to be called before using other routines of PORT Expander library.
SPI_Init; must be called before initializing Port Expander.

Example Expander_Init(PORTC, 0, PORTC, 1, 0);

page

298
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

PortExpanderSelect

Prototype procedure PortExpanderSelect;

Description Selects current port expander.

Requires PORT Expander must be initialized. See Expander_Init.

Example PortExpanderSelect;

PortExpanderUnSelect

Prototype procedure PortExpanderUnSelect;

Description Un-Selects current port expader.

Requires PORT Expander must be initialized. See Expander_Init.

Example PortExpanderUnSelect;

Expander_Read_Byte

Prototype function Expander_Read_Byte(ModuleAddress, RegAddress : byte) :

byte;

Returns Byte read from port expander.

Description Function reads byte from port expander on ModuleAddress and port on RegAddress.
Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Read_Byte(0,1);

Expander_Write_Byte
Prototype procedure Expander_Write_Byte(ModuleAddress, RegAddress, Data :
byte);

Returns Nothing.
Description This routine writes data to port expander on ModuleAddress and port on
RegAddress.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Write_Byte(0,1,$FF);

page
mikroElektronika: Development tools - Books - Compilers
299
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Expander_Set_Mode
Prototype procedure Expander_Set_Mode(ModuleAddress, Mode : byte);

Returns Nothing.
Description Sets port expander mode on ModuleAddress.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Set_Mode(1,0);

Expander_Read_ArrayPortA
Prototype procedure Expander_Read_ArrayPortA(ModuleAddress, NoBytes : byte;
var DestArray : array[100] of byte);

Returns Nothing.
Description This routine reads array of bytes (DestArray) from port expander on ModuleAddress
and portA. NoBytes represents number of read bytes.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Read_PortA(0,1,data);

Expander_Read_Array
Prototype procedure Expander_Read_Array(ModuleAddress, StartAddress,
NoBytes : byte; var DestArray : array[100] of byte);

Returns Nothing.
Description This routine reads array of bytes (DestArray) from port expander on ModuleAddress
and StartAddress. NoBytes represents number of read bytes.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Read_Array(1,1,5,data);

page

300
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Expander_Write_Array
Prototype procedure Expander_Write_Array(ModuleAddress, StartAddress,
NoBytes : byte; var SourceArray : array[100] of byte);

Returns Nothing.
Description This routine writes array of bytes (DestArray) to port expander on ModuleAddress
and StartAddress. NoBytes represents number of read bytes.
Requires PORT Expander must be initialized. See Expander_Init.
Example Expander_Write_Array(1,1,5,data);

Expander_Read_PortA
Prototype function Expander_Read_PortA(Address : byte) : byte;

Returns Read byte.

Description This routine reads byte from port expander on Address and PortA.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Read_PortA(1);

Expander_Read_Array
Prototype procedure Expander_Read_Array(ModuleAddress, StartAddress,
NoBytes : byte; var DestArray : array[100] of byte);

Returns Read byte.

Description This routine reads byte from port expander on Address and PortB.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Read_Array(1,1,5,data);

page
mikroElektronika: Development tools - Books - Compilers
301
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Expander_Read_ArrayPortB
Prototype procedure Expander_Read_ArrayPortB(ModuleAddress, NoBytes : byte;
var DestArray : array[100] of byte);

Returns Nothing.
Description This routine reads array of bytes (DestArray) from port expander on ModuleAddress
and portB. NoBytes represents number of read bytes.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Read_PortB(0,8,data);

Expander_Write_PortA
Prototype procedure Expander_Write_PortA(ModuleAddress, Data : byte);

Returns Nothing.
Description This routine writes byte to port expander on ModuleAddress and portA.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_write_PortA(3,$FF);

Expander_Write_PortB
Prototype procedure Expander_Write_PortB(ModuleAddress, Data : byte);

Returns Nothing.
Description This routine writes byte to port expander on ModuleAddress and portB.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_write_PortB(2,$FF);

page

302
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Expander_Set_DirectionPortA
Prototype procedure Expander_Set_DirectionPortA(ModuleAddress, Data :
byte);

Description Set port expander PortA pin as input or output.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Set_DirectionPortA(0,$FF);

Expander_Set_DirectionPortB
Prototype procedure Expander_Set_DirectionPortB(ModuleAddress, Data :
byte);

Description Set port expander PortB pin as input or output.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Set_DirectionPortB(0,$FF);

Expander_Set_PullUpsPortA
Prototype procedure Expander_Set_PullUpsPortA(ModuleAddress, Data : byte);

Description This routine sets port expander PortA pin as pullup or pulldown.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Set_PullUpsPortA(0,$FF);

Expander_Set_PullUpsPortB
Prototype procedure Expander_Set_PullUpsPortB(ModuleAddress, Data : byte);

Description This routine sets port expander PortB pin as pullup or pulldown.

Requires PORT Expander must be initialized. See Expander_Init.

Example Expander_Set_PullUpsPortB(0,$FF);

page
mikroElektronika: Development tools - Books - Compilers
303
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example
The example demonstrates how to communicate to port expander MCP23S17.

program PortExpander;

var i : byte;

begin
ADCON1 := ADCON1 or 0x0f;
TRISB := 0x00;
PORTB := 0xFF;
Delay_ms(200);

Spi_Init; // initialize SPI

Expander_Init(PORTC, 0, PORTC, 1, 0);

// initialize port expander

Expander_Set_DirectionPortA(0, 0);

// set expander's porta to be output

Expander_Set_DirectionPortB(0,0xFF);

// set expander's porta to be input

Expander_Set_PullUpsPortB(0,0xFF);

// set pull ups to all of the expander's portb pins

i := 0;
while 1 do
begin
Expander_Write_PortA(0, i);

// write i to expander's porta

i := i + 1;
PORTB := Expander_Read_PortB(0);

// read expander's portb and write it to PIC's PORTB

Delay_ms(20);
end;
end.

page

304
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

MCP23S17
1 28
GPB0 GPA7
2 27
GPB1 GPA6
3 26
GPB2 GPA5
4 25
GPB3 GPA4

PIC18F452
5 24
GPB4 GPA3
6 23
GPB5 GPA2
7 22
GPB6 GPA1
8 21 VCC
GPB7 GPA0
VCC

9 20
VDD INTA 11
10 19 VCC
12
VSS INTB GND
RC1 11 18 RC0 13
CS RESET OSC1
RC3 12 17 14
SCK A2 OSC2
RC5 13 16 15
SI A1 RC0
8 Mhz 16
RC4 14 15 RC1
SO A0 24
RC5
18 23
RC3 RC4

1 2 1 2
3 4 3 4
5 6 5 6
7 8 7 8
9 10 9 10

PORTB PORTA
VCC VCC

page
mikroElektronika: Development tools - Books - Compilers
305
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

SPI Graphic LCD Library

mikroPascal provides a library for operating the Graphic LCD 128x64 via SPI.
These routines work with the common GLCD 128x64 (samsung ks0108).

Note: Spi_Init; must be called before initializing SPI GLCD.

Library Routines

Basic routines:

Spi_Glcd_Init
Spi_Glcd_Set_Side
Spi_Glcd_Set_Page
Spi_Glcd_Set_X
Spi_Glcd_Read_Data
Spi_Glcd_Write_Data

Advanced routines:

Spi_Glcd_Fill
Spi_Glcd_Dot
Spi_Glcd_Line
Spi_Glcd_V_Line
Spi_Glcd_H_Line
Spi_Glcd_Rectangle
Spi_Glcd_Box
Spi_Glcd_Circle
Spi_Glcd_Set_Font
Spi_Glcd_Write_Char
Spi_Glcd_Write_Text
Spi_Glcd_Image

page

306
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Glcd_Init

Prototype procedure Spi_Glcd_Init(var RstPort : byte; RstPin : byte; var

CSPort : byte; CSPin, DeviceAddress : byte);

Description Initializes Graphic LCD 128x64 via SPI. RstPort and RstPin - Sets pin connected on
reset pin of spi expander. CSPort and CSPin - Sets pin connected on CS pin of spi
expander. device address - address of spi expander (hardware setting of A0, A1 and
A2 pins (connected on VCC or GND) on spi expander).
Requires This procedure needs to be called before using other routines of SPI GLCD library.
Spi_Init; must be called before initializing SPI GLCD.

Example Spi_Glcd_Init(PORTC, 0, PORTC, 1, 0);

Spi_Glcd_Set_Side

Prototype procedure Spi_Glcd_Set_Side(x : byte);

Description Selects side of GLCD, left or right. Parameter x specifies the side: values from 0 to 63
specify the left side, and values higher than 64 specify the right side. Use the functions
Spi_Glcd_Set_Side, Spi_Glcd_Set_X, and Spi_Glcd_Set_Page to specify an
exact position on GLCD. Then, you can use Spi_Glcd_Write_Data or
Spi_Glcd_Read_Data on that location.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Set_Side(0); // Select the left side of GLCD

page
mikroElektronika: Development tools - Books - Compilers
307
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_Glcd_Set_Page

Prototype procedure Spi_Glcd_Set_Page(page : byte);

Description Selects page of GLCD, technically a line on display; parameter page can be 0..7.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Set_Page(5);

Spi_Glcd_Set_X

Prototype procedure Spi_Glcd_Set_X(x : byte);

Description Positions to x dots from the left border of GLCD within the given page.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Set_X(25);

Spi_Glcd_Read_Data

Prototype function Spi_Glcd_Read_Data : byte;

Returns One word from the GLCD memory.

Description Reads data from from the current location of GLCD memory. Use the functions
Spi_Glcd_Set_Side, Spi_Glcd_Set_X, and Spi_Glcd_Set_Page to specify an
exact position on GLCD. Then, you can use Spi_Glcd_Write_Data or
Spi_Glcd_Read_Data on that location.

Requires Reads data from from the current location of GLCD memory.

Example tmp := Spi_Glcd_Read_Data;

page

308
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Glcd_Write_Data

Prototype procedure Spi_Glcd_Write_Data(data : byte);

Description Writes data to the current location in GLCD memory and moves to the next location.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Write_Data(data);

Spi_Glcd_Fill

Prototype procedure Spi_Glcd_Fill(pattern : byte);

Description Fills the GLCD memory with byte pattern. To clear the GLCD screen, use
Spi_Glcd_Fill(0); to fill the screen completely, use Spi_Glcd_Fill($FF).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Fill(0); // Clear screen

Spi_Glcd_Dot

Prototype procedure Spi_Glcd_Dot(x, y, color : byte);

Description Draws a dot on the GLCD at coordinates (x, y). Parameter color determines the dot
state: 0 clears dot, 1 puts a dot, and 2 inverts dot state.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Dot(0, 0, 2); // Invert the dot in the upper left corner

page
mikroElektronika: Development tools - Books - Compilers
309
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_Glcd_Line

Prototype procedure Spi_Glcd_Line(x1, y1, x2, y2, color : byte);

Description Draws a line on the GLCD from (x1, y1) to (x2, y2). Parameter color determines
the dot state: 0 draws an empty line (clear dots), 1 draws a full line (put dots), and 2
draws a “smart” line (invert each dot).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Line(0, 63, 50, 0, 2);

Spi_Glcd_V_Line

Prototype procedure Spi_Glcd_V_Line(y1, y2, x, color : byte);

Description Similar to GLcd_Line, draws a vertical line on the GLCD from (x, y1) to
(x, y2).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_V_Line(0, 63, 0, 1);

Spi_Glcd_H_Line

Prototype procedure Spi_Glcd_H_Line(x1, x2, y, color : byte);

Description Similar to GLcd_Line, draws a horizontal line on the GLCD from (x1, y) to
(x2, y).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_H_Line(0, 127, 0, 1);

page

310
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Glcd_Rectangle

Prototype procedure Spi_Glcd_Rectangle(x1, y1, x2, y2, color : byte);

Description Draws a rectangle on the GLCD. Parameters (x1, y1) set the upper left corner,
(x2, y2) set the bottom right corner. Parameter color defines the border: 0 draws an
empty border (clear dots), 1 draws a solid border (put dots), and 2 draws a “smart” bor-
der (invert each dot).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Rectangle(10, 0, 30, 35, 1);

Spi_Glcd_Box

Prototype procedure Spi_Glcd_Box(x1, y1, x2, y2, color : byte);

Description Draws a box on the GLCD. Parameters (x1, y1) set the upper left corner, (x2, y2)
set the bottom right corner. Parameter color defines the fill: 0 draws a white box (clear
dots), 1 draws a full box (put dots), and 2 draws an inverted box (invert each dot).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Box(10, 0, 30, 35, 1);

Spi_Glcd_Circle

Prototype procedure Spi_Glcd_Circle(x, y, radius, color : integer);

Description Draws a circle on the GLCD, centered at (x, y) with radius. Parameter color defines the
circle line: 0 draws an empty line (clear dots), 1 draws a solid line (put dots), and 2
draws a “smart” line (invert each dot).

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Circle(63, 31, 25, 1);

page
mikroElektronika: Development tools - Books - Compilers
311
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_Glcd_Set_Font

Prototype procedure Spi_Glcd_Set_Font(font_address : longint; font_width,

font_height : byte; font_offset : word);

Description Sets the font for text display routines, Spi_Glcd_Write_Char and
Spi_Glcd_Write_Text. Font needs to be formatted as an array of byte. Parameter
font_address specifies the address of the font; you can pass a font name with the @
operator. Parameters font_width and font_height specify the width and height of
characters in dots. Font width should not exceed 128 dots, and font height should not
exceed 8 dots. Parameter font_offset determines the ASCII character from which the
supplied font starts. Demo fonts supplied with the library have an offset of 32, which
means that they start with space.

If no font is specified, Spi_Glcd_Write_Char and Spi_Glcd_Write_Text will use

the default 5x8 font supplied with the library. You can create your own fonts by follow-
ing the guidelines given in the file “GLCD_Fonts.dpas”. This file contains the default
fonts for GLCD, and is located in your installation folder, “Extra Examples” > “GLCD”.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example // Use the custom 5x7 font "myfont" which starts with space (32):
Spi_Glcd_Set_Font(@myfont, 5, 7, 32);

Spi_Glcd_Write_Char

Prototype procedure Spi_Glcd_Write_Char(character, x, page, color : byte);

Description Prints character at page (one of 8 GLCD lines, 0..7), x dots away from the left border of
display. Parameter color defines the “fill”: 0 writes a “white” letter (clear dots), 1 writes
a solid letter (put dots), and 2 writes a “smart” letter (invert each dot).

Use routine Spi_Glcd_Set_Font to specify font, or the default 5x7 font (included
with the library) will be used.

Requires GLCD needs to be initialized, see Spi_Glcd_Init. Use the Spi_Glcd_Set_Font to

specify the font for display; if no font is specified, the default 5x8 font supplied with the
library will be used.

Example Spi_Glcd_Write_Char('C', 0, 0, 1);

page

312
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Glcd_Write_Text

Prototype procedure Spi_Glcd_Write_Text(text : string[20]; x, page, color :

byte);

Description Prints text at page (one of 8 GLCD lines, 0..7), x dots away from the left border of
display. Parameter color defines the “fill”: 0 prints a “white” letters (clear dots), 1
prints solid letters (put dots), and 2 prints “smart” letters (invert each dot).

Use routine Spi_Glcd_Set_Font to specify font, or the default 5x7 font (included
with the library) will be used.

Requires GLCD needs to be initialized, see Spi_Glcd_Init. Use the Spi_Glcd_Set_Font to

specify the font for display; if no font is specified, the default 5x8 font supplied with the
library will be used.

Example Spi_Glcd_Write_Text('Hello world!', 0, 0, 1);

Spi_Glcd_Image

Prototype procedure Spi_Glcd_Image(image : array[0..1023] of byte);

Description Displays bitmap image on the GLCD. Parameter image should be formatted as an array
of 1024 bytes. Use the mikroPascal’s integrated Bitmap-to-LCD editor (menu option
Tools > Graphic LCD Editor) to convert image to a constant array suitable for display
on GLCD.

Requires GLCD needs to be initialized. See Spi_Glcd_Init.

Example Spi_Glcd_Image(my_image);

page
mikroElektronika: Development tools - Books - Compilers
313
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Library Example

The example demonstrates how to communicate to KS0108 GLCD via SPI module, using serial to
parallel convertor MCP23S17.
program SerialGLCD;

uses images;

var
ii: byte;
someText: string[20];

procedure delay2S;
begin
delay_ms(2000);
end;

begin
//delay2S;

Spi_Init; // initialize SPI

Spi_Glcd_Init(PORTC, 0, PORTC, 1, 0);

Spi_Glcd_Fill(0xAA);
delay2S;
while TRUE do
begin
Spi_Glcd_Fill(0x00);
Spi_Glcd_Image(truck_bmp);
delay2S;

Spi_Glcd_Fill(0x00);
for ii := 1 to 40 do
Spi_Glcd_Dot(ii, ii, 1);
delay2S;

Spi_Glcd_Fill(0x00);
Spi_Glcd_Line(120, 1, 5,60, 1);
delay2S;
Spi_Glcd_Line(12, 42, 5,60, 1);
delay2S;

Spi_Glcd_Rectangle(12, 20, 93,57, 1);

delay2S;

//continues..

page

314
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

//continues..

Spi_Glcd_Line(120, 12, 12,60, 1);

delay2S;

Spi_Glcd_H_Line(5, 15, 6, 1);

Spi_Glcd_Line(0, 12, 120, 60, 1);
Spi_Glcd_V_Line(7, 63, 127, 1);
delay2S;

for ii := 1 to 10 do
Spi_Glcd_Circle(63, 32, 3*ii, 1);

delay2S;
Spi_Glcd_Box(12, 20, 70, 57, 2);
delay2S;

Spi_Glcd_Fill(0x00);

Spi_Glcd_Set_Font(@System3x6, 3, 6, 32);
someText := 'SMALL FONT: 3X6';
Spi_Glcd_Write_Text(someText, 20, 5, 1);

Spi_Glcd_Set_Font(@FontSystem5x8, 5, 8, 32);
someText := 'Large Font 5x8';
Spi_Glcd_Write_Text(someText, 3, 4, 1);
delay2S;
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
315
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection MCP23S17

D0 1 28
GPB0 GPA7
D1 2 27
GPB1 GPA6
D2 3 26 RST
GPB2 GPA5
D3 4 25 E
GPB3 GPA4

PIC18F452
D4 5 24 RW
GPB4 GPA3
D5 6 23 RS
GPB5 GPA2
D6 7 22 CS2
GPB6 GPA1
D7 8 21 CS1 VCC
GPB7 GPA0
VCC

9 20
VDD INTA 11
10 19 VCC
12
VSS INTB GND
RC1 11 18 RC0 13
CS RESET OSC1
RC3 12 17 14
SCK A2 OSC2
RC5 13 16 15
SI A1 RC0
8 Mhz 16
RC4 14 15 RC1
SO A0 24
RC5
18 23
RC3 RC4

Vee

Contrast
Adjustment
VCC VCC

P1 Vo
5K

1 20
LED+
GND
VCC
RS

RST
D6
D5
CS1

D0
D2

D7
R/W

D1
D3
D4
CS2

Vo

LED-
Vee
E

mikroElektronika
EasyPIC3
Development system

page

316
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SPI LCD Library (4-bit interface)

mikroPascal provides a library for communicating with commonly used LCD (4-
bit interface) via SPI interface. Figures showing HW connection of PIC and SPI
LCD are given at the end of the chapter.

Note: Spi_Init; must be called before initializing SPI LCD.

Library Routines

Spi_Lcd_Config
Spi_Lcd_Init
Spi_Lcd_Out
Spi_Lcd_Out_Cp
Spi_Lcd_Chr
Spi_Lcd_Chr_Cp
Spi_Lcd_Cmd

Spi_Lcd_Config

Prototype procedure Spi_Lcd_Config(DeviceAddress : byte; var rstport :

byte; rstpin : byte; var csport : byte; cspin : byte);

Description Initializes LCD via SPI interface with pin settings (Reset pin and Chip Select pin) you
specify.

Requires Spi_Init; must be called before initializing SPI LCD.

Example Spi_Lcd_Config(0,PORTB, 1, PORTB, 0);

page
mikroElektronika: Development tools - Books - Compilers
317
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_Lcd_Init

Prototype procedure Spi_Lcd_Init;

Description Initializes LCD at port with default pin settings (see the connection scheme at the end
of the chapter).

Requires Spi_Init; must be called before initializing SPI LCD.

Example Spi_Lcd_Init;

Spi_Lcd_Out

Prototype procedure Spi_Lcd_Out;

Description Prints text on LCD at specified row and column (parameters row and col). Both string
variables and literals can be passed as text.

Requires Port with LCD must be initialized. See Spi_Lcd_Config or Spi_Lcd_Init.

Example Spi_Lcd_Out(1, 3, 'Hello!');

Spi_Lcd_Out_Cp

Prototype procedure Spi_Lcd_Out_CP(var text : string[40]);

Description Prints text on LCD at current cursor position. Both string variables and literals can be
passed as text.

Requires Port with LCD must be initialized. See Spi_Lcd_Config or Spi_Lcd_Init.

Example Spi_Lcd_Out_Cp('Here!'); // Print "Here!" at current cursor posi-

tion

page

318
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Lcd_Chr

Prototype procedure Spi_Lcd_Chr(Row, Column, Out_Char : byte);

Description Prints character on LCD at specified row and column (parameters row and col).
Both variables and literals can be passed as character.

Requires Port with LCD must be initialized. See Spi_Lcd_Config or Spi_Lcd_Init.

Example Spi_Lcd_Chr(2, 3, 'i');

Spi_Lcd_Chr_Cp

Prototype procedure Spi_Lcd_Chr_Cp(character : byte);

Description Prints character on LCD at current cursor position. Both variables and literals can be
passed as character.

Requires Port with LCD must be initialized. See Spi_Lcd_Config or Spi_Lcd_Init.

Example Spi_Lcd_Chr_Cp('e'); // Print "e" at current cursor position

Spi_Lcd_Cmd

Prototype procedure Spi_Lcd_Cmd(command : byte);

Description Sends command to LCD. You can pass one of the predefined constants to the function.
The complete list of available commands is shown below.

Requires Port with LCD must be initialized. See Spi_Lcd_Config or Spi_Lcd_Init.

Example Spi_Lcd_Cmd(LCD_Clear); // Clear LCD display

page
mikroElektronika: Development tools - Books - Compilers
319
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

LCD Commands
LCD Command Purpose

LCD_FIRST_ROW Move cursor to 1st row

LCD_SECOND_ROW Move cursor to 2nd row

LCD_THIRD_ROW Move cursor to 3rd row

LCD_FOURTH_ROW Move cursor to 4th row

LCD_CLEAR Clear display

Return cursor to home position, returns a shifted display to original posi-

LCD_RETURN_HOME
tion. Display data RAM is unaffected.
LCD_CURSOR_OFF Turn off cursor

LCD_UNDERLINE_ON Underline cursor on

LCD_BLINK_CURSOR_ON Blink cursor on

LCD_MOVE_CURSOR_LEFT Move cursor left without changing display data RAM

Lcd_Move_Cursor_Right Move cursor right without changing display data RAM

LCD_TURN_ON Turn LCD display on

LCD_TURN_OFF Turn LCD display off

LCD_SHIFT_LEFT Shift display left without changing display data RAM

LCD_SHIFT_RIGHT Shift display right without changing display data RAM

Library Example (default pin settings)

program Spi_Lcd_demo;

begin
SPI_init(); // initialize SPI communication
Spi_Lcd_Init(); // initialize lcd via SPI interface
Spi_Lcd_Cmd(Lcd_CLEAR); // send command to LCD "clear display"
Spi_Lcd_Cmd(Lcd_CURSOR_OFF); // send command cursor off
Spi_Lcd_Out(2, 1, 'mikroElektronika'); // print txt to LCD, 2nd row, 1st column
Spi_Lcd_Out(1, 5, 'mikroE'); // print txt to LCD, 1st row, 5th column
Spi_Lcd_Out(3, 1, 'mikroE');
// print txt to LCD, 3rd row, 1st column, for lcd's with more than two rows
Spi_Lcd_Out(4, 10, 'mikroE');
// print txt to LCD, 4th row, 10th column, for lcd's with more than two rows
end.

page

320
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Hardware Connection

MCP23S17
1 28
GPB0 GPA7
2 27
GPB1 GPA6
RS 3 26
GPB2 GPA5
E 4 25
GPB3 GPA4

PIC18F452
D4 5 24
GPB4 GPA3
D5 6 23
GPB5 GPA2
D6 7 22
GPB6 GPA1
D7 8 21 VCC
GPB7 GPA0
VCC

9 20
VDD INTA 11
10 19 VCC
12
VSS INTB GND
RC1 11 18 RC0 13
CS RESET OSC1
RC3 12 17 14
SCK A2 OSC2
RC5 13 16 15
SI A1 RC0
8 Mhz 16
RC4 14 15 RC1
SO A0 24
RC5
18 23
RC3 RC4

VCC

Contrast
P4 Adjustment
5K

1 14
D1
GND
VCC
VEE
RS

E
D0

D2
D3

D7
D6
D5
D4
R/W

page
mikroElektronika: Development tools - Books - Compilers
321
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

SPI LCD8 (8-bit interface) Library

mikroPascal provides a library for communicating with commonly used 8-bit
interface LCD (with Hitachi HD44780 controller) via SPI Interface. Figures show-
ing HW connection of PIC and SPI LCD are given at the end of the chapter.

Note: Spi_Init; must be called before initializing SPI LCD8.

Library Routines

Spi_Lcd8_Config
Spi_Lcd8_Init
Spi_Lcd8_Out
Spi_Lcd8_Out_Cp
Spi_Lcd8_Chr
Spi_Lcd8_Chr_Cp
Spi_Lcd8_Cmd

Spi_Lcd8_Config

Prototype procedure Spi_LCD8_Config(DeviceAddress : byte; var rstport :

byte; rstpin : byte; var csport : byte; cspin : byte);

Description Initializes LCD via SPI interface with pin settings (Reset pin and Chip Select pin) you
specify.

Requires Spi_Init; must be called before initializing SPI LCD8.

Example Spi_Lcd8_Config(0, PORTB, 1, PORTB, 0);

page

322
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_Lcd8_Init

Prototype procedure Spi_Lcd8_Init;

Description Initializes LCD at Control port (ctrlport) and Data port (dataport) with default pin set-
tings (see the connection scheme at the end of the chapter).

Requires Spi_Init; must be called before initializing SPI LCD8.

Example Spi_Lcd8_Init;

Spi_Lcd8_Out

Prototype procedure Spi_LCD8_Out(row, column: byte; var Text: string[20]);

Description Prints text on LCD at specified row and column (parameters row and col). Both string
variables and literals can be passed as text.

Requires Ports with LCD must be initialized. See Spi_Lcd8_Config or Spi_Lcd8_Init.

Example Spi_Lcd8_Out(1, 3, 'Hello!'); // Print "Hello!" at line 1, char 3

Spi_Lcd8_Out_Cp

Prototype procedure Spi_LCD8_Out_CP(var text: string[20]);

Description Prints text on LCD at current cursor position. Both string variables and literals can be
passed as text.

Requires Ports with LCD must be initialized. See Spi_Lcd8_Config or Spi_Lcd8_Init.

Example Spi_Lcd8_Out_Cp('Here!'); // Print "Here!" at current cursor

position

page
mikroElektronika: Development tools - Books - Compilers
323
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_Lcd8_Chr

Prototype procedure Spi_LCD8_Chr(row, column, out_char: byte);

Description Prints character on LCD at specified row and column (parameters row and col).
Both variables and literals can be passed as character.

Requires Ports with LCD must be initialized. See Spi_Lcd8_Config or Spi_Lcd8_Init.

Example Spi_Lcd8_Out(2, 3, 'i'); // Print "i" at line 2, char 3

Spi_Lcd8_Chr_Cp

Prototype procedure Spi_Lcd8_Chr_Cp(character : byte);

Description Prints character on LCD at current cursor position. Both variables and literals can be
passed as character.

Requires Ports with LCD must be initialized. See Spi_Lcd8_Config or Spi_Lcd8_Init.

Example Spi_Lcd8_Chr_Cp('e'); // Print "e" at current cursor position

Spi_Lcd8_Cmd

Prototype procedure Spi_Lcd8_Cmd(command : byte);

Description Sends command to LCD. You can pass one of the predefined constants to the function.
The complete list of available commands is shown below.

Requires Ports with LCD must be initialized. See Spi_Lcd8_Config or Spi_Lcd8_Init.

Example Spi_Lcd8_Cmd(LCD_Clear); // Clear LCD display

page

324
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

LCD Commands
LCD Command Purpose

LCD_FIRST_ROW Move cursor to 1st row

LCD_SECOND_ROW Move cursor to 2nd row

LCD_THIRD_ROW Move cursor to 3rd row

LCD_FOURTH_ROW Move cursor to 4th row

LCD_CLEAR Clear display

Return cursor to home position, returns a shifted display to original posi-

LCD_RETURN_HOME
tion. Display data RAM is unaffected.
LCD_CURSOR_OFF Turn off cursor

LCD_UNDERLINE_ON Underline cursor on

LCD_BLINK_CURSOR_ON Blink cursor on

LCD_MOVE_CURSOR_LEFT Move cursor left without changing display data RAM

Lcd_Move_Cursor_Right Move cursor right without changing display data RAM

LCD_TURN_ON Turn LCD display on

LCD_TURN_OFF Turn LCD display off

LCD_SHIFT_LEFT Shift display left without changing display data RAM

LCD_SHIFT_RIGHT Shift display right without changing display data RAM

Library Example (default pin settings)

program SpiLcd8;

begin
SPI_init(); // initialize SPI communication
Spi_Lcd8_Init(); // initialize lcd via SPI interface
Spi_Lcd8_Cmd(LCD_CLEAR); // Clear display
Spi_Lcd8_Cmd(LCD_CURSOR_OFF); // Turn cursor OFF
Spi_Lcd8_Out(1, 5, 'mikroE'); // Write Txt to LCD
Spi_Lcd8_Out(2, 1, 'mikroElektronika'); // Write Txt to LCD
Spi_Lcd8_Out(3, 1, 'mikroE');
// Write Txt to LCD, for lcd's with more than two rows
Spi_Lcd8_Out(4, 10, 'mikroE');
// Write Txt to LCD, for lcd's with more than two rows
end.

page
mikroElektronika: Development tools - Books - Compilers
325
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection

MCP23S17
D0 1 28
GPB0 GPA7
D1 2 27
GPB1 GPA6
D2 3 26
GPB2 GPA5
D3 4 25 RS
GPB3 GPA4

PIC18F452
D4 5 24
GPB4 GPA3
D5 6 23 E
GPB5 GPA2
D6 7 22
GPB6 GPA1
D7 8 21 VCC
GPB7 GPA0
VCC

9 20
VDD INTA 11
10 19 VCC
12
VSS INTB GND
RC1 11 18 RC0 13
CS RESET OSC1
RC3 12 17 14
SCK A2 OSC2
RC5 13 16 15
SI A1 RC0
8 Mhz 16
RC4 14 15 RC1
SO A0 24
RC5
18 23
RC3 RC4

VCC

Contrast
P4 Adjustment
5K

1 14
D1
GND
VCC
VEE
RS

E
D0

D2
D3

D7
D6
D5
D4
R/W

page

326
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

SPI T6963C Graphic LCD Library

mikroPascal for PIC provides a library for drawing and writing on Toshiba
T6963C Graphic LCD (various sizes) via SPI interface.

Note: Spi_Init; must be called before initializing SPI LCD.

Library Routines
Spi_T6963C_Config
Spi_T6963C_writeData
Spi_T6963C_writeCommand
Spi_T6963C_setPtr
Spi_T6963C_waitReady
Spi_T6963C_fill
Spi_T6963C_dot
Spi_T6963C_write_char
Spi_T6963C_write_text
Spi_T6963C_line
Spi_T6963C_rectangle
Spi_T6963C_box
Spi_T6963C_circle
Spi_T6963C_image
Spi_T6963C_sprite
Spi_T6963C_set_cursor
Spi_T6963C_clearBit
Spi_T6963C_setBit
Spi_T6963C_negBit
Spi_T6963C_displayGrPanel
Spi_T6963C_displayTxtPanel
Spi_T6963C_setGrPanel
Spi_T6963C_setTxtPanel
Spi_T6963C_panelFill
Spi_T6963C_grFill
Spi_T6963C_txtFill
Spi_T6963C_cursor_height
Spi_T6963C_graphics
Spi_T6963C_text
Spi_T6963C_cursor
Spi_T6963C_cursor_blink
Spi_T6963C_Config_240x128
Spi_T6963C_Config_240x64

page
mikroElektronika: Development tools - Books - Compilers
327
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_T6963C_Config
Prototype procedure Spi_T6963C_Config(width, height, fntW : word; var rst-
port : byte; rstpin : byte; var csport : byte; cspin : byte; wr,
rd, cd, rst : byte; DeviceAddress : byte);

Description Initalizes the Graphic Lcd controller. This function must be called before all Spi T6963C
Library Routines.
width - Number of horizontal (x) pixels in the display.
height - Number of vertical (y) pixels in the display.
fntW - Font width, number of pixels in a text character, must be set accordingly to the
hardware.
data - Address of the port on which the Data Bus is connected.
cntrl - Address of the port on which the Control Bus is connected.
wr - !WR line bit number in the *cntrl port.
rd - !RD line bit number in the *cntrl port.
cd - !CD line bit number in the *cntrl port.
rst - !RST line bit number in the *cntrl port.
DeviceAddress - Device Address.

Display RAM :
The library doesn't know the amount of available RAM.
The library cuts the RAM into panels : a complete panel is one graphics panel followed
by a text panel, The programer has to know his hardware to know how much panel he
has.

Requires Spi_Init; must be called before initializing SPI Toshiba T6963C Graphic LCD.

Example Spi_T6963C_Config(240, 64, 8, PORTB, 1, PORTB, 0, 0, 1, 3, 4, 0);

{
* init display for 240 pixel width and 64 pixel height
* 8 bits character width
* reset pin on PORTB.1
* chip select pin on PORTB.0
* bit 0 is !WR
* bit 1 is !RD
* bit 3 is !CD
* bit 4 is RST
* chip enable, reverse on, 8x8 font internaly set in library
* device address is 0
}

page

328
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_T6963C_writeData
Prototype procedure Spi_T6963C_writeData(data : byte);

Description Routine that writes data to Spi T6963C controller.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_writeData(AddrL);

Spi_T6963C_writeCommand
Prototype procedure Spi_T6963C_writeCommand(data : byte);

Description Routine that writes command to Spi T6963C controller

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_writeCommand(T6963C_CURSOR_POINTER_SET);

Spi_T6963C_setPtr
Prototype procedure Spi_T6963C_setPtr(p : word; c : byte);

Description This routine sets the memory pointer p for command c.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_setPtr(T6963C_grHomeAddr + start, T6963C_ADDRESS_POINT-

ER_SET);

Spi_T6963C_waitReady
Prototype procedure Spi_T6963C_waitReady;

Description This routine pools the status byte, and loops until ready.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_waitReady;

page
mikroElektronika: Development tools - Books - Compilers
329
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_T6963C_fill
Prototype procedure Spi_T6963C_fill(v : byte; start, len : word);

Description This routine fills length with bytes to controller memory from start address.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_fill(0x33,0x00FF,0x000F);

Spi_T6963C_dot
Prototype procedure Spi_T6963C_dot(x, y : integer; color : byte);

Description This routine sets current graphic work panel. It sets the pixel dot (x0, y0).
pcolor = T6963C_[WHITE[BLACK].

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_dot(x0, y0, pcolor);

Spi_T6963C_write_char
Prototype procedure Spi_T6963C_write_char(c, x, y, mode : byte);

Description This routine sets current text work panel.

It writes char c row x line y.
mode = T6963C_ROM_MODE_[OR|EXOR|AND]

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_write_char('A',22,23,AND);

Spi_T6963C_write_text
Prototype procedure Spi_T6963C_write_text(var str : array[10] of byte; x,
y, mode : byte);

Description This sets current text work panel.

It writes string str row x line y.
mode = T6963C_ROM_MODE_[OR|EXOR|AND]
Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_write_text("GLCD LIBRARY DEMO, WELCOME !", 0, 0,

T6963C_ROM_MODE_XOR);

page

330
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_T6963C_line
Prototype procedure Spi_T6963C_line(x0, y0, x1, y1 : integer; pcolor :
byte);

Description This routine current graphic work panel.

It's draw a line from (x0, y0) to (x1, y1).
pcolor = T6963C_[WHITE[BLACK]
Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_line(0, 0, 239, 127, T6963C_WHITE);

Spi_T6963C_rectangle
Prototype procedure T6963C_rectangle(x0, y0, x1, y1 : integer; pcolor :
byte);

Description It sets current graphic work panel.

It draws the border of the rectangle (x0, y0)-(x1, y1).
pcolor = T6963C_[WHITE[BLACK].
Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_rectangle(20, 20, 219, 107, T6963C_WHITE);

Spi_T6963C_box

Prototype procedure Spi_T6963C_box(x0, y0, x1, y1 : integer; pcolor :

byte);

Description This routine sets current graphic work panel.

It draws a solid box in the rectangle (x0, y0)-(x1, y1).
pcolor = T6963C_[WHITE[BLACK].
Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_box(0, 119, 239, 127, T6963C_WHITE);

page
mikroElektronika: Development tools - Books - Compilers
331
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_T6963C_circle
Prototype procedure Spi_T6963C_circle(x, y : integer; r : longint; pcolor :
word);

Description This routine sets current graphic work panel.

It draws a circle, center is (x, y), diameter is r.
pcolor = T6963C_[WHITE[BLACK]
Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_circle(120, 64, 110, T6963C_WHITE);

Spi_T6963C_image
Prototype procedure Spi_T6963C_image(const pic : ^byte);

Description This routine sets current graphic work panel :

It fills graphic area with picture pointer by MCU.
MCU must fit the display geometry.
For example : for a 240x128 display, MCU must be an array of (240/8)*128 = 3840
bytes .
Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_image(my_image);

Spi_T6963C_sprite
Prototype procedure Spi_T6963C_sprite(px, py : byte; const pic : ^byte; sx,
sy : byte);

Description This routine sets current graphic work panel.

It fills graphic rectangle area (px, py)-(px + sx, py + sy) witch picture pointed by MCU.
Sx and sy must be the size of the picture.
MCU must be an array of sx*sy bytes.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_sprite(76, 4, einstein, 88, 119); // draw a sprite

page

332
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_T6963C_set_cursor
Prototype procedure Spi_T6963C_set_cursor(x, y : byte);

Description This routine sets cursor row x line y.

Requires Ports must be initialized. See Spi_T6963C_init.

Example Spi_T6963C_set_cursor(cposx, cposy);

Spi_T6963C_clearBit
Prototype procedure Spi_T6963C_clearBit(b : byte);

Description Clear control bit.

Requires Ports must be initialized. See Spi_T6963C_init.

Example Spi_T6963C_clearBit(b);

Spi_T6963C_setBit
Prototype procedure Spi_T6963C_setBit(b : byte);

Description Set control bit.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_setBit(b);

Spi_T6963C_negBit
Prototype procedure Spi_T6963C_negBit(b : byte);

Description Neg control bit.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_negBit(b);

page
mikroElektronika: Development tools - Books - Compilers
333
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_T6963C_displayGrPanel
Prototype procedure Spi_T6963C_displayGrPanel(n : word);

Description Display graphic panel number n.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_displayGrPanel(n);

Spi_T6963C_displayTxtPanel
Prototype procedure Spi_T6963C_displayTxtPanel(n : word);

Description Display text panel number n.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_displayTxtPanel(n);

Spi_T6963C_setGrPanel
Prototype procedure Spi_T6963C_setGrPanel(n : word);

Description Compute graphic start address for panel number n.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_setGrPanel(n);

Spi_T6963C_setTxtPanel
Prototype procedure Spi_T6963C_setTxtPanel(n : word);

Description Compute text start address for panel number n.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_setTxtPanel(n);

page

334
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_T6963C_panelFill
Prototype procedure Spi_T6963C_panelFill(v : word);

Description Fill full #n panel with v bitmap (0 to clear).

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_panelFill(v);

Spi_T6963C_grFill
Prototype procedure Spi_T6963C_grFill(v: word);

Description Fill graphic #n panel with v bitmap (0 to clear).

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_grFill(v);

Spi_T6963C_txtFill
Prototype procedure Spi_T6963C_txtFill(v : word);

Description Fill text #n panel with char v + 32 (0 to clear).

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_txtFill(v);

Spi_T6963C_cursor_height
Prototype procedure Spi_T6963C_cursor_height(n: word);

Description Set cursor size.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_cursor_height(n);

page
mikroElektronika: Development tools - Books - Compilers
335
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Spi_T6963C_graphics
Prototype procedure Spi_T6963C_graphics(n : word);

Description Set graphics on/off.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_graphics(1);

Spi_T6963C_text
Prototype procedure Spi_T6963C_text(n : word);

Description Set text on/off.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_text(1);

Spi_T6963C_cursor
Prototype procedure Spi_T6963C_cursor(n : word);

Description Set cursor on/off.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_cursor(1);

Spi_T6963C_cursor_blink
Prototype procedure Spi_T6963C_cursor_blink(n : word);

Description Set cursor blink on/off.

Requires GLCD needs to be initialized, see Spi_T6963C_Config.

Example Spi_T6963C_cursor_blink(0);

page

336
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Spi_T6963C_Config_240x128
Prototype procedure Spi_T6963C_Config_240x128;

Description Initialize T6963C based GLCD (240x128 pixels) with default settings for mE GLCD's.

Requires Spi_Init; must be called before initializing SPI Toshiba T6963C Graphic LCD.

Example Spi_T6963C_Config_240x128;

Spi_T6963C_Config_240x64
Prototype procedure Spi_T6963C_Config_240x64;

Description Set graphics on/off.

Requires Initialize T6963C based GLCD (240x64 pixels) with default settings for mE GLCD's.

Example Spi_T6963C_Config_240x64;

Library Example
The following drawing demo tests advanced routines of SPI T6963C GLCD
library.
program Spi_T6963C_240x64;

uses T6963C_Consts, bitmap2;

var panel : byte; // current panel
i : word; // general purpose register
curs : byte; // cursor visibility
cposx,
cposy : word; // cursor x-y position
txtcols : byte; // number of text colons
begin
PORTB := 0;
TRISB := 0xFF;

//continues...

page
mikroElektronika: Development tools - Books - Compilers
337
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

//continues...

{
* init display for 240 pixel width and 128 pixel height
* 8 bits character width
* data bus on PORTD
* control bus on PORTC
* bit 0 is !WR
* bit 1 is !RD
* bit 3 is !CD
* bit 4 is RST
*
* chip enable, reverse on, 8x8 font internaly set in
library
}
Spi_Init();
Spi_T6963C_Config_240x64();

// enable both graphics and text display at the same time

Spi_T6963C_graphics(1) ;
Spi_T6963C_text(1) ;

panel := 0 ;
i := 0 ;
curs := 0 ;
cposx := 0 ;
cposy := 0 ;
txtcols := 240 div 8;
// calculate number of text colomns
// (grafic display width divided by font width)

// text messages

Spi_T6963C_write_text(' GLCD LIBRARY DEMO, WELCOME !', 0,

0, T6963C_ROM_MODE_XOR) ;
Spi_T6963C_write_text(' EINSTEIN WOULD HAVE LIKED mE', 0,
7, T6963C_ROM_MODE_XOR) ;

// cursor

Spi_T6963C_cursor_height(8) ; // 8 pixel height

Spi_T6963C_set_cursor(0, 0) ; // move cursor to top left
Spi_T6963C_cursor(0) ; // cursor off

//continued...

page

338
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

//continues...

// draw rectangles

Spi_T6963C_rectangle(0, 0, 239, 63, T6963C_BLACK) ;

Spi_T6963C_rectangle(20, 11, 219, 53, T6963C_BLACK) ;
Spi_T6963C_rectangle(40, 21, 199, 43, T6963C_BLACK) ;
Spi_T6963C_rectangle(60, 30, 179, 34, T6963C_BLACK) ;

// draw a cross

Spi_T6963C_line(0, 0, 239, 63, T6963C_BLACK) ;

Spi_T6963C_line(0, 63, 239, 0, T6963C_BLACK) ;

// draw solid boxes

Spi_T6963C_box(0, 0, 239, 8, T6963C_BLACK) ;

Spi_T6963C_box(0, 55, 239, 63, T6963C_BLACK) ;

// draw circles

Spi_T6963C_circle(120, 32, 10, T6963C_BLACK) ;

Spi_T6963C_circle(120, 32, 30, T6963C_BLACK) ;
Spi_T6963C_circle(120, 32, 50, T6963C_BLACK) ;
Spi_T6963C_circle(120, 32, 70, T6963C_BLACK) ;
Spi_T6963C_circle(120, 32, 90, T6963C_BLACK) ;
Spi_T6963C_circle(120, 32, 110, T6963C_BLACK) ;
Spi_T6963C_circle(120, 32, 130, T6963C_BLACK) ;

Spi_T6963C_setGrPanel(1) ; // select other graphic panel

Spi_T6963C_image(test240x64_bmp) ;
// fill the graphic screen with a picture

//continued...

page
mikroElektronika: Development tools - Books - Compilers
339
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

//continues...

while true do
begin
// if RB1 is pressed, toggle the display between graphic panel
// 0 and graphic 1

if(PORTB.1 <> 0) then

begin
panel := panel + 1;
panel := panel and 1 ;
Spi_T6963C_displayGrPanel(panel) ;
Delay_ms(300) ;
end

// if RB2 is pressed, display only graphic panel

else
if(PORTB.2 <> 0) then
begin
Spi_T6963C_graphics(1) ;
Spi_T6963C_text(0) ;
Delay_ms(300) ;
end

// if RB3 is pressed, display only text panel

else
if(PORTB.3 <> 0) then
begin
Spi_T6963C_graphics(0) ;
Spi_T6963C_text(1) ;
Delay_ms(300) ;
end

// if RB4 is pressed, display text and graphic panels

else
if(PORTB.4 <> 0) then
begin
Spi_T6963C_graphics(1) ;
Spi_T6963C_text(1) ;
Delay_ms(300) ;
end

//continued...

page

340
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

//continues...

// if RB5 is pressed, change cursor

else
if(PORTB.5 <> 0) then
begin
curs := curs + 1;
if(curs = 3) then
curs := 0 ;
case curs of
0:
Spi_T6963C_cursor(0) ;

1:
begin
Spi_T6963C_cursor(1) ;
Spi_T6963C_cursor_blink(1) ;
end;

2:
begin
Spi_T6963C_cursor(1) ;
Spi_T6963C_cursor_blink(0) ;
end;
end;
Delay_ms(300) ;
end;

// move cursor, even if not visible

cposx := cposx + 1;
if(cposx = txtcols) then
begin
cposx := 0 ;
cposy := cposy + 1;
if(cposy = (128 div T6963C_CHARACTER_HEIGHT)) then
// if y end
cposy := 0 ;
// grafic height (128) div character height
end;
Spi_T6963C_set_cursor(cposx, cposy) ;
Delay_ms(100) ;
end;
end.

page
mikroElektronika: Development tools - Books - Compilers
341
 mikroPASCAL
mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers making it simple...

Hardware Connection MCP23S17

D0 1 28
GPB0 GPA7
D1 2 27 FS
GPB1 GPA6
D2 3 26 MD
GPB2 GPA5
D3 4 25 RST
GPB3 GPA4

PIC18F452
D4 5 24 CE
GPB4 GPA3
D5 6 23 E
GPB5 GPA2
D6 7 22 RW
GPB6 GPA1
D7 8 21 RS VCC
GPB7 GPA0
VCC
9 20
VDD INTA 11
10 19 VCC
12
VSS INTB GND
RC1 11 18 RC0 13
CS RESET OSC1
RC3 12 17 14
SCK A2 OSC2
RC5 13 16 15
SI A1 RC0
8 Mhz 16
RC4 14 15 RC1
SO A0 24
RC5
18 23
RC3 RC4

Contrast
Adjustment
P1
10K

VCC

VCC
R1
50

1 20
VDD

LED+
VSS

RST
VEE
R/W

MD
CE
RS

D0

D5
D7
D1
D3
D2
D4
D6

FS
Vo

mikroE
EasyPIC4
Dev. tool

Toshiba T6963C Graphic LCD (240x128)

page

342
mikroElektronika: Development tools - Books - Compilers
mikroPASCAL
making it simple... mikroPASCAL - Pascal Compiler for Microchip PIC microcontrollers

Contact us:

If you are experiencing problems with any of our products or you just want addi-
tional information, please let us know.

Technical Support for compiler

If you are experiencing any trouble with mikroPascal, please do not hesitate to
contact us - it is in our mutual interest to solve these issues.

Discount for schools and universities

mikroElektronika offers a special discount for educational institutions. If you

would like to purchase mikroPascal for purely educational purposes, please
contact us.

Problems with transport or delivery

If you want to report a delay in delivery or any other problem concerning distri-
bution of our products, please use the link given below.

Would you like to become mikroElektronika's distributor?

We in mikroElektronika are looking forward to new partnerships. If you would

like to help us by becoming distributor of our products, please let us know.

Other

If you have any other question, comment or a business proposal, please contact
us:

mikroElektronika
Admirala Geprata 1B
11000 Belgrade
EUROPE

Phone: + 381 (11) 30 66 377, + 381 (11) 30 66 378

Fax: + 381 (11) 30 66 379
E-mail: office@mikroe.com
Web: www.mikroe.com
Support: support@mikroe.com
Forum: www.mikroe.com/forum/

page
mikroElektronika: Development tools - Books - Compilers
343