mikroC for dsPIC Users Manual

mikroC for dsPIC Users Manual

mikroElektronika

Development tools - Books - Compilers w w w . m i k r o e . c o m

C Compiler for Microchip dsPIC microcontrollers

mikroC

f o r d s P I C

M a k i n g i t s i m p l e

Develop your applications quickly and easily with the world's most intuitive C compiler for dsPIC Microcontrollers (families dsPIC30).

Highly sophisticated IDE provides the power you need with the simplicity of a Windows based point-and-click environment.

With useful implemented tools, many practical code examples, broad set of built-in routines, and a comprehensive Help, mikroC for dsPIC makes a fast and reliable tool, which can satisfy needs of experienced engineers and beginners alike.

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

July 2006.

Reader’s note

DISCLAIMER:

mikroC for dsPIC 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, partially or as a whole without the written consent from the mikroEelktronika. 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 mikroC for dsPIC 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 communication 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 mikroC for dsPIC compiler, you agree to the terms of this agreement. Only one person may use licensed version of mikroC for dsPIC compiler at a time.

Copyright © mikroElektronika 2003 - 2006.

This manual covers mikroC version 2.0.0.0 and the related topics. Newer 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 [email protected] Please include next information in your bug report:

- Your operating system

- Version of mikroC for dsPIC

- 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: [email protected]

page iiii

dsPIC, dsPICmicro 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.

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

Table of Contents

CHAPTER 1

CHAPTER 2

CHAPTER 3

CHAPTER 4

mikroC for dsPIC IDE

Building Applications mikroC for dsPIC Reference mikroC for dsPIC Libraries

Miik ro ek tr niik a:: ev lo pm en t ls -- Bo ok -- om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CHAPTER 1: mikroC IDE 1

Quick Overview

Code Editor

Code Explorer 6

Debugger 7

1

3

Error Window 11

Statistics 12

Integrated Tools

Keyboard Shortcuts

15

17

CHAPTER 2: Building Applications

Projects

Source Files

Search Paths

Managing Source Files

Compilation

Output Files

Assembly View

Error Messages

CHAPTER 3: mikroC Language Reference

dsPIC Specifics mikroC for dsPIC Specifics

ANSI Standard Issues

Predefined Globals and Constants

Accessing Individual Bits

Interrupts

Linker Directives

Code Optimization

Lexical Elements

Tokens

Constants

Integer Constants

Floating Point Constants

Character Constants

String Constants

Enumeration Constants

Pointer Constants

Constant Expressions

21

27

27

27

28

22

24

24

25

31

43

44

46

47

38

40

41

41

47

47

34

35

36

37

32

33

33

34 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Keywords

Identifiers

Punctuators

Objects and Lvalues

Scope and Visibility

Name Spaces

Duration

Types

Fundamental Types

Arithmetic Types

Enumeration Types

Void Type

Derived Types

Arrays

Pointers

Function Pointer

Pointer Arithmetic

Structures

Unions

Bit Fields

Types Conversions

Standard Conversions

Explicit Typecasting

Declarations

Linkage

Storage Classes

Type Qualifiers

Typedef Specifier asm Declaration

Initialization

Functions

Function Declaration

Function Prototypes

Function Definition

Function Reentrancy

Function Calls

Ellipsis Operator

Operators

Precedence and Associativity

Arithmetic Operators

Relational Operators

Bitwise Operators

Logical Operators

Conditional Operator ? :

Assignment Operators

91

93

95

96

97

99

100

100

86

86

88

89

74

78

83

84

67

67

70

72

62

62

64

66

56

58

59

61

48

49

50

54

101

102

102

103

105

106

106

108

110

111

113

115

116 page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers sizeof Operator

Expressions

Statements

Labeled Statements

Expression Statements

Selection Statements

Iteration Statements

Jump Statements

Compound Statements (Blocks)

Preprocessor

Preprocessor Directives

Macros

File Inclusion

Preprocessor Operators

Conditional Compilation

CHAPTER 4: mikroC for dsPIC Libraries

Built-in Routines

Library Routines

ADC Library

CAN Library

CANSPI Library

Compact Flash Library

EEPROM Library

SPI Ethernet Library

Flash Memory Library

I2C Library

Keypad Library

LCD Custom Library (4-bit interface)

LCD8 Custom Library (8-bit interface)

Graphic LCD Library

T6963C Graphic LCD Library

Manchester Code Library

Multi Media Card Library

OneWire Library

PS/2 Library

PWM Library

RS-485 Library

Software I2C Library

Software SPI Library

Software UART Library page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

141

247

255

260

264

270

274

285

297

142

148

149

151

168

182

194

197

302

313

318

321

324

330

334

337 mikroC for dsPIC making it simple...

130

131

131

132

136

137

138

118

119

121

121

122

122

125

128

mikroC for dsPIC making it simple...

Contact Us miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Sound Library

SPI Library

USART Library

DSP Library

Util Library

ANSI C Ctype Library

ANSI C Math Library

ANSI C Stdlib Library

ANSI C String Library

Conversions Library

Trigonometry Library

Sprint Library

SPI Graphic LCD Library

Port Expander Library

340

342

349

355

367

373

377

383

387

393

398

399

404

415

423

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

CHAPTER

1

mikroC for dsPIC IDE

QUICK OVERVIEW

mikroC for dsPIC is a powerful, feature rich development tool for dsPICmicros. It is designed to provide the customer with the easiest possible solution for developing applications for embedded systems, without compromising performance or control.

dsPIC and C fit together well: dsPIC is new Microchip 16-bit MCU with DSP capatibilities, used in a wide variety of applications, and C, prized for its efficiency, is the natural choice for developing embedded systems. mikroC for dsPIC provides a successful match featuring highly advanced IDE, ANSI compliant compiler, broad set of hardware libraries, comprehensive documentation, and plenty of ready-torun examples.

Miik ro ek tr niik a:: ev lo pm en t ls -- Bo ok -- om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers mikroC for dsPIC making it simple...

Watch

Window

Code

Explorer

Code

Editor

Project

Summary

Error

Window

Breakpoints

Window

Code

Assistant mikroC for dsPIC allows you to quickly develop and deploy complex applications:

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

- Use the included mikroC for dsPIC libraries to dramatically speed up the development: data acquisition, memory, displays, conversions, communications…

- Monitor your program structure, variables, and functions in the Code Explorer.

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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CODE EDITOR

The Code Editor is an advanced text editor fashioned to satisfy the needs of professionals. General code editing is same as working with any standard text-editor, including familiar Copy, Paste, and Undo actions, common for Windows environment.

Advanced Editor features include:

- Adjustable Syntax Highlighting

- Code Assistant

- Parameter Assistant

- Code Templates (Auto Complete)

- Auto Correct for common typos

- Bookmarks and Goto Line

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

Tools Icon.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Code Assistant [CTRL+SPACE]

If you type a first few letter of a word and then press CTRL+SPACE, all the valid identifiers matching the letters you typed will be prompted 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 the keyboard arrows and Enter.

Parameter Assistant [CTRL+SHIFT+SPACE]

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

page

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 the Code Editor will automatically generate the code. Or you can click a button from the Code toolbar and select a 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 Settings Toolbar, and then select the Auto Complete Tab. Here you can enter the appropriate keyword, description, and code of your template.

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC 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, and then select the Auto Correct Tab. You can also add your own preferences to the list.

Comment/Uncomment

Comment /

Uncomment Icon.

The Code Editor allows you to comment or uncomment selected block of code by 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> : Go to a bookmark

CTRL+SHIFT+<number> : Set a 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.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CODE EXPLORER

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

Collapse/Expand

All Icon.

Also, two more tabs are available in Code Explorer. QHelp Tab lists all the available built-in and library functions, for a quick reference. Double-clicking a routine in QHelp Tab opens the relevant Help topic. Keyboard Tab lists all the available keyboard shortcuts in mikroC.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

DEBUGGER

Start Debugger

The source-level Debugger is an integral component of mikroC for dsPIC development environment. It is designed to simulate operations of Microchip technology's dsPICmicros and to assist users in debugging software written for these devices.

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

After you have successfully compiled your project, you can run the Debugger by selecting Run > Debug from the drop-down menu, or by clicking the 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.

Pause Debugger

Debug [F9]

Start the Debugger.

Run/Pause Debugger [F6]

Run or pause the Debugger.

Step Into

Step Over

Step Out

Run to Cursor

Step Into [F7]

Execute the current C (single– or multi–cycle) instruction, then halt. If the instruction is a routine call, enter the routine and halt at the first instruction following the call.

Step Over [F8]

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

Step Out [Ctrl+F8]

Execute the current C (single– or multi–cycle) instruction, then halt. If the instruction is within a routine, execute the instruction and halt at the first instruction following the call.

Run to cursor [F4]

Executes all instructions between the current instruction and the cursor position.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Toggle

Breakpoint.

Toggle Breakpoint [F5]

Toggle breakpoint at current cursor position. To view all the breakpoints, select

Run > View Breakpoints from the drop-down menu. Double clicking an item in window list locates the breakpoint.

Watch Window

Variables

The Watch Window allows you to monitor program items while running your program. It displays variables and special function registers of dsPIC MCU, their addresses and values. Values are updated as you go through the simulation.

page

Double clicking one of the items opens a window in which you can assign a new value to the selected variable or register and change number formatting.

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Stopwatch Window

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 the 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.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC 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 dsPIC’s RAM, with recently changed items colored red. You can change value of any field by double-clicking it.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ERROR WINDOW

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

The Error Window is located under the message tab, and displays location and type of errors compiler has encountered. The compiler also reports warnings, but these do not affect the output; 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.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

STATISTICS

Statistics Icon.

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 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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

Miik r

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Procedures (Locations) Window

Displays how functions are distributed in microcontroller’s memory.

RAM Window

Summarizes all GPR and SFR registers and their addresses. Also displays symbolic names of variables and their addresses.

r oE ek tr on a:: ev lo me t oo s Bo ok -- C om le s page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ROM Window

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

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

INTEGRATED TOOLS

USART Terminal

mikroC 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 display. You can launch it from the drop-down menu Tools > ASCII chart.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC 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 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 dsPIC microcontroller.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

KEYBOARD SHORTCUTS

Below is the complete list of keyboard shortcuts available in mikroC for dsPIC

IDE. You can also view keyboard shortcuts in Code Explorer window, tab

Keyboard.

IDE Shortcuts

F1

CTRL+N

Help

New Unit

CTRL+O Open

CTRL+F9 Compile

CTRL+F11 Code Explorer on/off

CTRL+SHIFT+F5 View breakpoints

Basic Editor shortcuts

F3

CTRL+A

CTRL+C

CTRL+F

CTRL+P

CTRL+R

CTRL+S

CTRL+SHIFT+S

CTRL+V

CTRL+X

CTRL+Y

CTRL+Z

Find, Find Next

Select All

Copy

Find

Print

Replace

Save unit

Save As

Paste

Cut

Redo

Undo

Advanced Editor shortcuts

CTRL+SPACE

CTRL+SHIFT+SPACE

CTRL+D

CTRL+G

CTRL+J

CTRL+<number>

Code Assistant

Parameters Assistant

Find declaration

Goto line

Insert Code Template

Goto bookmark

CTRL+SHIFT+<number> Set bookmark

CTRL+SHIFT+I Indent selection

CTRL+SHIFT+U Unindent selection page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Select columns CTRL+ALT+SELECT

Debugger Shortcuts

F4

F5

F6

F7

F8

F9

CTRL+F2

Run to Cursor

Toggle breakpoint

Run/Pause Debugger

Step into

Step over

Debug

Reset mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

CHAPTER

2

Building

Applications

Creating applications in mikroC 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.

mikroC for dsPIC allows you to distribute your projects in as many files 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 mikroPascal or mikroBasic!

Miik ro ek tr niik a:: ev lo pm en t ls -- Bo ok -- om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PROJECTS

mikroC for dsPIC organizes applications into projects, consisting of a single project file (extension

.dpc

) and one or more source files (extension

.c

). You can compile source files only if they are part of a project.

Project file carries the following information:

- project name and optional description,

- Amount if dynamic and static memory

- 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 mikroC will create the appropriate project file. Also, an empty source file named after the project will be created by default.

Edit Project.

Add to Project.

Remove from

Project.

Editing Project

Later, you can change project settings from drop-down menu Project > Edit

Project. You can 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.

Add/Remove Files from Project

Project can contain any number of source files (extension

.c

). The list of relevant source files is stored in the project file (extension

.dpc

). To add source file to your project, select Project > Add to Project from drop-down menu. Each added source file must be self-contained, i.e. it must have all the necessary definitions after preprocessing. To remove file(s) from your project, select Project > Remove from Project from drop-down menu.

Note: For inclusion of header files, use the preprocessor directive

#include

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Extended functionality of the Project Files tab

By using the Project Files new features, you can reach all the output files (.lst,

.asm) by a single click. You can also include in project the library files (.mcl), for libraries, either your own or compiler default, that are project-specific.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

SOURCE FILES

Source files containing C code should have the extension

.c

. List of source files relevant for the application is stored in project file with extension

.dpc

, along with other project information. You can compile source files only if they are part of a project.

Use the preprocessor directive

#include to include headers. Do not rely on preprocessor to include other source files — see Projects for more information.

Search Paths

Paths for source files (

.c

)

You can specify your own custom search paths. This can be configured by selecting Tools > Options from drop-down menu and then tab window Advanced.

In project settings, you can specify either absolute or relative path to the source file. If you specify a relative path, mikroC for dsPIC will look for the file in following locations, in this particular order:

1. the project folder (folder which contains the project file

.ppc

),

2. your custom search paths,

3. mikroC for dsPIC installation folder > “uses” folder.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Paths for Header Files (

.h

)

Header files are included by means of preprocessor directive #include. If you place an explicit path to the header file in preprocessor directive, only that location will be searched.

You can specify your own custom search paths: select Tools › Options from the drop-down menu and then select Search Path.

In project settings, you can specify either absolute or relative path to the header. If you specify a relative path, mikroC will look for the file in following locations, in this particular order:

1. the project folder (folder which contains the project file

.ppc

),

2. mikroC for dsPIC installation folder > “include” folder,

3. your custom search paths.

New File.

Managing Source Files

Creating a new source file

To create a new source file, do the following:

Select File > New from 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 drop-down menu to name it the way you want.

If you have used New Project Wizard, an empty source file, named after the project with extension

.c

, is created automatically. mikroC for dsPIC does not require you to have source file named same as the project, it’s just a matter of convenience.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Opening an Existing File

Open File Icon.

Select File > Open from 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 Icon.

Make sure that window containing the file you want to print is the active window.

Select File > Print from 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 Icon.

Make sure that window containing the file you want to save is the active window.

Select File > Save from 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 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.

Close File.

Closing a File

Make sure that tab containing the file you want to close is the active tab. Select

File > Close from 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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

COMPILATION

Compile Icon.

When you have created the project and written the source code, you will want to compile it. Select Project > Build from drop-down menu, or click Build 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, mikroC for dsPIC will generate output files.

Output Files

Upon successful compilation, mikroC for dsPIC will generate output files in the project folder (folder which contains the project file

.dpc

). 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

View Assembly

Icon.

After compiling your program in mikroC for dsPIC, you can click View Assembly

Icon or select Project › View Assembly from drop-down menu to review generated assembly code (.asm file) in a new tab window. Assembly is human 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

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ERROR MESSAGES

Error Messages

- Specifier needed

- Invalid declarator

- Expected '(' or identifier

- Integer const expected

- Array dimension must be greater then 0

- Local objects cannot be extern

- Declarator error

- Bad storage class

- Arguments cannot be of void type

- Specifer/qualifier list expected

- Address must be greater than 0

- Identifier redefined

- case out of switch

- default label out of switch

- switch exp. must evaluate to integral type

- continue outside of loop

- break outside of loop or switch

- void func cannot return values

- Unreachable code

- Illegal expression with void

- Left operand must be pointer

- Function required

- Too many chars

- Undefined struct

- Nonexistent field

- Aggregate init error

- Incompatible types

- Identifier redefined

- Function definition not found

- Signature does not match

- Cannot generate code for expression

- Too many initializers of subaggregate

- Nonexistent subaggregate

- Stack Overflow: func call in complex expression

- Syntax Error: expected %s but %s found

- Array element cannot be function

- Function cannot return array page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

- Inconsistent storage class

- Inconsistent type

- %s tag redefined

- Illegal typecast

- %s is not a valid identifier

- Invalid statement

- Constant expression required

- Internal error %s

- Too many arguments

- Not enough parameters

- Invalid expresion

- Identifier expected, but %s found

- Operator [%s] not applicable to this operands [%s]

- Assigning to non-lvalue [%s]

- Cannot cast [%s] to [%s]

- Cannot assign [%s] to [%s]

- lvalue required

- Pointer required

- Argument is out of range

- Undeclared identifier [%s] in expression

- Too many initializers

- Cannot establish this baud rate at %s MHz clock

Compiler Warning Messages

- Highly inefficent code: func call in complex expression

- Inefficent code: func call in complex expression

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

CHAPTER

3

mikroC for dsPIC

Language Reference

C offers unmatched power and flexibility in programming microcontrollers.

mikroC for dsPIC adds even more power with an array of libraries, specialized for dsPIC HW modules and communications. This chapter should help you learn or recollect C syntax, along with the specifics of programming dsPIC microcontrollers. If you are experienced in C programming, you will probably want to consult mikroC for dsPIC Specifics first.

Miik ro ek tr niik a:: ev lo pm en t ls -- Bo ok -- om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

dsPIC SPECIFICS

In order to get the most from your mikroC for dsPIC compiler, you should be familiar with certain aspects of dsPIC MCU. This knowledge is not essential, but it can provide you a better understanding of dsPIC's capabilities and limitations, and their impact on the code writing.

Types Efficiency

First of all, you should know that dsPIC’s ALU, which performs arithmetic operations, is optimized for working with int type.Although mikroC for dsPIC is capable of handling types like char or short, dsPIC will generate better code for int type so use char nad short only in places where you can significantlly save RAM

(e.g. for arrays char a[30]).

Nested Calls Limitations

There is no Nested Calls Limitations, except by RAM size. Nested call represents a function call within function body, either to itself (recursive calls) or to another function.

Recursive calls, as form of cross-calling, are supported by mikroC for dsPIC but you should use them very carefully due to the dsPIC’s stack and memory limitations. Also calling functions from interrupt is allowed. Calling function both from interrupt and main thread is allowed but you should bear in mind what this kind of programming technics causes.

Limits of Indirect Approach Through PSV

Constant agregates are stored in Flash and accesed trough PSV, this menas that you can have max 32kbyte of constants.

Limits of Pointer to Function

Currentlly pointer to functions are 16 bit. For functions which address exceeds 16 bit limit, compiler is using handle (16-bit pointer on GOTO). Handle usage is automatic compiler process so there is no need for user intervention.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

mikroC SPECIFICS

ANSI Standard Issues

Divergence from the ANSI C Standard

mikroC for dsPIC diverges from the ANSI C standard in few areas. Some of these modifications are improvements intenteded to facilitate dsPIC programming, while others are result of dsPICmicro hardware limitations.

- Case Sensitivity. Check identifiers.

- Pointers to variables and pointers to constants are not compatible, i.e. no assigning or comparison is possible between the two.

- mikroC for dsPIC treats identifiers declared with const qualifier as “true constants” (C++ style). This allows using const objects in places where ANSI C would expect a constant expression. If aiming at portability, use the traditional preprocessor defined constants. See Type Qualifiers and Constants.

- mikroC allows C++ style single–line comments using two adjacent slashes (//).

The comment can start at any position, and extends until the next new line. See

Comments.

- A number of standard C libraries (ctype, math, stdlib, string) have been implemented; check the individual functions for divergence.

Features currently under construction:

Anonymous structures and unions are unsupported at present.

Implementation-defined Behavior

Certain sections of the ANSI standard have implementation-defined behavior. This means that the exact behavior of some C code can vary from compiler to compiler.

Throughout the help are sections describing how the mikroC for dsPIC compiler behaves in such situations. The most notable specifics include: Floating-point

Types, Storage Classes, and Bit Fields.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Predefined Globals and Constants

To facilitate dsPIC programming, mikroC for dsPIC implements a number of predefined globals and constants.

All dsPIC SFR registers are implicitly declared as global variables of volatile unsigned int. These identifiers have external linkage, and are visible in the entire project. When creating a project, mikroC for dsPIC will include an appropriate

(*.c) file from defs folder, containing declarations of available SFR and constants

(such as PORTB, ADPCFG, etc). Identifiers are all in uppercase, identical to nomenclature in Microchip datasheets. All dsPIC SFR registers are also avaible as structures with bitfields with names identical to microchip datasheets to fascilate bit access e.g

TRISBbits.TRISB3 = 1;

Accessing Individual Bits

mikroC for dsPIC allows you to access individual bits of 16-bit variables, types unsigned int

. Simply use the direct member selector (.) with a variable, followed by one of identifiers

F0, F1, … , F15

, with

F15 being the most significant bit.

There is no need for any special declarations; this kind of selective access is an intrinsic feature of mikroC and can be used anywhere in the code. Identifiers

F0–F15 are not case sensitive and have a specific namespace. You may override these with your own members

F0–F15 within any given structure.

Provided you are familiar with the particular chip, you can also access bits by name:

// Clear TRISB3

TRISBbits.TRISB3 = 0;

See Predefined Globals and Constants for more information on register/bit names.

Note: If aiming at portability, avoid this style of accessing individual bits, and use the bit fields instead.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Interrupts

The dsPIC30F interrupt controller module reduces the numerous peripheral interrupt request signals to a single interrupt request signal to the dsPIC30F CPU and has the following features:

- Up to 8 processor exceptions and software traps

- 7 user selectable priority levels

- Interrupt Vector Table (IVT) with up to 62 vectors

- A unique vector for each interrupt or exception source

- Fixed priority within a specified user priority level

- Alternate Interrupt Vector Table (AIVT) for debug support

ISR's are organized in IVT. ISR is defined as standard function but with org 0x26 directive afterwards.

0x26 is IVT address of U1RX(UART1 Receiver) interrupt source.For more info about IVT can be found in dsPIC30F Family Reference

Manual.

Function Calls from Interrupt

Calling functions from within the interrupt routine is possible. The compiler takes care about the registers being used, both in "interrupt" and in "main" thread, and performs "smart" context-switching between the two, saving only the registers that have been used in both threads. The usage of function calls from interrupt is not recommended and its usage must be taken very carefully (especially stack depth).

Here is a simple example of handling the interrupts from UART1 (if no other interrupts are allowed):

//-------------- Interrupt routine

void interrupt_uart() org 0x26 {

Rs485master_Receive(dat);

IFS0bits.U1RXIF = 0; //ensure interrupt not pending

}//~!~

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Linker Directives

mikroC for dsPIC uses internal algorithm to distribute objects within memory. If you need to have variable or routine at specific predefined address, use linker directives 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:

int foo absolute 0x23;

// Variable will occupy 2 bytes at addresses 0x23 and 0x24;

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

char i absolute 0x33;

// Variable i will occupy 1 byte at address 0x33

long jjjj absolute 0x30;

// Variable will occupy 4 bytes at 0x30, 0x31, 0x32, 0x33,

// so changing i changes jjjj highest byte at the same time

Directive org

Directive org specifies the starting address of routine in ROM.

Directive org is appended to the function definition. Directives applied to nondefining declarations will be ignored, with an appropriate warning issued by linker. Directive org cannot be applied to an interrupt routine.

Here is a simple example:

void func(char par) org 0x200 {

// Function will start at address 0x200

nop;

} page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

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 recognizes 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 implement specific solutions for the code "building bricks" that further reduce output code size.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

LEXICAL ELEMENTS

These topics provide a formal definition of the mikroC for dsPIC lexical elements.

They describe the different categories of word-like units (tokens) recognized by a language.

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

A mikroC program starts as a sequence of ASCII characters representing the source code, created by keystrokes using a suitable text editor (such as the mikroC editor). The basic program unit in mikroC is the file. This usually corresponds to a named file located in RAM or on disk and having the extension

.c

.

Whitespace

Whitespace is the collective name given to spaces (blanks), horizontal and vertical tabs, newline characters, and comments. Whitespace can serve to indicate where tokens start and end, but beyond this function, any surplus whitespace is discarded. For example, the two sequences

int i; float f; and

int i;

float f; are lexically equivalent and parse identically to give the six tokens.

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

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Comments

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

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 delineate comments: the C method and the C++ method. Both are supported by mikroC.

C comments

C comment is any sequence of characters placed after the symbol pair

/*

. The comment terminates at the first occurrence of the pair

*/ following the initial

/*

.

The entire sequence, including the four comment-delimiter symbols, is replaced by one space after macro expansion.

In mikroC,

int /* type */ i /* identifier */; parses as:

int i;

Note that mikroC does not support the nonportable token pasting strategy using

/**/

. For more on token pasting, refer to Preprocessor topics.

C++ comments

mikroC allows single-line comments using two adjacent slashes (

//

). The comment can start in any position, and extends until the next new line. The following code,

int i; // this is a comment

int j; parses as:

int i;

int j; page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TOKENS

Token is the smallest element of a C program that is meaningful to the compiler.

The parser separates tokens from the input stream by creating the longest token possible using the input characters in a left–to–right scan.

mikroC recognizes following 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: inter = a+++b;

First, note that inter would be parsed as a single identifier, rather than as the keyword int followed by the identifier er

.

The programmer who wrote the code might have intended to write inter = a + (++b) but it won’t work that way. The compiler would parse it as the following seven tokens: inter

= a

++

+ b

;

// identifier

// assignment operator

// identifier

// postincrement operator

// addition operator

// identifier

// semicolon separator

Note that

+++ parses as

++

(the longest token possible) followed by

+

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CONSTANTS

Constants or literals are tokens representing fixed numeric or character values.

mikroC supports:

- integer constants,

- floating point constants,

- character constants,

- string constants (strings literals),

- enumeration constants.

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

Integer Constants

Integer constants can be decimal (base 10), hexadecimal (base 16), binary (base

2), or octal (base 8). In the absence of any overriding suffixes, the data type of an integer constant is derived from its value.

Long and Unsigned Suffixes

The suffix

L

(or l

) attached to any constant forces the constant to be represented as a long

. Similarly, the suffix

U

(or u

) forces the constant to be unsigned

. You can use both

L and

U suffixes on the same constant in any order or case: ul

,

Lu

,

UL

, etc.

In the absence of any suffix (

U

, u

,

L

, or l

), constant is assigned the “smallest” of the following types that can accommodate its value: short

, unsigned short

, int

, unsigned int

, long int

, unsigned long int

.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Otherwise:

If the constant has a

U or u suffix, its data type will be the first of the following that can accommodate its value: unsigned short

, unsigned int

, unsigned long int

.

If the constant has an

L or l suffix, its data type will be the first of the following that can accommodate its value: long int

, unsigned long int

.

If the constant has both

U and

L suffixes, ( ul

, lu

,

Ul

, lU

, uL

,

Lu

,

LU

, or

UL

), its data type will be unsigned long int

.

Decimal Constants

Decimal constants from -2147483648 to 4294967295 are allowed. Constants exceeding these bounds will produce an “Out of range” error. Decimal constants must not use an initial zero. An integer constant that has an initial zero is interpreted as an octal constant.

In the absence of any overriding suffixes, the data type of a decimal constant is derived from its value, as shown below:

< -2147483648

-2147483648 .. -32769

-32768 .. -129

-128 .. 127

128 .. 255

256 .. 32767

32768 .. 65535

65536 .. 2147483647

2147483648 .. 4294967295

> 4294967295

Error: Out of range!

long int short unsigned short int unsigned int long unsigned long

Error: Out of range!

Hexadecimal Constants

All constants starting with

0x

(or

0X

) are taken to be hexadecimal. In the absence of any overriding suffixes, the data type of an hexadecimal constant is derived from its value, according to the rules presented above. For example,

0xC367 will be treated as unsigned int

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Binary Constants

All constants starting with

0b

(or

0B

) are taken to be binary. In the absence of any overriding suffixes, the data type of an binary constant is derived from its value, according to the rules presented above. For example,

0b11101 will be treated as short

.

Octal Constants

All constants with an initial zero are taken to be octal. If an octal constant contains the illegal digits 8 or 9, an error is reported. In the absence of any overriding suffixes, the data type of an octal constant is derived from its value, according to the rules presented above. For example,

0777 will be treated as int

.

Floating Point Constants

A floating-point constant consists of:

- Decimal integer,

- Decimal point,

- Decimal fraction,

- e or

E and a signed integer exponent (optional),

- Type suffix: f or

F or l or

L

(optional).

You can omit either the decimal integer or the decimal fraction (but not both). You can omit either the decimal point or the letter e

(or

E

) and the signed integer exponent (but not both). These rules allow for conventional and scientific (exponent) notations.

Negative floating constants are taken as positive constants with the unary operator minus (

-

) prefixed.

mikroC limits floating-point constants to range

±1.17549435082E38 .. ±6.80564774407E38

.

mikroC floating-point constants are of type double

. Note that mikroC’s implementation of ANSI Standard considers float and double

(together with the long double variant) to be the same type.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Character Constants

A character constant is one or more characters enclosed in single quotes, such as

'A'

,

'+'

, or

'\n'

. In C, single-character constants have data type int

. Multicharacter constants are referred to as string constants or string literals. For more information refer to String Constants.

Escape Sequences

The backslash character (

\

) is used to introduce an escape sequence, which allows the visual representation of certain nongraphic characters. One of the most common escape constants is the newline character (

\n

).

A backslash is used with octal or hexadecimal numbers to represent the ASCII symbol or control code corresponding to that value; for example,

'\x3F' for the question mark. You can use any string of up to three octal or any number of hexadecimal numbers in an escape sequence, provided that the value is within legal range for data type char (0 to 0xFF for mikroC). Larger numbers will generate the compiler error “Numeric constant too large”.

For example, the octal number

\777 is larger than the maximum value allowed

(

\377

) and will generate an error. The first nonoctal or nonhexadecimal character encountered in an octal or hexadecimal escape sequence marks the end of the sequence.

Note: You must use

\\ to represent an ASCII backslash, as used in operating system paths.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

The following table shows the available escape sequences in mikroC:

Sequence

\a

\'

\"

\?

\O

\xH

\XH

\r

\t

\v

\\

\b

\f

\n

Value

0x07

0x08

0x0C

0x0A

0x0D

0x09

0x0B

0x5C

0x27

0x22

0x3F any any

"

?

any

'

\

HT

VT

Char

BEL

BS

FF

LF

CR

What it does

Audible bell

Backspace

Formfeed

Newline (Linefeed)

Carriage Return

Tab (horizontal)

Vertical Tab

Backslash

Single quote

(Apostrophe)

Double quote

Question mark

O = string of up to 3 octal digits

H = string of hex digits

H = string of hex digits page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

String Constants

String constants, also known as string literals, are a special type of constants which store fixed sequences of characters. A string literal is a sequence of any number of characters surrounded by double quotes:

"This is a string."

The null string, or empty string, is written like

""

. A literal string is stored internally as the given sequence of characters plus a final null character. A null string is stored as a single null character.

The characters inside the double quotes can include escape sequences, e.g.

"\t\"Name\"\\\tAddress\n\n"

Adjacent string literals separated only by whitespace are concatenated during the parsing phase. For example:

"This is " "just"

" an example." is an equivalent to

"This is just an example."

Line continuation with backslash

You can also use the backslash (

\

) as a continuation character to extend a string constant across line boundaries:

"This is really \ a one-line string." page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Enumeration Constants

Enumeration constants are identifiers defined in enum type declarations. The identifiers are usually chosen as mnemonics to assist legibility. Enumeration constants are of int type. They can be used in any expression where integer constants are valid.

For example:

enum weekdays {SUN = 0, MON, TUE, WED, THU, FRI, SAT};

The identifiers (enumerators) used must be unique within the scope of the enum declaration. Negative initializers are allowed. See Enumerations for details of enum declarations.

Pointer Constants

A pointer or the pointed-at object can be declared with the const modifier.

Anything declared as a const cannot be have its value changed. It is also illegal to create a pointer that might violate the nonassignability of a constant object.

Constant Expressions

A constant expression is an expression that always evaluates to a constant and consists only of constants (literals) or symbolic constants. It is evaluated at compile-time and it must evaluate to a constant that is in the range of representable values for its type. Constant expressions are evaluated just as regular expressions are.

Constant expressions can consist only of the following: literals, enumeration constants, simple constants (no constant arrays or structures), sizeof operators.

Constant expressions cannot contain any of the following operators, unless the operators are contained within the operand of a sizeof operator: assignment, comma, decrement, function call, increment.

You can use a constant expression anywhere that a constant is legal.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

KEYWORDS

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

Beside standard C 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 C: asm auto break case char const continue default do double else enum extern float for goto if int long register return short signed sizeof static struct switch typedef union unsigned void volatile while

Also, mikroC 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 mikroC Libraries.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IDENTIFIERS

Identifiers are arbitrary names of any length given to functions, variables, symbolic 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

mikroC identifiers are not case sensitive at present, so that

Sum

, sum

, and suM represent an equivalent identifier. However, future versions of mikroC will offer the option of activating/suspending case sensitivity. The only exceptions at present are the reserved words main and interrupt which must be written in lowercase.

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 regardless of scope rules. For more information on scope, refer to Scope and Visibility.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PUNCTUATORS

The mikroC punctuators (also known as separators) include brackets, parentheses, braces, comma, semicolon, colon, asterisk, equal sign, and pound sign. Most of these punctuators also function as operators.

Brackets

Brackets

[ ] indicate single and multidimensional array subscripts:

char ch, str[] = "mikro";

int mat[3][4]; ch = str[3];

/* 3 x 4 matrix */

/* 4th element */

Parentheses

Parentheses

( ) are used to group expressions, isolate conditional expressions, and indicate function calls and function parameters: d = c * (a + b);

if (d == z) ++x; func();

/* override normal precedence */

/* essential with conditional statement */

/* function call, no args */

void func2( int n);

/* function declaration with parameters */

Parentheses are recommended in macro definitions to avoid potential precedence problems during expansion:

#define CUBE(x) ((x)*(x)*(x))

For more information, refer to Expressions and Operators Precedence.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Braces

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Braces

{ } indicate the start and end of a compound statement:

if (d == z) {

++x; func();

}

The closing brace serves as a terminator for the compound statement, so a semicolon is not required after the }, except in structure declarations. Often, the semicolon is illegal, as in

if (statement)

{ ... }; /* illegal semicolon! */

else

{ ... };

For more information, refer to Compound Statements.

Comma

The comma (

,

) separates the elements of a function argument list:

void func(int n, float f, char ch);

The comma is also used as an operator in comma expressions. Mixing the two uses of comma is legal, but you must use parentheses to distinguish them. Note that ( exp1

, exp2

) evalutates both but is equal to the second:

/* call func with two args */

func(i, j);

/* also calls func with two args! */

func((exp1, exp2), (exp3, exp4, exp5)); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Semicolon

The semicolon (

;

) is a statement terminator. Any legal C expression (including the empty expression) followed by a semicolon is interpreted as a statement, known as an expression statement. The expression is evaluated and its value is discarded. If the expression statement has no side effects, mikroC might ignore it.

a + b;

++a;

;

/* evaluate a + b, but discard value */

/* side effect on a, but discard value of ++a */

/* empty expression or a null statement */

Semicolons are sometimes used to create an empty statement:

for (i = 0; i < n; i++) ;

For more information, see Statements.

Colon

Use the colon (

:

) to indicate a labeled statement. For example: start: x = 0;

...

goto start;

Labels are discussed in Labeled Statements.

Asterisk (Pointer Declaration)

The asterisk (

*

) in a declaration denotes the creation of a pointer to a type:

char *char_ptr; /* a pointer to char is declared */

You can also use the asterisk as an operator to either dereference a pointer or as the multiplication operator: i = *char_ptr;

For more information, see Pointers.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Equal Sign

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

The equal sign (

=

) separates variable declarations from initialization lists:

int test[5] = {1, 2, 3, 4, 5};

int x = 5;

The equal sign is also used as the assignment operator in expressions:

int a, b, c; a = b + c;

For more information, see Assignment Operators.

Pound Sign (Preprocessor Directive)

The pound sign (

#

) indicates a preprocessor directive when it occurs as the first nonwhitespace character on a line. It signifies a compiler action, not necessarily associated with code generation. See Preprocessor Directives for more information.

# and

## are also used as operators to perform token replacement and merging during the preprocessor scanning phase. See Preprocessor Operators.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

OBJECTS AND LVALUES

Objects

An object is a specific region of memory that can hold a fixed or variable value

(or set of values). To prevent confusion, this use of the word object is different from the more general term used in object-oriented languages. Our definiton of the word would encompass functions, variables, symbolic constants, user-defined data types, and labels.

Each value has an associated name and type (also known as a data type). The name is used to access the object. This name can be a simple identifier, or it can be a complex expression that uniquely references the object.

Objects and Declarations

Declarations establish the necessary mapping between identifiers and objects.

Each declaration associates an identifier with a data type.

Associating identifiers with objects requires each identifier to have at least two attributes: storage class and type (sometimes referred to as data type). The mikroC compiler deduces these attributes from implicit or explicit declarations in the source code. Commonly, only the type is explicitly specified and the storage class specifier assumes automatic value auto.

Generally speaking, an identifier cannot be legally used in a program before its declaration point in the source code. Legal exceptions to this rule (known as forward references) are labels, calls to undeclared functions, and struct or union tags.

The range of objects that can be declared includes: variables; functions; types; arrays of other types; structure, union, and enumeration tags; structure members; union members; enumeration constants; statement labels; preprocessor macros.

The recursive nature of the declarator syntax allows complex declarators. You’ll probably want to use typedefs to improve legibility if constructing complex objects.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Lvalues

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

An lvalue is an object locator: an expression that designates an object. An example of an lvalue expression is

*P

, where

P is any expression evaluating to a non-null pointer. A modifiable lvalue is an identifier or expression that relates to an object that can be accessed and legally changed in memory. A const pointer to a constant, for example, is not a modifiable lvalue. A pointer to a constant can be changed

(but its dereferenced value cannot).

Historically, the l stood for “left”, meaning that an lvalue could legally stand on the left (the receiving end) of an assignment statement. Now only modifiable lvalues can legally stand to the left of an assignment operator. For example, if a and b are nonconstant integer identifiers with properly allocated memory storage, they are both modifiable lvalues, and assignments such as a = 1 and b = a + b are legal.

Rvalues

The expression a + b is not an lvalue: a + b = a is illegal because the expression on the left is not related to an object. Such expressions are sometimes called

rvalues (short for right values).

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

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: block (or local), function, function prototype, and file. These depend on how and where identifiers are declared.

Block Scope

The scope of an identifier with block (or local) scope starts at the declaration point and ends at the end of the block containing the declaration (such a block is known as the enclosing block). Parameter declarations with a function definition also have block scope, limited to the scope of the function body.

File Scope

File scope identifiers, also known as globals, are declared outside of all blocks; their scope is from the point of declaration to the end of the source file.

Function Scope

The only identifiers having function scope are statement labels. Label names can be used with goto statements anywhere in the function in which the label is declared. Labels are declared implicitly by writing label_name: followed by a statement. Label names must be unique within a function.

Function Prototype Scope

Identifiers declared within the list of parameter declarations in a function prototype (not part of a function definition) have function prototype scope. This scope ends at the end of the function prototype.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Visibility

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

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. Take a look at the following example:

void f (int i) {

int j; j = 3;

// auto by default

// int i and j are in scope and visible

{

double j; j = 0.1;

// nested block

// j is local name in the nested block

// i and double j are visible;

// int j = 3 in scope but hidden

}

} j += 1;

// double j out of scope

// int j visible and = 4

// i and j are both out of scope

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

NAME SPACES

Name space is the scope within which an identifier must be unique. C uses four distinct categories of identifiers:

Goto label names

These must be unique within the function in which they are declared.

Structure, union, and enumeration tags

These must be unique within the block in which they are defined. Tags declared outside of any function must be unique.

Structure and union member names

These must be unique within the structure or union in which they are defined.

There is no restriction on the type or offset of members with the same member name in different structures.

Variables, typedefs, functions, and enumeration members

These must be unique within the scope in which they are defined. Externally declared identifiers must be unique among externally declared variables.

Duplicate names are legal for different name spaces regardless of scope rules.

For example:

int blue = 73;

{ // open a block

enum colors { black, red, green, blue, violet, white } c;

/* enumerator blue hides outer declaration of int blue */

struct colors { int i, j; };

// ILLEGAL: colors duplicate tag

double red = 2;

// ILLEGAL: redefinition of red

} blue = 37; // back in int blue scope page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

DURATION

Duration, closely related to storage class, defines the period during which the declared identifiers have real, physical objects allocated in memory. We also distinguish between compile-time and run-time objects. Variables, for instance, unlike typedefs and types, have real memory allocated during run time. There are two kinds of duration: static and local.

Static Duration

Memory is allocated to objects with static duration as soon as execution is underway; this storage allocation lasts until the program terminates. Static duration objects usually reside in fixed data segments allocated according to the memory model in force. All globals have static duration. All functions, wherever defined, are objects with static duration. Other variables can be given static duration by using the explicit static or extern storage class specifiers.

In mikroC, static duration objects are not initialized to zero (or null) in the absence of any explicit initializer.

An object can have static duration and local scope – see the example on the following page.

Local Duration

Local duration objects are also known as automatic objects. They are created on the stack (or in a register) when the enclosing block or function is entered. They are deallocated when the program exits that block or function. Local duration objects must be explicitly initialized; otherwise, their contents are unpredictable.

The storage class specifier auto can be used when declaring local duration variables, but is usually redundant, because auto is the default for variables declared within a block.

An object with local duration also has local scope, because it does not exist outside of its enclosing block. The converse is not true: a local scope object can have static duration.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Here is an example of two objects with local scope, but with different duration:

void f() {

/* local duration var; init a upon every call to f */

int a = 1;

/* static duration var; init b only upon 1st call to f */

static int b = 1;

}

/* checkpoint! */

a++; b++;

void main() {

/* At checkpoint, we will have: */

f();

// a=1, b=1, after first call,

f();

// a=1, b=2, after second call,

f();

// a=1, b=3, after third call,

// etc.

} page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

TYPES

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

C is strictly typed language, which means that every object, function, and expression need to have a strictly defined type, known in the time of compilation. Note that C works exclusively with numeric types.

The type serves:

- to determine the correct memory allocation required initially,

- to interpret the bit patterns found in the object during subsequent accesses,

- in many type-checking situations, to ensure that illegal assignments are trapped.

mikroC supports many standard (predefined) and user-defined data types, including signed and unsigned integers in various sizes, floating-point numbers in various precisions, arrays, structures, and unions. In addition, pointers to most of these objects can be established and manipulated in memory.

The type determines how much memory is allocated to an object and how the program will interpret the bit patterns found in the object’s storage allocation. A given data type can be viewed as a set of values (often implementation-dependent) that identifiers of that type can assume, together with a set of operations allowed on those values. The compile-time operator, sizeof

, lets you determine the size in bytes of any standard or user-defined type.

The mikroC standard libraries and your own program and header files must provide unambiguous identifiers (or expressions derived from them) and types so that mikroC can consistently access, interpret, and (possibly) change the bit patterns in memory corresponding to each active object in your program.

Type Categories

The fudamental types represent types that cannot be separated into smaller parts.

They are sometimes referred to as unstructured types. The fundamental types are void

, char

, int

, float

, and double

, together with short

, long

, signed

, and unsigned variants of some of these.

The derived types are also known as structured types. The derived types include pointers to other types, arrays of other types, function types, structures, and unions.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

FUNDAMENTAL TYPES

Arithmetic Types

The arithmetic type specifiers are built from the following keywords: void

, char

, int

, float

, and double

, together with prefixes short

, long

, signed

, and unsigned

. From these keywords you can build the integral and floating-point types. Overview of types is given on the following page.

Integral Types

Types char and int

, together with their variants, are considered integral data types. Variants are created by using one of the prefix modifiers short

, long

, signed

, and unsigned

.

The table below is the overview of the integral types – keywords in parentheses can be (and often are) omitted.

The modifiers signed and unsigned can be applied to both char and int. In the absence of unsigned prefix, signed is automatically assumed for integral types.

The only exception is the char, which is unsigned by default. The keywords signed and unsigned

, when used on their own, mean signed int and unsigned int

, respectively.

The modifiers short and long can be applied only to the int

. The keywords short and long used on their own mean short int and long int

, respectively.

Floating-point Types

Types float and double

, together with the long double variant, are considered floating-point types. mikroC’s implementation of ANSI Standard considers all three to be the same type.

Floating point in mikroC is implemented using the Microchip AN575 32-bit format (IEEE 754 compliant).

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Below is the overview of arithmetic types:

Type

(unsigned) char signed char

(signed) short (int) unsigned short (int)

(signed) int unsigned (int)

(signed) long (int) unsigned long (int) float double long double

Size

16-bit

16-bit

32-bit

32-bit

8-bit

8-bit

8-bit

8-bit

32-bit

32-bit

32-bit

Range

0 .. 255

- 128 .. 127

- 128 .. 127

0 .. 255

-32768 .. 32767

0 .. 65535

-2147483648 .. 2147483647

0 .. 4294967295

±1.17549435082E-38 ..

±6.80564774407E38

±1.17549435082E-38 ..

±6.80564774407E38

±1.17549435082E-38 ..

±6.80564774407E38

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Enumerations

An enumeration data type is used for representing an abstract, discreet set of values with appropriate symbolic names.

Enumeration Declaration

Enumeration is declared like this:

enum tag {enumeration-list};

Here,

tag

is an optional name of the enumeration;

enumeration-list

is a list of discreet values, enumerators. The enumerators listed inside the braces are also known as enumeration constants. Each is assigned a fixed integral value. In the absence of explicit initializers, the first enumerator is set to zero, and each succeeding enumerator is set to one more than its predecessor.

Variables of enum type are declared same as variables of any other type. For example, the following declaration

enum colors {black, red, green, blue, violet, white} c; establishes a unique integral type, colors

, a variable c of this type, and a set of enumerators with constant integer values ( black = 0

, red = 1

, ...). In C, a variable of an enumerated type can be assigned any value of type int

– no type checking beyond that is enforced. That is: c = red; c = 1;

// OK

// Also OK, means the same

With explicit integral initializers, you can set one or more enumerators to specific values. The initializer can be any expression yielding a positive or negative integer value (after possible integer promotions). Any subsequent names without initializers will then increase by one. These values are usually unique, but duplicates are legal.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

The order of constants can be explicitly re-arranged. For example:

enum colors { black, red, green, blue=6, violet,

// value 0

// value 1

// value 2

// value 6

// value 7

white=4 };

// value 4

Initializer expression can include previously declared enumerators. For example, in the following declaration:

enum memory_sizes { bit = 1, nibble = 4 * bit, byte = 2 * nibble, kilobyte = 1024 * byte }; nibble would acquire the value 4, byte the value 8, and kilobyte the value

8192.

Anonymous Enum Type

In our previous declaration, the identifier colors is the optional enumeration tag that can be used in subsequent declarations of enumeration variables of type colors

:

enum colors bg, border; // declare variables bg and border

As with struct and union declarations, you can omit the tag if no further variables of this enum type are required:

/* Anonymous enum type: */

enum {black, red, green, blue, violet, white} color;

Enumeration Scope

Enumeration tags share the same name space as structure and union tags.

Enumerators share the same name space as ordinary variable identifiers. For more information, consult Name Spaces.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Void Type

void is a special type indicating the absence of any value. There are no objects of void

; instead, void is used for deriving more complex types.

Void Functions

Use the void keyword as a function return type if the function does not return a value. For example:

void print_temp(char temp) {

Lcd_Out_Cp("Temperature:");

Lcd_Out_Cp(temp);

Lcd_Chr_Cp(223); // degree character

Lcd_Chr_Cp('C');

}

Use void as a function heading if the function does not take any parameters.

Alternatively, you can just write empty parentheses: main( void) { // same as main()

...

}

Generic Pointers

Pointers can be declared as void

, meaning that they can point to any type. These pointers are sometimes called generic.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

DERIVED TYPES

The derived types are also known as structured types. These types are used as elements in creating more complex user-defined types.

Arrays

Array is the simplest and most commonly used structured type. Variable of array type is actually an array of objects of the same type. These objects represent elements of an array and are identified by their position in array. An array consists of a contiguous region of storage exactly large enough to hold all of its elements.

Array Declaration

Array declaration is similar to variable declaration, with the brackets added after identifer:

type array_name[constant-expression]

This declares an array named as

array_name

composed of elements of

type

.

The

type

can be scalar type (except void

), user-defined type, pointer, enumeration, or another array. Result of the

constant-expression

within the brackets determines the number of elements in array. If an expression is given in an array declarator, it must evaluate to a positive constant integer. The value is the number of elements in the array.

Each of the elements of an array is numbered from 0 through the number of elements minus one. If the number is n

, elements of array can be approached as variables

array_name[0]

..

array_name[n-1] of

type

.

Here are a few examples of array declaration:

#define MAX = 50

int vector_one[10];

float vector_two[MAX];

float vector_three[MAX - 20];

/* an array of 10 integers */

/* an array of 50 floats */

/* an array of 30 floats */

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Array Initialization

Array can be initialized in declaration by assigning it a comma-delimited sequence of values within braces. When initializing an array in declaration, you can omit the number of elements – it will be automatically determined acording to the number of elements assigned. For example:

/* An array which holds number of days in each month: */

int days[12] = {31,28,31,30,31,30,31,31,30,31,30,31};

/* This declaration is identical to the previous one */

int days[] = {31,28,31,30,31,30,31,31,30,31,30,31};

If you specify both the length and starting values, the number of starting values must not exceed the specified length. Vice versa is possible, when the trailing

“excess” elements will be assigned some encountered runtime values from memory.

In case of array of char

, you can use a shorter string literal notation. For example:

/* The two declarations are identical: */

const char msg1[] = {'T', 'e', 's', 't', '\0'};

const char msg2[] = "Test";

For more information on string literals, refer to String Constants.

Arrays in Expressions

When name of the array comes up in expression evaluation (except with operators

& and sizeof

), it is implicitly converted to the pointer pointing to array’s first element. See Arrays and Pointers for more information.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC 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:

float m[50][20]; /* 2-dimensional array of size 50x20 */

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

Thus, we have a matrix of 50x20 elements: the first element is m[0][0]

, the 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 dimension 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:

int a[3][2][4]; /* 3-dimensional array of size 3x2x4 */

void func(int n[][2][4]) { /* we can omit first dimension */

//...

n[2][1][3]++; /* increment the last element*/

}//~

void main() {

//...

func(a);

}//~!

You can initialize a multi-dimensional array with an appropriate set of values within braces. For example:

int a[3][2] = {{1,2}, {2,6}, {3,7}}; page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Pointers

Pointers are special objects for holding (or “pointing to”) memory addresses. In C, address of an object in memory can be obtained by means of unary operator

&

. To reach the pointed object, we use indirection operator (

*

) on a pointer.

A pointer of type “pointer to object of type” holds the address of (that is, points to) an object of type. Since pointers are objects, you can have a pointer pointing to a pointer (and so on). Other objects commonly pointed at include arrays, structures, and unions.

A pointer to a function is best thought of as an address, usually in a code segment, where that function’s executable code is stored; that is, the address to which control is transferred when that function is called.

Although pointers contain numbers with most of the characteristics of unsigned integers, they have their own rules and restrictions for declarations, assignments, conversions, and arithmetic. The examples in the next few sections illustrate these rules and restrictions.

Note: Currently, mikroC does not support pointers to functions, but this feature will be implemented in future versions.

Pointer Declarations

Pointers are declared same as any other variable, but with

* ahead of identifier.

Type at the beginning of declaration specifies the type of a pointed object. A pointer must be declared as pointing to some particular type, even if that type is void

, which really means a pointer to anything. Pointers to void are often called gener-

ic pointers, and are treated as pointers to char in mikroC.

If type is any predefined or user-defined type, including void, the declaration

type *p; /* Uninitialized pointer */ declares p to be of type “pointer to

type

”. All the scoping, duration, and visibility rules apply to the p object just declared. You can view the declaration in this way: if

*p is an object of

type

, then p has to be a pointer to such objects.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Note: You must initialize pointers before using them! Our previously declared pointer

*p is not initialized (i.e. assigned a value), so it cannot be used yet.

Note: In case of multiple pointer declarations, each identifier requires an indirect operator. For example:

int *pa, *pb, *pc;

/* is same as: */

int *pa;

int *pb;

int *pc;

Once declared, though, a pointer can usually be reassigned so that it points to an object of another type. mikroC lets you reassign pointers without typecasting, but the compiler will warn you unless the pointer was originally declared to be pointing to void

. You can assign a void pointer to a non-void pointer – refer to Void

Type for details.

Null Pointers

A null pointer value is an address that is guaranteed to be different from any valid pointer in use in a program. Assigning the integer constant 0 to a pointer assigns a null pointer value to it. Instead of zero, the mnemonic

NULL

(defined in the standard library header files, such as stdio.h

) can be used for legibility. All pointers can be successfully tested for equality or inequality to

NULL

.

For example:

int *pn = 0; /* Here's one null pointer */

int *pn = NULL; /* This is an equivalent declaration */

/* We can test the pointer like this: */

if ( pn == 0 ) { ... }

/* .. or like this: */

if ( pn == NULL ) { ... } page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Function Pointers

Function Pointers are pointers, i.e. variables, which point to the address of a function.

// Define a function pointer

int (*pt2Function) (float, char, char);

Note: Thus functions and function pointers with different calling convention

(argument order, arguments type or return type is different) are incompatible with each other.

Assign an address to a Function Pointer

It's quite easy to assign the address of a function to a function pointer. You simply take the name of a suitable and known function or member function. It's optional to use the address operator & infront of the function's name.

//Assign an address to the function pointer

int DoIt (float a, char b, char c){ return a+b+c; } pt2Function = &DoIt; // assignment page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Example:

int addC(char x,char y){

}

return x+y;

int subC(char x,char y){

}

return x-y;

int mulC(char x,char y){

}

return x*y;

int divC(char x,char y){

}

return x/y;

int modC(char x,char y){

}

return x%y;

//array of pointer to functions that receive two chars and returns int

int

(*arrpf[])( char,char) = { addC ,subC,mulC,divC,modC};

int res;

char i;

void main() {

for (i=0;i<5;i++){ res = arrpf[i](10,20);

}

}//~! page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Pointer Arithmetic

Pointer arithmetic in C is limited to:

- assigning one pointer to another,

- comparing two pointers,

- comparing pointer to zero (

NULL

),

- adding/subtracting pointer and an integer value,

- subtracting two pointers.

The internal arithmetic performed on pointers depends on the memory model in force and the presence of any overriding pointer modifiers. When performing arithmetic with pointers, it is assumed that the pointer points to an array of objects.

Arrays and Pointers

Arrays and pointers are not completely independent types in C. When name of the array comes up in expression evaluation (except with operators

& and sizeof

), it is implicitly converted to the pointer pointing to array’s first element. Due to this fact, arrays are not modifiable lvalues.

Brackets

[ ] indicate array subscripts. The expression

id[exp] is defined as

*((id) + (exp)) where either:

id

is a pointer and

exp

is an integer, or

id

is an integer and

exp

is a pointer.

The following is true:

&a[i] = a + i a[i] = *(a + i) page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

According to these guidelines, we can write: pa = &a[4]; x = *(pa + 3); y = *pa + 3;

// pa points to a[4]

// x = a[7]

// y = a[4] + 3

Also, you need to be careful with operator precedence:

*pa++;

(*pa)++;

// is equal to *(pa++), increments the pointer!

// increments the pointed object!

Following examples are also valid, but better avoid this syntax as it can make the code really illegible:

(a + 1)[i] = 3;

// same as: *((a + 1) + i) = 3, i.e. a[i + 1] = 3

(i + 2)[a] = 0;

// same as: *((i + 2) + a) = 0, i.e. a[i + 2] = 0

Assignment and Comparison

You can use a simple assignment operator (

=

) to assign value of one pointer to another if they are of the same type. If they are of different types, you must use a typecast operator. Explicit type conversion is not necessary if one of the pointers is generic (of void type).

Assigning the integer constant 0 to a pointer assigns a null pointer value to it. The mnemonic

NULL

(defined in the standard library header files, such as stdio.h

) can be used for legibility.

Two pointers pointing into the same array may be compared by using relational operators

==

,

!=

,

<

,

<=

,

>

, and

>=

. Results of these operations are same as if they were used on subscript values of array elements in question:

int *pa = &a[4], *pb = &a[2];

if (pa > pb) { ...

// this will be executed as 4 is greater than 2

} page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

You can also compare pointers to zero value – this tests if pointer actually points to anything. All pointers can be successfully tested for equality or inequality to

NULL:

if (pa == NULL) { ... }

if (pb != NULL) { ... }

Note: Comparing pointers pointing to different objects/arrays can be performed at programmer’s responsibility — precise overview of data’s physical storage is required.

Pointer Addition

You can use operators

+

,

++

, and

+= to add an integral value to a pointer. The result of addition is defined only if pointer points to an element of an array and if the result is a pointer pointing into the same array (or one element beyond it).

If a pointer is declared to point to

type

, adding an integral value to the pointer advances the pointer by that number of objects of type. Informally, you can think of

P+n as advancing the pointer

P by

(n*sizeof(type)) bytes, as long as the pointer remains within the legal range (first element to one beyond the last element). If

type

has size of 10 bytes, then adding 5 to a pointer to

type

advances the pointer 50 bytes in memory. In case of void type, size of the step is one byte.

For example:

int a[10];

int *pa = &a[0];

// array a containing 10 elements of int

// pa is pointer to int, pointing to a[0]

*(pa + 3) = 6;

// pa+3 is a pointer pointing to a[3],

// so a[3] now equals 6

pa++; // pa now points to the next element of array, a[1]

There is no such element as “one past the last element”, of course, but a pointer is allowed to assume such a value. C “guarantees” that the result of addition is defined even when pointing to one element past array. If

P points to the last array element,

P+1 is legal, but

P+2 is undefined.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

This allows you to write loops which access the array elements in a sequence by means of incrementing pointer — in the last iteration you will have a pointer pointing to one element past an array, which is legal. However, applying the indirection operator (

*

) to a “pointer to one past the last element” leads to undefined behavior.

For example:

void f (some_type a[], int n) {

/* function f handles elements of array a; */

/* array a has n elements of some_type */

int i; some_type *p = &a[0];

}

for (i = 0; i < n; i++) {

/* .. here we do something with *p .. */

p++;

/* .. and with the last iteration p exceeds the last element of array a */

}

/* at this point, *p is undefined! */

Pointer Subtraction

Similar to addition, you can use operators

-

,

--

, and

-= to subtract an integral value from a pointer.

Also, you may subtract two pointers. Difference will equal the distance between the two pointed addresses, in bytes.

For example:

int a[10];

int *pi1 = &a[0], *pi2 = &[4]; i = pi2 - pi1; pi2 -= (i >> 1);

// i equals 8

// pi2 = pi2 - 4: pi2 now points to a[0]

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Structures

A structure is a derived type usually representing a user-defined collection of named members (or components). The members can be of any type, either fundamental or derived (with some restrictions to be noted later), in any sequence. In addition, a structure member can be a bit field type not allowed elsewhere.

Unlike arrays, structures are considered single objects. The mikroC structure type lets you handle complex data structures almost as easily as single variables.

Note: mikroC does not support anonymous structures (ANSI divergence).

Structure Declaration and Initialization

Structures are declared using the keyword struct

:

struct tag { member-declarator-list };

Here,

tag

is the name of the structure;

member-declarator-list

is a list of structure members, actually a list of variable declarations. Variables of structured type are declared same as variables of any other type.

The member type cannot be the same as the struct type being currently declared.

However, a member can be a pointer to the structure being declared, as in the following example:

struct mystruct { mystruct s;};

struct mystruct { mystruct *ps;};

/* illegal! */

/* OK */

Also, a structure can contain previously defined structure types when declaring an instance of a declared structure. Here is an example:

/* Structure defining a dot: */

struct Dot {float x, y;};

/* Structure defining a circle: */

struct Circle {

double r;

struct Dot center;

} o1, o2; /* declare variables o1 and o2 of circle type */ page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Note that you can omit structure tag, but then you cannot declare additional objects of this type elsewhere. For more information, see the “Untagged

Structures” below.

Structure is initialized by assigning it a comma-delimited sequence of values within braces, similar to array. Referring to declarations from the previous example:

/* Declare and initialize dots p and q: */

struct Dot p = {1., 1.}, q = {3.7, -0.5};

/* Initialize already declared circles o1 and o2: */

o1 = {1, {0, 0}};

// r is 1, center is at (0, 0)

o2 = {4, { 1.2, -3 }};

// r is 4, center is at (1.2, -3)

Incomplete Declarations

Incomplete declarations are also known as forward declarations. A pointer to a structure type

A can legally appear in the declaration of another structure

B before

A has been declared:

struct A;

// incomplete

struct B {struct A *pa;};

struct A {struct B *pb;};

The first appearance of

A is called incomplete because there is no definition for it at that point. An incomplete declaration is allowed here, because the definition of

B doesn’t need the size of

A

.

Untagged Structures and Typedefs

If you omit the structure tag, you get an untagged structure. You can use untagged structures to declare the identifiers in the comma-delimited struct-id-list to be of the given structure type (or derived from it), but you cannot declare additional objects of this type elsewhere.

It is possible to create a typedef while declaring a structure, with or without a tag:

typedef struct { ... } Mystruct;

Mystruct s, *ps, arrs[10]; page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Structure Assignment

Variables of same structured type may be assigned one to another by means of simple assignment operator (

=

). This will copy the entire contents of the variable to destination, regardless of the inner complexitiy of a given structure.

Note that two variables are of same structured type only if they were both defined by the same instruction or were defined using the same type identifier. For example:

/* a and b are of the same type: */

struct {int m1, m2;} a, b;

/* But c and d are _not_ of the same type although their structure descriptions are identical: */

struct {int m1, m2;} c;

struct {int m1, m2;} d;

Size of Structure

You can get size of the structure in memory by means of operator sizeof

. Size of the structure does not necessarily need to be equal to the sum of its members’ sizes. It is often greater due to certain limitations of memory storage.

Structures and Functions

A function can return a structure type or a pointer to a structure type: mystruct func1();

// func1() returns a structure

mystruct *func2();

// func2() returns pointer to structure

A structure can be passed as an argument to a function in the following ways:

void func1(mystruct s);

void func2(mystruct *sptr);

// directly

// via pointer

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Structure Member Access

Structure and union members are accessed using the following two selection operators:

.

(period)

->

(right arrow)

The operator

.

is called the direct member selector and it is used to directly access one of the structure’s members. Suppose that the object s is of struct type

S

. Then if m is a member identifier of type

M declared in s

, the expression s.m

// direct access to member m

is of type

M

, and represents the member object m in s

.

The operator

-> is called the indirect (or pointer) member selector. Suppose that ps is a pointer to s

. Then if m is a member identifier of type

M declared in s

, the expression ps->m

// indirect access to member m;

// identical to (*ps).m

is of type

M

, and represents the member object m in s

. The expression ps->m is a convenient shorthand for

(*ps).m

.

For example:

struct mystruct {

int i; char str[10]; double d;

} s, *sptr = &s;

.

.

.

s.i = 3; sptr -> d = 1.23;

// assign to the i member of mystruct s

// assign to the d member of mystruct s

The expression s.m

is an lvalue, provided that s is an lvalue and m is not an array type. The expression sptr->m is an lvalue unless m is an array type.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Accessing Nested Structures

If structure

B contains a field whose type is structure

A

, the members of

A can be accessed by two applications of the member selectors:

struct A {

int j; double x;

};

struct B {

int i; struct A a; double d;

} s, *sptr;

//...

s.i = 3; s.a.j = 2;

// assign 3 to the i member of B

// assign 2 to the j member of A

sptr->d = 1.23;

// assign 1.23 to the d member of B

sptr->a.x = 3.14;

// assign 3.14 to x member of A

Structure Uniqueness

Each structure declaration introduces a unique structure type, so that in

struct A {

int i,j; double d;

} aa, aaa;

struct B {

int i,j; double d;

} bb; the objects aa and aaa are both of type struct

A

, but the objects aa and bb are of different structure types. Structures can be assigned only if the source and destination have the same type: aa = aaa; /* OK: same type, member by member assignment */ aa = bb; /* ILLEGAL: different types */

/* but you can assign member by member: */

aa.i = bb.i; aa.j = bb.j; aa.d = bb.d; page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Unions

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Union types are derived types sharing many of the syntactic and functional features of structure types. The key difference is that a union allows only one of its members to be “active” at any given time, the most recently changed member.

Note: mikroC does not support anonymous unions (ANSI divergence).

Union Declaration

Unions are declared same as structures, with the keyword union used instead of struct

:

union tag { member-declarator-list };

Unlike structures’ members, the value of only one of union’s members can be stored at any time. Let’s have a simple example:

union myunion { // union tag is 'myunion'

int i;

double d;

char ch;

} mu, *pm = &mu;

The identifier mu

, of type union myunion

, can be used to hold a 2-byte int

, a

4-byte double

, or a single-byte char

, but only one of these at any given time.

Size of Union

The size of a union is the size of its largest member. In our previous example, both sizeof(union myunion) and sizeof(mu) return 4, but 2 bytes are unused

(padded) when mu holds an int object, and 3 bytes are unused when mu holds a char

.

Union Member Access

Union members can be accessed with the structure member selectors (

.

and

->

), but care is needed. Check the example on the following page.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Referring to declarations from the previous example: mu.d = 4.016;

Lcd_Out_Cp(FloatToStr(mu.d));

Lcd_Out_Cp(IntToStr(mu.i)); pm->i = 3;

Lcd_Out_Cp(IntToStr(mu.i));

// OK: displays mu.d = 4.016

// peculiar result

// OK: displays mu.i = 3

The second

Lcd_Out_Cp is legal, since mu.i

is an integral type. However, the bit pattern in mu.i

corresponds to parts of the previously assigned double

. As such, it probably does not provide a useful integer interpretation.

When properly converted, a pointer to a union points to each of its members, and vice versa.

Bit Fields

Bit fields are specified numbers of bits that may or may not have an associated identifier. Bit fields offer a way of subdividing structures into named parts of userdefined sizes.

Structures and unions can contain bit fields. Bit fields can be up to 16 bits.

You cannot take the address of a bit field.

Note: If you need to handle specific bits of 8-bit variables (char and unsigned short) or registers, you don’t need to declare bit fields. Much more elegant solution is to use mikroC’s intrinsic ability for individual bit access — see Accessing

Individual Bits for more information.

Bit Fields Declaration

Bit fields can be declared only in structures. Declare a structure normally, and assign individual fields like this (fields need to be unsigned):

struct tag { unsigned bitfield-declarator-list; } page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Here, tag is an optional name of the structure; bitfield-declarator-list is a list of bit fields. Each component identifer requires a colon and its width in bits to be explicitly specified. Total width of all components cannot exceed two bytes (16 bits).

As an object, bit fields structure takes two bytes. Individual fields are packed within two bytes from right to left. In bitfield-declarator-list, you can omit identifier(s) to create artificial “padding”, thus skipping irrelevant bits.

For example, if we need to manipulate only bits 2–4 of a register as one block, we could create a structure:

struct {

unsigned

: 2, mybits : 3;

} myreg;

// Skip bits 0 and 1, no identifier here

// Relevant bits 2, 3, and 4

// Bits 5, 6, and 7 are implicitly left out

Here is an example:

typedef struct { prescaler : 2; timeronoff : 1; postscaler : 4;} mybitfield; which declares structured type mybitfield containing three components: prescaler

(bits 0 and 1), timeronoff

(bit 2), and postscaler

(bits 3, 4, 5, and 6).

Bit Fields Access

Bit fields can be accessed in same way as the structure members. Use direct and indirect member selector (

.

and

->

). For example, we could work with our previously declared mybitfield like this:

// Declare a bit field TimerControl:

mybitfield TimerControl;

void main() {

TimerControl.prescaler = 0;

TimerControl.timeronoff = 1;

TimerControl.postscaler = 3;

T2CON = TimerControl;

} page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TYPES CONVERSIONS

C is strictly typed language, with each operator, statement and function demanding appropriately typed operands/arguments. However, we often have to use objects of

“mismatching” types in expressions. In that case, type conversion is needed.

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). C defines a set of standard conversions for built-in types, provided by compiler when necessary.

Conversion is required in following situations:

- if statement requires an expression of particular type (according to language definition), and we use an expression of different type,

- if operator requires an operand of particular type, and we use an operand of different type,

- if a function requires a formal parameter of particular type, and we pass it an object of different type,

- if an expression following the keyword return does not match the declared function return type,

- if intializing an object (in declaration) with an object of different type.

In these situations, compiler will provide an automatic implicit conversion of types, without any user interference. Also, user can demand conversion explicitly by means of typecast operator. For more information, refer to Explicit

Typecasting.

Standard Conversions

Standard conversions are built in C. These conversions are performed automatically, whenever required in the program. They can be also explicitly required by means of typecast operator (refer to Explicit Typecasting).

The basic rule of automatic (implicit) conversion is that the operand of simpler type is converted (promoted) to the type of more complex operand. Then, type of the result is that of more complex operand.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Arithmetic Conversions

When you use an arithmetic expression, such as a+b

, where a and b are of different arithmetic types, mikroC 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 signed char always use sign extension; objects of type unsigned char 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.

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

1. char converts to int

2. signed char converts to int

, with the same value

3. short converts to int

, with the same value, sign-extended

4. unsigned short converts to unsigned int, with the same value, zero-filled

5. enum converts to int

, with the same value

After this, any two values associated with an operator are either int

(including the long and unsigned modifiers), or they are float (equivalent with double and long double in mikroC).

1. If either operand is float

, the other operand is converted to float

2. Otherwise, if either operand is unsigned long

, the other operand is converted to unsigned long

3. Otherwise, if either operand is long

, the other operand is converted to long

4. Otherwise, if either operand is unsigned

, the other operand is converted to u nsigned

5. Otherwise, both operands are int page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

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

5/4*3.

3.*5/4

// = 2. + 3.1 = 5.1

// = (5/4)*3. = 1*3. = 1.*3. = 3.0

// = (3.*5)/4 = (3.*5.)/4 = 15./4 = 15./4. = 3.75

Pointer Conversions

Pointer types can be converted to other pointer types using the typecasting mechanism:

char *str;

int *ip; str = (

char *)ip;

More generally, the cast (

type*

) will convert a pointer to type “pointer to

type

”.

Explicit Types Conversions (Typecasting)

In most situations, compiler will provide an automatic implicit conversion of types where needed, without any user interference. Also, you can explicitly convert an operand to another type using the prefix unary typecast operator:

(type) object

For example:

char a, b;

/* Following line will coerce a to unsigned int: */

( unsigned int) a;

/* Following line will coerce a to double, then coerce b to double automatically, resulting in double type value: */

( double) a + b; // equivalent to ((double) a) + b; page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

DECLARATIONS

Introduction to Declarations

Declaration introduces one or several names to a program – it informs the compiler what the name represents, what is its type, what are allowed operations with it, etc. This section reviews concepts related to declarations: declarations, definitions, declaration specifiers, and initialization.

The range of objects that can be declared includes:

- Variables

- Constants

- Functions

- Types

- Structure, union, and enumeration tags

- Structure members

- Union members

- Arrays of other types

- Statement labels

- Preprocessor macros

Declarations and Definitions

Defining declarations, also known as definitions, beside introducing the name of an object, also establish the creation (where and when) of the object; that is, the allocation of physical memory and its possible initialization. Referencing declarations, or just declarations, simply make their identifiers and types known to the compiler.

Here is an overview. Declaration is also a definition, except if:

- it declares a function without specifying its body,

- it has an extern specifier, and has no initializator or body (in case of func.),

- it is a typedef declaration.

There can be many referencing declarations for the same identifier, especially in a multifile program, but only one defining declaration for that identifier is allowed.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Let’s have an example:

/* Here is a nondefining declaration of function max; */

/* it merely informs compiler that max is a function */

int max();

/* Here is a definition of function max: */

int max(int x, int y) {

return (x>=y) ? x : y;

}

int i; /* Definition of variable i */

int i; /* Error: i is already defined! */

Declarations and Declarators

A declaration is a list of names. The names are sometimes referred to as declarators or identifiers. The declaration begins with optional storage class specifiers, type specifiers, and other modifiers. The identifiers are separated by commas and the list is terminated by a semicolon.

Declarations of variable identifiers have the following pattern:

storage-class [type-qualifier] type var1 [=init1], var2 [=init2],

...; where var1

, var2

,... are any sequence of distinct identifiers with optional initializers. Each of the variables is declared to be of

type

; if omitted,

type

defaults to int

. Specifier

storage-class

can take values extern

, static

, register

, or the default auto

. Optional

type-qualifier

can take values const or volatile

. For more details, refer to Storage Classes and Type Qualifiers.

Here is an example of variable declaration:

/* Create 3 integer variables called x, y, and z and initialize x and y to the values 1 and 2, respectively: */

int x = 1, y = 2, z; // z remains uninitialized

These are all defining declarations; storage is allocated and any optional initializers are applied.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Linkage

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

An executable program is usually created by compiling several independent translation units, then linking the resulting object files with preexisting libraries. The term translation unit refers to a source code file together with any included files, but less any source lines omitted by conditional preprocessor directives. A problem arises when the same identifier is declared in different scopes (for example, in different files), or declared more than once in the same scope.

Linkage is the process that allows each instance of an identifier to be associated correctly with one particular object or function. All identifiers have one of two linkage attributes, closely related to their scope: external linkage or internal linkage. These attributes are determined by the placement and format of your declarations, together with the explicit (or implicit by default) use of the storage class specifier static or extern

.

Each instance of a particular identifier with external linkage represents the same object or function throughout the entire set of files and libraries making up the program. Each instance of a particular identifier with internal linkage represents the same object or function within one file only.

Linkage Rules

Local names have internal linkage; same identifier can be used in different files to signify different objects. Global names have external linkage; identifier signifies the same object throughout all program files.

If the same identifier appears with both internal and external linkage within the same file, the identifier will have internal linkage.

Internal Linkage Rules:

1. names having file scope, explicitly declared as static

, have internal linkage,

2. names having file scope, explicitly declared as const and not explicitly, declared as extern

, have internal linkage,

3. typedef names have internal linkage,

4. enumeration constants have internal linkage .

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

External Linkage Rule:

1. names having file scope, that do not comply to any of previously stated internal linkage rules, have external linkage.

The storage class specifiers auto and register cannot appear in an external declaration. For each identifier in a translation unit declared with internal linkage, no more than one external definition can be given. An external definition is an external declaration that also defines an object or function; that is, it also allocates storage. If an identifier declared with external linkage is used in an expression

(other than as part of the operand of sizeof

), then exactly one external definition of that identifier must be somewhere in the entire program.

mikroC allows later declarations of external names, such as arrays, structures, and unions, to add information to earlier declarations. Here's an example:

int a[];

struct mystruct;

.

.

.

int a[3] = {1, 2, 3};

struct mystruct {

int i, j;

};

// No size

// Tag only, no member declarators

// Supply size and initialize

// Add member declarators

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Storage Classes

Associating identifiers with objects requires each identifier to have at least two attributes: storage class and type (sometimes referred to as data type). The mikroC compiler deduces these attributes from implicit or explicit declarations in the source code.

Storage class dictates the location (data segment, register, heap, or stack) of the object and its duration or lifetime (the entire running time of the program, or during execution of some blocks of code). Storage class can be established by the syntax of the declaration, by its placement in the source code, or by both of these factors:

storage-class type identifier

The storage class specifiers in mikroC are: auto register static extern

Auto

Use the auto modifer to define a local variable as having a local duration. This is the default for local variables and is rarely used. You cannot use auto with globals. See also Functions.

Register

By default, mikroC stores variables within internal microcontroller memory. Thus, modifier register technically has no special meaning. mikroC compiler simply ignores requests for register allocation.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Static

Global name declared with static specifier has internal linkage, meaning that it is local for a given file. See Linkage for more information.

Local name declared with static specifier has static duration. Use static with a local variable to preserve the last value between successive calls to that function.

See Duration for more information.

Extern

Name declared with extern specifier has external linkage, unless it has been previously declared as having internal linkage. Declaration is not a definition if it has extern specifier and is not initialized. The keyword extern is optional for a function prototype.

Use the extern modifier to indicate that the actual storage and initial value of a variable, or body of a function, is defined in a separate source code module.

Functions declared with extern are visible throughout all source files in a program, unless you redefine the function as static

.

See Linkage for more information.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Type Qualifiers

Type qualifiers const and volatile are optional in declarations and do not actually affect the type of declared object.

Qualifier const

Qualifier const implies that the declared object will not change its value during runtime. In declarations with const qualifier, you need to initialize all the objects in the declaration.

Effectively, mikroC treats objects declared with const qualifier same as literals or preprocessor constants. Compiler will report an error if trying to change an object declared with const qualifier.

For example:

const double PI = 3.14159;

Qualifier volatile

Qualifier volatile implies that variable may change its value during runtime indepent from the program. Use the volatile modifier to indicate that a variable can be changed by a background routine, an interrupt routine, or an I/O port.

Declaring an object to be volatile warns the compiler not to make assumptions concerning the value of the object while evaluating expressions in which it occurs because the value could change at any moment.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Typedef Specifier

Specifier typedef introduces a synonym for a specified type. You can use typedef declarations to construct shorter or more meaningful names for types already defined by the language or for types that you have declared. You cannot use the typedef specifier inside a function definition.

The specifier typedef stands first in the declaration:

typedef <type-definition> synonym;

The typedef keyword assigns the

synonym

to the

<type-definition>

. The

synonym

needs to be a valid identifier.

Declaration starting with the typedef specifier does not introduce an object or function of a given type, but rather a new name for a given type. That is, the typedef declaration is identical to “normal” declaration, but instead of objects, it declares types. It is a common practice to name custom type identifiers with starting capital letter — this is not required by C.

For example:

// Let's declare a synonym for "unsigned long int":

typedef unsigned long int Distance;

// Now, synonym "Distance" can be used as type identifier:

Distance i; // declare variable i of unsigned long int

In typedef declaration, as in any declaration, you can declare several types at once.

For example:

typedef int *Pti, Array[10];

Here,

Pti is synonym for type “pointer to int

”, and Array is synonym for type

“array of 10 int elements”.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

asm Declaration

C allows embedding assembly in the source code by means of asm declaration.

Declarations _asm and __asm are also allowed in mikroC, and have the same meaning. Note that you cannot use numerals as absolute addresses for SFR or

GPR variables in assembly instructions. You may use symbolic names instead

(listing will display these names as well as addresses).

You can group assembly instructions by the asm keyword (or

_asm

, or

__asm

):

asm {

block of assembly instructions

}

C comments (both single-line and multi-line) are allowed in embedded assembly code. Assembly-style comments starting with semicolon are not allowed.

If you plan to use a certain C variable in embedded assembly only, be sure to at least initialize it in C code; otherwise, linker will issue an error. This does not apply to predefined globals such as

PORTB

.

For example, the following code will not be compiled, as linker won’t be able to recognize variable myvar

:

unsigned myvar;

void main() {

asm {

MOVLW 10 // just a test

MOVLW test_main_global_myvar_1

}

}

Adding the following line (or similar) above asm block would let linker know that variable is used: myvar := 0;

Note: mikroC will not check if the banks are set appropriately for your variable.

You need to set the banks manually in assembly code.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Variable mangling is altered, and is more in C-manner. 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 individual bytes).

The only types whose name remains the same in asm as it is in C are constants, 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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Initialization

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

At the time of declaration, you can set the initial value of a declared object, i.e.

initialize it. Part of the declaration which specifies the initialization is called the initializer.

Initializers for globals and static objects must be constants or constant expressions.

The initializer for an automatic object can be any legal expression that evaluates to an assignment-compatible value for the type of the variable involved.

Scalar types are initialized with a single expression, which can optionally be enclosed in braces. The initial value of the object is that of the expression; the same constraints for type and conversions apply as for simple assignments.

For example:

int i = 1;

char *s = "hello";

struct complex c = {0.1, -0.2};

// where 'complex' is a structure (float, float)

For structures or unions with automatic storage duration, the initializer must be one of the following:

- an initializer list,

- a single expression with compatible union or structure type. In this case, the initial value of the object is that of the expression.

For more information, refer to Structures and Unions.

Also, you can initialize arrays of character type with a literal string, optionally enclosed in braces. Each character in the string, including the null terminator, initializes successive elements in the array. For more information, refer to Arrays.

Automatic Initialization

mikroC does not provide automatic initialization for objects. Uninitialized globals and objects with static duration will take random values from memory.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

FUNCTIONS

Functions are central to C programming. Functions are usually defined as subprograms which return a value based on a number of input parameters. Return value of a function can be used in expressions – technically, function call is considered an operator like any other.

C allows a function to create results other than its return value, referred to as side

effects. Often, function return value is not used at all, depending on the side effects. These functions are equivalent to procedures of other programming languages, such as Pascal. C does not distinguish between procedure and function – functions play both roles.

Each program must have a single external function named main marking the entry point of the program. Functions are usually declared as prototypes in standard or user-supplied header files, or within program files. Functions have external linkage by default and are normally accessible from any file in the program. This can be restricted by using the static storage class specifier in function declaration (see

Storage Classes and Linkage).

Note: Check the PIC Specifics for more info on functions’ limitations on PIC micros.

Function Declaration

Functions are declared in your source files or made available by linking precompiled libraries. Declaration syntax of a function is:

type function_name(parameter-declarator-list);

The

function_name

must be a valid identifier. This name is used to call the function; see Function Calls for more information. The

type

represents the type of function result, and can be any standard or user-defined type. For functions that do not return value, you should use void type. The

type

can be omitted in global function declarations, and function will assume int type by default.

Function

type

can also be a pointer. For example, float* means that the function result is a pointer to float

. Generic pointer, void* is also allowed. Function

cannot return array or another function.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Within parentheses,

parameter-declarator-list

is a list of formal arguments that function takes. These declarators specify the type of each function parameter.

The compiler uses this information to check function calls for validity. If the list is empty, function does not take any arguments. Also, if the list is void

, function also does not take any arguments; note that this is the only case when void can be used as an argument’s type.

Unlike with variable declaration, each argument in the list needs its own type specifier and a possible qualifier const or volatile

.

Function Prototypes

A given function can be defined only once in a program, but can be declared several times, provided the declarations are compatible. If you write a nondefining declaration of a function, i.e. without the function body, you do not have to specify the formal arguments. This kind of declaration, commonly known as the function

prototype, allows better control over argument number and type checking, and type conversions.

Name of the parameter in function prototype has its scope limited to the prototype.

This allows different parameter names in different declarations of the same function:

/* Here are two prototypes of the same function: */

int test(const char*) // declares function test

int test(const char*p) // declares the same function test

Function prototypes greatly aid in documenting code. For example, the function

Cf_Init takes two parameters: Control Port and Data Port. The question is, which is which? The function prototype

void Cf_Init(char *ctrlport, char *dataport); makes it clear. If a header file contains function prototypes, you can that file to get the information you need for writing programs that call those functions. If you include an identifier in a prototype parameter, it is used only for any later error messages involving that parameter; it has no other effect.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Function Definition

Function definition consists of its declaration and a function body. The function body is technically a block – a sequence of local definitions and statements enclosed within braces

{}

. All variables declared within function body are local to the function, i.e. they have function scope.

The function itself can be defined only within the file scope. This means that function declarations cannot be nested.

To return the function result, use the return statement. Statement return in functions of void type cannot have a parameter – in fact, you can omit the return statement altogether if it is the last statement in the function body.

Here is a sample function definition:

/* function max returns greater one of its 2 arguments: */

int max(int x, int y) {

return (x>=y) ? x : y;

}

Here is a sample function which depends on side effects rather than return value:

/* function converts Descartes coordinates (x,y) to polar coordinates (r,fi): */

#include <math.h>

void polar(double x, double y, double *r, double *fi) {

*r = sqrt(x * x + y * y);

*fi = (x == 0 && y == 0) ? 0 : atan2(y, x);

return; /* this line can be omitted */

}

Function Reentrancy

Limited reentrancy for functions is allowed. The functions that don't have their own function frame (no arguments and local variables) can be called both from the interrupt and the "main" thread. Functions that have input arguments and/or local variables can be called only from one of the before mentioned program threads. page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Function Calls

A function is called with actual arguments placed in the same sequence as their matching formal parameters. Use a function-call operator

()

:

function_name(expression_1, ... , expression_n)

Each expression in the function call is an actual argument. Number and types of actual arguments should match those of formal function parameters. If types disagree, implicit type conversions rules apply. Actual arguments can be of any complexity, but you should not depend on their order of evaluation, because it is not specified.

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 created in the place of the call, and it is initialized by the expression of return statement. This means that function call as an operand in complex expression is treated as the function result.

If the function is without result (type void

) or you don’t need the result, you can write the function call as a self-contained expression.

In C, scalar parameters are always passed to function by value. A function can modify the values of its formal parameters, but this has no effect on the actual arguments in the calling routine. You can pass scalar object by the address by declaring a formal parameter to be a pointer. Then, use the indirection operator

* to access the pointed object.

Argument Conversions

When a function prototype has not been previously declared, mikroC converts integral arguments to a function call according to the integral widening (expansion) rules described in Standard Conversions. When a function prototype is in scope, mikroC converts the given argument to the type of the declared parameter as if by assignment.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

If a prototype is present, the number of arguments must match. The types need to be compatible only to the extent that an assignment can legally convert them. You can always use an explicit cast to convert an argument to a type that is acceptable to a function prototype.

Note: If your function prototype does not match the actual function definition, mikroC will detect this if and only if that definition is in the same compilation unit as the prototype. If you create a library of routines with a corresponding header file of prototypes, consider including that header file when you compile the library, so that any discrepancies between the prototypes and the actual definitions will be caught.

The compiler is also able to force arguments to the proper type. Suppose you have the following code:

int limit = 32;

char ch = 'A';

long res;

extern long func(long par1, long par2); main() {

//...

res = func(limit, ch);

}

// prototype

// function call

Since it has the function prototype for func

, this program converts limit and ch to long

, using the standard rules of assignment, before it places them on the stack for the call to func

.

Without the function prototype, limit and ch would have been placed on the stack as an integer and a character, respectively; in that case, the stack passed to func would not match in size or content what func was expecting, leading to problems.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Ellipsis ('...') Operator

An ellipsis ('...') consists of three successive periods with no whitespace intervening. You can use an ellipsis in the formal argument lists of function prototypes to indicate a variable number of arguments, or arguments with varying types. For example:

void func (int n, char ch, ...);

This declaration indicates that func will be defined in such a way that calls must have at least two arguments, an int and a char, but can also have any number of additional arguments.

Example:

#include <stdarg.h>

int addvararg(char a1,...){ va_list ap;

char temp; va_start(ap,a1);

while( temp = va_arg(ap,char)) a1 += temp;

return a1;

}

int res;

void main() { res = addvararg(1,2,3,4,5,0); res = addvararg(1,2,3,4,5,6,7,8,9,10,0);

}//~! page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

OPERATORS

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

mikroC recognizes following operators:

- Arithmetic Operators

- Assignment Operators

- Bitwise Operators

- Logical Operators

- Reference/Indirect Operators

- Relational Operators

- Structure Member Selectors

- Comma Operator

,

- Conditional Operator

? :

- Array subscript operator

[]

- Function call operator

()

- sizeof

Operator

- Preprocessor Operators

# and

##

(see Pointer Arithmetic)

(see Structure Member Access)

(see Comma Expressions)

(see Arrays)

(see Function Calls)

(see Preprocessor Operators)

Operators Precedence and Associativity

There are 15 precedence categories, some of which contain only one operator.

Operators in the same category have equal precedence with each other.

Table on the following page sums all mikroC operators.

Where duplicates of operators appear in the table, the first occurrence is unary, the second binary. 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.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

5

4

7

6

3

2

1

9

8

11

10

Precedence Operands Operators

13

12

15

14

2

1

2

2

() [] . ->

Associativity

! ~ ++ -- + - *

& (type)

sizeof

right-to-left

* / %

+ left-to-right left-to-right left-to-right

2

2

2

2

<< >>

< <= > >=

== !=

& left-to-right left-to-right left-to-right left-to-right

2

2

2

2

3

2

2

^

|

&&

||

?:

= *= /= %= += -=

&= ^= |= <<= >>=

, left-to-right left-to-right left-to-right left-to-right left-to-right right-to-left left-to-right page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Arithmetic Operators

Arithmetic operators are used to perform mathematical computations. They have numerical operands and return numerical results. Type char technically represents small integers, so char variables can used as operands in arithmetic operations.

All of arithmetic operators associate from left to right.

Operator

+

-

*

/

%

+

(unary)

-

(unary)

++

--

Operation

addition subtraction multiplication division returns the remainder of integer division (cannot be used with floating points) unary plus does not affect the operand unary minus changes the sign of operand increment adds one to the value of the operand decrement subtracts one from the value of the operand

Precedence

12

13

13

12

13

14

14

14

14

Note: Operator

* is context sensitive and can also represent the pointer reference operator. See Pointers for more information.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Binary Arithmetic Operators

Division of two integers returns an integer, while remainder is simply truncated:

/* for example: */

7 / 4; // equals 1

7 * 3 / 4; // equals 5

/* but: */

7. * 3./ 4.; // equals 5.25 as we are working with floats

Remainder operand % works only with integers; sign of result is equal to the sign of first operand:

/* for example: */

9 % 3;

// equals 0

7 % 3;

// equals 1

-7 % 3;

// equals -1

We can use arithmetic operators for manipulating characters:

'A' + 32;

'G' - 'A' + 'a';

// equals 'a' (ASCII only)

// equals 'g' (both ASCII and EBCDIC)

Unary Arithmetic Operators

Unary operators

++ and

-are the only operators in C which can be either prefix

(e.g.

++k

,

--k

) or postfix (e.g.

k++

, k--

).

When used as prefix, operators

++ and

--

(preincrement and predecrement) add or subtract one from the value of operand before the evaluation. When used as suffix, operators

++ and

-add or subtract one from the value of operand after the evaluation.

For example:

int j = 5; j = ++k;

/* k = k + 1, j = k, which gives us j = 6, k = 6 */

int j = 5; j = k++;

/* j = k, k = k + 1, which gives us j = 5, k = 6 */

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Relational Operators

Use relational operators to test equality or inequality of expressions. If the expression evaluates to true, it returns 1; otherwise it returns 0.

All relational operators associate from left to right.

Relational Operators Overview

Operator

==

!=

>=

<=

>

<

Operation

equal not equal greater than less than greater than or equal less than or equal

Precedence

9

10

10

9

10

10

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 // i.e. (a + 5) >= (c - (1.0 / e))

Always bear in mind that relational operators return either 0 or 1. Consider the following examples:

8 == 13 > 5

14 > 5 < 3 a < b < 5

// returns 0: 8==(13>5), 8==1, 0

// returns 1: (14>5)<3, 1<3, 1

// returns 1: (a<b)<5, (0 or 1)<5, 1

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Bitwise Operators

Use the bitwise operators to modify the individual bits of numerical operands.

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

~ which associates from right to left.

Bitwise Operators Overview

Operator

&

|

>>

<<

^

~

Operation

bitwise AND; returns 1 if both bits are 1, otherwise returns 0 bitwise (inclusive) OR; returns 1 if either or both bits are 1, otherwise returns 0 bitwise exclusive OR (XOR); returns 1 if the bits are complementary, otherwise 0 bitwise complement (unary); inverts each bit bitwise shift left; moves the bits to the left, see below bitwise shift right; moves the bits to the right, see below

Precedence

9

10

10

9

10

10

Note: Operator

& can also be the pointer reference operator. Refer to Pointers for more information.

Bitwise operators

&

,

|

, and

^ perform logical operations on appropriate pairs of bits of their operands. For example:

0x1234 & 0x5678; /* equals 0x1230 */

/* because ..

0x1234 : 0001 0010 0011 0100

0x5678 : 0101 0110 0111 1000

---------------------------------

& : 0001 0010 0011 0000

.. that is, 0x1230 */

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

/* Similarly: */

0x1234 | 0x5678;

0x1234 ^ 0x5678;

~ 0x1234;

/* equals 0x567C */

/* equals 0x444C */

/* equals 0xEDCB */

Bitwise Shift Operators

Binary operators

<< and

>> 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.

With shift left (

<<

), left most bits are discarded, and “new” bits on the right are assigned zeroes. Thus, shifting unsigned operand to 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.

000001 << 5;

0x3801 << 4;

/* equals 000040 */

/* equals 0x8010, overflow! */

With shift right (

>>

), 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 right by n positions is equivalent to dividing it by 2n.

0xFF56 >> 4;

0xFF56u >> 4;

/* equals 0xFFF5 */

/* equals 0x0FF5 */

Bitwise vs. Logical

Be aware of the principle difference between how bitwise and logical operators work. For example:

0222222 & 0555555;

0222222 && 0555555;

~ 0x1234;

! 0x1234;

/* equals 000000 */

/* equals 1 */

/* equals 0xEDCB */

/* equals 0 */

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Logical Operators

Operands of logical operations are considered true or false, that is non-zero or zero. Logical operators always return 1 or 0. Operands in a logical expression must be of scalar type.

Logical operators

&& and

|| associate from left to right. Logical negation operator

! associates from right to left.

Logical Operators Overview

Operator

&&

||

!

Operation

logical AND logical OR logical negation

Precedence

5

4

14

Precedence of logical, relational, and arithmetic operators was chosen in such a way to allow complex expressions without parentheses to have expected meaning: c >= '0' && c <= '9'; // reads as: (c>='0') && (c<='9') a + 1 == b || ! f(x;) // reads as: ((a+1)== b) || (!(f(x)))

Logical AND (

&&

) returns 1 only if both expressions evaluate to be nonzero, otherwise returns 0. If the first expression evaluates to false, the second expression is not evaluated. For example: a > b && c < d;

// reads as: (a>b) && (c<d)

// if (a>b) is false (0), (c<d) will not be evaluated

Logical OR (

||

) returns 1 if either of the expressions evaluate to be nonzero, otherwise returns 0. If the first expression evaluates to true, the second expression is not evaluated. For example: a && b || c && d;

// reads as: (a && b) || (c && d)

// if (a&&b) is true (1), (c&&d) will not be evaluated

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Logical Expressions and Side Effects

General rule with complex logical expressions is that the evaluation of consecutive logical operands stops the very moment the final result is known. For example, if we have an expression: a && b && c where a is false (0), then operands b and c will not be evaluated. This is very important if b and c are expressions, as their possible side effects will not take place!

Logical vs. Bitwise

Be aware of the principle difference between how bitwise and logical operators work. For example:

0222222 & 0555555

0222222 && 0555555

~ 0x1234

! 0x1234

/* equals 000000 */

/* equals 1 */

/* equals 0xEDCB */

/* equals 0 */

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Conditional Operator ? :

The conditional operator

? : is the only ternary operator in C. Syntax of the conditional operator is:

expression1 ? expression2 : expression3

Expression1

evaluates first. If its value is true, then

expression2

evaluates and

expression3

is ignored. If

expression1

evaluates to false, then

expression3

evaluates and

expression2

is ignored. The result will be the value of either

expression2

or

expression3

depending upon which evaluates. The fact that only one of these two expressions evaluates is very important if you expect them to produce side effects!

Conditional operator associates from right to left.

Here are a couple of practical examples:

/* Find max(a, b): */

max = (a > b) ? a : b;

/* Convert small letter to capital: */

/* (no parentheses are actually necessary) */

c = (c >= 'a' && c <= 'z') ? (c - 32) : c;

Conditional Operator Rules

Expression1

must be a scalar expression;

expression2

and

expression3

must obey one of the following rules:

1. Both of arithmetic type;

expression2

and

expression3

are subject to the usual arithmetic conversions, which determines the resulting type.

2. Both of compatible struct or union types. The resulting type is the structure or union type of

expression2

and

expression3

.

3. Both of void type. The resulting type is void

.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

4. Both of type pointer to qualified or unqualified versions of compatible types.

The resulting type is a pointer to a type qualified with all the type qualifiers of the types pointed to by both operands.

5. One operand is a pointer, and the other is a null pointer constant. The resulting type is a pointer to a type qualified with all the type qualifiers of the types pointed to by both operands.

6. One operand is a pointer to an object or incomplete type, and the other is a pointer to a qualified or unqualified version of void

. The resulting type is that of the non-pointer-tovoid operand.

Assignment Operators

Unlike many other programming languages, C treats value assignment as an operation (represented by an operator) rather than instruction.

Simple Assignment Operator

For a common value assignment, we use a simple assignment operator (=) :

expression1 = expression2

Expression1

is an object (memory location) to which we assign value of

expression2

. Operand

expression1

has to be a lvalue, and

expression2

can be any expression. The assignment expression itself is not an lvalue.

If

expression1

and

expression2

are of different types, result of the

expression2

will be converted to the type of

expression1

, if necessary. Refer to Type

Conversions for more information.

Compound Assignment Operators

C allows more comlex assignments by means of compound assignment operators.

Syntax of compound assignment operators is:

expression1 op= expression2 where

op

can be one of binary operators

+

,

-

,

*

,

/

,

%

,

&

,

|

,

^

,

<<

, or

>>

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Thus, we have 10 different compound assignment operators:

+=

,

-=

,

*=

,

/=

,

%=

,

&=

,

|=

,

^=

,

<<=

, and

>>=

. All of these associate from right to left. Spaces separating compound operators (e.g.

+ =

) will generate error.

Compound assignment has the same effect as

expression1 = expression1 op expression2 except the lvalue

expression1

is evaluated only once. For example,

expression1 += expression2 is the same as

expression1 = expression1 + expression2

Assignment Rules

For both simple and compound assignment, the operands

expression1

and

expression2

must obey one of the following rules:

1.

expression1

is a qualified or unqualified arithmetic type and

expression2

is an arithmetic type.

2.

expression1

has a qualified or unqualified version of a structure or union type compatible with the type of

expression2

.

3.

expression1

and

expression2

are pointers to qualified or unqualified versions of compatible types, and the type pointed to by the left has all the qualifiers of the type pointed to by the right.

4. Either

expression1

or

expression2

is a pointer to an object or incomplete type and the other is a pointer to a qualified or unqualified version of void

.

The type pointed to by the left has all the qualifiers of the type pointed to by the right.

5.

expression1

is a pointer and

expression2

is a null pointer constant.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Sizeof Operator

Prefix unary operator sizeof returns an integer constant that gives the size in bytes of how much memory space is used by its operand (determined by its type, with some exceptions).

Operator sizeof can take either a type identifier or an unary expression as an operand. You cannot use sizeof with expressions of function type, incomplete types, parenthesized names of such types, or with an lvalue that designates a bit field object.

Sizeof Applied to Expression

If applied to expression, size of the operand is determined without evaluating the expression (and therefore without side effects). Result of the operation will be the size of the type of the expression’s result.

Sizeof Applied to Type

If applied to a type identifier, sizeof returns the size of the specified type. Unit for type size is the

sizeof(char) which is equivalent to one byte. Operation

sizeof(char) gives the result 1, whether the char is signed or unsigned.

sizeof(char)

sizeof(int)

sizeof(unsigned long)

/* returns 1 */

/* returns 2 */

/* returns 4 */

When the operand is a non-parameter of array type, the result is the total number of bytes in the array (in other words, an array name is not converted to a pointer type):

int i, j, a[10];

//...

j = sizeof(a[1]); i = sizeof(a);

/* j = sizeof(int) = 2 */

/* i = 10*sizeof(int) = 20 */

If the operand is a parameter declared as array type or function type, sizeof gives the size of the pointer. When applied to structures and unions, sizeof gives the total number of bytes, including any padding. Operator sizeof cannot be applied to a function.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

EXPRESSIONS

An expression is a sequence of operators, operands, and punctuators that specifies a computation. Formally, expressions are defined recursively: subexpressions can be nested without formal limit. However, the compiler will report an out-of-memory error if it can’t compile an expression that is too complex.

In ANSI C, the primary expressions are: constant (also referred to as literal), identifier, and

(expression)

, defined recursively.

Expressions are evaluated according to certain conversion, grouping, associativity, and precedence rules that depend on the operators used, the presence of parentheses, 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 mikroC.

Expressions can produce an lvalue, an rvalue, or no value. Expressions might cause side effects whether they produce a value or not.

Comma Expressions

One of the specifics of C is that it allows you to use comma as a sequence operator to form the so-called comma expressions or sequences. Comma expression is a comma-delimited list of expressions – it is formally treated as a single expression so it can be used in places where an expression is expected. The following sequence:

expression_1, expression_2; results in the left-to-right evaluation of each expression, with the value and type of

expression_2

giving the result of the whole expression. Result of

expression_1

is discarded.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Binary operator comma (

,

) has the lowest precedence and associates from left to right, so that a, b, c is same as

(a, b), c

. This allows us to write sequences with any number of expressions:

expression_1, expression_2, ... expression_n; this results in the left-to-right evaluation of each expression, with the value and type of expression_n giving the result of the whole expression. Results of other expressions are discarded, but their (possible) side-effect do occur.

For example: result = (a = 5, b /= 2, c++);

/* returns preincremented value of variable c, but also intializes a, divides b by 2, and increments c */

result = (x = 10, y = x + 3, x--, z -= x * 3 - --y);

/* returns computed value of variable z, and also computes x and y */

Note

Do not confuse comma operator (sequence operator) with the comma punctuator which separates elements in a function argument list and initializator lists. Mixing the two uses of comma is legal, but you must use parentheses to distinguish them.

To avoid ambiguity with the commas in function argument and initializer lists, use parentheses. For example, func(i, (j = 1, j + 4), k); calls function func with three arguments

(i, 5, k)

, not four.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

STATEMENTS

Statements specify the flow of control as a program executes. In the absence of specific jump and selection statements, statements are executed sequentially in the order of appearance in the source code.

Statements can be roughly divided into:

- Labeled Statements

- Expression Statements

- Selection Statements

- Iteration Statements (Loops)

- Jump Statements

- Compound Statements (Blocks)

Labeled Statements

Every statement in program can be labeled. Label is an identifier added before the statement like this:

label_identifier : statement;

There is no special declaration of a label – it just “tags” the statement.

Label_identifier

has a function scope and label cannot be redefined within the same function.

Labels have their own namespace: label identifier can match any other identifier in the program.

A statement can be labeled for two reasons:

1. The label identifier serves as a target for the unconditional goto statement,

2. The label identifier serves as a target for the switch statement. For this purpose, only case and default labeled statements are used:

case constant-expression : statement

default : statement page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Expression Statements

Any expression followed by a semicolon forms an expression statement:

expression; mikroC executes an expression statement by evaluating the expression

. All side effects from this evaluation are completed before the next statement is executed.

Most expression statements are assignment statements or function calls.

The null statement is a special case, consisting of a single semicolon (

;

). The null statement does nothing, and is therefore useful in situations where the mikroC syntax expects a statement but your program does not need one. For example, null statement is commonly used in “empty” loops:

for (; *q++ = *p++ ;);

/* body of this loop is a null statement */

Selection Statements

Selection or flow-control statements select from alternative courses of action by testing certain values. There are two types of selection statements in C: if and switch

.

If Statement

Use the if statement to implement a conditional statement. Syntax of the if statement is:

if (expression) statement1 [else statement2]

When

expression

evaluates to true,

statement1

executes. If expression is false,

statement2

executes. The

expression

must evaluate to an integral value; otherwise, the condition is ill-formed. Parentheses around the

expression

are mandatory.

The else keyword is optional, but no statements can come between the if and the else

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Nested if statements

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:

if (expression1) statement1

else if (expression2)

if (expression3) statement2

else statement3

/* this belongs to: if (expression3) */

else statement4

/* this belongs to: if (expression2) */

Note: The

#if and

#else preprocessor statements (directives) look similar to the if and else statements, but have very different effects. They control which source file lines are compiled and which are ignored. See Preprocessor for more information.

Switch Statement

Use the switch statement to pass control to a specific program branch, based on a certain condition. Syntax of switch statement is:

switch (expression) {

case constant-expression_1 : statement_1;

.

.

.

case constant-expression_n : statement_n;

[ default : statement;]

}

First, the

expression

(condition) is evaluated. The switch statement then compares it to all the available

constant-expressions

following the keyword case

. If the match is found, switch passes control to that matching case

, at which point the

statement

following the match evaluates. Note that

constant-expressions

must evaluate to integer. There cannot be two same

constant-expressions

evaluating to same value.

.

Parantheses around

expression

are mandatory.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Upon finding a match, program flow continues normally: following instructions will be executed in natural order regardless of the possible case label. If no case satisfies the condition, the default case evaluates (if the label default is specified).

For example, if variable i has value between 1 and 3, following switch would always return it as 4:

switch (i) {

case 1: i++;

case 2: i++;

case 3: i++;

}

To avoid evaluating any other cases and relinquish control from the switch

, terminate each case with break

.

Conditional switch statements can be nested – labels case and default are then assigned to the innermost enclosing switch statement.

Here is a simple example with switch

. Let’s assume we have a variable with only

3 different states (0, 1, or 2) and a corresponding function (event) for each of these states. This is how we could switch the code to the appopriate routine:

switch (state) {

case 0: Lo(); break;

case 1: Mid(); break;

case 2: Hi(); break;

default: Message("Invalid state!");

} page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Iteration Statements

Iteration statements let you loop a set of statements. There are three forms of iteration statements in C: while

, do

, and for

.

While Statement

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

while (expression) statement

The

statement

executes repeatedly until the value of expression is false. The test takes place before

statement

executes. Thus, if

expression

evaluates to false on the first pass, the loop does not execute.

Parentheses around

expression

are mandatory.

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

int s = 0, i = 0;

while (i < n) { s += a[i] * b[i]; i++;

}

Note that body of a loop can be a null statement. For example:

while (*q++ = *p++);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Do Statement

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

do statement while (expression);

The

statement

is executed repeatedly as long as the value of

expression

remains non-zero. The

expression

is evaluated after each iteration, so the loop will execute

statement

at least once.

Parentheses around

expression

are mandatory.

Note that do is the only control structure in C which explicitly ends with semicolon (;). Other control structures end with statement which means that they implicitly include a semicolon or a closing brace.

Here is an example of calculating scalar product of two vectors, using the do statement: s = 0; i = 0;

do { s += a[i] * b[i]; i++;

}

while (i < n);

For Statement

The for statement implements an iterative loop. Syntax of for statement is:

for ([init-exp]; [condition-exp]; [increment-exp]) statement

Before the first iteration of the loop, expression

init-exp

sets the starting variables for the loop. You cannot pass declarations in

init-exp

.

Expression

condition-exp

is checked before the first entry into the block;

statement

is executed repeatedly until the value of

condition-exp

is false.

After each iteration of the loop,

increment-exp

increments a loop counter.

Consequently, i++ is functionally the same as ++i.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

All the expressions are optional. If

condition-exp

is left out, it is assumed to be always true. Thus, “empty” for statement is commonly used to create an endless loop in C:

for ( ; ; ) {...}

The only way to break out of this loop is by means of break statement.

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

for (s = 0, i = 0; i < n; i++) s += a[i] * b[i];

You can also do it like this:

/* valid, but ugly */

for (s = 0, i = 0; i < n; s += a[i] * b[i], i++); but this is considered a bad programming style. Although legal, calculating the sum should not be a part of the incrementing expression, because it is not in the service of loop routine. Note that we used a null statement (

;

) for a loop body.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Jump Statements

A jump statement, when executed, transfers control unconditionally. There are four such statements in mikroC: break

, continue

, goto

, and return

.

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 innermost switch

, for

, while

, or do block.

Break is commonly used in switch statements to stop its execution upon the first positive match. For example:

switch (state) {

case 0: Lo(); break;

case 1: Mid(); break;

case 2: Hi(); break;

default: Message("Invalid state!");

}

Continue Statement

You can use the continue statement within loops ( while

, do

, for

) to “skip the cycle”. It passes control to the end of the innermost enclosing end brace belonging to a looping construct. At that point the loop continuation condition is re-evaluated. This means that continue demands the next iteration if loop continuation condition is true.

Goto Statement

Use the goto statement to unconditionally jump to a local label — for more information on labels, refer to Labeled Statements. Syntax of goto statement is:

goto label_identifier;

This will transfer control to the location of a local label specified by

label_identifier

. The

label_identifier

has to be a name of the label within the same function in which the goto statement is. The goto line can come before or after the label.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

You can use goto to break out from any level of nested control structures. But, goto cannot be used to jump into block while skipping that block’s initializations

– for example, jumping into loop’s body, etc.

Use of goto statement is generally discouraged as practically every algorithm can be realized without it, resulting in legible structured programs. One possible application of goto statement is breaking out from deeply nested control structures:

for (...) {

for (...) {

...

if (disaster) goto Error;

...

}

}

.

.

.

Error: /* error handling code */

Return Statement

Use the return statement to exit from the current function back to the calling routine, optionally returning a value. Syntax is:

return [expression];

This will evaluate the

expression

and return the result. Returned value will be automatically converted to the expected function type, if needed. The

expression

is optional; if omitted, function will return a random value from memory.

Note: Statement return in functions of void type cannot have an

expression

– in fact, you can omit the return statement altogether if it is the last statement in the function body.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Compound Statements (Blocks)

A compound statement, or block, is a list (possibly empty) of statements enclosed in matching braces

{}

. Syntactically, a block can be considered to be a single statement, but it also plays a role in the scoping of identifiers. An identifier declared within a block has a scope starting at the point of declaration and ending at the closing brace. Blocks can be nested to any depth up to the limits of memory.

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

for (i = 0; i < n; i++) {

int temp = a[i]; a[i] = b[i]; b[i] = temp;

}

Note that, unlike other statements, compound statements do not end with semicolon (

;

), i.e. there is never a semicolon following the closing brace.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PREPROCESSOR

Preprocessor is an integrated text processor which prepares the source code for compiling. Preprocessor allows:

- inserting text from a specifed file to a certain point in code,

- replacing specific lexical symbols with other symbols,

- conditional compiling which conditionally includes or omits parts of code.

Note that preprocessor analyzes text at token level, not at individual character level. Preprocessor is controled by means of preprocessor directives and preprocessor operators.

Preprocessor Directives

Any line in source code with a leading

# is taken as a preprocessing directive (or

control line), unless the

# is within a string literal, in a character constant, or embedded in a comment. The initial

# can be preceded or followed by whitespace

(excluding new lines).

The null directive consists of a line containing the single character

#

. This line is always ignored.

Preprocessor directives are usually placed at the beginning of the source code, but they can legally appear at any point in a program. The mikroC preprocessor detects preprocessor directives and parses the tokens embedded in them. Directive is in effect from its declaration to the end of the program file.

mikroC supports standard preprocessor directives:

# (null directive)

#define

#elif

#else

#endif

#error

#if

#ifndef

#ifndef

#include

#line

#undef

Note:

#pragma directive is under construction.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Line Continuation with Backslash

If you need to break directive into multiple lines, you can do it by ending the line with a backslash (

\

):

#define MACRO This directive continues to \ the following line.

Macros

Macros provide a mechanism for token replacement, prior to compilation, with or without a set of formal, function-like parameters.

Defining Macros and Macro Expansions

The

#define directive defines a macro:

#define macro_identifier <token_sequence>

Each occurrence of

macro_identifier

in the source code following this control line will be replaced in the original position with the possibly empty token_sequence

(there are some exceptions, which are noted later). Such replacements are known as macro expansions. The

token_sequence

is sometimes called body of the macro. An empty token sequence results in the removal of each affected macro identifier from the source code.

No semicolon (

;

) is needed to terminate a preprocessor directive. Any character found in the token sequence, including semicolons, will appear in the macro expansion. The token_sequence terminates at the first non-backslashed new line encountered. Any sequence of whitespace, including comments in the token sequence, is replaced with a single-space character.

After each individual macro expansion, a further scan is made of the newly expanded text. This allows for the possibility of nested macros: The expanded text can contain macro identifiers that are subject to replacement. However, if the macro expands into what looks like a preprocessing directive, such a directive will not be recognized by the preprocessor. Any occurrences of the macro identifier found within literal strings, character constants, or comments in the source code are not expanded page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

A macro won’t be expanded during its own expansion (so

#define MACRO

MACRO won’t expand indefinitely).

Let’s have an example:

/* Here are some simple macros: */

#define ERR_MSG "Out of range!"

#define EVERLOOP for( ; ; )

/* which we could use like this: */

main() {

EVERLOOP {

...

if (error) {Lcd_Out_Cp(ERR_MSG); break;}

...

}

}

Attempting to redefine an already defined macro identifier will result in a warning unless the new definition is exactly the same token-by-token definition as the existing one. The preferred strategy where definitions might exist in other header files is as follows:

#ifndef BLOCK_SIZE

#define BLOCK_SIZE 512

#endif

The middle line is bypassed if

BLOCK_SIZE is currently defined; if

BLOCK_SIZE is not currently defined, the middle line is invoked to define it.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Macros with Parameters

The following syntax is used to define a macro with parameters:

#define macro_identifier(<arg_list>) token_sequence

Note there can be no whitespace between the

macro_identifier

and the “

(

”.

The optional

arg_list

is a sequence of identifiers separated by commas, not unlike the argument list of a C function. Each comma-delimited identifier plays the role of a formal argument or placeholder.

Such macros are called by writing

macro_identifier(<actual_arg_list>) in the subsequent source code. The syntax is identical to that of a function call; indeed, many standard library C “functions” are implemented as macros.

However, there are some important semantic differences.

The optional

actual_arg_list

must contain the same number of comma-delimited token sequences, known as actual arguments, as found in the formal

arg_list

of the

#define line – there must be an actual argument for each formal argument. An error will be reported if the number of arguments in the two lists is different.

A macro call results in two sets of replacements. First, the macro identifier and the parenthesis-enclosed arguments are replaced by the token sequence. Next, any formal arguments occurring in the token sequence are replaced by the corresponding real arguments appearing in the

actual_arg_list

. As with simple macro definitions, rescanning occurs to detect any embedded macro identifiers eligible for expansion.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Here is a simple example:

// A simple macro which returns greater of its 2 arguments:

#define _MAX(A, B) ((A) > (B)) ? (A) : (B)

// Let's call it:

x = _MAX(a + b, c + d);

/* Preprocessor will transform the previous line into: x = ((a + b) > (c + d)) ? (a + b) : (c + d) */

It is highly recommended to put parentheses around each of the arguments in macro body – this will avoid possible problems with operator precedence.

Undefining Macros

You can undefine a macro using the

#undef directive.

#undef macro_identifier

Directive

#undef detaches any previous token sequence from the

macro_identifier

; the macro definition has been forgotten, and the

macro_identifier

is undefined. No macro expansion occurs within

#undef lines.

The state of being defined or undefined is an important property of an identifier, regardless of the actual definition. The

#ifdef and

#ifndef conditional directives, used to test whether any identifier is currently defined or not, offer a flexible mechanism for controlling many aspects of a compilation.

After a macro identifier has been undefined, it can be redefined with

#define

, using the same or a different token sequence.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

File Inclusion

The preprocessor directive

#include pulls in header files (extension

.h

) into the source code. Do not rely on preprocessor to include source files (extension

.c

) — see Projects for more information.

The syntax of

#include directive has two formats:

#include <header_name>

#include "header_name"

The preprocessor removes the

#include line and replaces it with the entire text of the header file at that point in the source code. The placement of the

#include can therefore influence the scope and duration of any identifiers in the included file.

The difference between the two formats lies in the searching algorithm employed in trying to locate the include file.

If

#include directive was used with the

<header_name> version, the search is made successively in each of the following locations, in this particular order:

1. mikroC installation folder > “include” folder,

2. your custom search paths.

The

"header_name" version specifies a user-supplied include file; mikroC will look for the header file in following locations, in this particular order:

1. the project folder (folder which contains the project file

.ppc

),

2. mikroC installation folder > “include” folder,

3. your custom search paths.

Explicit Path

If you place an explicit path in the header_name

, only that directory will be searched. For example:

#include "C:\my_files\test.h" page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Note: There is also a third version of

#include directive, rarely used, which assumes that neither

< nor

" appears as the first non-whitespace character following

#include

:

#include macro_identifier

It assumes a macro definition exists that will expand the macro identifier into a valid delimited header name with either of the

<header_name> or

"header_name" formats.

Preprocessor Operators

The

#

(pound sign) is a preprocessor directive when it occurs as the first nonwhitespace character on a line. Also,

# and

## perform operator replacement and merging during the preprocessor scanning phase.

Operator #

In C preprocessor, character sequence enclosed by quotes is considered a token and its content is not analyzed. This means that macro names within quotes are not expanded.

If you need an actual argument (the exact sequence of characters within quotes) as result of preprocessing, you can use the

# operator in macro body. It can be placed in front of a formal macro argument in definition in order to convert the actual argument to a string after replacement.

For example, let’s have macro

LCD_PRINT for printing variable name and value on LCD:

#define LCD_PRINT(val) Lcd_Out_Cp(#val ": "); \

Lcd_Out_Cp(IntToStr(val));

(note the backslash as a line-continuation symbol) page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Now, the following code,

LCD_PRINT(temp) will be preprocessed to this:

Lcd_Out_Cp("temp" ": "); Lcd_Out_Cp(IntToStr(temp));

Operator ##

Operator

## is used for token pasting: you can paste (or merge) two tokens together by placing

## in between them (plus optional whitespace on either side). The preprocessor removes the whitespace and the

##

, combining the separate tokens into one new token. This is commonly used for constructing identifiers.

For example, we could define macro

SPLICE for pasting two tokens into one identifier:

#define SPLICE(x,y) x ## _ ## y

Now, the call

SPLICE(cnt, 2) expands to identifier cnt_2

.

Note: mikroC does not support the older nonportable method of token pasting using

(l/**/r)

.

Conditional Compilation

Conditional compilation directives are typically used to make source programs easy to change and easy to compile in different execution environments. mikroC supports conditional compilation by replacing the appropriate source-code lines with a blank line.

All conditional compilation directives must be completed in the source or include file in which they are begun.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Directives

#if

,

#elif

,

#else

, and

#endif

The conditional directives

#if

,

#elif

,

#else

, and

#endif work very similar to the common C conditional statements. If the expression you write after the

#if has a nonzero value, the line group immediately following the

#if directive is retained in the translation unit.

Syntax is:

#if constant_expression_1

<section_1>

[#elif constant_expression_2

<section_2>]

...

[#elif constant_expression_n

<section_n>]

[#else

<final_section>]

#endif

Each

#if directive in a source file must be matched by a closing

#endif directive. Any number of

#elif directives can appear between the

#if and

#endif directives, but at most one

#else directive is allowed. The

#else directive, if present, must be the last directive before

#endif

.

The sections can be any program text that has meaning to the compiler or the preprocessor. The preprocessor selects a single section by evaluating the

constant_expression

following each

#if or

#elif directive until it finds a true (nonzero) constant expression. The

constant_expressions

are subject to macro expansion.

If all occurrences of constant-expression are false, or if no

#elif directives appear, the preprocessor selects the text block after the

#else clause. If the

#else clause is omitted and all instances of

constant_expression

in the

#if block are false, no section is selected for further processing.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Any processed

section

can contain further conditional clauses, nested to any depth. Each nested

#else

,

#elif

, or

#endif directive belongs to the closest preceding

#if directive.

The net result of the preceding scenario is that only one code

section

(possibly empty) will be compiled.

Directives

#ifdef and

#ifndef

You can use the

#ifdef and

#ifndef directives anywhere

#if can be used. The

#ifdef and

#ifndef conditional directives let you test whether an identifier is currently defined or not. The line

#ifdef identifier has exactly the same effect as

#if 1 if

identifier

is currently defined, and the same effect as

#if 0 if

identifier

is currently undefined. The other directive,

#ifndef

, tests true for the “not-defined” condition, producing the opposite results.

The syntax thereafter follows that of the

#if

,

#elif

,

#else

, and

#endif

.

An identifier defined as NULL is considered to be defined.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

CHAPTER

4

mikroC for dsPIC

Libraries

mikroC for dsPIC provides a number of built-in and library routines which help you develop your application faster and easier. Libraries for ADC, CAN, UART,

SPI, I2C, 1-Wire, LCD, PWM, RS485, numeric formatting, bit manipulation, and many other are included along with practical, ready-to-use code examples.

Miik ro ek tr niik a:: ev lo pm en t ls -- Bo ok -- om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

BUILT-IN ROUTINES

mikroC for dsPIC compiler provides a set of useful built-in utility functions. Builtin functions do not require any header files to be included; you can use them in any part of your project.

Built-in routines are implemented as “inline”; i.e. code is generated in the place of the call, so the call doesn’t count against the nested call limit. The only exceptions are Vdelay_ms and Delay_Cyc, which are actual C routines.

Note: Lob, Hib, Higherb, Highestb, Lo, Hi, Higher and Highest functions are not implemented in compiler any more. If you want to use these functions you must include built_in.h into your project.

Lob

Hib

Higherb

Highestb

Lo

Hi

Higher

Highest

Delay_us

Delay_ms

Vdelay_ms

Delay_Cyc

Clock_Khz

Clock_Mhz page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Lob

Prototype

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned short Lob(long number);

Returns

Description

Requires

Example

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

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1AC30F4; tmp = Lob(d); // Equals 0xF4

Hib

Prototype

Returns

Description

Requires

Example

unsigned short Hib(long number);

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

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1AC30F4; tmp = Hib(d); // Equals 0x30

Higherb

Prototype

Returns

Description

Requires

Example

unsigned short Higherb(long number);

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

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1AC30F4; tmp = Higherb(d); // Equals 0xAC page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Highestb

Prototype

Returns

Description

Requires

Example

unsigned short Highestb(long number);

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

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1AC30F4; tmp = Highestb(d); // Equals 0x01

Lo

Prototype

unsigned int Lo(long number);

Returns

Returns the lowest 16 bits (word) of number, bits 0..15.

Description

Requires

Example

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1AC30F41AC30F4F0F1; tmp = Lo(d); // Equals 0xF0F1

Hi

Prototype

Returns

Description

Requires

Example

unsigned int Hi(long number);

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

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1A0F41AC30F4F0F1; tmp = Hi(d); // Equals 0x30F4 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Higher

Prototype

Returns

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned int Higher(long number);

Returns next to the highest word of number, bits 32..47.

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1A0F41AC30F4F0F1; tmp = Higher(d); // Equals 0x41AC

Highest

Prototype

Returns

Description

Requires

Example

unsigned int Highest(long number);

Returns the highest word of number, bits 48..63.

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

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.

Arguments must be scalar type (i.e. Arithmetic Types and Pointers).

d = 0x1A0F41AC30F4F0F1; tmp = Highest(d); // Equals 0x1A0F

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Delay_us

void Delay_us(const time_in_us);

Prototype

Description

Creates a software delay in duration of time_in_us microseconds (a constant). Range of applicable constants depends on the oscillator frequency.

Delay_us(10); /* Ten microseconds pause */

Example

Delay_ms

Prototype

Description

void Delay_ms(const time_in_ms);

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 */

Vdelay_ms

Prototype

Description

void Vdelay_ms(unsigned time_in_ms);

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 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Delay_Cyc

void Delay_Cyc(char Cycles_div_by_10);

Prototype

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Description

Example

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.

Delay_Cyc(10); /* Hundred MCU cycles pause */

Clock_Khz

Prototype

unsigned Clock_Khz(void);

Returns

Description

Example

Device clock in KHz, rounded to the nearest integer.

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

clk = Clock_Khz();

Clock_Mhz

Prototype

unsigned Clock_Mhz(void);

Returns

Description

Example

Device clock in MHz, rounded to the nearest integer.

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

clk = Clock_Mhz(); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

LIBRARY ROUTINES

mikroC provides a set of libraries which simplifies the initialization and use of dsPIC MCU and its modules. Library functions do not require any header files to be included; you can use them anywhere in your projects.

Currently available libraries are:

- ADC Library

- CAN Library

- CANSPI Library

- Compact Flash Library

- EEPROM Library

- SPI Ethernet Library

- Flash Memory Library

- Graphic LCD Library

- T6963C Graphic LCD Library

- I²C Library

- Keypad Library

- LCD Custom Library

- LCD8 Custom 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

- UART Library

- DSP Library

- Util Library

- ANSI C Ctype Library

- ANSI C Math Library

- ANSI C Stdlib Library

- ANSI C String Library

- Conversions Library

- Trigonometry Library

- sprint Library page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

ADC Library

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ADC (Analog to Digital Converter) module is available with a number of dsPIC

MCU models. Library function Adc_Read is included to provide you comfortable work with the module.

Adc_Read

Prototype

Returns

Description

Requires

Example

unsigned Adc_Read(char channel);

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

Initializes dsPIC’s internal ADC module to:

- Work with instruction cycle clock;

- Conversion clock is 32*Tcy;

- Sampling is auto-sample, auto-sample time is 31TAD;

Parameter channel represents the channel from which the analog value is to be acquired.

Refer to the appropriate datasheet for channel-to-pin mapping.

dsPIC MCU with built-in ADC module. You should consult the Datasheet documentation for specific device.

Before using the function, be sure to configure the appropriate TRISx bits to designate the pins as input. Also, configure the desired pin as analog (register ADPCFG), and set

Vref (voltage reference value).

unsigned tmp;

...

tmp = Adc_Read(1); /* read analog value from channel 1 */ page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

//--- for dsPIC30F4013

unsigned adcRes;

void main() {

PORTB = 0x0000;

TRISB = 0xFFFF; //all inputs

ADPCFG = 0; //all analog

Uart1_Init(9600);

Delay_ms(100);

while (1) { adcRes = Adc_Read(1);

Uart1_Write_Char(adcRes);

Delay_ms(5);

}

}//~!

Hardware Connection

mikroC for dsPIC making it simple...

VCC

RG15

RC1

RC2

RC3

RC4

RG6

RG7

RG8

MCLR

RG9

Vss

Vdd

RA12

RA13

RB5

RB4

RB3

RB2

RB1

RB0

RG12 RG14

RA7 RA6

RG0 RG1 RF1 RF0 Vdd Vss RD7 RD6 RD5 RD4 RD13 RD12 RD3 RD2 RD1

RC13

RD0

RD11

RD10 dsPIC30F6014

RD9

RD8

RA15

RA14

Vss

OSC2

OSC1

Vdd

RG2

RG3

RF6

RF7

RF8

RF2

RF3

RB6 RB7 RA9 RA10 A RB8 RB9 RB10 RB1

Vss Vdd RB12 RB13 RB14 RB15 RD14 RD15 RF4 RF5

VCC

Reset

10MHz

330

330

330

330

330

330

330

330

330

330

330

330

LD11

LD10

LD9

LD8

LD7

LD6

LD5

LD4

LD3

LD2

LD1

LD0 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN Library

mikroC for dsPIC provides a library (driver) for working with the CAN module.

CAN is a very robust protocol that has error detection and signalling, self–checking 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 dsPICmicros with CAN.

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

Library Routines

CAN1SetOperationMode

CAN1GetOperationMode

CAN1Initialize

CAN1SetBaudRate

CAN1SetMask

CAN1SetFilter

CAN1Read

CAN1Write

CAN2SetOperationMode

CAN2GetOperationMode

CAN2Initialize

CAN2SetBaudRate

CAN2SetMask

CAN2SetFilter

CAN2Read

CAN2Write page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Following routines are for the internal use by compiler only: mikroC for dsPIC making it simple...

- RegsToCANID

- CANIDToRegs

Be sure to check CAN constants necessary for using some of the functions.

CAN1SetOperationMode

Prototype

Description

void CAN1SetOperationMode(unsigned int mode, unsigned int wait_flag);

Sets CAN1 to requested mode

, i.e. copies mode to CAN1STAT. Parameter mode needs to be one of CAN1_OP_MODE constants (see CAN constants).

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 CAN1 module is switched to requested mode or not. Caller must use

CAN1GetOperationMode to verify correct operation mode before performing mode specific operation.

Requires

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

Example

CAN1SetOperationMode(CAN_MODE_CONFIG, 0xFF);

CAN1GetOperationMode

Prototype

unsigned int CAN1GetOperationMode(void);

Returns

Description

Requires

Current opmode.

Function returns current operational mode of CAN module.

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

Example

if (CAN1GetOperationMode() == CAN_MODE_NORMAL) { ... }; page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

CAN1Initialize

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void CAN1Initialize(unsigned int SJW, unsigned int BRP, unsigned

int PHSEG1, unsigned int PHSEG2, unsigned int PROPSEG, unsigned

int CAN_CONFIG_FLAGS);

Initializes CAN1. All pending transmissions are aborted. Sets all mask registers to 0 to allow all messages. The Config mode is internaly set by this function. Upon a execution of this function Normal mode is set.

Filter registers are set according to flag value: if (CAN_CONFIG_FLAGS & CAN_CONFIG_VALID_XTD_MSG != 0)

// Set all filters to XTD_MSG

else if (config & CONFIG_VALID_STD_MSG != 0)

// Set all filters to STD_MSG

else

// Set half the filters to STD, and the rest to XTD_MSG

Parameters:

SJW as defined in dsPIC datasheet (CAN1 Module)

BRP as defined in dsPIC datasheet (CAN1 Module)

PHSEG1 as defined in dsPIC datasheet (CAN1 Module)

PHSEG2 as defined in dsPIC datasheet (CAN1 Module)

PROPSEG as defined in dsPIC datasheet (CAN1 Module)

CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants)

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

init = CAN_CONFIG_SAMPLE_THRICE &

CAN_CONFIG_PHSEG2_PRG_ON &

CAN_CONFIG_STD_MSG &

CAN_CONFIG_DBL_BUFFER_ON &

CAN_CONFIG_VALID_XTD_MSG &

CAN_CONFIG_LINE_FILTER_OFF;

...

CAN1Initialize(1, 1, 3, 3, 1, init); // initialize CAN1 page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN1SetBaudRate

Prototype

Description

void CAN1SetBaudRate(unsigned int SJW, unsigned int BRP, unsigned

int PHSEG1, unsigned int PHSEG2, unsigned int PROPSEG, unsigned

int CAN_CONFIG_FLAGS);

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

Parameters:

SJW as defined in dsPIC datasheet (CAN1 Module)

BRP as defined in dsPIC datasheet (CAN1 Module)

PHSEG1 as defined in dsPIC datasheet (CAN1 Module)

PHSEG2 as defined in dsPIC datasheet (CAN1 Module)

PROPSEG as defined in dsPIC datasheet (CAN1 Module)

CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants)

Requires

Example

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

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

init = CAN_CONFIG_SAMPLE_THRICE &

CAN_CONFIG_PHSEG2_PRG_ON &

CAN_CONFIG_STD_MSG &

CAN_CONFIG_DBL_BUFFER_ON &

CAN_CONFIG_VALID_XTD_MSG &

CAN_CONFIG_LINE_FILTER_OFF;

...

CAN1SetBaudRate(1, 1, 3, 3, 1, init); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

CAN1SetMask

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void CAN1SetMask(unsigned int CAN_MASK, long value, unsigned int

CAN_CONFIG_FLAGS);

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

.

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

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

/* Set all mask bits to 1, i.e. all filtered bits are relevant:

*/

CAN1SetMask(CAN_MASK_B1, -1, CAN_CONFIG_XTD_MSG);

/* Note that -1 is just a cheaper way to write 0xFFFFFFFF.

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

CAN1SetFilter

Prototype

Description

void CAN1SetFilter(unsigned int CAN_FILTER, long value, unsigned

int CAN_CONFIG_FLAGS);

Function sets message filter. Given value is bit adjusted to appropriate buffer mask registers.

Requires

Example

Parameters:

-

CAN_FILTER 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

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

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

/* Set id of filter B1_F1 to 3: */

CAN1SetFilter(CAN_FILTER_B1_F1, 3, CAN_CONFIG_XTD_MSG); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN1Read

Prototype

Returns

Description

unsigned int CAN1Read(unsigned long *id, char *data, unsigned int

*datalen,

unsigned int *CAN_RX_MSG_FLAGS);

Message from receive buffer or zero if no message found.

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.

Requires

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).

CAN must be in mode in which receiving is possible.

Example

unsigned int rcv, rx, len; char data[8]; unsigned long id;

// ...

rx = 0;

// ...

rcv = CAN1Read(id, data, len, rx);

CAN1Write

Prototype

unsigned int CAN1Write(long id, char *data, unsigned int datalen,

unsigned int CAN_TX_MSG_FLAGS);

Returns

Description

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

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

Example

CAN must be in Normal mode.

unsigned int tx; char *data; long id; tx = CAN_TX_PRIORITY_0 &

CAN_TX_XTD_FRAME;

CAN1Write(id, data, 2, tx); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN2SetOperationMode

Prototype

Description

void CAN2SetOperationMode(unsigned int mode, unsigned int wait_flag);

Sets CAN2 to requested mode

, i.e. copies mode to CAN2STAT. Parameter mode needs to be one of CAN_OP_MODE constants (see CAN constants).

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 CAN2 module is switched to requested mode or not. Caller must use

CAN2GetOperationMode to verify correct operation mode before performing mode specific operation.

Requires

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

Example

CAN2SetOperationMode(CAN_MODE_CONFIG, 0xFF);

CAN2GetOperationMode

Prototype

unsigned int CAN2GetOperationMode(void);

Returns

Description

Requires

Current opmode.

Function returns current operational mode of CAN module.

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

Example

if (CAN2GetOperationMode() == CAN_MODE_NORMAL) { ... }; page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN2Initialize

Prototype

Description

Requires

Example

void CAN2Initialize(unsigned int SJW, unsigned int BRP, unsigned

int PHSEG1, unsigned int PHSEG2, unsigned int PROPSEG, unsigned

int CAN_CONFIG_FLAGS);

Initializes CAN2. All pending transmissions are aborted. Sets all mask registers to 0 to allow all messages. The Config mode is internaly set by this function. Upon a execution of this function Normal mode is set.

Filter registers are set according to flag value: if (CAN_CONFIG_FLAGS & CAN_CONFIG_VALID_XTD_MSG != 0)

// Set all filters to XTD_MSG

else if (config & CONFIG_VALID_STD_MSG != 0)

// Set all filters to STD_MSG

else

// Set half the filters to STD, and the rest to XTD_MSG

Parameters:

SJW as defined in dsPIC datasheet (CAN2 Module)

BRP as defined in dsPIC datasheet (CAN2 Module)

PHSEG1 as defined in dsPIC datasheet (CAN2 Module)

PHSEG2 as defined in dsPIC datasheet (CAN2 Module)

PROPSEG as defined in dsPIC datasheet (CAN2 Module)

CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants)

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

init = CAN_CONFIG_SAMPLE_THRICE &

CAN_CONFIG_PHSEG2_PRG_ON &

CAN_CONFIG_STD_MSG &

CAN_CONFIG_DBL_BUFFER_ON &

CAN_CONFIG_VALID_XTD_MSG &

CAN_CONFIG_LINE_FILTER_OFF;

...

CAN2Initialize(1, 1, 3, 3, 1, init); // initialize CAN2 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

CAN2SetBaudRate

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void CAN2SetBaudRate(unsigned int SJW, unsigned int BRP, unsigned

int PHSEG1, unsigned int PHSEG2, unsigned int PROPSEG, unsigned

int CAN_CONFIG_FLAGS);

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

Parameters:

SJW as defined in dsPIC datasheet (CAN2 Module)

BRP as defined in dsPIC datasheet (CAN2 Module)

PHSEG1 as defined in dsPIC datasheet (CAN2 Module)

PHSEG2 as defined in dsPIC datasheet (CAN2 Module)

PROPSEG as defined in dsPIC datasheet (CAN2 Module)

CAN_CONFIG_FLAGS is formed from predefined constants (see CAN constants)

Requires

Example

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

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

init = CAN_CONFIG_SAMPLE_THRICE &

CAN_CONFIG_PHSEG2_PRG_ON &

CAN_CONFIG_STD_MSG &

CAN_CONFIG_DBL_BUFFER_ON &

CAN_CONFIG_VALID_XTD_MSG &

CAN_CONFIG_LINE_FILTER_OFF;

...

CAN2SetBaudRate(1, 1, 3, 3, 1, init);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN2SetMask

Prototype

Description

Requires

Example

void CAN2SetMask(unsigned int CAN_MASK, long value, unsigned int

CAN_CONFIG_FLAGS);

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

.

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

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

/* Set all mask bits to 1, i.e. all filtered bits are relevant:

*/

CAN2SetMask(CAN_MASK_B1, -1, CAN_CONFIG_XTD_MSG);

/* Note that -1 is just a cheaper way to write 0xFFFFFFFF.

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

CAN2SetFilter

Prototype

Description

void CAN2SetFilter(unsigned int CAN_FILTER, long value, unsigned

int CAN_CONFIG_FLAGS);

Function sets message filter. Given value is bit adjusted to appropriate buffer mask registers.

Requires

Example

Parameters:

-

CAN_FILTER 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

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

CAN routines are currently supported only by dsPICmicros with CAN modules.

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

/* Set id of filter B1_F1 to 3: */

CAN2SetFilter(CAN_FILTER_B1_F1, 3, CAN_CONFIG_XTD_MSG); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN2Read

Prototype

Returns

Description

unsigned int CAN2Read(unsigned long *id, char *data, unsigned int

*datalen,

unsigned int *CAN_RX_MSG_FLAGS);

Message from receive buffer or zero if no message found.

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.

Requires

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).

CAN must be in mode in which receiving is possible.

Example

unsigned int rcv, rx, len; char data[8]; unsigned long id;

// ...

rx = 0;

// ...

rcv = CAN2Read(id, data, len, rx);

CAN2Write

Prototype

unsigned int CAN2Write(long id, char *data, unsigned int datalen,

unsigned int CAN_TX_MSG_FLAGS);

Returns

Description

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

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

Example

CAN must be in Normal mode.

unsigned int tx; char *data; long id; tx = CAN_TX_PRIORITY_0 &

CAN_TX_XTD_FRAME;

CAN2Write(id, data, 2, tx); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC 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:

#define CAN_MODE_BITS

#define CAN_MODE_NORMAL

#define CAN_MODE_SLEEP

#define CAN_MODE_LOOP

#define CAN_MODE_LISTEN

#define CAN_MODE_CONFIG

0xE0 // Use it to access mode bits

0

0x20

0x40

0x60

0x80

CAN_CONFIG_FLAGS

CAN_CONFIG_FLAGS constants define flags related to CAN module configuration.

Functions

CANInitialize and

CANSetBaudRate expect one of these (or a bitwise combination) as their argument:

#define CAN_CONFIG_DEFAULT 0xFF // 11111111

#define CAN_CONFIG_PHSEG2_PRG_BIT

#define CAN_CONFIG_PHSEG2_PRG_ON

#define CAN_CONFIG_PHSEG2_PRG_OFF

#define CAN_CONFIG_LINE_FILTER_BIT

#define CAN_CONFIG_LINE_FILTER_ON

#define CAN_CONFIG_LINE_FILTER_OFF

#define CAN_CONFIG_SAMPLE_BIT

#define CAN_CONFIG_SAMPLE_ONCE

#define CAN_CONFIG_SAMPLE_THRICE

#define CAN_CONFIG_MSG_TYPE_BIT

#define CAN_CONFIG_STD_MSG

#define CAN_CONFIG_XTD_MSG

// continues..

0x01

0xFF // XXXXXXX1

0xFE // XXXXXXX0

0x02

0xFF // XXXXXX1X

0xFD // XXXXXX0X

0x04

0xFF // XXXXX1XX

0xFB // XXXXX0XX

0x08

0xFF // XXXX1XXX

0xF7 // XXXX0XXX page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// ..continued

#define CAN_CONFIG_DBL_BUFFER_BIT

#define CAN_CONFIG_DBL_BUFFER_ON

#define CAN_CONFIG_DBL_BUFFER_OFF

#define CAN_CONFIG_MSG_BITS

#define CAN_CONFIG_ALL_MSG

#define CAN_CONFIG_VALID_XTD_MSG

#define CAN_CONFIG_VALID_STD_MSG

#define CAN_CONFIG_ALL_VALID_MSG

0x10

0xFF // XXX1XXXX

0xEF // XXX0XXXX

0x60

0xFF // X11XXXXX

0xDF // X10XXXXX

0xBF // X01XXXXX

0x9F // X00XXXXX

You may use bitwise AND (

&

) to form config byte out of these values. For example: init = CAN_CONFIG_SAMPLE_THRICE & CAN_CONFIG_PHSEG2_PRG_ON &

CAN_CONFIG_STD_MSG & CAN_CONFIG_DBL_BUFFER_ON &

CAN_CONFIG_VALID_XTD_MSG & 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:

#define CAN_TX_PRIORITY_BITS

#define CAN_TX_PRIORITY_0

#define CAN_TX_PRIORITY_1

#define CAN_TX_PRIORITY_2

#define CAN_TX_PRIORITY_3

#define CAN_TX_FRAME_BIT

#define CAN_TX_STD_FRAME

#define CAN_TX_XTD_FRAME

#define CAN_TX_RTR_BIT

#define CAN_TX_NO_RTR_FRAME

#define CAN_TX_RTR_FRAME

0x03

0xFC // XXXXXX00

0xFD // XXXXXX01

0xFE // XXXXXX10

0xFF // XXXXXX11

0x08

0xFF // XXXXX1XX

0xF7 // XXXXX0XX

0x40

0xFF // X1XXXXXX

0xBF // 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 && CAN_TX_XTD_FRAME &

CAN_TX_NO_RTR_FRAME;

//...

CANSendMessage(id, data, 1, send_config); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC 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.

#define CAN_RX_FILTER_BITS 0x07

// Use it to access filter bits

#define CAN_RX_FILTER_1 0x00

#define CAN_RX_FILTER_2 0x01

#define CAN_RX_FILTER_3

#define CAN_RX_FILTER_4

#define CAN_RX_FILTER_5

#define CAN_RX_FILTER_6

#define CAN_RX_OVERFLOW

0x02

0x03

0x04

0x05

0x08

// Set if Overflowed; else clear

#define CAN_RX_INVALID_MSG 0x10

// Set if invalid; else clear

#define CAN_RX_XTD_FRAME 0x20

// Set if XTD msg; else clear

#define CAN_RX_RTR_FRAME 0x40

// Set if RTR msg; else clear

#define CAN_RX_DBL_BUFFERED 0x80 // Set if msg was

// hardware double-buffered

You may use bitwise AND (

&

) to adjust the appropriate flags. For example:

if (MsgFlag & CAN_RX_OVERFLOW != 0) {

... // 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:

#define CAN_MASK_B1 0

#define CAN_MASK_B2 1

CAN_FILTER

CAN_FILTER constants define filter codes. Function

CANSetFilter expects one of these as its argument:

#define CAN_FILTER_B1_F1 0

#define CAN_FILTER_B1_F2 1

#define CAN_FILTER_B2_F1 2

#define CAN_FILTER_B2_F2 3

#define CAN_FILTER_B2_F3 4

#define CAN_FILTER_B2_F4 5 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

unsigned int aa, aa1, len, aa2;

unsigned char data[8];

unsigned long id;

unsigned int zr, cont, oldstate;

void main() {

ADPCFG = 0xFFFF;

PORTB = 0;

TRISB = 0;

PORTF = 0;

TRISF = 0; aa = 0; aa1 = 0; aa2 = 0; aa1 = CAN_TX_PRIORITY_0 & // Form value to be used

CAN_TX_XTD_FRAME & // with CANSendMessage

CAN_TX_NO_RTR_FRAME; aa = CAN_CONFIG_SAMPLE_THRICE & // Form value to be used

CAN_CONFIG_PHSEG2_PRG_ON & // with CANInitialize

CAN_CONFIG_STD_MSG &

CAN_CONFIG_DBL_BUFFER_ON &

CAN_CONFIG_MATCH_MSG_TYPE &

CAN_CONFIG_LINE_FILTER_OFF; data[0] = 9;

CAN1Initialize(1,3,3,3,1,aa); // initialize CAN

CAN1SetOperationMode(CAN_MODE_CONFIG,0xFF); // set CONFIGURATION mode id = -1;

CAN1SetMask(CAN_MASK_B1,id,CAN_CONFIG_MATCH_MSG_TYPE & CAN_CONFIG_XTD_MSG);

// set all mask1 bits to ones

CAN1SetMask(CAN_MASK_B2,id,CAN_CONFIG_MATCH_MSG_TYPE & CAN_CONFIG_XTD_MSG);

// set all mask2 bits to ones

CAN1SetFilter(CAN_FILTER_B2_F3,3,CAN_CONFIG_XTD_MSG); // set id of filter

B1_F1 to 3

CAN1SetOperationMode(CAN_MODE_NORMAL,0xFF); // set NORMAL mode

// code continues on next page...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//..continued

id = 12111; data[1] = 0xF1;

CAN1Write(id,data,1,aa1);

while (1) { zr = CAN1Read(&id , data , &len, &aa2);

if ((id == 3u) && zr) {

PORTB = data[0]; // output data at portB data[0]++ ;

Delay_ms(10); id = 12111;

CAN1Write(id, data, 1,aa1); // send incremented data back

}

}

}//~! page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CAN TX of MCU

CAN RX of MCU

VCC

10

1

2

3

4

TX-CAN RS

GND CANH

VCC CANL

RXD Vref

8

7

6

5

MCP2551

Shielded pair no longer than 300m

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI Library

SPI module is available with a number of dsPICmicros. mikroC provides a library

(driver) for working with the external CAN modules (such as MCP2515 or

MCP2510) via SPI.

In mikroC, 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 dsPIC MCU that has SPI module. Also,

CS pin of MCP2510 or MCP2515 must be connected to RF0. Example of HW connection is given at the end of the chapter.

- CANSPI library uses SPI1 module for SPI communication.

Library Routines

CANSPI1SetOperationMode

CANSPI1GetOperationMode

CANSPI1Initialize

CANSPI1SetBaudRate

CANSPI1SetMask

CANSPI1SetFilter

CANSPI1Read

CANSPI1Write

CANSPI2SetOperationMode

CANSPI2GetOperationMode

CANSPI2Initialize

CANSPI2SetBaudRate

CANSPI2SetMask

CANSPI2SetFilter

CANSPI2Read

CANSPI2Write

Following routines are for the internal use by compiler only:

RegsToCANSPI1ID, CANSPI1IDToRegs

RegsToCANSPI2ID, CANSPI2IDToRegs page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI1SetOperationMode

Prototype

Description

Requires

Example

void CANSPI1SetOperationMode(unsigned short mode, unsigned short wait_flag);

Sets CANSPI1 to requested mode. Parameter mode needs to be one of

CANSPI1_OP_MODE constants (see CANSPI constants).

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 CANSPI1 is switched to requested mode or not. Caller must use CANSPI1GetOperationMode to verify correct operation mode before performing mode specific operation.

CANSPI1 functions are supported by any dsPIC MCU that has SPI. Also, CS pin of

MCP2510 or MCP2515 must be connected to RF0.

CANSPI1SetOperationMode(CANSPI_MODE_CONFIG, 0xFF);

CANSPI1GetOperationMode

Prototype

unsigned short CANSPI1GetOperationMode(void);

Returns

Description

Example

Current opmode.

CANSPI1 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

CANSPI1GetOperationMode();

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI1Init

Prototype

Description

void CANSPI1Init( char SJW, char BRP, char PHSEG1, char PHSEG2,

char PROPSEG, char CAN_CONFIG_FLAGS, unsigned int * RstPort, char

RstPin, unsigned int * CSPort, char CSPin);

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

Filter registers are set according to flag value:

if (CANSPI_CONFIG_FLAGS & CANSPI_CONFIG_VALID_XTD_MSG != 0)

// Set all filters to XTD_MSG

else if (config & CONFIG_VALID_STD_MSG != 0)

// Set all filters to STD_MSG

else

// Set half the filters to STD, and the rest to XTD_MSG

Parameters:

SJW as defined in dsPIC datasheet (CAN Module).

BRP as defined in dsPIC datasheet (CAN Module).

PHSEG1 as defined in dsPIC datasheet (CAN Module).

PHSEG2 as defined in dsPIC datasheet (CAN Module).

PROPSEG as defined in dsPIC datasheet (CAN Module).

CANSPI_CONFIG_FLAGS is formed from predefined constants (see CANSPI Constants).

Requires

Example

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

CANSPI1 functions are supported by any PIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

init = CANSPI_CONFIG_SAMPLE_THRICE &

CANSPI_CONFIG_PHSEG2_PRG_ON &

CANSPI_CONFIG_STD_MSG &

CANSPI_CONFIG_DBL_BUFFER_ON &

CANSPI_CONFIG_VALID_XTD_MSG &

CANSPI_CONFIG_LINE_FILTER_OFF;

...

CANSPI1Init(1, 1, 3, 3, 1, init); // initialize CANSPI1 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

CANSPI1SetBaudRate

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void CANSPI1SetBaudRate(unsigned short SJW, unsigned short BRP,

unsigned short PHSEG1, unsigned short PHSEG2, unsigned short

PROPSEG, unsigned short CANSPI_CONFIG_FLAGS);

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

Parameters:

SJW as defined in datasheet (1–4)

BRP as defined in datasheet (1–64)

PHSEG1 as defined in datasheet (1–8)

PHSEG2 as defined in datasheet (1–8)

PROPSEG as defined in datasheet (1–8)

CANSPI_CONFIG_FLAGS is formed from predefined constants (see CANSPI Constants).

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

CANSPI1 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

init = CANSPI_CONFIG_SAMPLE_THRICE &

CANSPI_CONFIG_PHSEG2_PRG_ON &

CANSPI_CONFIG_STD_MSG &

CANSPI_CONFIG_DBL_BUFFER_ON &

CANSPI_CONFIG_VALID_XTD_MSG &

CANSPI_CONFIG_LINE_FILTER_OFF;

...

CANSPI1SetBaudRate(1, 1, 3, 3, 1, init);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI1SetMask

Prototype

Description

Requires

Example

void CANSPI1SetMask(unsigned short CANSPI_MASK, long value,

unsigned short CANSPI_CONFIG_FLAGS);

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

Parameters:

-

CANSPI_MASK is one of predefined constant values (see CANSPI Constants)

- value is the mask register value

-

CANSPI_CONFIG_FLAGS selects type of message to filter, either

CANSPI_CONFIG_XTD_MSG or

CANSPI_CONFIG_STD_MSG

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

CANSPI functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

/* Set id of filter B1_F1 to 3: */

CANSPI1SetFilter(CANSPI_FILTER_B1_F1, 3, CANSPI_CONFIG_XTD_MSG);

CANSPI1SetFilter

Prototype

Description

Requires

Example

void CANSPI1SetFilter(unsigned short CANSPI_FILTER, long value,

unsigned short CANSPI_CONFIG_FLAGS);

Function sets message filter. Given value is bit adjusted to appropriate buffer mask registers.

Parameters:

-

CANSPI_FILTER is one of predefined constant values (see CANSPI Constants)

- value is the filter register value

-

CANSPI_CONFIG_FLAGS selects type of message to filter, either

CANSPI_CONFIG_XTD_MSG or

CANSPI_CONFIG_STD_MSG

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

CANSPI1 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

/* Set id of filter B1_F1 to 3: */

CANSPI1SetFilter(CANSPI_FILTER_B1_F1, 3, CANSPI_CONFIG_XTD_MSG); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI1Read

Prototype

unsigned short CANSPI1Read(long *id, unsigned short *data,

unsigned short *datalen, unsigned short *CANSPI_RX_MSG_FLAGS);

Returns

Description

Message from receive buffer or zero if no message found.

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:

Requires

Example

- id is message identifier.

- data is an array of bytes up to 8 bytes in length.

- datalen is data length, from 1–8.

-

CANSPI_RX_MSG_FLAGS is value formed from constants (see CANSPI Constants).

CANSPI1 must be in mode in which receiving is possible.

CANSPI1 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

unsigned short rcv, rx, len, data[8]; long id; rcv = CANSPI1Read(id, data, len, rx);

CANSPI1Write

Prototype

Returns

Description

unsigned short CANSPI1Write(long id, unsigned short *data,

unsigned short datalen, unsigned short CANSPI_TX_MSG_FLAGS);

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

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 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

- CANSPI_TX_MSG_FLAGS is value formed from constants (see CANSPI Constants).

Requires

Example

CANSPI1 must be in Normal mode. CANSPI1 functions are supported by any dsPIC

MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

unsigned short tx, data; long id; tx = CANSPI_TX_PRIORITY_0 & CANSPI_TX_XTD_FRAME;

CANSPI1Write(id, data, 2, tx);

Miik ro le tr niik De ve op en t ol -- oE le tr niik D ev lo me t oo s B oo ks page

C om piil er

17

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI2SetOperationMode

Prototype

Description

Requires

Example

void CANSPI2SetOperationMode(unsigned short mode, unsigned short wait_flag);

Sets CANSPI2 to requested mode. Parameter mode needs to be one of

CANSPI_OP_MODE constants (see CANSPI constants).

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 CANSPI2 is switched to requested mode or not. Caller must use CANSPI2GetOperationMode to verify correct operation mode before performing mode specific operation.

CANSPI2 functions are supported by any dsPIC MCU that has SPI. Also, CS pin of

MCP2510 or MCP2515 must be connected to RF0.

CANSPI2SetOperationMode(CANSPI_MODE_CONFIG, 0xFF);

CANSPI2GetOperationMode

Prototype

unsigned short CANSPI2GetOperationMode(void);

Returns

Description

Example

Current opmode.

CANSPI2 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

CANSPI2GetOperationMode(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

CANSPI2Init

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void CANSPI2Init( char SJW, char BRP, char PHSEG1, char PHSEG2,

char PROPSEG, char CAN_CONFIG_FLAGS, unsigned int * RstPort, char

RstPin, unsigned int * CSPort, char CSPin);

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

Filter registers are set according to flag value:

if (CANSPI_CONFIG_FLAGS & CANSPI_CONFIG_VALID_XTD_MSG != 0)

// Set all filters to XTD_MSG

else if (config & CONFIG_VALID_STD_MSG != 0)

// Set all filters to STD_MSG

else

// Set half the filters to STD, and the rest to XTD_MSG

Parameters:

SJW as defined in dsPIC datasheet (CAN Module).

BRP as defined in dsPIC datasheet (CAN Module).

PHSEG1 as defined in dsPIC datasheet (CAN Module).

PHSEG2 as defined in dsPIC datasheet (CAN Module).

PROPSEG as defined in dsPIC datasheet (CAN Module).

CANSPI_CONFIG_FLAGS is formed from predefined constants (see CANSPI Constants).

Requires

Example

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

CANSPI2 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

init = CANSPI_CONFIG_SAMPLE_THRICE &

CANSPI_CONFIG_PHSEG2_PRG_ON &

CANSPI_CONFIG_STD_MSG &

CANSPI_CONFIG_DBL_BUFFER_ON &

CANSPI_CONFIG_VALID_XTD_MSG &

CANSPI_CONFIG_LINE_FILTER_OFF;

...

CANSPI2Init(1, 1, 3, 3, 1, init); // initialize CANSPI2 page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI2SetBaudRate

Prototype

Description

Requires

Example

void CANSPI2SetBaudRate(unsigned short SJW, unsigned short BRP,

unsigned short PHSEG1, unsigned short PHSEG2, unsigned short

PROPSEG, unsigned short CANSPI_CONFIG_FLAGS);

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

Parameters:

SJW as defined in datasheet

BRP as defined in datasheet

PHSEG1 as defined in datasheet

PHSEG2 as defined in datasheet

PROPSEG as defined in datasheet

CANSPI_CONFIG_FLAGS is formed from predefined constants (see CANSPI Constants).

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

CANSPI2 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

init = CANSPI_CONFIG_SAMPLE_THRICE &

CANSPI_CONFIG_PHSEG2_PRG_ON &

CANSPI_CONFIG_STD_MSG &

CANSPI_CONFIG_DBL_BUFFER_ON &

CANSPI_CONFIG_VALID_XTD_MSG &

CANSPI_CONFIG_LINE_FILTER_OFF;

...

CANSPI2SetBaudRate(1, 1, 3, 3, 1, init); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

CANSPI2SetMask

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void CANSPI2SetMask(unsigned short CANSPI_MASK, long value,

unsigned short CANSPI_CONFIG_FLAGS);

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

Parameters:

-

CANSPI_MASK is one of predefined constant values (see CANSPI Constants)

- value is the mask register value

-

CANSPI_CONFIG_FLAGS selects type of message to filter, either

CANSPI_CONFIG_XTD_MSG or

CANSPI_CONFIG_STD_MSG

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

CANSPI2 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

/* Set id of filter B1_F1 to 3: */

CANSPI2SetFilter(CANSPI_FILTER_B1_F1, 3, CANSPI_CONFIG_XTD_MSG);

CANSPI2SetFilter

Prototype

Description

Requires

Example

void CANSPI2SetFilter(unsigned short CANSPI_FILTER, long value,

unsigned short CANSPI_CONFIG_FLAGS);

Function sets message filter. Given value is bit adjusted to appropriate buffer mask registers.

Parameters:

-

CANSPI_FILTER is one of predefined constant values (see CANSPI Constants)

- value is the filter register value

-

CANSPI_CONFIG_FLAGS selects type of message to filter, either

CANSPI_CONFIG_XTD_MSG or

CANSPI_CONFIG_STD_MSG

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

CANSPI2 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

/* Set id of filter B1_F1 to 3: */

CANSPI2SetFilter(CANSPI_FILTER_B1_F1, 3, CANSPI_CONFIG_XTD_MSG); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

CANSPI2Read

Prototype

unsigned short CANSPI2Read(long *id, unsigned short *data,

unsigned short *datalen, unsigned short *CANSPI_RX_MSG_FLAGS);

Returns

Description

Message from receive buffer or zero if no message found.

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:

Requires

Example

- id is message identifier.

- data is an array of bytes up to 8 bytes in length.

- datalen is data length, from 1–8.

-

CANSPI_RX_MSG_FLAGS is value formed from constants (see CANSPI Constants).

CANSPI2 must be in mode in which receiving is possible.

CANSPI2 functions are supported by any dsPIC MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

unsigned short rcv, rx, len, data[8]; long id; rcv = CANSPI2Read(id, data, len, rx);

CANSPI2Write

Prototype

Returns

Description

unsigned short CANSPI2Write(long id, unsigned short *data,

unsigned short datalen, unsigned short CANSPI_TX_MSG_FLAGS);

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

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 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

- CANSPI_TX_MSG_FLAGS is value formed from constants (see CANSPI Constants).

Requires

Example

CANSPI2 must be in Normal mode. CANSPI2 functions are supported by any dsPIC

MCU that has SPI interface. Also, CS pin of MCP2510 or MCP2515 must be connected to RF0.

unsigned short tx, data; long id; tx = CANSPI_TX_PRIORITY_0 & CANSPI_TX_XTD_FRAME;

CANSPI2Write(id, data, 2, tx); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The code is a simple demonstration of CANSPI protocol. It is a simple data exchange between 2 dsPIC’s, where data is incremented upon each bounce. Data is printed on PORTB (lower byte) and

PORTD (higher byte) for a visual check.

char

aa, aa1, len, aa2;

char

data[8];

long

id;

unsigned short

zr;

void main() {

char dcanstat;

ADPCFG = 0xFFFF;

PORTB = 0;

TRISB =0;

Spi1_Init();

PORTD = 0;

TRISD = 0; aa = 0; aa1 = 0; aa2 = 0; aa = CANSPI_CONFIG_SAMPLE_THRICE & // form value to be used

CANSPI_CONFIG_PHSEG2_PRG_ON & // with CANSPIInitialize

CANSPI_CONFIG_STD_MSG &

CANSPI_CONFIG_DBL_BUFFER_ON &

CANSPI_CONFIG_VALID_XTD_MSG; aa1 = CANSPI_TX_PRIORITY_0 & // form value to be used

//portd = 1;

CANSPI1Init(1,3,3,3,1,aa, &PORTF, 1, &PORTF, 0); // initialize external CAN

module

CANSPI_TX_XTD_FRAME & // with CANSPISendMessage

CANSPI_TX_NO_RTR_FRAME; portd = 3;

CANSPI1SetOperationMode(CANSPI_MODE_CONFIG,0xFF); // set CONFIGURATION mode portd = 4;

ID=-1;

// continues ..

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// .. continued

CANSPI1SetMask(CANSPI_MASK_B1,id,CANSPI_CONFIG_XTD_MSG);// set all mask1 bits

to ones

CANSPI1SetMask(CANSPI_MASK_B2,id,CANSPI_CONFIG_XTD_MSG);// set all mask2 bits

to ones

CANSPI1SetFilter(CANSPI_FILTER_B2_F4,3,CANSPI_CONFIG_XTD_MSG);// set id of

filter B1_F1 to 12111

CANSPI1SetOperationMode(CANSPI_MODE_NORMAL,0xFF);// set NORMAL mode portd = 5; data[0] = 7; id = 12111;

CANSPI1Write(id,data,1,aa1); while(1) { zr = CANSPI1Read(&id , data , &len, &aa2);// receive data, if any if ((id == 3) && (zr)) {

PORTB = data[0]; data[0]++; // output data at portB id=12111; delay_ms(100);

CANSPI1Write(id,data,1,aa1);

}

}//~! if (len == 2) { // send incremented data back

PORTD = data[1]; // if message contains two data bytes

}

} // output second byte at portd page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

VCC

100K

8 MhZ

1

4

5

2

3

8

9

6

7

TX

RX

CLKO

Vdd

RST

CS

TX0

TX1

SO

SI

TX2

OSC2

SCK

INT

OSC1 RX0B

Vss RX1B

18

17

16

15

14

13

12

11

10

MCP2510

VCC

VCC

10

1

2

3

4

TX-CAN RS

GND CANH

VCC CANL

RXD

Vref

MCP2551

8

7

6

5

Shielded pair no longer than 300m

VCC

13

14

VCC

GND

OSC1

OSC2

10 MhZ

RF0

30

RF2

RF3

RF6

26

25

24

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

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 performed directly, but successively through 512B buffer. Following routines can be used for CF with FAT16, and FAT32 file system. Note that routines for file handling can be used only with FAT16 file system.

Important! File accessing routines can write file. File names must be exactly 8 characters long and written in uppercase. User must ensure different names for each file, as CF routines will not check for possible match.

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_Enable

Cf_Disable

Cf_Read_Init

Cf_Read_Byte

Cf_Read_Word

Cf_Write_Init

Cf_Write_Byte

Cf_Write_Word

Cf_Read_Sector

Cf_Write_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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Cf_Init

Prototype

Description

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Cf_Init(unsigned *port_A012, unsigned pin_A0, unsigned pin_A1, unsigned pin_A2, unsigned *port_RDY, unsigned pin_RDY,

unsigned *port_WE, unsigned pin_WE, unsigned *port_OE, unsigned pin_OE,

unsigned *port_CD1, unsigned pin_CD1, unsigned *port_CE1,

unsigned pin_CE1, unsigned *port_Data);

Initializes ports appropriately for communication with CF card. Specify dataport as the lower byte of any port. Every control line must be specified by its port and pin. Data port is determined by the port_Data

, where it uses lines <0:7>.

Cf_Init(&PORTB, &PORTD);

Cf_Detect

Prototype

Returns

Description

Requires

Example

unsigned Cf_Detect(void);

Returns 1 if CF is present, otherwise returns 0.

Checks for presence of CF card on ctrlport

.

Ports must be initialized. See

Cf_Init

.

// Wait until CF card is inserted:

do nop; while (!Cf_Detect());

Cf_Enable

Prototype

Description

void Cf_Enable(void);

Enables the device. Routine needs to be called only if you have disabled the device by means of

Cf_Disable

. These two routines in conjuction allow you to free/occupy data line when working with multiple devices. Check the example at the end of the chapter.

Requires

Example

Ports must be initialized. See

Cf_Init

.

Cf_Enable(); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Cf_Disable

void Cf_Disable(void);

Prototype

Description

Requires

Example

Routine disables the device and frees the data line for other devices. To enable the device again, call

Cf_Enable

. These two routines in conjuction allow you to free/occupy data line when working with multiple devices. Check the example at the end of the chapter.

Ports must be initialized. See

Cf_Init

.

Cf_Disable();

Cf_Read_Init

Prototype

Description

void Cf_Read_Init(unsigned long address, unsigned short sectcnt);

Initializes CF card for reading. Parameter address specifies sector address from where data will be read, and sectcnt is the number of sectors prepared for reading operation.

Requires

Example

Ports must be initialized. See

Cf_Init

.

Cf_Read_Init(590, 1);

Cf_Read_Byte

unsigned Cf_Read_Byte(void);

Prototype

Returns

Description

Requires

Example

Returns byte from CF. Note: Higher byte of unsigned return value is cleared. Returns byte from CF.

Reads one byte from CF.

Ports must be initialized. See

Cf_Init

.

CF must be initialized for read operation. See

Cf_Read_Init

.

PORTC = Cf_Read_Byte(); // Read byte and display it on PORTC page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Cf_Read_Word

Prototype

unsigned Cf_Read_Word(void);

Returns

Description

Requires

Example

Returns word (16-bit) from CF.

Reads one word from CF.

Ports must be initialized. See

Cf_Init

.

CF must be initialized for read operation. See

Cf_Read_Init

.

PORTC = Cf_Read_Word(); // Read byte and display it on PORTC

Cf_Write_Init

Prototype

Description

Requires

Example

void Cf_Write_Init(unsigned long address, unsigned short sectcnt);

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.

Ports must be initialized. See

Cf_Init

.

Cf_Write_Init(590, 1);

Cf_Write_Byte

void Cf_Write_Byte(unsigned short data);

Prototype

Description

Requires

Writes one byte ( data

) to CF.

Ports must be initialized. See

Cf_Init

.

CF must be initialized for write operation. See

Cf_Write_Init

.

Example

Cf_Write_Byte(100);

Cf_Write_Word

Prototype

void Cf_Write_Word(unsigned data);

Returns

Description

Requires

Example

Nothing.

Writes one word (data) to CF. All 512 bytes are transferred to a buffer.

Ports must be initialized. See

Cf_Init

. CF must be initialized for read operation. See

Cf_Read_Init

.

Cf_Write_Word(i + 11); // Write word to CF page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Cf_Read_Sector

Prototype

void Cf_Read_Sector(unsigned sector_number, unsigned char

*buffer);

Description

Requires

Reads one sector (sector_number) into buffer.

Ports must be initialized. See

Cf_Init

.

Example

Cf_Read_Sector(22, &data);

Cf_Write_Sector

Prototype

Returns

Description

Requires

Example

void Cf_Write_Sector(unsigned sector_number, unsigned char

*buffer);

Nothing.

Writes value from buffer to CF sector at sector_number

.

Ports must be initialized. See

Cf_Init

.

Cf_Write_Sector(22, &data); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Cf_Fat_Init

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Prototype

Returns

Description

unsigned short Cf_Fat_Init(char * ctrlport, char * dataport);

Returns 1 if initialization is successful, 0 if boot sector was not found and 255 if card was not detected.

Initializes ports appropriately for FAT operations with CF card. Specify two different ports: ctrlport and dataport

.

Nothing.

CF_Fat_Init(PORTD,PORTC);

Requires

Example

Cf_Fat_Assign

Prototype

unsigned short Cf_Fat_Assign(char *filename, char create_file);

Returns

Description

Requires

Example

"1" is file is present(or file isn't present but new file is created), or "0" if file isn't present and no new file is created.

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).

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

Cf_Fat_Assign('MIKROELE.TXT',1);

Cf_Fat_Reset

Prototype

Returns

Description

Requires

Example

void Cf_fat_Reset(unsigned long *size);

Size of file in bytes. Size is stored on address of input variable.

Opens assigned file for reading.

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

File must be assigned. See Cf_Fat_Assign.

Cf_Fat_Reset(size); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Cf_Fat_Read

Prototype

void Cf_Fat_Read(unsigned short *bdata);

Description

Requires

Example

Reads data from file. bdata is data read from file.

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.

Cf_Fat_Read(character);

Cf_Fat_Rewrite

Prototype

void Cf_fat_Rewrite();

Returns

Nothing.

Description

Requires

Example

Rewrites assigned file.

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

File must be assigned. See Cf_Fat_Assign.

Cf_Fat_Rewrite;

Cf_Fat_Append

void Cf_fat_Append();

Prototype

Returns

Description

Requires

Example

Nothing.

Opens file for writing. This procedure continues writing from the last byte in file.

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

File must be assigned. See Cf_Fat_Assign.

Cf_Fat_Append; page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Cf_Fat_Delete

void Cf_Fat_Delete();

Prototype

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Description

Requires

Example

Deletes file from CF.

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

File must be assigned. See Cf_Fat_Assign.

Cf_Fat_Delete;

Cf_Fat_Write

Prototype

Returns

void Cf_fat_Write(char *fdata, unsigned data_len);

Nothing.

Description

Requires

Example

Writes data to CF. fdata parameter is data written to CF. data_len number of bytes that is written to CF.

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.

Cf_Fat_Write(file_contents, 42); // write data to the assigned

file

Cf_Fat_Set_File_Date

Prototype

Returns

Description

Requires

Example

void Cf_fat_Set_File_Date(unsigned int year, unsigned short month, unsigned short day, unsigned short hours, unsigned short mins, unsigned short seconds);

Nothing.

Sets time attributes of file.You can set file year, month, day. hours, mins, seconds.

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.

Cf_Fat_Set_File_Date(2005,9,30,17,41,0); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Cf_Fat_Get_File_Date

Prototype

Description

Requires

Example

void Cf_Fat_Get_File_Date(unsigned int *year, unsigned short

*month, unsigned short *day, unsigned short *hours, unsigned

short *mins);

Reads time attributes of file.You can read file year, month, day. hours, mins.

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

File must be assigned. See Cf_Fat_Assign.

Cf_Fat_Get_File_Date(year, month, day, hours, mins);

Cf_Fat_Get_File_Size

unsigned long Cf_fat_Get_File_Size();

Prototype

Returns

Size of file in bytes.

Description

Requires

Example

This function returns size of file in bytes.

Ports must be initialized for FAT operations with CF. See Cf_Fat_Init.

File must be assigned. See Cf_Fat_Assign.

Cf_Fat_Get_File_Size; page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Cf_Fat_Get_Swap_File

Prototype

unsigned long Cf_Fat_Get_Swap_File(unsigned long sectors_cnt);

Returns

Description

No. of start sector for the newly created swap file, if swap file was created; otherwise, the function returns zero.

This function is used to create a swap file on the Compact Flash 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 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.

Requires

Example

The purpose of the swap file is to make reading and writing to the card as fast as possible, by using the Cf_Read_Sector() and Cf_Write_Sector() functions directly, 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 mikroC's library is to be used for fast data acquisition; when the time-critical acquisition has finished, the data can be re-written into a "normal" file, and formatted in the most suitable way.

Ports must be initialized for FAT operations with CF.

See Cf_Fat_Init.

//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 UART1

void M_Create_Swap_File() { size = Cf_Fat_Get_Swap_File(1000);

if (size) {

Uart1_Write_Char(0xAA);

Uart1_Write_Char(Lob(size));

Uart1_Write_Char(Hib(size));

Uart1_Write_Char(Higherb(size));

Uart1_Write_Char(Highestb(size));

Uart1_Write_Char(0xAA);

}

}//~ page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The following example writes 512 bytes at sector no.620, and then reads the data and sends it over

UART1 for a visual check.

void main() {

unsigned int i, tmp;

Uart1_Init(19200);

CF_Write_Init(620,1); // Initialize write at sector address 620

// for 1 sector (byte)

Uart1_Write_Char('s'); // Notify that write has started

Delay_ms(1000);

for (i=0; i<=511; i++) { // Write 512 bytes to sector 620

CF_Write_Byte(i);

}

Delay_ms(1000);

}

//--- read written data

CF_Read_Init(620,2); // Initialize read from sector address 620

Delay_ms(1000);

// for 1 sector (byte)

Cf_Read_Sector(620, buff); // Read 512 bytes from sector address 620

for (i=0; i<=511; i++) {

Uart1_Write_Char(buff[i]);

} page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

HW Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

RG14

RG12

RD11

RG15

RG13

RD10

RD9

RD8

RD7

RD6

RD5

RD4

RD3

RD2

RD1

RD0

RG15

RC1

RC2

RC3

RC4

RG6

RG7

RG8

MCLR

RG9

Vss

Vdd

RA12

RA13

RB5

RB4

RB3

RB2

RB1

RB0

RG13 RG12

RB6 RB7

RA7 RA6 RD7 RD6 dsPIC30FXXXX

RC14

RC13

RD0

RD11

RD10

RD9

RD8

RA15

RA14

Vss

OSC2

OSC1/CLKI

Vdd

RG2

RG3

RF6

RF7

RF8

RF2

RF3

RA10 AV Vdd RB12

VCC

VCC

50

25

49

48

24

47

23

22

46

45

21

44

20

43

19

18

42

41

17

40

28

27

16

39

15

29

14

38

37

12

36

33

11

35

34

10

9

8

32

31

30

13

7

6

5

4

3

2

26

1

R25

10K

VCC

Compact Flash

Card

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

EEPROM Library

EEPROM data memory is available with a number of dsPICmicros. mikroC for dsPIC includes library for comfortable work with EEPROM.

Library Routines

Eeprom_Erase

Eeprom_Erase_Block

Eeprom_Read

Eeprom_Write

Eeprom_Write_Block

Eeprom_Erase

void Eeprom_Erase(unsigned long address);

Prototype

Returns

Description

Requires

Example

Nothing.

Erases a single (16-bit) location in EEPROM memory.

Requires EEPROM module.

Erase cycle will complete in 2mS. CPU is not stalled for the Data Erase cycle. User can poll WR bit, use NVMIF or Timer IRQ to determine completion of erase sequence.

unsigned short take;

...

Eeprom_Erase(0x7FFC20); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Eeprom_Erase_Block

Prototype

void Eeprom_Erase_Block(unsigned long address);

Returns

Description

Requires

Nothing.

Erases a 16-word (32-byte) block of EEPROM memory.

Requires EEPROM module.

Example

Erase cycle will complete in 2mS. CPU is not stalled for the Data Erase cycle. User can poll WR bit, use NVMIF or Timer IRQ to determine completion of erase sequence.

Eeprom_Erase_Block(0x7FFC20);

Eeprom_Read

unsigned int Eeprom_Read(unsigned long address);

Prototype

Returns

Description

Requires

Example

Returns word from the specified address.

Reads data from specified address. It is programmer’s responsibility to obtain proper address parity (in this case, even).

Requires EEPROM module.

take = Eeprom_Read(0x7FFC30);

Eeprom_Write

Prototype

void Eeprom_Write(unsigned long address, unsigned int data);

Returns

Description

Nothing.

Writes data to specified address.

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

Example

Requires EEPROM module.

Write cycle will complete in 2mS. CPU is not stalled for the Data Write Cycle. User can poll WR bit, use NVMIF or Timer IRQ to determine write complete.

eeRead = 0xAAAA; wrAddr = 0x7FFC30;

Eeprom_Write(wrAddr, eeRead++); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Eeprom_Write_Block

Prototype

Description

Requires

Example

void Eeprom_Write_Block(unsigned long address, unsigned int * data);

Writes a block (16 words) of data from an array or structure to specified address.

It is user's responsibility to maintain proper address allignment. In this case, address has to be a multiply of 32, which is the size (in bytes) of one row of PIC's EEPROM memory.

Requires EEPROM module.

Write cycle will last at least for 2mS. CPU is not stalled for the Data Write Cycle. User can poll WR bit, use NVMIF or Timer IRQ to determine write complete.

eeRead = 0xAAAA; wrAddr = 0x7FFC30;

Eeprom_Write(wrAddr, eeRead++);

Library Example

unsigned int eeRead;

unsigned long wrAddr;

unsigned int iArr[16] = {'m', 'i', 'k', 'r', 'o', 'E', 'l', 'e', 'k'};

void main() {

//--- disable analog inputs

ADPCFG = 0xFFFF;

TRISB = 0;

LATB = 0xFFFF; eeRead = 0xAAAA; wrAddr = 0x7FFC30;

while (eeRead < 0xAABA) {

Eeprom_Write(wrAddr, eeRead++); while(NVMCONbits.WR) ;

LATB = Eeprom_Read(wrAddr); wrAddr += 2;

Delay_ms(500);

}

//--- write entire row of EEPROM data

Eeprom_Write_Block(0x7FFC20, iArr);

}//~! page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

SPI Ethernet Library

This library is designed to simplify handling of the underlying hardware

(ENC28J60). 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 dsPIC available to a much broader audience than you could do with the RS232/485 (UART) or CAN.

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 number of packet filtering schemes to limit incoming packets. It also provides an internal DMA module for fast data throughput and hardware assisted IP checksum calculations. Communication with the host controller is implemented via two interrupt 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.

Note: This library uses TIMER1 for timeout logic.

Library Routines

Ethernet Initialization

EthSetMACAddr

EthSetIPAddr

EthSetIPMask

EthSetGateWayAddr

EthInit 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

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Media Access Control Layer (MAC)

MACInit

MACIsTxReady

MACGetHeader

MACGet

MACGetArray

MACDiscardRx

MACPutHeader

MACPut

MACPutArray

MACFlush

MACDiscardTx

MACSetTxBuffer

MACSetRxBuffer

MACReserveTxBuffer

MACGetFreeRxSize

MACSetDuplex

Internet Protocol (IP)

IPIsTxReady

IPSetTxBuffer

IPPutHeader

IPPutArray

IPGetHeader

IPGetArray

IPSetRxBuffer

Internet Control Message Protocol(ICMP)

ICMPIsTxReady

ICMPPut

ICMPGet mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Transmission Control Protocol (TCP)

TCPInit

TCPListen

TCPConnect

TCPIsConnected

TCPDisconnect

TCPIsPutReady

TCPPut

TCPFlush

TCPGet

TCPGetArray

TCPDiscard

TCPProcess

TCPTick

User Datagram Protocol (UDP)

TCPInit

TCPListen

TCPConnect

TCPIsConnected

TCPDisconnect

TCPIsPutReady

TCPPut

TCPFlush

TCPGet

TCPGetArray

TCPDiscard

TCPProcess

TCPTick

Other

StackInit

StackTask

HTTPInit

HTTPServer page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

EthSetMACAddr

Prototype

Returns

Description

Requires

Example

void EthSetMACAddr(char MACByte1, char MACByte2, char MACByte3,

char MACByte4, char MACByte5, char MACByte6);

Nothing.

This routine sets MAC address.

Nothing.

// Sets MAC address

EthSetMACAddr(00,02,04,06,08,10);

EthSetIPAddr

Prototype

Description

void EthSetIPAddr(char IpByte1, char IpByte2, char IpByte3, char

IpByte4);

This routine sets IP address.

Requires

Example

EthSetIPMask

Nothing.

// Sets IP address

EthSetIPAddr(192,168,20,1);

Prototype

Description

void EthSetIPMask(char IPMaskByte1, char IPMaskByte2, char

IPMaskByte3, char IPMaskByte4);

This routine sets IP address mask.

Requires

Example

Nothing.

// Sets address mask

EthSetIPMask(255,255,255,0);

EthSetGateWayAddr

Prototype

Description

void EthSetGateWayAddr(char GateWayByte1, char GateWayByte2, char

GateWayByte3, char GateWayByte4);

This routine sets Gateway IP address.

Requires

Example

Nothing.

// Sets Gateway IP address

EthSetGateWayAddr(192,168,20,1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

EthInit

Prototype

Description

Requires

Example

void EthInit(unsigned int * RstPort, unsigned int RstPin,

unsigned int *CSPort, unsigned int CSPin);

This routine initializes NIC and global variables needed for Ethernet connection.

EthSetMACAddr, EthSetIPAddr, EthSetIPMask needs to be set before calling this routine. Calling EthSetGateWayAddr before this routine is optional.

// Initializes Ethernet connection

EthInit(PORTF,0,PORTF,1);

MACInit

Prototype

Description

Requires

Example

MACIsTxReady

Prototype

char MACIsTxReady();

Returns

Description

Requires

Example

void MACInit(unsigned int * RstPort, unsigned int RstPin,

unsigned int* CSPort, unsigned int CSPin);

This function initializes MAC layer. It initializes internal buffers and resets the NIC to a known state. All pending transmission and receptions are discarded.

As specified for the entire library (MAC.c).

// Initialize MAC Module

MACInit(PORTF,0,PORTF,1);

(!=0) - If at least one MAC transmit buffer is empty.

(==0) - If all MAC transmit buffers are full.

This function indicates whether at least one MAC transmit buffer is empty or not.

As specified for the entire library (MAC.c).

// Check MAC transmit readiness...

if ( MACIsTxReady() )

{

// Transmit buffer is empty, transmit a message.

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACGetHeader

char MACGetHeader(MAC_ADDR *remote, unsigned char *type);

Prototype

Returns

Description

(!=0) : If a data packet is received and found to be valid. All parameters are populated.

(==0) : If no data packet is received or found to be invalid.

This function checks the MAC receive buffer; if any packet is found, it returns the remote host and data packet information.

Remote specifies Remote MAC address and type represents Data packet type. Possible values for type parameter are: MAC_IP (An

IP data packet is received), MAC_ARP (An ARP data packet is received)

MAC_UNKNOWN (An unknown or unsupported data packet is received).

Requires

Example

As specified for the entire library (MAC.c).

// Get possible data packet info.

if ( MACGetHeader(&RemoteNodeMAC, &PacketType) )

{

// A packet is received, process it.

...

// Once done, discard it.

MACDiscardRx();

...

MACGet

Prototype

Returns

Description

Requires

Example

unsigned char MACGet();

Data byte.

This function returns the next byte from an active transmit or receive buffer.

MACGetHeader, MACPutHeader, MACSetRxBuffer or MACSetTxBuffer must have been called.

// Get possible data packet info.

if ( MACGetHeader(&RemoteNode, &PacketType) )

{

// A packet is received, process it.

data = MACGet();

...

// When done, discard it.

MACDiscardRx();

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACGetArray

Prototype

unsigned int MACGetArray(unsigned char *val, unsigned int len);

Returns

Description

Requires

Total number of bytes fetched.

This function fetches an array of bytes from the active transmit or receive buffer. val represents pointer to a byte array and len represents number of bytes to fetch.

MACGetHeader, MACPutHeader,MACSetRxBuffer or MACSetTxBuffer must have been called.

Example

// Get possible data packet info.

if ( MACGetHeader(&RemoteNode, &PacketType) )

{

// A packet is received, process it.

actualCount = MACGetArray(data, count);

...

MACDiscardRx

void MACDiscardRx();

Prototype

Returns

Description

Requires

Example

Nothing.

This function discards the active receive buffer data and marks that buffer as free.

Nothing.

// Get possible data packet info.

if ( MACGetHeader(&RemoteNode, &PacketType) )

{

// A packet is received, process it.

actualCount = MACGetArray(data, count);

...

// Done processing it. Discard it.

MACDiscardRx();

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACPutHeader

Prototype

Returns

Description

void MACPutHeader(MAC_ADDR *remote, unsigned char type, unsigned

int dataLen);

Nothing.

This function assembles the MAC header and loads it to an active transmit buffer.

remote

- Remote node MAC address, type

- Type of data packet being sent. Possible values for this parameter are: MAC_IP(An IP data packet is to be transmitted) and

MAC_ARP(An ARP data packet is to be transmitted), data

- Number of bytes for this packet, including IP header.

Requires

Example

Nothing.

// Check to see if at least one transmit buffer is empty

if ( MACIsTxReady() )

{

// Assemble IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

...

MACPut

Prototype

Returns

Description

Requires

Example

void MACPut(unsigned char val);

Nothing.

This function loads the given data byte into an active transmit or receive buffer. val

-

Data byte to be written.

MACGetHeader, MACPutHeader, MACSetRxBuffer or MACSetTxBuffer must have been called.

// Check to see if at least one transmit buffer is empty

if ( MACIsTxReady() )

{

// Assemble IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

// Now put the actual IP data bytes

MACPut(0x55);

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACPutArray

Prototype

Returns

Description

Requires

Example

void MACPutArray(unsigned char *val, unsigned int len);

Nothing.

This function writes an array of data bytes into an active transmit or receive buffer. val

- Data bytes to be written. len

- Total number of bytes to write.

MACGetHeader, MACPutHeader, MACSetTxBuffer or MACSetRxBuffer must have been called.

// Check to see if at least one transmit buffer is empty

if ( MACIsTxReady() )

{

// Assemble IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

// Now put the actual IP data bytes

MACPut(0x55);

MACPutArray(data, count);

...

MACFlush

Prototype

Description

Requires

Example

void MACFlush();

This function marks active transmit buffer as ready for transmission.

MACPutHeader or MACSetTxBuffer must have been called.

// Check to see if at least one transmit buffer is empty if ( MACIsTxReady() )

{

// Assemble IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

// Put the actual IP data bytes

MACPut(0x55);

MACPutArray(data, count);

...

// Now transmit it.

MACFlush();

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACDiscardTx

void MACDiscardTx(BUFFER buffer);

Prototype

Description

Requires

Example

This function discards given transmit buffer content and marks it as free.

Nothing.

// Check to see if at least one transmit buffer is empty

if ( MACIsTxReady() )

{

// Assemble IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

// Get current transmit buffer

buffer = MACGetTxBuffer();

// Reserve it.

MACReserveTxBuffer (Buffer);

// Put the actual IP data bytes

...

// Now transmit it.

MACFlush();

// No longer need this buffer

MACDiscardTx(buffer);

...

MACSetRxBuffer

Prototype

void MACSetRxBuffer(unsigned int offset);

Description

This function sets the access location for the active receive buffer. offset - Location

(with respect to beginning of buffer) where next access is to occur.

Requires

Nothing.

Example

// Get possible data packet info.

if ( MACGetHeader(&RemoteNode, &PacketType) )

{

// A packet is received, process it.

actualCount = MACGetArray(data, count);

...

// Fetch data beginning at offset 20

MACSetRxBuffer(20); data = MACGet();

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACSetTxBuffer

void MACSetTxBuffer(BUFFER buffer, unsigned int offset);

Prototype

Description

Requires

Example

This function sets the access location for a given transmit buffer, and makes that transmit buffer active. buffer

- A transmit buffer where this access offset be applied. offset

- Location (with respect to beginning of buffer) where next access is to occur.

Nothing.

// Check to see if at least one transmit buffer is empty

if ( MACIsTxReady() )

{

// Assemble IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

// Get current transmit buffer

buffer = MACGetTxBuffer();

// Put the actual IP data bytes

...

// Calculate the checksum of data packet that is being transmit-

ted

...

// Now update the checksum in this packet.

// To update the checksum, set transmit buffer access to checksum

MACSetTxBuffer(buffer, checksumLocation);

...

// Now transmit it.

MACFlush();

...

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACReserveTxBuffer

Prototype

void MACReserveTxBuffer(BUFFER buffer);

Description

This function reserves a given transmit buffer and marks it as unavailable. This function is useful for TCP layer where a message would be queued until it is correctly acknowledged by remote host. buffer

- A transmit buffer to reserve. This value must be a valid transmit buffer identifier as returned by MACGetTxBuffer function.

Requires

Example

Nothing.

// Check to see if at least one transmit buffer is empty

if ( MACIsTxReady() )

{

// Transmit IP packet with total IP packet size of 100 bytes

// including IP header.

MACPutHeader(&RemoteNodeMAC, MAC_IP, 100);

// Get current transmit buffer

buffer = MACGetTxBuffer();

// Reserve it, to be discarded when ACK is received.

MACReserveTxBuffer(buffer);

// Put the actual IP data bytes

...

// Calculate the checksum of data packet that is being transmitted

...

// Now update the checksum in this packet.

// To update the checksum, set transmit buffer access to checksum

MACSetTxBuffer(buffer, checksumLocation);

...

// Now transmit it.

MACFlush();

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

MACGetFreeRxSize

Prototype

Returns

Description

Requires

Example

unsigned int MACGetFreeRxSize();

Total number of bytes available for future data packets.

This function returns total receive buffer size available for future data packets.

Nothing.

// Get available receive buffer size

freeRxBuffer = MACGetFreeRxSize();

MACSetDuplex

Prototype

Returns

Description

Requires

Example

void MACSetDuplex(DUPLEX DuplexState);

Nothing.

This routine sets FULL-DUPLEX or HALF-DUPLEX communication mode. Input value can be 1 for FULL-DUPLEX, 0 for HALF-DUPLEX and 2 for NIC defined communication mode.

Nothing.

//FULL-DUPLEX communication is set

MACSetDuplex(1);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ARPGet

Prototype

Returns

Description

Requires

Example

char ARPGet(NODE_INFO *remote, unsigned char *opCode);

(!=0)

- If a valid ARP packet that was addressed to local host was fetched; remote and opCode contain valid values.

(==0)

- Either unknown ARP code was fetched or this packet was not addressed to local host.

This function fetches complete ARP packet and returns necessary information. remote

-

Remote node information such as MAC and IP addresses. opCode

- ARP code. Possible values for this parameter are:

ARP_REPLY

("ARP Reply" packet is received),

ARP_REQUEST

(“ARP Request” packet is received),

ARP_UNKNOWN

(An unknown ARP packet is received).

MACGetHeader is already called AND Received MAC packet type == MAC_ARP

// If MAC packet is received...

if ( MACGetHeader(&RemoteNode, &PacketType) )

{

// If this is an ARP packet, fetch it.

If ( PacketType == MAC_ARP )

{

// This is ARP packet.

ARPGet(&RemoteNode, &ARPCode);

...

ARPPut

Prototype

Description

Requires

Example

void ARPPut(NODE_INFO *remote, unsigned char opCode);

This function loads MAC buffer with valid ARP packet. remote

- Remote node information such as MAC and IP addresses. opCode

- ARP code. Possible values for this parameter are:

ARP_REPLY

(Transmit this packet as "ARP Reply"),

ARP_REQUEST

(Transmit this packet as "ARP Request").

ARPIsTxReady == TRUE

// Check to see if transmit buffer is available

if ( ARPIsTxReady() )

{

// Transmit it

ARPPut(&RemoteNode, ARP_REQUEST);

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ARPInit

Prototype

Description

Requires

Example

void ARPInit();

This function initializes the ARPTask state machine and prepares it to handle ARP requests and replies.

Nothing.

// Initialize ARPTask

ARPInit();

...

IPIsTxReady

Prototype

char IPIsTxReady();

Returns

Description

Requires

Example

(!=0)

- If there is at least one transmit buffer empty.

(==0)

- If there is no empty transmit buffer.

This is a macro that calls MACIsTxReady in turn.

Nothing.

// If IP transmit buffer is ready, transmit IP packet

if ( IPIsTxReady() )

{

// Assemble IP packet.

IPPutHeader(&Remote, MAC_TCP, IPPacketLen);

...

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IPSetTxBuffer

Prototype

void IPSetTxBuffer(BUFFER buffer, unsigned int offset);

Returns

Description

Requires

Nothing.

This is a macro to allow higher level layer set transmit buffer access pointer. This macro takes IP header into account before calling MACSetTxBuffer. buffer

- Transmit buffer identifier whose access pointer is to be set. offset

- An offset with respect to IP Data.

Nothing.

Example

// If IP transmit buffer is ready, transmit IP packet

if ( IPIsTxReady() )

{

// Assemble IP packet.

IPPutHeader(&Remote, MAC_TCP, IPPacketLen);

// Get current transmit buffer id.

buffer = MACGetTxBuffer();

// Load transmit data

...

// Calculate checksum checkHi:checkLo

...

// Update the checksum.

IPSetTxBuffer(buffer, checkLocation);

MACPut (checkHi);

MACPut (checkLo);

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IPPutHeader

Prototype

Returns

Description

Requires

Example

unsigned int IPPutHeader(NODE_INFO *remote, char protocol,

unsigned int len);

Nothing.

This function assembles a valid IP header and loads it into active transmit buffer.

remote

- Remote node information such as MAC and IP addresses. protocol

-

Protocol to use for this data packet. Possible values for this parameter are:

IP_PROT_ICMP

(Assemble this packet as ICMP),

IP_PROT_TCP

(Assemble this packet as TCP segment),

IP_PROT_UDP

(Assemble this packet as UDP segment). len

- Total length of IP data bytes, excluding IP header.

IPIsTxReady == TRUE

// Check to see if transmit buffer is available

if ( IPIsTxReady() )

{

// Load the header

IPPutHeader(&RemoteNode, IP_PROT_ICMP, ICMP_HEADER_SIZE+dataLen);

// Load ICMP data

IPPutArray(ICMPData, dataLen);

// Mark it as ready to be transmitted

MACFlush();

...

IPPutArray

Prototype

void IPPutArray(char *buffer, unsigned int len);

Returns

Description

Nothing.

This macro loads an array of bytes into the active transmit buffer. buffer

- Data array that is to loaded. len

- Total number of items in data array.

Requires

Example

IPIsTxReady == TRUE

// Check to see if transmit buffer is available

if ( IPIsTxReady() )

{

// Load the header

IPPutHeader(&RemoteNode, IP_PROT_ICMP, ICMP_HEADER_SIZE+dataLen);

// Load ICMP data

IPPutArray(ICMPData, dataLen);

// Mark it as ready to be transmitted

MACFlush();

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IPGetHeader

Prototype

Returns

Description

Requires

Example

char IPGetHeader(IP_ADDR *localIP, NODE_INFO *remote, char *protocol, unsigned int *len);

(!=0)

- A valid IP packet was received. Remote IP address, packet protocol and packet length parameters are populated.

(==0)

- An invalid IP packet was received. Parameters are not populated.

This function fetches the IP header from the active transmit buffer and validates it.

localIP

- Local node information such as MAC and IP addresses, remote

- Remote node information such as MAC and IP addresses, protocol

- Protocol associated with this IP packet. Possible values for this parameter are: IP_PROT_ICMP (This is an ICMP packet), IP_PROT_TCP (This is a TCP packet), IP_PROT_UDP (This is a UDP packet), all others Unknown protocol. len

- Total length of IP data in this packet.

MACGetHeader == TRUE

// Check to see if any packet is ready

if ( MACGetHeader(&RemoteMACAddr, &PacketType) )

{

// Check what kind of protocol it is

if ( PacketType == MAC_IP )

{

// This is IP packet. Fetch it.

IPGetHeader(&Local, &Remote, &IPProtocol, &IPLen);

// Process this IP packet.

...

// When done processing this packet, discard it

MACDiscardRx();

}

else

{

// This is not an IP packet. Handle it

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IPGetArray

Prototype

Returns

Description

Requires

Example

unsigned int IPGetArray(char *val, unsigned int len);

Total number of bytes fetched.

This macro fetches an array of bytes from an active transmit or receive buffer. val

-

Pointer to a buffer to byte array. len

- Number of bytes to fetch.

IPGetHeader, IPPutHeader, IPSetRxBuffer or IPSetTxBuffer must have been called.

// Check to see if any packet is ready

if ( MACGetHeader(&RemoteMACAddr, &PacketType) )

{

// Check what kind of protocol it is

if ( PacketType == MAC_IP )

{

// This is IP packet. Fetch it.

IPGetHeader(&Remote, &IPProtocol, &IPLen);

// Get 20 bytes of data

IPGetArray(IPData, 20);

...

// When done processing this packet, discard it

MACDiscardRx();

}

else

{

// This is not an IP packet. Handle it

...

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IPSetRxBuffer

Prototype

void IPSetRxBuffer(unsigned int offset);

Returns

Description

Requires

Example

Nothing.

This macro allows a higher level layer to set the receive buffer access pointer. It takes the IP header into account before calling MACSetRxBuffer. offset

- An offset with respect to IP Data.

Nothing.

// Check to see if any packet is ready

if ( MACGetHeader(&RemoteMACAddr, &PacketType) )

{

// Check what kind of protocol it is

if ( PacketType == MAC_IP )

{

// This is IP packet. Fetch it.

IPGetHeader(&Remote, &IPProtocol, &IPLen);

// Fetch 20th byte within IP data.

IPSetRxBuffer(20); data = MACGet();

...

// When done processing this packet, discard it

MACDiscardRx();

}

else

{

// This is not an IP packet. Handle it

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ICMPIsTxReady

char ICMPIsTxReady();

Prototype

Returns

Description

Requires

Example

(!=0)

- If there is at least one transmit buffer empty.

(==0)

- If there is no empty transmit buffer.

This macro determines if at least one transmit buffer is empty.

Nothing.

// If IP transmit buffer is ready, transmit IP packet if ( ICMPIsTxReady() )

{

// Transmit ICMP packet.

...

ICMPPut

Prototype

Returns

Description

Requires

Example

void ICMPPut(NODE_INFO *remote, ICMP_CODE code, char *data, char len, unsigned int id, unsigned int seq);

Nothing.

This function assembles a valid ICMP packet and transmits it. remote

- Remote node information such as MAC and IP addresses, code

- ICMP code to be used for this ICMP packet. Possible values for this parameter are:

ICMP_ECHO_REPLY

(This is an ICMP

Echo reply packet),

ICMP_ECHO_REQUEST

(This is an ICMP Echo request packet).

data

- ICMP data. len

- ICMP data length. id

- ICMP packet identifier. seq

- ICMP packet sequence number.

IPIsTxReady == TRUE

// Check to see if transmit buffer is available

if ( ICMPIsTxReady() )

{

// Transmit ICMP packet.

ICMPPut(&RemoteNode, ICMP_ECHO_REPLY, data, datalen, id, seq);

// Done. ICMP is put into transmit queue.

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ICMPGet

Prototype

Returns

Description

Requires

Example

void ICMPGet(NODE_INFO *remote, ICMP_CODE *code, char *data, char

*len, unsigned int *id, unsigned int *seq);

(!=0)

- A valid ICMP packet was received. All parameters are populated.

(==0)

- An invalid ICMP packet was received. Parameters are not populated.

This function fetches the ICMP header from the active transmit buffer and validates it.

remote

- Remote node information such as MAC and IP addresses. code

- ICMP code for received ICMP packet. Possible values for this parameter are:

ICMP_ECHO_REPLY

(An ICMP Echo reply packet is received),

ICMP_ECHO_REQUEST

(An ICMP Echo request packet is received), for all others (An unknown/unsupported packet is received).

data

- ICMP data. len

- ICMP data length. id

- ICMP packet identifier. seq

- ICMP packet sequence number.

IPGetHeader == TRUE

PacketType == IP_PROT_ICMP

// Check to see if any packet is ready

if ( IPGetHeader(&Remote, &IPProtocol, &IPLen) )

{

// Check what kind of protocol it is

if ( IPProtocol == IP_PROT_ICMP )

{

// This is ICMPP packet. Fetch it.

ICMPGet(&ICMPCode, data, &dataLen, &id, &seq);

// Process this ICMP packet.

...

// When done processing this packet, discard it

MACDiscardRx();

}

else

{

// This is not an ICMP packet. Handle it

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPInit

Prototype

Description

Requires

Example

void TCPInit();

This function initializes the TCP state machine and prepares it for multiple TCP connections.

Nothing.

// Initialize TCP

TCPInit();

TCPListen

Prototype

Returns

Description

Requires

Example

TCP_SOCKET TCPListen(TCP_PORT port);

A valid socket identifier if there was at least one free socket. INVALID_SOCKET if there is no socket available.

This function assigns one of the available sockets to listen on given TCP port. port

-

TCP Port number on which to listen.

Nothing.

...

switch(smState)

{

case SM_LISTEN:

// Listen for HTTP requests.

httpSocket = TCPListen(80);

If ( httpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

...

}

else

smState = SM_LISTEN_WAIT; return;

case SM_LISTEN_WAIT:

// Wait for connection...

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPConnect

Prototype

Returns

Description

Requires

TCP_SOCKET TCPConnect(NODE_INFO *remote, TCP_PORT port);

A valid socket identifier if there was at least one free socket. INVALID_SOCKET if there is no socket available.

This function initiates a connection request to a remote host on a given remote port.

remote

- Remote host that needs to be connected. port

- TCP Port number on remote host to connect to.

Nothing.

Example

...

switch(smState)

{

case SM_CONNECT:

// Connect to a remote FTP server.

ftpSocket = TCPConnect(&RemoteNode, 21);

If ( ftpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_CONNECT_WAIT; return;

case SM_CONNECT_WAIT:

// Wait for connection...

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPIsConnected

Prototype

char TCPIsConnected(TCP_SOCKET socket);

Returns

(!=0)

If given socket is connected to remote host.

(==0)

If given socket is not connected to remote host.

Description

Requires

This function determines whether a given socket is connected to remote host or not.

socket

- Socket identifier for which the connection is to be checked.

Nothing.

switch(smState)

{

case SM_CONNECT:

// Connect to a remote FTP server.

ftpSocket = TCPConnect(&RemoteNode, 21);

If ( ftpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_CONNECT_WAIT; return;

case SM_CONNECT_WAIT:

// Wait for connection...

if ( TCPIsConnected(ftpSocket) ) smState = SM_CONNECTED;

return;

...

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPPut

Prototype

Returns

Description

Requires

Example

char TCPPut(TCP_SOCKET socket, char byte);

(!=0)

- If a given data byte was successfully loaded into the transmit buffer and there is room for more data.

(==0)

- If a given data byte was successfully loaded into the transmit buffer and there is no room for more data.

This function loads a data byte into the transmit buffer for a given socket. socket

-

Socket identifier that needs to be checked. byte

- Data byte to be loaded.

TCPIsPutReady == TRUE

...

switch(smState)

{

case SM_CONNECT:

// Connect to a remote FTP server.

ftpSocket = TCPConnect(&RemoteNode, 21);

If ( ftpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_CONNECT_WAIT;

return;

case SM_CONNECT_WAIT:

// Wait for connection...

if ( TCPIsConnected(ftpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Send data

if ( TCPIsPutReady(ftpSocket) )

{

// Send data

TCPPut(ftpSocket, dataByte);

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

TCPFlush

Prototype

Returns

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void TCPFlush(TCP_SOCKET socket);

Nothing.

This function marks given socket transmit buffer as ready to be transmitted. socket -

Socket identifier that needs to transmitted.

TCPIsPutReady == TRUE

...

switch(smState)

{

case SM_CONNECT:

// Connect to a remote FTP server.

ftpSocket = TCPConnect(&RemoteNode, 21);

If ( ftpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_CONNECT_WAIT;

return;

case SM_CONNECT_WAIT:

// Wait for connection...

if ( TCPIsConnected(ftpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Send data

if ( TCPIsPutReady(ftpSocket) )

{

// Send data

TCPPut(ftpSocket, dataByte);

...

// Now transmit it.

TCPFlush(ftpSocket);

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPIsGetReady

Prototype

char TCPIsGetReady(TCP_SOCKET socket);

Returns

Description

Nothing.

(!=0)

- If given socket contains receive data.

(==0)

- If given socket does not contain any data.

Requires

Example

This function determines if the given socket contains receive data. socket

- Socket identifier that needs to transmitted.

...

switch(smState)

{

case SM_LISTEN:

// Listen to HTTP socket

httpSocket = TCPListen(&RemoteNode, 80);

If ( httpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_LISTEN_WAIT;

return;

case SM_LISTEN_WAIT:

// Wait for connection...

if ( TCPIsConnected(httpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Fetch data

if ( TCPIsGetReady(httpSocket) )

{

// Fetch data

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

TCPGet

Prototype

Returns

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

char TCPGet(TCP_SOCKET socket, char *byte);

(!=0)

- If a byte was read.

(==0)

- If no byte was read.

This function fetches one data byte from a given socket receive buffer. socket

- Socket identifier that needs to be fetched. byte

- Data byte that was read.

TCPIsGetReady == TRUE

...

switch(smState)

{

case SM_LISTEN:

// Listen to HTTP socket

httpSocket = TCPListen(&RemoteNode, 80);

If ( httpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_LISTEN_WAIT;

return;

case SM_LISTEN_WAIT:

// Wait for connection...

if ( TCPIsConnected(httpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Fetch data

if ( TCPIsGetReady(httpSocket) )

{

// Fetch data

TCPGet(httpSocket, &dataByte);

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPGetArray

Prototype

unsigned int TCPGetArray(TCP_SOCKET socket, char *byte, unsigned

int count);

Returns

Description

Requires

Example

Total number of data bytes read.

This function fetches a data array from a given socket receive buffer. socket

- Socket identifier that needs to be fetched. byte

- Data array that was read. count

- Total number of bytes to read.

TCPIsGetReady == TRUE

...

switch(smState)

{

case SM_LISTEN:

// Listen to HTTP socket

httpSocket = TCPListen(&RemoteNode, 80);

If ( httpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_LISTEN_WAIT;

return;

case SM_LISTEN_WAIT:

// Wait for connection...

if ( TCPIsConnected(httpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Fetch data

if ( TCPIsGetReady(httpSocket) )

{

// Fetch 20 bytes of data

TCPGetArray(httpSocket, buffer, 20);

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPDiscard

Prototype

char TCPDiscard(TCP_SOCKET socket);

Returns

(!=0)

- If receive buffer for given was successfully discarded.

(==0)

- If receive buffer for given buffer was already discarded.

Description

Requires

Example

This function releases the receive buffer associated with a given socket. socket - Socket identifier that needs to transmitted.

Nothing.

...

switch(smState)

{ case SM_LISTEN:

// Listen to HTTP socket

httpSocket = TCPListen(&RemoteNode, 80);

If ( httpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_LISTEN_WAIT;

return;

case SM_LISTEN_WAIT:

// Wait for connection...

if ( TCPIsConnected(httpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Fetch data

if ( TCPIsGetReady(httpSocket) )

{

// Fetch 20 bytes of data

TCPGetArray(httpSocket, buffer, 20);

// Process data.

...

// Release the buffer.

TCPDiscard(httpSocket);

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPDisconnect

void TCPDisconnect(TCP_SOCKET socket);

Prototype

Returns

Description

Requires

Example

Nothing.

This function requests remote host to disconnect.

Nothing.

switch(smState)

{

case SM_CONNECT:

// Connect to a remote FTP server.

ftpSocket = TCPConnect(&RemoteNode, 21);

If ( ftpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_CONNECT_WAIT;

return;

case SM_CONNECT_WAIT:

// Wait for connection...

if ( TCPIsConnected(ftpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Send data

...

// Disconnect

TCPDisconnect(ftpSocket);

...

mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPIsPutReady

Prototype

char TCPIsPutReady(TCP_SOCKET socket);

Returns

Description

(!=0)

- If given socket is ready to transmit.

(==0)

- If given socket is not connected or there is no transmit buffer ready.

This function determines if a socket is ready to transmit. A socket is ready to transmit when it is connected to a remote host and its transmit buffer is empty. socket

- Socket identifier that needs to be checked.

Requires

Example

Nothing.

...

switch(smState)

{

case SM_CONNECT:

// Connect to a remote FTP server.

ftpSocket = TCPConnect(&RemoteNode, 21);

If ( ftpSocket == INVALID_SOCKET )

{

// Socket is not available

// Return error.

}

else

smState = SM_CONNECT_WAIT; return;

case SM_CONNECT_WAIT:

// Wait for connection...

if ( TCPIsConnected(ftpSocket) ) smState = SM_CONNECTED;

return;

case SM_CONNECTED:

// Send data

if ( TCPIsPutReady(ftpSocket) )

{

// Send data

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

TCPProcess

Prototype

Returns

char TCPProcess(NODE_INFO *remote, unsigned int len);

(!=0)

- If this function (task) has completely processed current packet.

(==0)

- If this function (task) has partially processed current packet.

Description

Requires

Example

This function acts as "TCPTask". It fetches an already received TCP packet and executes the TCP State machine for matching sockets. This function must be called only when a

TCP packet is received.

IPGetHeader == TRUE

IPProtocol = IP_PRO_TCP

...

switch(smState)

{

case SM_STACK_IDLE:

if ( MACGetHeader(&RemoveMAC, &MACFrameType) )

{

if ( MACFrameType == MAC_IP ) smState = SM_STACK_IP;

...

return;

case SM_STACK_IP:

if ( IPGetHeader(&RemoteNode, &IPFrameType, &IPDataCount) )

{

if ( IPFrameType == IP_PROT_TCP ) smState = SM_STACK_TCP;

...

return;

case SM_STACK_TCP:

if ( TCPProcess(&RemoteNode, IPDataCount) ) smState = SM_STACK_IDLE;

return;

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

TCPTick

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void TCPTick();

This function acts as another "TCPTask" in addition to TCPProcess. This function checks for time-out conditions for all sockets and attempts to recover from them.

IPGetHeader == TRUE

IPProtocol = IP_PRO_TCP

TCPTick();

UDPInit

Prototype

Description

Requires

Example

void UDPInit();

This function initializes the UDP module and prepares it for multiple UDP connections.

Nothing.

// Initialize UDP

UDPInit();

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPOpen

Prototype

Returns

Description

Requires

Example

UDP_SOCKET UDPOpen(UDP_PORT localPort, NODE_INFO *remoteNode,

TCP_PORT remotePort);

A valid socket identifier if there was at least one free socket. INVALID_UDP_SOCKET if there is no socket available.

This function prepares the next available UDP socket on a given port for possible data transfer. Either the local or remote node may initiate the data transfer. localPort

-

Local UDP port number on which data transfer will occur. remoteNode

- Remote host that contains remotePort. remotePort

- UDP Port number on remote host to transfer the data to and from.

Nothing.

...

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Broadcast DHCP Broadcast message.

break;

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPIsPutReady

Prototype

char UDPIsPutReady(UDP_SOCKET socket);

Returns

(!=0)

- If a given socket is ready to transmit.

(==0)

- If there is no transmit buffer ready.

Description

Requires

Example

This macro determines if a given socket is ready to transmit. A socket is ready to transmit when at least one of the MAC transmit buffers is empty. It also sets the given socket as an active UDP socket. socket

- Identifier of the socket that needs to be checked and set active.

Nothing.

...

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Broadcast DHCP Broadcast message.

smState = SM_BROADCAST;

break;

case SM_BROADCAST:

if ( UDPIsPutReady(DHCPSocket) )

{

// Socket is ready to transmit. Transmit the data...

...

}

break;

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPPut

Prototype

Returns

Description

Requires

Example

char UDPPut(unsigned char byte);

(!=0)

- If a given data byte was successfully loaded into the transmit buffer and there is room for more data.

(==0)

- If a given data byte was successfully loaded into the transmit buffer and there is no room for more data.

This function loads a data byte into the transmit buffer for an active socket. byte

- Data byte to be loaded.

UDPIsPutReady == TRUE

...

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Broadcast DHCP Broadcast message.

smState = SM_BROADCAST;

break;

case SM_BROADCAST:

if ( UDPIsPutReady(DHCPSocket) )

{

// Socket is ready to transmit. Transmit the data...

// Note that there is DHCPSocket parameter in UDPPut.

// This UDPPut call will use active socket

// as set by UDPIsPutReady() - that is DHCPSocket.

UDPPut(0x55);

...

}

break;

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

UDPFlush

Prototype

Returns

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void UDPFlush();

Nothing.

This function marks the active socket transmit buffer as ready to be transmitted.

UDPPut() is already called, and the desired UDP socket is set as the active socket by calling UDPIsPutReady().

...

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Broadcast DHCP Broadcast message.

smState = SM_BROADCAST;

break;

case SM_BROADCAST:

if ( UDPIsPutReady(DHCPSocket) )

{

// Socket is ready to transmit. Transmit the data...

// Note that there is DHCPSocket parameter in UDPPut.

// This UDPPut call will use active socket

// as set by UDPIsPutReady() - that is DHCPSocket.

UDPPut(0x55);

...

// Now transmit it.

UDPFlush();

}

break;

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPIsGetReady

Prototype

char UDPIsGetReady(UDP_SOCKET socket);

Returns

Description

Requires

Example

(!=0)

- If a given socket contains receive data.

(==0)

- If a given socket does not contain any data.

This function determines if the given socket contains receive data. It also sets a given socket as an active socket. socket - Identifier for the socket that needs to transmitted and set active.

UDPOpen() is already called. The value of socket must be that returned by UDPOpen() call.

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Wait for response from DHCP server

smState = SM_WAIT_FOR_DATA;

break;

case SM_WAIT_FOR_DATA:

if ( UDPIsGetReady(DHCPSocket) )

{

// Socket does contain some data. Fetch it and process it.

...

}

break;

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

UDPGet

Prototype

Returns

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

char UDPGet(unsigned char *byte);

(!=0)

If a byte was read.

(==0)

If no byte was read.

This function fetches one data byte from an active socket receive buffer. byte

- Data byte that was read.

UDPIsGetReady == TRUE

...

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Wait for response from DHCP server

smState = SM_WAIT_FOR_DATA;

break;

case SM_WAIT_FOR_DATA:

if ( UDPIsGetReady(DHCPSocket) )

{

// Socket does contain some data. Fetch it all.

// buffer is a pointer to BYTE.

while( UDPGet(buffer) ) buffer++;

// Process it.

...

// Discard the socket buffer.

...

}

break;

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPDiscard

Prototype

Returns

Description

Requires

Example

char UDPDiscard();

Nothing.

This function releases the receive buffer associated with an active socket.

Nothing.

...

switch(smState)

{

case SM_OPEN:

// Talk to a remote DHCP server.

DHCPSocket = UDPOpen(68, &DHCPServerNode, 67);

If ( DHCPSocket == INVALID_UDP_SOCKET )

{

// Socket is not available

// Return error.

}

else

// Wait for response from DHCP server

smState = SM_WAIT_FOR_DATA;

break;

case SM_WAIT_FOR_DATA:

if ( UDPIsGetReady(DHCPSocket) )

{

// Socket does contain some data. Fetch it all.

// buffer is a pointer to BYTE.

while( UDPGet(buffer) ) buffer++;

// Process it..

...

// Discard the socket buffer.

UDPDiscard();

}

break;

...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPProcess

Prototype

Returns

Description

Requires

Example

char UDPProcess(NODE_INFO *remote, unsigned int len);

(!=0)

- If this function (task) has completely processed the current packet.

(==0)

- If this function (task) has partially processed the current packet.

This function acts as “UDPTask”. It fetches an already received UDP packet and assigns it to a matching UDP socket. This function must be called only when a UDP packet is received. remote

- Remote node from which the current UDP packet was received. len

- Total length of UDP packet length, including UDP header.

IPGetHeader == TRUE

IPProtocol = IP_PRO_UDP

...

switch(smState)

{

case SM_STACK_IDLE:

if ( MACGetHeader(&RemoveMAC, &MACFrameType) )

{

if ( MACFrameType == MAC_IP ) smState = SM_STACK_IP;

...

return;

case SM_STACK_IP:

if ( IPGetHeader(&RemoteNode, &IPFrameType, &IPDataCount) )

{

if ( IPFrameType == IP_PROT_UDP ) smState = SM_STACK_UDP;

...

return;

case SM_STACK_UDP:

if ( UDPProcess(&RemoteNode, IPDataCount) ) smState = SM_STACK_IDLE;

return;

...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UDPWrite

Prototype

Returns

Description

Requires

Example

unsigned char UDPWrite(unsigned int UDPSocket, char * UDPBuffer,

char NoBytes);

Number of written bytes.

Sends data over UDP protocol.

UDPSocket

- Writes data to this socket.

UDPBuffer

-

Data to be sent.

NoBytes

.

Requires UDPInit and UDPOpenSocket.

socket = UDPOpenSocket(10001, 192,168,20,1, 10001);

//assign socket for UDP protocol

numofbytes = UDPWrite(socket, mydata);

UDPRead

Prototype

Returns

Description

Requires

Example

unsigned char UDPRead(unsigned int UDPSocket, char * UDPBuffer );

Number of read bytes.

Reads data over UDP protocol.

UDPSocket

- Reads data from this socket.

UDPBuffer

-

Data to be read.

Requires UDPInit and UDPOpenSocket.

socket = UDPOpenSocket(10001, 192,168,20,1, 10001);

//assign socket for UDP protocol

numofbytes = UDPRead(socket, mydata);

UDPOpenSocket

Prototype

Returns

Description

Requires

Example

unsigned int UDPOpenSocket(unsigned int LocUDPPort, char

RemoteIPByte1, char RemoteIPByte2, char RemoteIPByte3, char

RemoteIPByte4, unsigned int RemUDPPort);

Number of initialized UDP socket.

Opens socket for UDP communication with remote node.

LocUDPPort

- NIC Udp port,

RemoteIPByte1 ... RemoteIPByte4

- Remote host IP address,

RemUDPPort

-

Remote host UDP port.

Requires UDPInit.

socket = UDPOpenSocket(10001, 192,168,20,1, 10001);

//assign socket for UDP protocol

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

StackInit

Prototype

Returns

Description

Requires

Example

void StackInit(unsigned int * RstPort, unsigned int RstPin,

unsigned int* CSPort, unsigned int CSPin);

Nothing.

This routine initializes stack and its components.

Nothing.

StackInit(PORTF, 0, PORTF, 1); //initialize stack

StackTask

Prototype

Returns

Description

Requires

Example

HTTPInit

Prototype

Returns

Description

Requires

Example

void StackTask(void);

Nothing.

This routine executes Stack FSM.

StackInit() must be called before calling this routine.

StackTask();

void HTTPInit(void);

Nothing.

This routine initializes HTTP protocol.

Nothing.

HTTPInit();

HTTPServer

Prototype

Returns

Description

void HTTPServer(void);

Nothing.

This routine starts HTTP server.

Requires

Example

HTTPInit(); must be called before using this routine.

HTTPServer(); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

# include "SerEth.h"

//# include "Tick.h"

# define BaudRate 9600

# define DefaultUDPPort 10001

void *CopyConst2Ram(void * dest, const void * sors, unsigned char n)

{

char * ramptr;

const char * constptr; constptr = sors; ramptr = dest;

while(n--)

*ramptr++ = *constptr++;

return dest;

}

unsigned int main_socket;

static char Buffer0[8];

static char Buffer1[8];

void Interrupt_T1 (void) org 0x001A

{

TimeOutUpdate();

}

static void ReadAnalogInputs(void)

{

unsigned int ADCResult;

ADCResult = Adc_Read(0);

IntToStr(ADCResult, Buffer0);

ADCResult = Adc_Read(1);

IntToStr(ADCResult, Buffer1);

}

#

define DISPLAY

(0)

// continues...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// continued...

# define LED_D2 (0x00)

#

define LED_D3 (0x01)

# define ANALOGINPUT_0 (0x02)

# define ANALOGINPUT_1 (0x03)

# define SETLED_D2 (0x04)

# define SETLED_D3 (0x05)

const char HTTP_DEFAULT_PAGE[] = "CENTER.HTM";

const char EXECUTE_PAGE[] = "EXECUTE.CGI";

const char UNKNOWN_PAGE[] = "UNKNOWN.HTM";

void HTTPExecCmd(unsigned char** argv, unsigned char argc)

{

char command;

char var; command = argv[0][0] - '0';

switch(command)

{

case DISPLAY: var = argv[1][0] - '0';

switch(var)

{

case LED_D2:

LATDbits.LATD2 ^= 1;

break;

case LED_D3:

LATDbits.LATD3 ^= 1;

break;

}

CopyConst2Ram((void*)argv[0],

(const void*)EXECUTE_PAGE, sizeof(EXECUTE_PAGE));

break;

default:

CopyConst2Ram((void*)argv[0],

(const void*)UNKNOWN_PAGE, sizeof(UNKNOWN_PAGE));

break;

}

}

//continues...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// continued...

unsigned int HTTPGetVar(char var, unsigned int ref, char* val)

{

switch(var)

{

case LED_D2:

*val = LATDbits.LATD2 ? '1':'0';

break;

case LED_D3:

*val = LATDbits.LATD3 ? '1':'0';

break;

case ANALOGINPUT_0:

*val = Buffer0[(char)ref];

if ( Buffer0[(char)ref] == '\0' )

return 0xFFFF;

(char)ref++;

return ref;

case ANALOGINPUT_1:

*val = Buffer1[(char)ref];

if ( Buffer1[(char)ref] == '\0' )

return 0xFFFF;

(char)ref++;

return ref;

case SETLED_D2:

*val = LATDbits.LATD2 ? '0':'1';

break;

case SETLED_D3:

*val = LATDbits.LATD3 ? '0':'1';

break;

}

return 0xFFFF;

}

char Bbuffer[20] = " ";

char i = 0;

// continues..

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// continued...

void main(void)

{

static unsigned long t = 0;

ADPCFG = 0xFFFF;

PORTD = 0;

TRISD = 0;

// Set up analog inputs

TRISBbits.TRISB0 = 1;

TRISBbits.TRISB1 = 1;

// Set up the LED's.

LATD = 0x00;

LATDbits.LATD2 = 1;

LATDbits.LATD3 = 1;

TRISD = 0x00;

// Initialize Usart module

Uart1_Init(19200);

U1MODEbits.ALTIO = 1;

Delay_ms(100);

// Enable interrupts

INTCON1bits.NSTDIS = 1;

EthSetIPAddr(192, 168, 20, 60);

EthSetMACAddr(0x00, 0x02, 0x04, 0x06, 0x08, 0x0A);

EthSetIPMask(0xFF, 0xFF, 0xFF, 0x00);

EthSetGateWayAddr(192, 168, 20, 60);

EthInit( &PORTF, 0, &PORTF, 1);

// Open UDP communication sockets needed

main_socket = UDPOpenSocket(DefaultUDPPort, 192, 168, 20, 1,

DefaultUDPPort);

while(1)

{

if ( TickGetDiff(TickGet(), t) >= TICK_SECOND/2 )

{ t = TickGet();

LATDbits.LATD0 ^= 1;

}

StackTask();

/*Process incoming UDP packets and send a reply if needed.

User specific code.*/

if(i = UDPRead(main_socket, Bbuffer)) {

Bbuffer[i] = 0;

UDPWrite(main_socket, Bbuffer, strlen(Bbuffer));

}

HTTPServer();

ReadAnalogInputs();

} page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

HW Connection

mikroC for dsPIC making it simple...

VCC

10 Mhz

11

12

13

14

VCC

GND

OSC1

OSC2

RF0

RF1

RF4

RF5

RF2

RF3

RF6

page

VCC

RF4

RF5

3

4

1

2

5

6

7

1A

1B

1Y

2A

2B

2Y

GND

VCC

4B

4A

4Y

3B

3A

3Y

14

13

12

11

10

9

8 RF2

VCC3

L1

FERRITE

BEAD

RF3

RF6

RF1

RF0

1B

2B

3B

E3

10uF

VCC3

7

8

9

10

11

12

13

3

4

1

2

5

6

14

ENC28J60

VCAP

VCC

GND

WOL

SO

LEDA

LEDB

CLKOUT

INT OSC-VCC

OSC2

OSC1

SI OSCGND

PLL-GND

SCK

CS PLL-VCC

RESET

RX-VCC

GND-RX

TX-GND

TPIN-

TPIN+

TPOUT+

TPOUT-

RBIAS TX-VCC

18

17

16

15

21

20

19

28

27

26

25

24

23

22

R1

2K

LD2

LED

LD3

LED

R2

500

25 MHz

R3

500

R4

51

R5

51

R6

51

R7

51

12

K2

11

A2

RJ45

TD+

CT

TD-

RD+

CT

RD-

10

K1 A1

9

2

7

6

1

3

8

C4

100nF

C3

10nF

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flash Memory Library

This library provides routines for accessing microcontroller's (internal) Flash memory.

On dsPICs, Flash memory is mapped to address space 3:2, meaning every 3 consecutive bytes of Flash have 2 consecutive address locations available. That is why mikroE's library allows data to be written to flash in two ways: 'regular' and 'compact'. In 'regular' mode, which is used for variables that are size of 2 bytes and more, the 3rd (un-addressable) byte remains unused. In 'compact' mode, which can be used for 1 byte-sized variables/arrays, all bytes of flash are being used.

All dsPIC MCUs use the RTSP (Run-Time Self-Programming) module to perform

Read/Erase/Write operations on Flash memory. This, together with the internal structure of the Flash, imposes certain rules when working with Flash memory:

- Erase can be done only in 32-instructions (64 addresses, 96 bytes) memory blocks. This means that the block start address should be a multiply of 64 (i.e.

have 6 lower bits set to zero).

- Data is read and written in 4-instructions (8 address, 12 bytes) blocks.This means that the block start address should be a multiply of 8 (i.e. have 3 lower bits set to zero).

- On dsPICs, 2 address locations are assigned on every 3 bytes of (flash) program memory. Due to this specific and non-one-to-one address mapping, mikroC offers two sets of Flash handling functions: "regular" and "compact".

Using the "regular" set, user can write one byte of data to a single address; this means that each byte of data written has its own address, but on every 2 bytes written one byte of Flash memory remains empty.

Using the "compact" set, every byte of Flash memory, including those nonaddressable, is filled with data; this method can only be used for data organized in bytes.

The "compact" functions have

_Compact as name suffix.

- For the run-time FLASH read/write, dsPIC's RTSP (Run Time Self

Programming) module is being used. It organizes the data into rows and panels.

Each row contains write latches that can hold 4 instructions (12 bytes). The number of panels varies between the dsPIC MCU models. Because of this, the flash write sequence has been split into multiple operations (

_Write_Init(),

_Write_LoadLatch4(), _Write_DoWrite()

), in order to be usable on all dsPICs. page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Routines

Flash_Erase32

Flash_Write_Block

Flash_Write_Compact

Flash_Write_Init

Flash_Write_Loadlatch4

Flash_Write_Loadlatch4_Compact

Flash_Write_DoWrite

Flash_Read4

Flash_Read4_Compact

Flash_Erase32

Prototype

Description

Requires

Example

void Flash_Erase32(unsigned long address);

Erases one block (32 instructions, 64 addresses, 96 bytes) of program FLASH memory.

Nothing.

//--- erase the 32-instruction block, starting from address

//0x006000

Flash_Erase32(0x006000);

Flash_Write_Block

Prototype

Description

Requires

void Flash_Write_Block(unsigned long address, unsigned int * data);

Fills one writeable block of Flash memory (4 instructions, 8 addresses, 12 bytes) in

"common" mode, with data starting from the *data location, on FLASH address address

. This means that addresses and data are being mapped 1-on-1. This also means that 3rd byte of each program instruction remains unused.

The block that is being written to must be erased first, either from the user code

(through the RTSP), or during the programming of the MCU (through the ICSP). Please note that block size that is being erased is different than the one that can be written with this function!

Example

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flash_Write_Compact

Prototype

Description

Requires

void Flash_Write_Compact(unsigned long address, void * data,

unsigned bytes);

Fills a portion of Flash memory starting from address address

, with data pointed to by the *data, the amount of data being written is bytes

. This is being done through the usage of dsPICs RTSP (Run Time Self Programming) module, in "compact" manner.

This way, multiple blocks of RTSP's latch can be written in one pass. One latch block contains 4 instructions (8 addresses, 12 bytes). Up to (but not necesserily) 8 latch blocks can be written in one round, resulting of total of 8*12 = 96 bytes. This method uses all the available bytes of the program FLASH memory, including those that are not mapped to address space (every 3rd byte).

The block that is being written to must be erased first, either from the user code

(Flash_Erase32), or during the programming of the MCU. Please note that block size that is being erased is different than the one that can be written with this function!

FLASH write start address must be a multiply of 32, meaning that first 5 bytes of it are zeroes.

The amount of bytes to be written must be a multiply of 12, since this is the size of the

RTSP's write latch(es).

Example

Flash_Write_Init

Prototype

void Flash_Write_Init(unsigned long address, void * data);

Description

Requires

Example

Initializes the RTSP for write-to-FLASH operation, starting from address address

, with data at location data

.

The block that is being written to must be erased first, either from the user code

(Flash_Erase32), or during the programming of the MCU. Please note that block size that is being erased is different than the one that can be written with this function!

FLASH write start address must be a multiply of 32, meaning that first 5 bytes of it are zeroes.

//--- Initializes the Flash to be written, starting from address

//0x006100, the data is located at *pv1

void *pv1;

...

Flash_Write_Init(0x006100, pv1); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flash_Write_Loadlatch4

Prototype

void Flash_Write_Loadlatch4(void);

Description

Loads the current RTSP write latch with data (4 instructions, 8 addresses, 12 bytes). The data is filled in "classic" manner, i.e. only addressable bytes are used.

Requires

The block that is being written to must be erased first, either from the user code

(Flash_Erase32), or during the programming of the MCU. Please note that block size that is being erased is different than the one that can be written with this function!

Example

This function is used as a part of the Flash write sequence, therefore Flash_Write_Init() function must be called before this one.

This function can be called multiple times before comminting actual write-to-Flash operation (Flash_Write_DoWrite()). This depends on the organisation of the RTSP module for certain dsPIC. Please consult the Datasheet for particular dsPIC on this subject.

//--- writes data from an array, in "classic" manner

unsigned int iArr[16] = {'m', 'i', 'k', 'r', 'o', 'E', 'l',

'e', 'k'};

void * pv1;

...

pv1 = iArr;

Flash_Write_Init(0x006100, pv1);

Flash_Write_Loadlatch4();

Flash_Write_Loadlatch4();

Flash_Write_DoWrite(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flash_Write_Loadlatch4_Compact

Prototype

void Flash_Write_Loadlatch4_Compact(void);

Description

Loads the current RTSP write latch with data (4 instructions, 8 addresses, 12 bytes). The data is filled in "compact" manner, i.e. all bytes in Flash are used. This function, however, can be used only for the single-byte data.

Requires

The block that is being written to must be erased first, either from the user code

(Flash_Erase32), or during the programming of the MCU. Please note that block size that is being erased is different than the one that can be written with this function!

Example

This function is used as a part of the Flash write sequence, therefore Flash_Write_Init() function must be called before this one.

This function can be called multiple times before comminting actual write-to-Flash operation (Flash_Write_DoWrite()). This depends on the organisation of the RTSP module for certain dsPIC. Please consult the Datasheet for particular dsPIC on this subject.

This function can be used only on the single-byte type of data.

//--- writes data from an array of char, in "compact" manner

char cArr[] = "supercalifragillisticexpialidotious";//35+1

void * pv1;

...

pv1 = cArr;

Flash_Write_Init(0x006000, pv1); //init

Flash_Write_Loadlatch4_Compact(); //12 bytes

Flash_Write_Loadlatch4_Compact(); //12 bytes

Flash_Write_Loadlatch4_Compact(); //12 bytes

Flash_Write_DoWrite(); //commit write

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flash_Write_DoWrite

Prototype

void Flash_Write_DoWrite(void);

Description

Requires

Commits the FLASH write operation.

The block that is being written to must be erased first, either from the user code

(Flash_Erase32), or during the programming of the MCU. Please note that block size that is being erased is different than the one that can be written with this function!

This function is used as a part of the Flash write sequence, therefore Flash_Write_Init() and certain number of Flash_Write_Loadlatch4() or Flash_Write_Loadlatch4_Compact() function calls must be made before this one.

Example

This function is to be called once, at the and of the FLASH write sequence.

//--- writes data from an array, in "classic" manner

unsigned int iArr[16] = {'m', 'i', 'k', 'r', 'o', 'E', 'l',

'e', 'k'};

void * pv1;

...

pv1 = iArr;

Flash_Write_Init(0x006100, pv1);

Flash_Write_Loadlatch4();

Flash_Write_Loadlatch4();

Flash_Write_DoWrite();

Flash_Read4

Prototype

Returns

Description

Requires

Example

unsigned int *Flash_Read4(unsigned long address, unsigned int

*write_to);

Pointer to data that has just been read.

Reads one latch row (4 instructions, 8 addresses) from the memory location specified by address, and stores it at RAM location starting at

*write_to

.

Starting read address must be 8-byte alligned.

//--- reads 8 bytes (4 words) from location 0x006000 and stores

//it to *pv1;

unsigned int *pv1;

...

Flash_Read4(0x006000, pv1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flash_Read4_Compact

Prototype

Returns

Description

Requires

unsigned int *Flash_Read4_Compact(unsigned long address, void

*write_to);

Pointer to data that has just been read.

Reads one latch row (4 instructions, 8 addresses, 12 bytes) from the memory location specified by address, and stores it at RAM location starting at

*write_to

.

Starting read address must be 8-byte alligned.

Example

FLASH contents are being read byte-by-byte.

//--- reads 12 bytes (4 words) from location 0x006000 and stores

//it to *pv1;

unsigned int *pv1;

...

Flash_Read4_Compact(0x006000, pv1);

Library Example

The example demonstrates simple write to the flash memory in "classic" and

"compact" manner, then reads the data and displays it on PORTB.

unsigned int iArr[16] = {'m', 'i', 'k', 'r', 'o', 'E', 'l', 'e',

'k'};

char cArr[] = "supercalifragillisticexpialidotious";

char cArr2[40];

void * pv1;

unsigned bb;

void main() {

unsigned i; pv1 = cArr;

/*

*

This is what Flash_Write_Compact() does 'benath the hood'

Flash_Write_Init(0x006000, pv1);

Flash_Write_Loadlatch4_Compact();

Flash_Write_Loadlatch4_Compact();

Flash_Write_Loadlatch4_Compact();

...

Flash_Write_DoWrite();

*/

// continues...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// continued...

//--- erase the block first

Flash_Erase32(0x006000);

//--- write compact format to flash

Flash_Write_Compact(0x006000, pv1, 36);

//--- read compact format

pv1 = cArr2;

Flash_Read4_Compact(0x006000, pv1); pv1 += 12;

Flash_Read4_Compact(0x006008, pv1); pv1 += 12;

Flash_Read4_Compact(0x006010, pv1); pv1 += 12;

*pv1 = 0; //termination

//--- show what has been written

i = 0;

Uart1_Init(9600);

Uart1_Write_Char('s'); Uart1_Write_Char('t');

Uart1_Write_Char('a'); Uart1_Write_Char('r');

Uart1_Write_Char('t'); Uart1_Write_Char(10); while(cArr2[i]) { bb = cArr2[i++];

Uart1_Write_Char(bb);

}

//--- now for some non-compact flash-write

pv1 = iArr;

Flash_Write_Init(0x006100, pv1);

Flash_Write_Loadlatch4();

Flash_Write_Loadlatch4();

Flash_Write_DoWrite();

}//~! mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

I2C Library

I²C full master MSSP module is available with a number of dsPIC MCU models.

mikroC for dsPIC provides library which supports the master I²C mode.

Note: This library works solely with the I2C module and its registers. The I2C module takes full control over the SDA and SCL lines at init, so user doesn't need to take care of PORT/TRIS settings for those pins.

Library Routines

I2C_Init

I2C_Start

I2C_Restart

I2C_Wait_For_Idle

I2C_Read

I2C_Write

I2C_Stop

I2C_Init

Prototype

Description

Requires

Example

void I2C_Init(unsigned long clock);

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 I²C Library.

Library requires I2C module.

I2C_Init(100000);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

I2C_Start

Prototype

Returns

Description

Requires

Example

unsigned short I2C_Start(void);

If there is no error, function returns 0.

Determines if I²C bus is free and issues START signal.

I²C must be configured before using this function. See

I2C_Init

.

I2C_Start(); mikroC for dsPIC making it simple...

I2C_Restart

Prototype

Description

Requires

Example

void I2C_Restart(void);

Issues repeated START signal.

I²C must be configured before using this function. See

I2C_Init

.

I2C_Restart();

I2C_Wait_For_Idle

void I2C_Wait_For_Idle(void);

Prototype

Returns

Description

Requires

Example

The function waits until I²C bus gets free. This is a blocking function.

Waits for I²C bus to become free.

I²C must be configured before using this function. See

I2C_Init

.

I2C_Wait_For_Idle(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

I2C_Read

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned char I2C_Read(unsigned int ack);

Prototype

Returns

Description

Returns one byte from the slave.

Reads one byte from the slave, and sends not acknowledge signal if parameter ack is 0, otherwise it sends acknowledge.

Requires

Example

START signal needs to be issued in order to use this function. See

I2C_Start

.

temp = I2C_Rd(0); // Read data and send not acknowledge signal

I2C_Write

Prototype

Returns

Description

Requires

Example

unsigned int I2C_Write(unsigned char data);

Returns 0 if there were no errors.

Sends data byte (parameter data) via I²C bus.

START signal needs to be issued in order to use this function. See

I2C_Start

.

I2C_Write(0xA3);

I2C_Stop

Prototype

Description

Requires

void I2C_Stop(void);

Issues STOP signal.

I²C must be configured before using this function. See

I2C_Init

.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

This code demonstrates use of I²C library. dsPIC 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 I2C from EEPROM and send its value to

PORTB, to check if the cycle was successful (see the figure below how to interface 24c02 to dsPIC).

void main(){

PORTB = 0;

TRISB = 0;

I2c_Init(0x000186A0);

I2c_Start(); // issue I2C start signal

I2c_Write(0xA2); // send byte via I2C (command to 24cO2)

I2c_Write(2); // send byte (address of EEPROM location)

I2c_Write(0xF4); // send data (data to be written)

I2c_Stop();

Delay_100ms();

}

I2c_Start(); // issue I2C start signal

I2c_Write(0xA2); // send byte via I2C (device address + W)

I2c_Write(2); // send byte (data address)

I2c_Restart(); // issue I2C signal repeated start

I2c_Write(0xA3); // send byte (device address + R)

PORTB = I2c_Read(0); // Read the data (NO acknowledge)

I2c_Stop(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

HW Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

VCC

11

12

13

14

VCC

GND

OSC1

OSC2

RF2

RF3

34

33

VCC VCC

1

2

3

4

A0

A1

NC

GND

Vcc

WP

SCL

SDA

24C02

8

7

6

5

10 Mhz

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Keypad Library

mikroC for dsPIC 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_Key_Press

Keypad_Key_Click

Keypad_Init

Prototype

Description

Example

void Keypad_Init(unsigned *key_port);

Initializes key_port to work with keypad. All The function needs to be called before using other routines from Keypad library.

On dsPIC platform, keypad library uses lower 8 bits <0:7> of the key_port

//--- PORTB<0:7> is now "occupied" by the keypad...

Keypad_Init(&PORTB);

Keypad_Key_Press

unsigned Keypad_Key_Press(void);

Prototype

Returns

Description

1..16, depending on the key pressed, or 0 if no key is pressed.

Checks if any key is pressed. Function returns 1 to 16, depending on the key pressed, or

0 if no key is pressed.

Requires

Example

Port needs to be appropriately initialized; see

Keypad_Init

.

kp = Keypad_Key_Press(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Keypad_Key_Click

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned Keypad_Key_Click(void);

Prototype

Returns

Description

Requires

Example

1..16, depending on the key.

Call to

Keypad_Key_Click is a blocking call: function waits until any key is pressed and released. When released, function returns 1 to 16, depending on the key.

Port needs to be appropriately initialized; see

Keypad_Init

.

kp = Keypad_Key_Click();

Library Example

The following code can be used for testing the keypad. It is written for keypad_4x3 or _4x4. The code returned by the keypad functions (1..16) is transformed into ASCII codes [0..9,A..F], and is then sent via UART1.

char txt[5];

void main() {

ADPCFG = 0xFFFF; // turn off analogue inputs cnt = 0;

Keypad_Init(&PORTB); // portb.0 to portb.7

TRISF.f2 = 1;

TRISF.f3 = 0;

Uart1_Init(9600);

Delay_ms(200);

Uart1_Write_Char('R');

do { kp = 0;

//--- Wait for key to be pressed

do { kp = Keypad_Key_Click();

//kp = Keypad_Key_Press();

} while (!kp);

// continues...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

// continued...

//--- Prepare value for output

switch (kp) {

//case 10: kp = 42; break; // '*'

//case 11: kp = 48; break; // '0'

// uncomment this block for keypad_4x3

//case 12: kp = 35; break; // '#'

//default: kp += 48;

case

1: kp = 49; break; // 1

case

2: kp = 50; break; // 2

case

3: kp = 51;

break; // 3

case

4: kp = 65; break; // A

case

5: kp = 52; break; // 4

case

6: kp = 53; break; // 5

case

7: kp = 54; break; // 6

case

8: kp = 66;

break; // B

// uncomment this block for keypad_4x4

case

9: kp = 55; break; // 7

case 10: kp = 56; break; // 8

case 11: kp = 57; break; // 9

case 12: kp = 67; break; // C

case 13: kp = 42; break; // *

case 14: kp = 48; break; // 0

case 15: kp = 35; break; // #

case 16: kp = 68; break; // D

}

//--- Send on UART1

Uart1_Write_Char(kp);

if (cnt == 255) { cnt = 0;

}

} while (1);

} //~! mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

HW Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

1 2 3 A

4 5 6 B

7 8 9 C

*

0 # D

KEYPAD

4X4

10 Mhz

VCC

11

12

13

14

4

5

6

7

2

3

8

9

RB0

RB1

RB2

RB3

RB4

RB5

RB6

RB7

VCC

GND

OSC1

OSC2

VCC

P2

10K

RD0

RD1

34

33

RF0

RF1

RF4

RF5

30

29

28

27

VCC

E13

10uF

Key:5

Times:10

LCD 2X16

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

LCD Custom Library (4-bit interface)

mikroC for dsPIC provides a library for communicating with commonly used

LCD (4-bit interface) with custom defined pinout. Figures showing HW connection of dsPIC and LCD are given at the end of the chapter.

Note: Be sure to designate port with LCD as output, before using any of the following library functions.

Library Routines

Lcd_Custom_Config

Lcd_Custom_Out

Lcd_Custom_Out_Cp

Lcd_Custom_Chr

Lcd_Custom_Chr_Cp

Lcd_Custom_Cmd

Lcd_Custom_Config

Prototype

void Lcd_Custom_Config(char * data_port, char D7, char D6, char

D5,

char D4, char * ctrl_port, char RS, char WR, char EN);

Description

Initializes LCD data port and control port with pin settings you specify.

Example

Lcd_Custom_Config(&PORTD,3,2,1,0,&PORTB,2,3,4); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Lcd_Custom_Out

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Lcd_Custom_Out(char row, char col, char *text);

Prototype

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

Example

Port with LCD must be initialized. See

Lcd_Config

.

Lcd_Custom_Out(1, 3, "Hello!");//Print "Hello!" at line 1, char 3

Lcd_Custom_Out_Cp

Prototype

void Lcd_Custom_Out_Cp(char *text);

Description

Prints text on LCD at current cursor position. Both string variables and literals can be passed as text

.

Requires

Example

Port with LCD must be initialized. See

Lcd_Config

.

Lcd_Custom_Out_Cp("Here!"); // Print "Here!" at current cursor

position

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Lcd_Custom_Chr

void Lcd_Custom_Chr(char row, char col, char character);

Prototype

Description

Prints character on LCD at specified row and column (parameters row and col

).

Both variables and literals can be passed as character

.

Requires

Example

Port with LCD must be initialized. See

Lcd_Config

.

Lcd_Custom_Chr(2, 3, 'i'); // Print 'i' at line 2, char 3

Lcd_Custom_Chr_Cp

void Lcd_Custom_Chr_Cp(char character);

Prototype

Description

Prints character on LCD at current cursor position. Both variables and literals can be passed as character

.

Requires

Example

Port with LCD must be initialized. See

Lcd_Config

.

Lcd_Custom_Out_Cp('e'); // Print 'e' at current cursor position

Lcd_Custom_Cmd

void Lcd_Custom_Cmd(char command);

Prototype

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 following page.

Requires

Example

Port with LCD must be initialized. See

Lcd_Config

.

Lcd_Custom_Cmd(Lcd_Clear); // Clear LCD display page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

LCD Commands

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

LCD Command

LCD_FIRST_ROW

LCD_SECOND_ROW

LCD_THIRD_ROW

LCD_FOURTH_ROW

LCD_CLEAR

LCD_RETURN_HOME

Purpose

Move cursor to 1st row

Move cursor to 2nd row

Move cursor to 3rd row

Move cursor to 4th row

Clear display

Return cursor to home position, returns a shifted display to original position. Display data RAM is unaffected.

LCD_CURSOR_OFF

LCD_UNDERLINE_ON

LCD_BLINK_CURSOR_ON

Turn off cursor

Underline 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

LCD_TURN_OFF

LCD_SHIFT_LEFT

LCD_SHIFT_RIGHT

Turn LCD display on

Turn LCD display off

Shift display left without changing display data RAM

Shift display right without changing display data RAM page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

char cArr1[17] = "LCD4 Custom Test";

char cArr2[17] = "mikroElektronika";

char *t;

int main() {

CORCON = CORCON;

PSVPAG = PSVPAG;

ADPCFG = 0xFFFF;

TRISF = 0;

TRISD = 0;

Lcd_Custom_Config(&LATF, 5,4,1,0, &LATD, 1,0,2);

Lcd_Custom_Out(1,1, cArr1);

Lcd_Custom_Out(2,1, cArr2);

}//~! mikroC for dsPIC making it simple...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

VCC

P2

10K

10 Mhz

VCC

11

12

13

14

VCC

GND

OSC1

OSC2

RD0

RD1

34

33

RF0

RF1

RF4

RF5

30

29

28

27

VCC

E13

10uF

LCD4 Custom Test mikroElektronika

LCD 2X16

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

LCD8 Custom Library (8-bit interface)

mikroC for dsPIC provides a library for communicating with commonly used 8-bit interface LCD (with Hitachi HD44780 controller). Figures showing Custom HW connection of PIC and LCD are given at the end of the chapter.

Note: Be sure to designate Control and Data ports with LCD as output, before using any of the following library functions.

Library Routines

Lcd8_Custom_Config

Lcd8_Custom_Out

Lcd8_Custom_Out_Cp

Lcd8_Custom_Chr

Lcd8_Custom_Chr_Cp

Lcd8_Custom_Cmd

Lcd8_Custom_Config

Prototype

Description

void Lcd8_Custom_Config(unsigned int * data_port, unsigned int db7,

unsigned int db6, unsigned int db5, unsigned int db4,

unsigned int db3, unsigned int db2, unsigned int db1, unsigned

int db0, unsigned int * ctrl_port, unsigned int rs, unsigned int ctrl_rw, unsigned int enable);

Initializes LCD at Control port ( ctrlport

) and Data port ( dataport

) with pin settings you specify: Parameters

RS

,

EN

, and

WR need to be in range 0–7; Parameters

D7

..

D0 need to be a combination of values 0–7 (e.g. 3,6,5,0,7,2,1,4).

Example

Lcd8_Custom_Config(&PORTB, 7, 6, 5, 4, 3, 2, 1, 0, &PORTD, 0, 1,

2); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Lcd8_Custom_Out

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Lcd8_Custom_Out(unsigned int row, unsigned int column, char

*text);

Prints text on LCD at specified row and column (parameter row and col

). Both string variables and literals can be passed as text

.

Requires

Example

Ports with LCD must be initialized. See

Lcd8_Custom_Config

.

Lcd8_Custom_Out(1, 3, "Hello!");

// Print "Hello!" at line 1, char 3

Lcd8_Custom_Out_CP

void Lcd8_Custom_Out_CP(char *text);

Prototype

Description

Prints text on LCD at current cursor position. Both string variables and literals can be passed as text

.

Requires

Example

Ports with LCD must be initialized. See

Lcd8_Custom_Config

.

Lcd8_Custom_Out_CP("Here!");

// Print "Here!" at current cursor position

Lcd8_Custom_Chr

Prototype

Description

void Lcd8_Custom_Chr(unsigned int row, unsigned int column,

unsigned int out_char);

Prints character on LCD at specified row and column (parameters row and col

).

Both variables and literals can be passed as character

.

Requires

Example

Ports with LCD must be initialized. See

Lcd8_Custom_Config

.

Lcd8_Custom_Chr(2, 3, 'i'); // Print 'i' at line 2, char 3 page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Lcd8_Custom_Chr_CP

void Lcd8_Custom_Chr_CP(unsigned int out_char);

Prototype

Description

Prints character on LCD at current cursor position. Both variables and literals can be passed as character

.

Requires

Example

Ports with LCD must be initialized. See

Lcd8_Custom_Config

.

Lcd8_Custom_Chr_CP('e'); // Print 'e' at current cursor position

Lcd8_Custom_Cmd

void Lcd8_Custom_Cmd(unsigned int out_char);

Prototype

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 LCD4 Custom page.

Requires

Example

Ports with LCD must be initialized. See

Lcd8_Custom_Config

.

Lcd8_Custom_Cmd(Lcd_Clear); // Clear LCD display

Library Example

void main(){

ADPCFG = 0xFFFF;

Lcd8_Custom_Config(&PORTB, 7, 6, 5, 4, 3, 2, 1, 0, &PORTD, 0, 1, 2);

Lcd8_Custom_Cmd(LCD_CLEAR);

Lcd8_Custom_Cmd(LCD_CURSOR_OFF);

Lcd8_Custom_Out(1, 1, "LCD8 Custom Test");

Lcd8_Custom_Out(2, 1, "mikroElektronika");

}//~! page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

10 Mhz

VCC

RB0

RB1

RB2

RB3

RB4

RB5

RB6

RB7

11

12

13

14

VCC

GND

OSC1

OSC2

RD0

RD1

34

33

RD2

22

VCC

P2

10K

VCC

E13

10uF

LCD8 Custom Test mikroElektronika

LCD 2X16

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

GLCD Library

mikroC provides a library for drawing and writing on commonly used Samsung

(KS108/KS107) Graphic LCD 128x64.

Note: Be sure to designate port with GLCD as output, before using any of the following library functions.

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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Glcd_Init

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Glcd_Init(unsigned int *cs1_port, unsigned int cs1_pin,

unsigned int *cs2_port, unsigned int cs2_pin, unsigned int

*rs_port, unsigned int rs_pin, unsigned int *rw_port, unsigned

int rw_pin, unsigned int *rst_port, unsigned int rst_pin,

unsigned int *en_port, unsigned int en_pin, unsigned int

*data_port);

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 function needs to be called befored using other routines of GLCD library.

Example

Glcd_Init(&PORTD,8, &PORTD,9, &PORTD,10, &PORTD,3, &PORTG,12,

&PORTD,11, &PORTB);

Glcd_Set_Side

Prototype

void Glcd_Set_Side(unsigned short x);

Description

Requires

Example

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.

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Select_Side(0);

Glcd_Set_Page

void Glcd_Set_Page(unsigned short page);

Prototype

Description

Requires

Example

Selects page of GLCD, technically a line on display; parameter page can be 0..7.

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Set_Page(5); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Glcd_Set_X

void Glcd_Set_X(unsigned short x_pos);

Prototype

Description

Requires

Example

Positions to x dots from the left border of GLCD within the given page.

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Set_X(25);

Glcd_Read_Data

unsigned short Glcd_Read_Data(void);

Prototype

Returns

Description

One word from the GLCD memory.

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

Example

Reads data from from the current location of GLCD memory.

tmp = Glcd_Read_Data();

Glcd_Write_Data

Prototype

void Glcd_Write_Data(unsigned short data);

Description

Requires

Example

Writes data to the current location in GLCD memory and moves to the next location.

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Write_Data(data); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Glcd_Fill

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Glcd_Fill(unsigned short pattern);

Prototype

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

Example

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Fill(0); // Clear screen

Glcd_Dot

Prototype

Description

Requires

Example

void Glcd_Dot(unsigned short x, unsigned short y, unsigned short color);

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.

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Dot(0, 0, 2); // Invert the dot in the upper left corner

Glcd_Line

Prototype

Description

void Glcd_Line(int x1, int y1, int x2, int y2, unsigned short color);

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

Example

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Line(0, 63, 50, 0, 2); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Glcd_V_Line

Prototype

Description

Requires

Example

void Glcd_V_Line(unsigned short y1, unsigned short y2, unsigned

short x, unsigned short color);

Draws a vertical line on the GLCD from ( x_pos

, y_start

) to ( x_pos

, y_end

).

Parameter color determines the dot state: 0 draws an empty line (clear dots), 1 draws a solid line (put dots), and 2 draws a “smart” line (invert each dot).

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_V_Line(0, 63, 0, 1);

Glcd_H_Line

Prototype

Description

Requires

Example

void Glcd_H_Line(unsigned short x1, unsigned short x2, unsigned

short y, unsigned short color);

Draws a horizontal line on the GLCD from ( x_start

, y_pos

) to ( x_end

, y_pos

).

Parameter color determines the dot state: 0 draws an empty line (clear dots), 1 draws a solid line (put dots), and 2 draws a “smart” line (invert each dot).

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_H_Line(0, 127, 0, 1);

Glcd_Rectangle

Prototype

Description

Requires

void Glcd_Rectangle(unsigned short x1, unsigned short y1,

unsigned short x2, unsigned short y2, unsigned short color);

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” border (invert each dot).

GLCD needs to be initialized. See

Glcd_Init

.

Example

Glcd_Rectangle(10, 0, 30, 35, 1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Glcd_Box

Prototype

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Glcd_Box(unsigned short x1, unsigned short y1, unsigned

short x2, unsigned short y2, unsigned short color);

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

Example

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Box(10, 0, 30, 35, 1);

Glcd_Circle

Prototype

void Glcd_Circle(int x, int y, int radius, unsigned short color);

Description

Requires

Example

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).

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Circle(63, 31, 25, 2);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Glcd_Set_Font

Prototype

Description

Requires

Example

void Glcd_Set_Font(const char *activeFont, unsigned short aFontWidth, unsigned short aFontHeight, unsigned int aFontOffs);

Sets font for routines

Glcd_Write_Char and

Glcd_Write_Text

. Parameter activeFont needs to be formatted as an array of char.

Parameters aFontWidth and aFontHeight 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 aFontOffs is number that represents difference between mikroC character set and regular ASCII set (eg. if 'A' is 65 in ASCII character, and 'A' is 45 in mikroC character set, aFontOffs is 20). Demo fonts supplied with the library have an offset of

32, which means that they start with space.

You can create your own fonts by following the guidelines given in file

“GLCD_Fonts.c”. This file contains the default fonts for GLCD, and is located in your installation folder, “Extra Examples” › “GLCD”.

GLCD needs to be initialized. See

Glcd_Init

.

// Use the custom 5x8 font "myfont" which starts with space (32):

Glcd_Set_Font(myfont_5x8, 5, 8, 32);

Glcd_Write_Char

Prototype

Description

void Glcd_Write_Char(unsigned short character, unsigned short x,

unsigned short page, unsigned short color);

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 prints a “white” letter (clear dots),

1 prints a solid letter (put dots), and 2 prints a “smart” letter (invert each dot).

Requires

Example

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Write_Char('C', 0, 0, 1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Glcd_Write_Text

Prototype

Description

Requires

Example

void Glcd_Write_Text(char *text, unsigned short x, unsigned short page,

unsigned short color);

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).

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.

Glcd_Write_Text("Hello world!", 0, 0, 1);

Glcd_Image

Prototype

void Glcd_Image(const unsigned short *image);

Description

Displays bitmap image on the GLCD. Parameter image should be formatted as an array of integers. Use the mikroC’s integrated Bitmap-to-LCD editor (menu option Tools >

BMP2LCD) to convert image to a constant array suitable for display on GLCD.

Requires

Example

GLCD needs to be initialized. See

Glcd_Init

.

Glcd_Image(my_image);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The following drawing demo tests advanced routines of GLCD library.

#

include "bmp1.h"

#

include "Glcd_Fonts.h"

char cArr[20];

char *someText;

void Delay2S(){ delay_ms(2000);

}//~

void main() { unsigned short ii; unsigned int jj; sometext = cArr;

CORCON = CORCON;

PSVPAG = PSVPAG;

//--- turn off A/D inputs

ADPCFG = 0xFFFF;

Glcd_Init(&PORTF, 0,1, &PORTD, 0,1,3,2, &PORTB);

Delay_100ms(); lMainLoop:

Glcd_Fill(0x00);

Glcd_Image( maska_bmp );

Delay2S(); Delay2S();

Glcd_Fill(0x00);

Glcd_Circle(63,32, 20, 1);

Delay2S();

Glcd_Line(120,1, 5,60, 1);

Glcd_Line(12,42, 5,60, 1);

Delay2S();

Glcd_Rectangle(12,20, 93,57, 1);

Delay2S();

Glcd_Line(120,12, 12,60, 1);

Delay2S();

//continues...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

//continues...

for (ii = 1; ii <= 10; ii++)

Glcd_Circle(63,32, 3*ii, 1);

Delay2S();

Glcd_Box(12,20, 70,57, 2);

Delay2S();

Glcd_Set_Font(defaultFont, 5,7, 48); someText = "BIG:ONE";

Glcd_Write_Text(someText, 5,3, 2);

Delay2S(); someText = "SMALL:NOT:SMALLER";

Glcd_Write_Text(someText, 20,5, 1);

Delay2S();

Glcd_Fill(0x00);

Glcd_Set_Font(System3x6, 3, 6, 0x20);

Glcd_Write_Text(someText, 10,5, 1);

Delay2S();

goto lMainLoop;

}//~!

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Hardware Connection

VCC

D7 D6

R/W

RS

CS2

CS1

RG15

RC1

RC2

RC3

RC4

RG6

RG7

RG8

MCLR

RG9

Vss

Vdd

RA12

RA13

RB5

RB4

RB3

RB2

RB1

RB0

RG13 RG12 RG14

RA7 RA6

RG0 RG1 RF1

Vdd Vss RD7 RD6 RD5 RD4 dsPIC30FXXXX

RD13 RD12

RD3 RD2 RD1

RC14

RC13

RD0

RD11

RD10

RD9

RD8

RA15

RA14

Vss

OSC2

OSC1/CLKI

Vdd

RG2

RG3

RF6

RF7

RF8

RF2

RF3

RB6 RB7 RA9 RA10 A RB8 RB9

Vss Vdd RB12 RB13 RB14 RB15 RD14 RD15 RF4 RF5

D0

Vee

VCC

Contrast

Adjustment

Vo

P1

5K

VCC

20

1

mikroElektronika dsPICPRO

Development system

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C Graphic LCD Library

mikroC for dsPIC provides a library for drawing and writing on Toshiba T6963C

Graphic LCD (changeable size).

Note: Be sure to designate port with GLCD as output, before using any of the following library functions.

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

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C_init

Prototype

void T6963C_init(unsigned int w, unsigned int h, unsigned int fntW,

unsigned int *data, unsigned int *cntrl, unsigned int bitwr, unsigned int bitrd, unsigned int bitcd, unsigned int bitreset);

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.

Requires

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.

Nothing.

Example

T6963C_init(240, 128, 8, &PORTF, &PORTD, 5, 7, 6, 4) ;

/*

* init display for 240 pixel width and 128 pixel height

* 8 bits character width

* data bus on PORTF

* control bus on PORTD

* bit 5 is !WR

* bit 7 is !RD

* bit 6 is C!D

* bit 4 is RST

*/

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C_writeData

Prototype

void T6963C_writeData(unsigned char data);

Description

Requires

Example

Routine that writes data to T6963C controller.

Ports must be initialized. See

T6963C_init

.

T6963C_writeData(AddrL);

T6963C_writeCommand

Prototype

Description

void T6963C_writeCommand(unsigned char data);

Routine that writes command to T6963C controller.

Requires

Ports must be initialized. See

T6963C_init

.

Example

T6963C_writeCommand(T6963C_CURSOR_POINTER_SET);

T6963C_setPtr

void T6963C_setPtr(unsigned int addr, unsigned char t);

Prototype

Description

This routine sets the memory pointer p for command c.

Requires

Ports must be initialized. See

T6963C_init

.

Example

T6963C_writeCommand(T6963C_CURSOR_POINTER_SET);

T6963C_waitReady

Prototype

Description

void T6963C_waitReady(void);

This routine pools the status byte, and loops until ready.

Requires

Ports must be initialized. See

T6963C_init

.

Example

T6963C_waitReady(); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C_fill

Prototype

Description

Requires

void T6963C_fill(unsigned char data, unsigned int start, unsigned

int len);

This routine fills length with bytes to controller memory from start address.

Ports must be initialized. See

T6963C_init

.

T6963C_fill(0x33,0x00FF,0x000F);

Example

T6963C_dot

Prototype

Description

Requires

void T6963C_dot(int x, int y, unsigned char color);

This sets current text work panel. It writes string str row x line y. mode =

T6963C_ROM_MODE_[OR|EXOR|AND].

Ports must be initialized. See

T6963C_init

.

Example

T6963C_dot(x0, y0, pcolor);

T6963C_write_char

Prototype

Description

void T6963C_dot(int x, int y, unsigned char color);

This routine sets current text work panel.

It writes char c row x line y.

mode = T6963C_ROM_MODE_[OR|EXOR|AND]

Requires

Example

Ports must be initialized. See

T6963C_init

.

T6963C_write_char('A',22,23,AND);

T6963C_write_text

Prototype

Description

Requires

Example

void T6963C_write_text(unsigned char *str, unsigned char x,

unsigned char y, unsigned char mode);

This sets current text work panel.

It writes string str row x line y.

mode = T6963C_ROM_MODE_[OR|EXOR|AND]

Ports must be initialized. See

T6963C_init

.

T6963C_write_text(" GLCD LIBRARY DEMO, WELCOME !", 0, 0,

T6963C_ROM_MODE_XOR); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C_line

Prototype

Description

Requires

Example

void T6963C_line(int px0, int py0, int px1, int py1, unsigned

char pcolor);

This routine current graphic work panel.

It's draw a line from (x0, y0) to (x1, y1).

pcolor = T6963C_[WHITE[BLACK]

Ports must be initialized. See

T6963C_init

.

T6963C_line(0, 0, 239, 127, T6963C_WHITE);

T6963C_rectangle

Prototype

Description

Requires

Example

void T6963C_rectangle(int x0, int y0, int x1, int y1, unsigned

char pcolor);

It sets current graphic work panel.

It draws the border of the rectangle (x0, y0)-(x1, y1).

pcolor = T6963C_[WHITE[BLACK].

Ports must be initialized. See

T6963C_init

.

T6963C_rectangle(20, 20, 219, 107, T6963C_WHITE);

T6963C_box

Prototype

Description

Requires

Example

void T6963C_box(int x0, int y0, int x1, int y1, unsigned char pcolor);

This routine sets current graphic work panel.

It draws a solid box in the rectangle (x0, y0)-(x1, y1).

pcolor = T6963C_[WHITE[BLACK].

Ports must be initialized. See

T6963C_init

.

T6963C_box(0, 119, 239, 127, T6963C_WHITE); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C_circle

Prototype

void T6963C_circle(int x, int y, long r, unsigned char pcolor);

Description

Requires

Example

This routine sets current graphic work panel.

It draws a circle, center is (x, y), diameter is r.

pcolor = T6963C_[WHITE[BLACK]

Ports must be initialized. See

T6963C_init

.

T6963C_circle(120, 64, 110, T6963C_WHITE);

T6963C_image

Prototype

Description

Requires

Example

void T6963C_image(const char *pic);

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 .

Ports must be initialized. See

T6963C_init

.

T6963C_image(mc);

T6963C_sprite

Prototype

Description

void T6963C_sprite(unsigned char px, unsigned char py, const char

*pic, unsigned char sx, unsigned char sy);

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

Example

Ports must be initialized. See

T6963C_init

.

T6963C_sprite(76, 4, einstein, 88, 119); // draw a sprite page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

T6963C_set_cursor

Prototype

Description

Requires

Example

void T6963C_set_cursor(unsigned char x, unsigned char y);

This routine sets cursor row x line y.

Ports must be initialized. See

T6963C_init

.

T6963C_set_cursor(cposx, cposy);

Library Example

The following drawing demo tests advanced routines of T6963C GLCD library.

#

include

"T6963C.h"

// ------------------------------------------------------

// GLCD Picture name: panel_128x128.bmp

// GLCD Model: Toshiba T6963C 128x128

// ------------------------------------------------------

/*

* bitmap pictures stored in ROM

*/

extern const char mc[] ;

extern const char einstein[] ;

/*

* initial PWM duty cycle for contrast power supply

*/

unsigned char

PWM_duty = 200 ;

void main(void)

{

unsigned char unsigned int unsigned char unsigned int

panel ; // current panel i ; // general purpose register curs ; // cursor visibility cposx, cposy ; // cursor x-y position

ADPCFG = 0xFFFF;

TRISC = 0;

TRISB = 0xFFFF;

TRISD = 0 ;

PORTD = 0b00000000 ;

//continues...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//continued...

/*

* init display for 240 pixel width and 128 pixel height

* 8 bits character width

* data bus on PORTF

* control bus on PORTD

* bit 5 is !WR

* bit 7 is !RD

* bit 6 is C!D

* bit 4 is RST

*/

T6963C_init(240, 128, 8, &PORTF, &PORTD, 5, 7, 6, 4) ;

/*

* enable both graphics and text display at the same time

*/

T6963C_graphics(1) ;

T6963C_text(1) ; panel = 0 ; i = 0 ; curs = 0 ; cposx = cposy = 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) ;

//continues...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//continued...

/*

* 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) ;

/*

* 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(mc); //fill the graphic screen with a picture

for(;;)

{

/*

* if RB0 is pressed, toggle the display between positive and negative mode

*/

if(PORTBbits.RB0)

{

PORTCbits.RC0 ^= 1;

Delay_ms(300) ;

}

//continues...

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//continued...

/*

* if RB1 is pressed, toggle the display between graphic panel 0 and graphic 1

*/

else if(PORTBbits.RB1)

{ panel++ ; panel &= 1 ;

T6963C_displayGrPanel(panel) ;

Delay_ms(300) ;

}

/*

* if RB2 is pressed, display only graphic panel

*/

else if(PORTBbits.RB2)

{

T6963C_graphics(1) ;

T6963C_text(0) ;

Delay_ms(300) ;

}

/*

* if RB3 is pressed, display only text panel

*/

else if(PORTBbits.RB3)

{

T6963C_graphics(0) ;

T6963C_text(1) ;

Delay_ms(300) ;

}

/*

* if RB4 is pressed, display text and graphic panels

*/

else if(PORTBbits.RB4)

{

T6963C_graphics(1) ;

T6963C_text(1) ;

Delay_ms(300) ;

}

//continues...

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//continued...

/*

* if RB5 is pressed, change cursor

*/

else if(PORTBbits.RB5)

{ curs++ ;

if(curs == 3) curs = 0 ;

switch(curs)

{

case 0:

// no cursor

T6963C_cursor(0) ;

break ;

case 1:

// blinking cursor

T6963C_cursor(1) ;

T6963C_cursor_blink(1) ;

break ;

case 2:

// non blinking cursor

T6963C_cursor(1) ;

T6963C_cursor_blink(0) ;

break ;

}

Delay_ms(300) ;

}

/*

* move cursor, even if not visible

*/

cposx++ ;

if(cposx == T6963C_txtCols)

{ cposx = 0 ; cposy++ ;

if(cposy == T6963C_grHeight / T6963C_CHARACTER_HEIGHT)

{ cposy = 0 ;

}

}

T6963C_set_cursor(cposx, cposy) ;

Delay_ms(100) ;

}

} page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Hardware Connection

VCC mikroC for dsPIC making it simple...

page

RG15

RC1

RC2

RC3

RC4

RG6

RG7

RG8

MCLR

RG9

Vss

Vdd

RA12

RA13

RB5

RB4

RB3

RB2

RB1

RB0

RG13 RG12 RG14

RA7 RA6

RG0 RG1 RF1

Vdd Vss RD7 RD6 RD5 RD4

RD13 RD12

RD3 RD2 RD1

RC14

RC13

RD0

RD11

RD10 dsPIC30FXXXX

RD9

RD8

RA15

RA14

Vss

OSC2

OSC1/CLKI

Vdd

RG2

RG3

RF6

RF7

RF8

RF2

RF3

RB6 RB7 RA9 RA10 AV RB8 RB9 Vss Vdd RB12 RB13 RB14 RB15 RD14 RD15 RF4 RF5

MD0

D6

D7

D2

D3

10MHz

Contrast

Adjustment

P1

10K

VCC

1

R1

50

VCC

20

D4 D5 D6 D7

mikroE dsPIC PRO

Dev. tool

Toshiba T6963C Graphic LCD (240x128)

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Manchester Code Library

mikroC 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 selfsynchronizing 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).

Manchest er RF_Send_Byt e format

St 1 St 2 Ct r B7 B6 B5 B4 B3 B2 B1 B0

Bi-phase coding

2.4m s

1 0

Example of transmission

1 1 0 0 0 1 0 0 0 1 1

Notes: Manchester receive routines are blocking calls (

Man_Receive_Config

,

Man_Receive_Init

,

Man_Receive

). This means that dsPIC 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

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Man_Receive_Config

void Man_Receive_Config(unsigned int *port, unsigned int rxpin);

Prototype

Description

The function 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(&PORTB, 12);

Man_Receive_Init

void Man_Receive_Init(unsigned int *port);

Prototype

Description

The function 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

unsigned int Man_Receive(unsigned int *error);

Prototype

Returns

Description

Returns one byte from signal.

Function extracts one byte from signal. If signal format does not match the expected, error flag will be set to 255.

Requires

Example

To use this function, you must first prepare the PIC for receiving. See

Man_Receive_Config or

Man_Receive_Init

.

temp = Man_Receive(error);

if (error) { ... /* error handling */ } page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Man_Send_Config

Prototype

void Man_Send_Config(unsigned short *port, unsigned short txpin);

Description

Example

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.

Man_Send_Config(&PORTD, 0);

Man_Send_Init

void Man_Receive_Init(unsigned int *port);

Prototype

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

Description

Requires

Example

void Man_Send(unsigned int data);

Sends one byte ( data

).

To use this function, you must first prepare the dsPIC for sending. See

Man_Send_Config or

Man_Send_Init

.

unsigned short msg;

...

Man_Send(msg);

Man_Synchro

Prototype

Returns

unsigned int Man_Synchro();

Half of the manchester bit length, given in multiples of 10us.

Description

Requires

Example

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.

To use this function, you must first prepare the PIC for receiving. See

Man_Receive_Config or

Man_Receive_Init

.

man_len = Man_Synchro(); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

unsigned int ERR, *error, ErrorCount, temp;

void main() {

ADPCFG = 0xFFFF;

TRISF = 0;

ERR = 0;

Uart1_Init(9600); error = &ERR;

ErrorCount = 0;

Lcd8_Custom_Config(&PORTB, 7, 6, 5, 4, 3, 2, 1, 0, &PORTD, 0, 1, 2);

// Initialize LCD on PORTB

Man_Receive_Init(&PORTD); // Configure and synchronize receiver

while (1) {

Lcd8_Custom_Cmd(LCD_FIRST_ROW);

while (1) // Wait for the start marker

{ temp = Man_Receive(error);

if (temp == 0x0B)

break; // We got the starting sequence

if (ERR) // Exit so we do not loop forever

break;

}

do

{ temp = Man_Receive(error); // Attempt byte receive

Uart1_Write_Char(0Xff);

Uart1_Write_Char(ERR);

Uart1_Write_Char(ERR >> 8);

if (ERR)

{

Lcd8_Custom_Chr_CP('?');

ErrorCount++;

if (ErrorCount > 20)

{

//Man_Receive_Init(&PORTD);

// alternative:

temp = Man_Synchro();

ErrorCount = 0;

}

}

else

{

if (temp != 0x0E) // Don't write the } marker on LCD

Lcd8_Custom_Chr_CP(temp);

}

while (temp != 0x0E) ;

}}//~!

}

Delay_ms(25); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Transmitter RF module

VCC

Antenna

VCC

A

VCC

RT4

GND

In

11

12

13

14

VCC

GND

OSC1

OSC2

10 Mhz

19

RD3

Antenna

Receiver RF module

VCC

RR4

Receiver RF module

VCC

10 Mhz

11

12

13

14

VCC

GND

OSC1

OSC2

19

RD3

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Multi Media Card Library

The Multi Media Card (MMC) is a flash 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 PDA’s. mikroC for dsPIC provides a library for accessing data on Multi Media Card via SPI communication.This library also supports SD(Secure Digital) memory cards.

Secure Digital Card

Secure Digital (SD) is a flash memory card standard, based on the older Multi

Media Card (MMC) format. SD cards are currently available in sizes of up to and including 2 GB, and are used in cell phones, mp3 players, digital cameras, and

PDAs.

Notes:

- Library functions create and read files from the root directory only;

- Library functions populate both FAT1 and FAT2 tables when writing to files, but the file data is being read from the FAT1 table only; i.e. there is no recovery if

FAT1 table gets corrupted. If 0-th sector is Master Boot Record (MBR), library reads the necessary information from it, and jumps to the first available primary logical partition.

- If 0-th sector is the boot sector (i.e. there is only one logical partition and no

MBRs), library works with entire card as a single partition.

For more information on MBR, physical and logical drives, primary/secondary partitions and partition tables, please consult other resources, e.g. Wikipedia and similar.

- Please note that this library uses SPI1 module for communication with the

MMC/SD card!

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_Set_File_Date

Mmc_Fat_Delete

Mmc_Fat_Get_File_Date

Mmc_Fat_Get_File_Size

Mmc_Fat_Get_Swap_File page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Mmc_Init

Prototype

Returns

Description

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned short Mmc_Init(unsigned int *port, unsigned int pin);

Returns 1 if MMC card is present and successfully initialized, otherwise returns 0.

Initializes MMC through hardware SPI communication, with chip select pin being given by the parameters port and pin

; communication port and pins are designated by the hardware SPI settings for the respective MCU. Function returns 1 if MMC card is present and successfully initialized, otherwise returns 0.

Mmc_Init needs to be called before using other functions of this library.

while (!Mmc_Init(&PORTC,2)) ; // Loop until MMC is initialized

Mmc_Read_Sector

Prototype

Returns

Description

Requires

Example

unsigned Mmc_Read_Sector(unsigned long sector, char *data);

Returns 0 if read was successful, or 1 if an error occurred.

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.

Library needs to be initialized, see

Mmc_Init

.

error = Mmc_Read_Sector(sector, data);

Mmc_Write_Sector

Prototype

Returns

Description

Requires

Example

unsigned Mmc_Write_Sector(unsigned long sector,char *data);

Returns 0 if write was successful; returns 1 if there was an error in sending write command; returns 2 if there was an error in writing.

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.

Library needs to be initialized, see

Mmc_Init

.

error = Mmc_Write_Sector(sector, data); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Mmc_Read_Cid

Prototype

unsigned Mmc_Read_Cid(unsigned short *data_cid); mikroC for dsPIC making it simple...

Returns

Description

Requires

Example

Returns 0 if read was successful, or 1 if an error occurred.

Function reads CID register and returns 16 bytes of content into data_cid

.

Library needs to be initialized, see

Mmc_Init

.

error = Mmc_Read_Cid(data);

Mmc_Read_Csd

Prototype

unsigned short Mmc_Read_Csd(unsigned short *data_csd);

Returns

Description

Requires

Example

Returns 0 if read was successful, or 1 if an error occurred.

Function reads CSD register and returns 16 bytes of content into data_csd

.

Library needs to be initialized, see

Mmc_Init

.

error = Mmc_Read_Csd(data); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Mmc_Fat_Init

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned Mmc_Fat_Init(unsigned *port, unsigned short pin);

Prototype

Returns

Description

Example

The function returns 1 if MMC card is present and successfully initialized and MBR/primary partition or Boot Sector were found, otherwise returns 0.

Initializes hardware SPI communication; designated CS line for communication is RC2.

The function returns 0 if MMC card is present and successfully initialized, otherwise returns 1.

This function needs to be called before using other functions of MMC FAT library.

// Loop until MMC FAT is initialized at RC2

while (Mmc_Fat_Init(&PORTC, 2)) ;

Mmc_Fat_Assign

Prototype

Description

Requires

Example

unsigned Mmc_Fat_Assign(char *filename, char create_file);

Assigns file for FAT operations. If file isn't present, function creates new file with given filename

. filename parameter is filename of file. 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).

Library needs to be initialized; see

Mmc_Fat_Init

.

Mmc_Fat_Assign('MIKROELE.TXT',1);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Mmc_Fat_Reset

Prototype

Description

Requires

Example

void Mmc_fat_Reset(unsigned long *size);

Opens file for reading. size is size of file in bytes.

Ports must be initialized for FAT operations with MMC.

See

Mmc_Fat_Init

.

File must be assigned.

See

Mmc_Fat_Assign

.

Mmc_Fat_Reset(size);

Mmc_Fat_Rewrite

void Mmc_Fat_Rewrite(void);

Prototype

Description

Function resets the file pointer and clears the assigned file, so that new data can be written into the file.

Requires

Example

Library needs to be initialized; see

Mmc_Fat_Init

.

Mmc_Fat_Rewrite();

Mmc_Fat_Append

void Mmc_Fat_Append(void);

Prototype

Description

The function moves the file pointer to the end of the assigned file, so that data can be appended to the file.

Requires

Example

Library needs to be initialized; see

Mmc_Fat_Init

.

Mmc_Fat_Append(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Mmc_Fat_Read

Prototype

void Mmc_Fat_Read(unsigned char *data);

Description

Requires

Example

Reads data from file. bdata is data read from file.

Ports must be initialized for FAT operations with MMC.

See

Mmc_Fat_Init

.

File must be assigned.

See

Mmc_Fat_Assign

.

File must be open for reading.

See

Mmc_Fat_Reset

.

Mmc_Fat_Read(character);

Mmc_Fat_Write

Prototype

void Mmc_Fat_Write(char *fdata, unsigned data_len);

Description

Requires

Example

Writes data to MMC. fdata parameter is data written to MMC. data_len number of bytes that is written to MMC.

Ports must be initialized for FAT operations with MMC. See

Mmc_Fat_Init

.

File must be assigned. See

Mmc_Fat_Assign

.

File must be open for writing. See

Mmc_Fat_Rewrite or

Mmc_Fat_Append

.

Mmc_Fat_Write(file_contents, 42);

Mmc_Set_File_Date

Prototype

Description

Requires

Example

void Mmc_fat_Set_File_Date(unsigned int year, unsigned short month,

unsigned short day, unsigned short hours, unsigned short mins,

unsigned short seconds);

Writes system timestamp to a file. Use this routine before each writing to the file; otherwise, file will be appended a random timestamp.

Ports must be initialized for FAT operations with MMC. See

Mmc_Fat_Init

.

File must be assigned. See

Mmc_Fat_Assign

.

File must be open for writing. See

Mmc_Fat_Rewrite or

Mmc_Fat_Append

.

// April 1st 2005, 18:07:00

Mmc_Fat_Set_File_Date(2005,9,30,17,41,0); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Mmc_Fat_Delete

Prototype

Description

Requires

Example

void Mmc_Fat_Delete();

Deletes file from MMC.

Ports must be initialized for FAT operations with MMC.

See

Mmc_Fat_Init

. File must be assigned. See

Mmc_Fat_Assign

.

Mmc_Fat_Delete; mikroC for dsPIC making it simple...

Mmc_Fat_Get_File_Date

Prototype

Description

Requires

Example

void Mmc_fat_Get_File_Date(unsigned int *year, unsigned short

*month, unsigned short *day, unsigned short *hours, unsigned

short *mins);

Reads time attributes of file.You can read file year, month, day. hours, mins, seconds.

Ports must be initialized for FAT operations with MMC.

See

Mmc_Fat_Init

.

File must be assigned.

See

Mmc_Fat_Assign

.

Mmc_Fat_Get_File_Date(year, month, day, hours, mins);

Mmc_Fat_Get_File_Size

Prototype

unsigned long Mmc_fat_Get_File_Size();

Description

Requires

Example

This function returns size of file in bytes.

Ports must be initialized for FAT operations with MMC.

See

Mmc_Fat_Init

.

File must be assigned. See

Mmc_Fat_Assign

. my_file_size = Mmc_Fat_Get_File_Size(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Mmc_Fat_Get_Swap_File

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Prototype

Returns

Description

Requires

Example

unsigned long Mmc_Fat_Get_Swap_File(unsigned long sectors_cnt);

No. of start sector for the newly created swap file, if swap file was created; otherwise, the function returns zero.

This function is used to create a swap file on the MMC/SD 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 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, by using the

Mmc_Read_Sector() and

Mmc_Write_Sector() functions directly, 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 mikroC's library is to be used for fast data acquisition; when the time-critical acquisition has finished, the data can be re-written into a "normal" file, and formatted in the most suitable way.

Ports must be initialized for FAT operations with MMC.

See

Mmc_Fat_Init

.

//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

void M_Create_Swap_File() { size = Mmc_Fat_Get_Swap_File(1000);

if (size) {

Uart_Write(0xAA);

Uart_Write(Lob(size));

Uart_Write(Hib(size));

Uart_Write(Higherb(size));

Uart_Write(Highestb(size));

Uart_Write(0xAA);

}

}//~ page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The following example performs MMC card init in SPI mode and, if successfuly initialized, writes

512 bytes (512*char('!')) at sector No.55. User is informed about the progress over UART1.

//--- constants

const char MSG_PICSTART[] = "PIC started\n\r";

const char MSG_MMCINIT[] = "MMC init OK\n\r";

const char MSG_MMCINIT_E[] = "MMC init Err\n\r";

const char MSG_WRITE[] = "MMC write OK\n\r";

const char MSG_WRITE_E[] = "MMC write Err\n\r";

const char MSG_CID_E[] = "CID read Err\n\r";

const char MSG_CSD_E[] = "CSD read Err\n\r";

const char MSG_RD_E[] = "MMC read Err\n\r";

// universal variables

unsigned int px, k; // universal for loops and other stuff

// Variables for MMC routines

unsigned char data[512]; // Buffer for MMC sector reading/writing

unsigned char data_for_registers[16]; // buffer for CID and CSD registers

// RS232 communication variables

unsigned char received_character;

unsigned long sector_address;

unsigned char first_byte, second_byte, third_byte, fourth_byte;

unsigned char serial_buffer[2];

unsigned char serial_pointer;

const char * msg_pt;

//-------------- Writes a null-terminated string from ROM to UART1

void Uart1_Write_Text_Flash(const char * txt) {

char wrt = *txt;

while (wrt) {

Uart1_Write_Char(wrt); wrt = *(++txt);

}

}//~ page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//-------------- Display byte in hex

void Print_Hex(unsigned char i) {

unsigned char hi,lo; hi = i & 0xF0; // High nibble hi = hi >> 4; hi = hi + '0';

if (hi>'9') hi = hi + 7; lo = (i & 0x0F) + '0'; // Low nibble

if (lo>'9') lo=lo+7;

Uart1_Write_Char(hi);

Uart1_Write_Char(lo);

}//~

void main() {

unsigned int i;

//--- init UART1 module

Uart1_Init(19200);

U1MODEbits.ALTIO = 1; //comm on alternative pins

Delay_ms(200); //wait to stabilize

//--- start-of-application

msg_pt = MSG_PICSTART;

Uart1_Write_Text_Flash(msg_pt);

//--- Before all, we must initialise a MMC card

ADPCFG = 0xFFFF; // disable A/D inputs i = Mmc_Init(&PORTB, 8); //this is the CS pin on EASYdsPIC2 board

if(i == 1) {

//--- report MMC present and initialised

msg_pt = MSG_MMCINIT;

Uart1_Write_Text_Flash(msg_pt);

}

if(i == 0) {

//--- MMC init error

msg_pt = MSG_MMCINIT_E;

Uart1_Write_Text_Flash(msg_pt);

}

//--- fill MMC buffer with some characters

for(i = 0; i < 512; i++) { data[i] = '!';

}

//--- write data to sector 55

i = Mmc_Write_Sector(55, data);

if(i == 0) { msg_pt = MSG_WRITE;

Uart1_Write_Text_Flash(msg_pt);

}

else { msg_pt = MSG_WRITE_E;

Uart1_Write_Text_Flash(msg_pt);

}

Uart1_Write_Char(13);

Uart1_Write_Char(10);}//~ page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Hardware Connection

mikroC for dsPIC making it simple...

SPI-MISO

MMC-CS#

SPI-MOSI

SPI-SCK

R13

2K2

R15

2K2

R17

2K2

R14

3K3

R16

3K3

R18

3K3

VCC3

3

4

5

6

7

1

2

CS

Din

GND

+3.3V

SCK

GND

Dout

MMC/SD

CARD

SPI-MOSI

SPI-MISO

SPI-SCK

RB4

RB5

RB6

MMC-CS#

RB8

VCC3

C20

100nF

VCC

REG2

MC33269

DT-3.3

VCC

C19

100nF

1

GND

2

3

VIN

VOUT

VCC3

E15

10uF

VCC

10 Mhz

6

7

8

RB4

RB5

RB6

10

11

12

13

14

RB8

VCC

GND

OSC1

OSC2

page

1 2 3 4 5 6 7

MMC

Back view

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

OneWire Library

OneWire library provides routines for communication via OneWire bus, for example 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

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Ow_Reset

unsigned int Ow_Reset(unsigned int *port, unsigned int pin);

Prototype

Returns

Description

Returns 0 if DS1820 is present, 1 if not present.

Issues OneWire reset signal for DS1820. Parameters port and pin specify the location of DS1820.

Requires

Example

Works with Dallas DS1820 temperature sensor only.

Ow_Reset(&PORTA, 5); // reset DS1820 connected to the RA5 pin

Ow_Read

Prototype

Returns

Description

Example

unsigned short Ow_Read(unsigned int *port, unsigned int pin);

Data read from an external device over the OneWire bus.

Reads one byte of data via the OneWire bus.

unsigned short tmp;

...

tmp = Ow_Read(&PORTD, 5);

Ow_Write

Prototype

Description

Example

void Ow_Write(unsigned int *port, unsigned int pin, unsigned

short par);

Writes one byte of data (argument par

) via OneWire bus.

Ow_Write(&PORTA, 5, 0xCC); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Library Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

const unsigned short TEMP_RESOLUTION = 12;

const int RES_FACTOR_1[4] = {5000, 2500, 1250, 625};

const unsigned int RES_FACTOR_2[4] = {0x0001, 0x0003, 0x0007, 0x000F};

const unsigned int RES_FACTOR_3[4] = {0x8000, 0xC000, 0xE000, 0xF000};

unsigned temp;

unsigned short

j, RES_SHIFT;

char * R_Trim(char *str1) {

while (*str1 == ' ') str1++;

return str1;

}//~

void Display_Temperature(unsigned int temp) {

// const unsigned short RES_SHIFT = TEMP_RESOLUTION - 8;

unsigned short RES_SHIFT = TEMP_RESOLUTION - 8;

unsigned int temp_whole, temp_fraction;

unsigned short i;

char text[8];

//--- isolate the fraction and make it a 4-digit decimal integer (for display)

temp_fraction = temp & RES_FACTOR_2[RES_SHIFT - 1]; temp_fraction = temp_fraction * RES_FACTOR_1[RES_SHIFT - 1];

//--- handle the whole part of temperature value

temp_whole = temp;

//--- is temperature negative?

if ((temp_whole & 0x8000) != 0u) i = 1; // Yes, i = 1

else

i = 0; // No, i = 0

//--- remove the fractional part

temp_whole >>= RES_SHIFT;

//--- correct the sign if necessary

if (i) temp_whole |= RES_FACTOR_3[RES_SHIFT - 1];

//--- convert whole part to string

IntToStr(temp_whole, text);

//--- print whole part on Lcd_Custom

Lcd8_Custom_Out(2, 2, text); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

//--- print dot to separate fractional part

Lcd8_Custom_Chr_CP('.');

//--- Convert fractional part to string

IntToStr(temp_fraction, text);

// Add leading zeroes (we display 4 digits fractional part)

if (temp_fraction < 1000u) Lcd8_Custom_Chr_CP('0');

if (temp_fraction < 100u) Lcd8_Custom_Chr_CP('0');

if (temp_fraction < 10u) Lcd8_Custom_Chr_CP('0');

//--- Print fractional part on Lcd_Custom

Lcd8_Custom_Out_CP(R_Trim(text));

// Print degree character, 'C' for Centigrades

Lcd8_Custom_Chr_CP(223);

Lcd8_Custom_Chr_CP('C');

}//~

char txt[10];

void main() {

ADPCFG = 0xFFFF;

Lcd8_Custom_Config(&PORTB,7,6,5,4,3,2,1,0, &PORTD,10,3,11);

Lcd8_Custom_Cmd(LCD_CURSOR_OFF);

Lcd8_Custom_Out(1, 1, " Temperature1: ");

//--- main loop

do {

//--- perform temperature reading

Ow_Reset(&PORTD,6); // Onewire reset signal

Ow_Write(&PORTD,6,0xCC); // Issue command SKIP_ROM

Ow_Write(&PORTD,6,0x44); // Issue command CONVERT_T

Delay_us(120);

Ow_Reset(&PORTD,6);

Ow_Write(&PORTD,6,0xCC); // Issue command SKIP_ROM

Ow_Write(&PORTD,6,0xBE); // Issue command READ_SCRATCHPAD

Delay_ms(400); temp = Ow_Read(&PORTD,6); temp = (Ow_Read(&PORTD,6) << 8) | temp;

//--- Format and display result on Lcd

Display_Temperature(temp);

Delay_ms(500);

} while (1);

}//~! page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

125 C

VCC

11

12

13

14

VCC

GND

OSC1

OSC2

10 Mhz

RF2

26

DS1820

GND

DQ

VCC

-50 C

VCC

VCC

R10

10K

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PS/2 Library

mikroC 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.

Library Routines

Ps2_Init

Ps2_Config

Ps2_Key_Read

Ps2_Init

Prototype

Description

Requires

void Ps2_Init(unsigned int *port);

Initializes port for work with PS/2 keyboard, with default pin settings. Port pin 0 is

Data line, and port pin 1 is Clock line.

You need to call either

Ps2_Init or

Ps2_Config before using other routines of PS/2 library.

Both Data and Clock lines need to be in pull-up mode.

Ps2_Config

Prototype

void Ps2_Config(unsigned int *port, unsigned int clock, unsigned

int data);

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 to the same pin.

You need to call either

Ps2_Init or

Ps2_Config before using other routines of PS/2 library.

Requires

Both Data and Clock lines need to be in pull-up mode.

Example

Ps2_Config(&PORTB, 2, 3); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Ps2_Key_Read

Prototype

Returns

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned int Ps2_Key_Read(unsigned int *value, unsigned int *special, unsigned int *pressed);

Returns 1 if reading of a key from the keyboard was successful, otherwise 0.

The function retrieves information about key pressed.

Parameter value holds the value of the key pressed. For characters, numerals, punctuation marks, and space, value will store the appropriate ASCII value. Routine “recognizes” 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

Example

PS/2 keyboard needs to be initialized; see

Ps2_Init or

Ps2_Config

.

// Press Enter to continue:

do {

if (Ps2_Key_Read(&value, &special, &pressed)) {

if ((value == 13) && (special == 1)) break;

}

} while (1);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

This simple example reads values of keys pressed on PS/2 keyboard and sends them via UART.

unsigned int

keydata = 0, special = 0, down = 0;

char *txt;

void main() {

ADPCFG = 0xFFFF;

TRISF.f2 = 1;

Uart1_Init(9600);

Ps2_Init(&PORTC); // Init PS/2 Keyboard on PORTD

Delay_ms(100); // Wait for keyboard to finish txt = " ";

Uart1_Write_Char(0xFF);

do {

if(Ps2_Key_Read(&keydata, &special, &down)) {

if(down && (keydata == 16)) {// Backspace

// Lcd_Cmd(LCD_MOVE_CURSOR_LEFT);

}

else if(down && (keydata == 13)) {// Enter

Uart1_Write_Char('\n');

}

else if(down && !special && keydata) {

// Lcd_Chr_CP(keydata);

}

}

//Uart1_Write_Char(keydata >> 8);

Uart1_Write_Char(keydata);

Delay_ms(10); // debounce

} while(1);

}//!~ page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PWM Library

CCP module is available with a number of dsPICmicros. mikroC for dsPIC provides library which simplifies using PWM HW Module.

Library Routines

Pwm_Init

Pwm_Set_Duty

Pwm_Start

Pwm_Stop

Pwm_Init

Prototype

Returns

Description

Requires

Example

unsigned int Pwm_Init(unsigned int freq_hz, unsigned int pair_output_mode,

unsigned int enable_output_x, unsigned int clock_prescale_output_postscale);

Value of the 50% of the PWM duty cycle, which was calculated for given parameters.

Initializes the PWM module 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.

Function parameters Parameters: freq_hz

- Desired PWM frequency, in Hz; pair_output_mode

- output mode for output pin pairs: 0- independent, 1- complementary, enable_output_x

: (pin4h.pin3h.pin2h.pin1h.pin4l.pin3l.pin2l.pin1l): 0- disabled (pin is standard I/O), 1- enabled (pin is PWM output); clock_prescale_output_postscale

: PWM clock prescale/postscale settings:<0..3><0..15> - <1:1, 1:4, 1:16, 1:64><1:1, 1:2, ..., 1:16>

This function (as well as the entire library) works on dsPICs that have the motor control

PWM unit, e.g. dsPIC30F3010.

Initializes PWM module at 5KHz, complementary pin-pair output, output enabled on pins 4l..1l, no clock prescale and no clock postscale: unsigned int duty_50;

...

duty_50 = Pwm_Init(5000,1,0xF,0); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Pwm_Set_Duty

Prototype

Description

Requires

Example

void Pwm_Set_Duty(unsigned int duty, unsigned int channel);

Changes PWM duty ratio. Parameter duty takes values from 0 to 65535, value of the

50% of the duty ratio for active settings is retuned upon PWM init.

You need a dsPIC with motor control PWM module to use this library. To use this function, module needs to be initalized – see

Pwm_Init

.

unsigned int duty_50; duty_50 = Pwm_Init(5000,1,0xF,0);

Pwm_Change_Duty(duty_50 * 3/2);

Pwm_Start

Prototype

void Pwm_Start(void);

Description

Requires

Starts PWM.

You need a CCP module to use this library. To use this function, module needs to be initalized – see

Pwm_Init

.

Example

Pwm_Start();

Pwm_Stop

Prototype

Description

Requires

void Pwm_Stop(void);

Stops PWM.

You need a CCP module to use this library. To use this function, module needs to be initalized – see

Pwm_Init

.

Example

Pwm_Stop(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

unsigned int i;

unsigned int duty_50;

void main(){

ADPCFG = 0xFFFF;

TRISE = 0;

PORTB = 0xAAAA;

TRISB = 0;

Delay_ms(1000); duty_50 = Pwm_Init(5000,1,0xF,0);

Pwm_Set_Duty(i = duty_50,1);

Pwm_Start();

do

{ i--;

Pwm_Set_Duty(i,1);

Delay_ms(10); if (i == 0) i = 8000;

PORTB = i;

}

while(1);

}//~

Hardware Connection

10 Mhz

8

9

10

GND

OSC1

OSC2

VCC

13

VCC

RE0

RE1

26

25

300R

300R

LD25 LD26

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

RS-485 Library

RS-485 is a multipoint communication which allows multiple devices to be connected to a single signal cable. mikroC for dsPIC provides a set of library routines to provide you comfortable work with RS485 system using Master/Slave architecture. 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 UART module on PORTF. Pins of UART need to be attached to RS-485 interface transceiver, such as LTC485 or similar. Pins of transceiver (Receiver Output Enable and Driver Outputs Enable) should be connected to PORTF, pin 0 (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.

Library Routines

RS485Master_Init

RS485Master_Receive

RS485Master_Send

RS485Slave_Init

RS485Slave_Receive

RS485Slave_Send page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

RS485Master_Init

Prototype

Description

void Rs485Master_Init(unsigned long baud_rate, unsigned int uart_no, unsigned int *port, unsigned int pin);

Initializes dsPIC MCU as Master in RS-485 communication.

Parameter baud_rate determines the baud rate of the used UART module.

Paramter uart_no specifies which UART module will be used to drive the RS485 module: 1 (for UART1) or 2 (for UART2). Note: if you specify some value other than 1 or

2, RS485 module will be initialized with UART1 module (default).

Requires

Example

Parameters port and pin determine the position (port and pin) of the Chip Select (CS) pin.

Nothing.

//--- initializes RS485 on UART2, at 19200 bps, CS pin is RD5

Rs485master_Init(19200,2, &PORTD,5);

RS485Master_Receive

Prototype

void RS485Master_Receive(unsigned short *data);

Description

Requires

Receives any message sent by Slaves. Messages are multi-byte, so this function 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.

MCU must be initialized as Master in RS-485 communication in order to be assigned an address. See

RS485Master_Init

.

Example

unsigned short msg[8];

...

RS485Master_Receive(msg); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

RS485Master_Send

Prototype

Description

void RS485Master_Send(unsigned short *data, unsigned short datalen, unsigned short address);

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

Example

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.

unsigned short msg[8];

...

RS485Master_Send(msg, 3, 0x12);

RS485Slave_Init

Prototype

void Rs485Slave_Init(unsigned long baud_rate, unsigned int uart_no, unsigned int *port, unsigned int pin, char address);

Description

Requires

Example

Initializes dsPIC MCU as a Slave in RS-485 communication.

Parameter baud_rate determines the baud rate of the used UART module.

Paramter uart_no specifies which UART module will be used to drive the RS485 module: 1 (for UART1) or 2 (for UART2). Note: if you specify some value other than 1 or

2, RS485 module will be initialized with UART1 module (default).

Parameters port and pin determine the position (port and pin) of the Chip Select (CS) pin.

Slave address can take any value between 0 and 255, except 50, which is common address for all slaves.

Nothing.

//--- initializes RS485 on UART2, at 19200 bps, CS pin is RD5,

//Slave address is 160

Rs485slave_Init(19200,2, &PORTD,5, 160); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

RS485Slave_Receive

void RS485Slave_Receive(unsigned short *data);

Prototype

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Description

Requires

Receives message addressed to it. Messages are multi-byte, so this function 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.

MCU must be initialized as Slave in RS-485 communication in order to be assigned an address. See

RS485Slave_Init

.

Example

unsigned short msg[8];

...

RS485Slave_Read(msg);

RS485Slave_Send

Prototype

Description

void RS485Slave_Send(unsigned short *data, unsigned short datalen);

Sends data from buffer to Master via RS-485; datalen is a number of bytes in message (1 <= datalen <= 3).

Requires

Example

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.

unsigned short msg[8];

...

RS485Slave_Send(msg, 2); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The example demonstrates working with dsPIC as Slave nod in RS-485 communication. dsPIC receives only packets addressed to it (address 160 in our example), and general messsages with target address 50. The received data is displayed on PORTB, and sent back to Master.

Communication errors are signalled on PORTG.

char dat[10]; // buffer for receving/sending messages

int i,j, Iflag;

//-------------- Interrupt routine (UART2 Rx)

void interrupt_uart() org 0x44 {

Rs485master_Receive(dat);

IFS1bits.U2RXIF = 0; //ensure interrupt not pending

}//~!~

main() {

PORTB = 0;

TRISB = 0;

PORTG = 0;

TRISG = 0; dat[4] = 0; // Ensure that msg received flag is 0 dat[5] = 0; // Ensure that error flag is 0

RS485Slave_Init(9600,2, &PORTD,5, 160);

// Initialize MCU as Slave with address 160, on UART2 at 9600bps

//--- interrupt setup

U2STAbits.URXISEL = 0;

INTCON1bits.NSTDIS = 1; //no nesting of interrupts

IFS1bits.U2RXIF = 0; //ensure interrupt not pending

IEC1bits.U2RXIE = 1; //enable intterupt

do { if (dat[5]) PORTG = 0xAA; // If there is error, set PORTD to $AA if (dat[4]) { // If message received: dat[4] = 0; // Clear message received flag j = dat[3]; // Number of data bytes received for (i = 1; i < j; i++)

PORTB = dat[--i]; // Output received data bytes dat[0]++; // Increment received dat[0]

RS485slave_Write(dat, 1); // Send it back to Master

}

} while (1);} //~! page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Hardware Connection

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Shielded pair no longer than 300m

VCC

1

2

3

4

R0

RE

DE

DI

LTC485

Vcc

B

A

GND

8

7

6

5

10 Mhz

VCC

11

12

13

14

VCC

GND

OSC1

OSC2

RF0

RF1

RF4

RF5

30

28

27

VCC

4.7uF

+

4.7uF

+

+

4.7uF

C1+

V+

C1-

C2+

C2-

V-

T2out

R2in

+

4.7uF

Vcc

GND

T1 OUT

R1IN

R1out

T1in

T2in

R2out

1

2

3

4

R0

RE

DE

DI

LTC485

Vcc

B

A

GND

620R

8

7

6

5

620R

TX

RX

RTS

GND

PC

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Software I2C Library

mikroC for dsPIC provides routines which implement software I²C. These routines are hardware independent and can be used with any MCU. Software I2C library enables you to use MCU as Master in I²C communication. Multi-master mode is not supported.

Note: This library implements time-based activities, so interrupts need to be disabled when using Soft I²C.

Note: Every hardware I²C library function has its counterpart in this software library, except Soft_I2C_Start is used instead of I2C_Repeated_Start.

Library Routines

Soft_I2C_Init

Soft_I2C_Start

Soft_I2C_Read

Soft_I2C_Write

Soft_I2C_Stop

Soft_I2C_Init

Prototype

Description

Example

void Soft_I2C_Init(unsigned short *port, const unsigned short

SDA, const unsigned short SCL);

Configures software I²C. Parameter port specifies port of MCU on which

SDA and

SCL pins are located. Parameters SDA and SCL need to be in range 0–7 and cannot point at the same pin.

Soft_I2C_Init needs to be called before using other functions from Soft I2C library.

Soft_I2C_Init(&PORTB, 1, 2); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Soft_I2C_Start

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Soft_I2C_Start(void);

Prototype

Description

Requires

Example

Issues START signal. Needs to be called prior to sending and receiving data.

Soft I²C must be configured before using this function. See

Soft_I2C_Init

.

Soft_I2C_Start();

Soft_I2C_Read

unsigned short Soft_I2C_Read(unsigned short ack);

Prototype

Returns

Description

Returns one byte from the slave.

Reads one byte from the slave, and sends not acknowledge signal if parameter ack is 0, otherwise it sends acknowledge.

Requires

Example

Soft I²C must be configured before using this function. See

Soft_I2C_Init

.

Also, START signal needs to be issued in order to use this function. See

Soft_I2C_Start

.

short take; take = Soft_I2C_Read(0);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Soft_I2C_Write

unsigned short Soft_I2C_Write(unsigned short data);

Prototype

Returns

Description

Requires

Example

Returns 0 if there were no errors.

Sends data byte (parameter data

) via I²C bus.

Soft I²C must be configured before using this function. See

Soft_I2C_Init

.

Also, START signal need to be issued in order to use this function. See

Soft_I2C_Start

.

Soft_I2C_Write(0xA3);

Soft_I2C_Stop

Prototype

void Soft_I2C_Stop(void);

Description

Requires

Example

Issues STOP signal.

Soft I²C must be configured before using this function. See

Soft_I2C_Init

.

Also, START signal need to be issued in order to use this function. See

Soft_I2C_Start

.

Soft_I2C_Stop(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The example demonstrates use of Software I²C Library. dsPIC MCU is connected

(SCL, SDA pins) to PCF8583 RTC (real-time clock). Program sends date data to

RTC.

void main() {

Soft_I2C_Init(&PORTB, 4, 3); // Initialize full master mode

Soft_I2C_Start(); // Issue start signal

Soft_I2C_Write(0xA0); // Address PCF8583

Soft_I2C_Write(0); // Start from word at address 0 (configuration word)

Soft_I2C_Write(0x80); // Write 0x80 to config. (pause counter...)

Soft_I2C_Write(0); // Write 0 to cents word

Soft_I2C_Write(0); // Write 0 to seconds word

Soft_I2C_Write(0x30); // Write 0x30 to minutes word

Soft_I2C_Write(0x11); // Write 0x11 to hours word

Soft_I2C_Write(0x30); // Write 0x24 to year/date word

Soft_I2C_Write(0x08); // Write 0x08 to weekday/month

Soft_I2C_Stop(); // Issue stop signal

Soft_I2C_Start(); // Issue start signal

Soft_I2C_Write(0xA0); // Address PCF8530

Soft_I2C_Write(0); // Start from word at address 0

Soft_I2C_Write(0); // Write 0 to config word (enable counting)

Soft_I2C_Stop(); // Issue stop signal

}//~!

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Software SPI Library

mikroC for dsPIC provides library which implement software SPI. These routines are hardware independent and can be used with any MCU. You can easily communicate 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.

Note: Function Soft_Spi_Init is for the internal use by compiler only.

Library Routines

Soft_Spi_Config

Soft_Spi_Init

Soft_Spi_Read

Soft_Spi_Write

Soft_Spi_Config

Prototype

Description

Example

void Soft_Spi_Config(unsigned short *port, const unsigned short

SDI,

const unsigned short SD0, const unsigned short SCK);

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.

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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Soft_Spi_Read

void Soft_Spi_Init(unsigned int *port);

Prototype

Returns

Description

Nothing.

Configures and initializes software SPI. Parameter port specifies port of MCU on which

SDI(pin 4), SDO(pin 5), and SCK(pin 3) will be located.

Requires

Example

Soft_Spi_Init needs to be called before using other functions from Soft SPI Library.

Nothing.

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_Init(PORTB);

Soft_Spi_Read

Prototype

unsigned short Soft_Spi_Read(unsigned short buffer);

Returns

Description

Returns the received data.

Provides clock by sending buffer and receives data.

Requires

Example

Soft SPI must be initialized and communication established before using this function.

See

Soft_Spi_Config

.

short take, buffer; take = Soft_Spi_Read(buffer);

Soft_Spi_Write

Prototype

void Soft_Spi_Write(unsigned short data);

Description

Requires

Immediately transmits data

.

Soft SPI must be initialized and communication established before using this function.

See

Soft_Spi_Config

.

Example

Soft_Spi_Write(1); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

This is a sample program which demonstrates the use of the Microchip's MCP4921 12-bit D/A converter with dsPIC mcu's. This device accepts digital input (number from 0..4095) and transforms it to the output voltage, ranging from 0..Vref. In this example the D/A is connected to PORTC and communicates with dsPIC through the SPI. The reference voltage on the mikroElektronika's DAC module is 5 V. In this example, the entire DAC’s resolution range (12bit ->4096 increments) is covered, meaning that you’ll need to hold a button for about 7 minutes to get from mid-range to the end-of-range.

const char _CHIP_SELECT = 1, _TRUE = 0xFF;

unsigned value;

void InitMain() {

Soft_SPI_Config(&PORTB, 4,5,3);

TRISB &= ~(_CHIP_SELECT);

// ClearBit(TRISC,CHIP_SELECT);

TRISC = 0x03;

}//~

// DAC increments (0..4095) --> output voltage (0..Vref)

void DAC_Output(unsigned valueDAC) {

char temp;

PORTB &= ~(_CHIP_SELECT); temp = (valueDAC >> 8) & 0x0F; temp |= 0x30;

Soft_Spi_Write(temp); temp = valueDAC;

Soft_Spi_Write(temp);

PORTB |= _CHIP_SELECT;

}//~

// ClearBit(PORTC,CHIP_SELECT);

// Prepare hi-byte for transfer

// It's a 12-bit number, so only

// lower nibble of high byte is used

// Prepare lo-byte for transfer

// SetBit(PORTC,CHIP_SELECT);

void main() {

InitMain();

DAC_Output(2048); value = 2048;

while (1) {

// When program starts, DAC gives

// the output in the mid-range

// Main loop

if ((Button(&PORTC,0,1,1)==_TRUE) // Test button on B0 (increment)

&& (value < 4095)) { value++ ;

} else {

if ((Button(&PORTC,1,1,1)==_TRUE)

&& (value > 0)) { value-- ;

}

}

DAC_Output(value);

Delay_ms(100);

// If RB0 is not active then test

// RB1 (decrement)

// Perform output

// Slow down key repeat pace

}

}//~! page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Software UART Library

mikroC for dsPIC provides library which implements software UART. These routines are hardware independent and can be used with any MCU. You can easily communicate with other devices via RS232 protocol – simply use the functions listed below.

Note: This library implements time-based activities, so interrupts need to be disabled when using Soft UART.

Library Routines

Soft_Uart_Init

Soft_Uart_Read

Soft_Uart_Write

Soft_Uart_Init

Prototype

Description

void Soft_Uart_Init(unsigned short *port, unsigned short rx,

unsigned short tx, unsigned short baud_rate, unsigned short inverted);

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 dsPIC’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

Soft_Uart_Init(&PORTB, 1, 2, 9600, 0); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Soft_Uart_Read

Prototype

Returns

Description

Requires

unsigned short Soft_Uart_Read(unsigned short *received);

Returns a received byte.

Function receives a byte via software UART. Parameter received will be not-zero if the transfer was successful. This is a non-blocking function call, so you should test the received manually (check the example below).

Soft UART must be initialized and communication established before using this function. See

Soft_Uart_Init

.

Example

unsigned short data, rec;

...

do

data = Soft_Uart_Read(rec);

while (!*rec);

/* Now we can work with data: */

if (data) {...}

Soft_Uart_Write

Prototype

Description

Requires

Example

void Soft_Uart_Write(unsigned short data);

Function transmits a byte (data) via UART.

Soft UART must be initialized and communication established before using this function. 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.

unsigned short some_byte = 0x0A;

...

Soft_Uart_Write(some_byte); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The example demonstrates simple data exchange via software UART. When dsPIC

MCU receives data, it immediately sends the same data back. If dsPIC is connected to the PC (see the figure below), you can test the example from mikroC terminal for RS232 communication, menu choice Tools › Terminal.

unsigned short data = 0, ro = 0;

unsigned short *rec;

void main() {

// Init (8 bit, 2400 baud rate, no parity bit..)

Soft_Uart_Init(&PORTB, 1, 2, 2400, 0);

do {

do { data = Soft_Uart_Read(rec); // Receive data

}

while (!*rec);

Soft_Uart_Write(data); // Send data via UART

} while (1);

}//~!

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Sound Library

mikroC for dsPIC provides a Sound Library which allows you to use sound signalization in your applications. You need a simple piezo speaker (or other hardware) on designated port.

Library Routines

Sound_Init

Sound_Play

Sound_Init

Prototype

Description

void Sound_Init(unsigned short *port, unsigned short pin);

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 on RB2

Sound_Play

Prototype

Description

void Sound_Play(unsigned short period_div_10, unsigned num_of_periods);

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

Example

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 before using this function.

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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

int adcValue;

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 frequencies 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).

void main() {

PORTB = 0x0000;

TRISB = 0xFFFF; //all inputs

ADPCFG = 0; //all analog

TRISF.F3 = 0;

Sound_Init(&PORTD, 0);

}

while (1) { adcValue = ADC_Read(2);

// Play in loop:

// Get lower byte from ADC

Sound_Play(adcValue, 200);

// Play the sound

}

Hardware Connection

PIEZO

SPEAKER

RB4

RB5

RB6

RB7

VCC

VCC

8

9

7

8

RB0

RB1

RB2

RB3

RB4

RB5

RB6

RB7

11

12

13

14

VCC

GND

OSC1

OSC2

RD0

34

10 Mhz

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

SPI Library

SPI module is available on all dsPIC MCU models. Some dsPICs have one SPI module, while others have two. They are named SPI1 and SPI2. mikroC provides a library for initializing Slave mode and comfortable work with Master mode.

dsPIC can easily communicate with other devices via SPI: A/D converters, D/A converters, MAX7219, LTC1290, etc.

Library Routines

Spi1_Init

Spi1_Init_Advanced

Spi1_Read

Spi1_Write

Spi2_Init

Spi2_Init_Advanced

Spi2_Read

Spi2_Write

Spi1_Init

Prototype

Description

Requires

Example

void Spi1_Init(void);

Configures and initializes SPI with default settings.

Spi1_Init_Advanced or

Spi1_Init needs to be called before using other functions from SPI Library.

Default settings are: Master mode, clock Fosc/64, clock idle state low, data transmitted on low to high edge, and input data sampled at the middle of interval.

For custom configuration, use

Spi1_Init_Advanced

.

Note:

Spi1_Init() and

Spi1_Init_Advanced() functions prepare only the appropriate SPI module 1 for operation. It is user's responsibility to set up TRIS register values accordingly: '1' for the SDI line, and '0' for the SDO and SCK lines.

All dsPIC MCUs have at least one SPI module.

Spi1_Init(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Spi1_Init_Advanced

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Spi1_Init_Advanced(unsigned int master_mode, unsigned int mode16, unsigned int sec_prescaler, unsigned int pri_prescaler,

unsigned int slave_select, unsigned int data_sample, unsigned int clock_idle,

unsigned intedge);

Configures and initializes SPI.

Spi1_Init_Advanced or

SPI1_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 interva l

Parameter clock_idle determines idle state for clock; can have the following values:

CLK_IDLE_HIGH

CLK_IDLE_LOW

// Clock idle HIGH

// Clock idle LOW

Parameter transmit_edge can have the following values:

LOW_2_HIGH

HIGH_2_LOW

// Data transmit on low to high edge

// Data transmit on high to low edge

Requires

Example

You need dsPIC MCU with hardware integrated SPI.

This will set SPI to Master Mode, data length is 16-bit, clock = Fcy (no clock scaling), data sampled at the middle of interval, clock IDLE state high and data transmitted at low to high clock edge:

Spi1_Init_Advanced(_SPI_MASTER, _SPI_16_BIT, _SPI_PRESCALE_PRI_1,

_SPI_PRESCALE_SEC_1, _SPI_SS_DISABLE, _SPI_DATA_SAMPLE_MIDDLE,

_SPI_CLK_IDLE_HIGH, _SPI_ACTIVE_2_IDLE); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Spi1_Read

Prototype

unsigned int Spi1_Read(unsigned short buffer);

Returns

Returns the received data.

Description

Requires

Example

Provides clock by sending buffer and receives data at the end of period.

You need dsPIC MCU with hardware integrated SPI.

SPI must be initialized and communication established before using this function. See

Spi1_Init_Advanced or

Spi1_Init

.

short take, buffer;

...

take = Spi1_Read(buffer);

Spi1_Write

Prototype

void Spi1_Write(unsigned short data);

Description

Requires

Example

Writes byte data to SPI1BUF(SPI1TBF), and immediately starts the transmission.

You need dsPIC MCU with hardware integrated SPI.

SPI must be initialized and communication established before using this function. See

Spi1_Init_Advanced or

Spi1_Init

.

Spi1_Write(1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Spi2_Init

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Spi2_Init(void);

Prototype

Description

Requires

Example

Configures and initializes SPI with default settings.

Spi2_Init_Advanced or

Spi2_Init needs to be called before using other functions from SPI Library.

Default settings are: Master mode, clock Fosc/64, clock idle state low, data transmitted on low to high edge, and input data sampled at the middle of interval.

For custom configuration, use

Spi2_Init_Advanced

.

Note:

Spi2_Init() and

Spi2_Init_Advanced() functions prepare only the appropriate SPI module 1 for operation. It is user's responsibility to set up TRIS register values accordingly: '1' for the SDI line, and '0' for the SDO and SCK lines.

All dsPIC MCUs have at least one SPI module.

Spi2_Init();

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Spi2_Init_Advanced

Prototype

Description

void Spi2_Init_Advanced(unsigned int master_mode, unsigned int mode16, unsigned int sec_prescaler, unsigned int pri_prescaler,

unsigned int slave_select, unsigned int data_sample, unsigned int clock_idle,

unsigned intedge);

Configures and initializes SPI.

Spi2_Init_Advanced or

SPI2_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 interva l

Parameter clock_idle determines idle state for clock; can have the following values:

CLK_IDLE_HIGH

CLK_IDLE_LOW

// Clock idle HIGH

// Clock idle LOW

Parameter transmit_edge can have the following values:

LOW_2_HIGH

HIGH_2_LOW

// Data transmit on low to high edge

// Data transmit on high to low edge

Requires

Example

You need dsPIC MCU with hardware integrated SPI.

This will set SPI to Master Mode, data length is 16-bit, clock = Fcy (no clock scaling), data sampled at the middle of interval, clock IDLE state high and data transmitted at low to high clock edge:

Spi2_Init_Advanced(_SPI_MASTER, _SPI_16_BIT, _SPI_PRESCALE_PRI_1,

_SPI_PRESCALE_SEC_1, _SPI_SS_DISABLE, _SPI_DATA_SAMPLE_MIDDLE,

_SPI_CLK_IDLE_HIGH, _SPI_ACTIVE_2_IDLE); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Spi2_Read

Prototype

unsigned int Spi2_Read(unsigned short buffer);

Returns

Requires

Example

Returns the received data.

Description

Requires

Example

Provides clock by sending buffer and receives data at the end of period.

You need dsPIC MCU with hardware integrated SPI.

SPI must be initialized and communication established before using this function. See

Spi2_Init_Advanced or

Spi2_Init

.

short take, buffer;

...

take = Spi2_Read(buffer);

Spi2_Write

Prototype

void Spi2_Write(unsigned short data);

Description

Writes byte data to SPI2BUF(SPI2TBF), and immediately starts the transmission.

You need dsPIC MCU with hardware integrated SPI.

SPI must be initialized and communication established before using this function. See

Spi2_Init_Advanced or

Spi2_Init

.

Spi2_Write(1);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The code demonstrates how to use SPI library functions. Assumed HW configuration is: max7219 (chip select pin) connected to RE5, and SDO, SDI, SCK pins are connected to corresponding pins of max7219.

int main() {

Spi1_Init();

CS_MAX7219 = 1;

TRISFbits.TRISF5 = 0; // PORTE.F5 => _CS_

Max7219_Init1(); // initialize max7219

Delay_ms(200);

for (j = 20; j >=8; j--) {

for (i = 1; i <= 8; i++) {

}

}//~!

Max7219_Write(i, j-i);

}

Delay_ms(2000); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

UART Library

UART hardware module is available with a number of dsPICmicros. mikroC for dsPIC UART 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 dsPIC MCU with hardware integrated UART, for example dsPIC30F4013. Then, simply use the functions listed below.

Note: UART library functions support module on PORTC and PORTF, and will not work with modules on other ports. Examples for dsPICmicros with module on other ports can be found in “Examples” in mikroC for dsPIC installation folder.

Library Routines

Uart1_Init

Uart1_Data_Ready

Uart1_Read

Uart1_Write

Uart2_Init

Uart2_Data_Ready

Uart2_Read

Uart2_Write

Uart1_Init

Prototype

Description

Requires

Example

void Uart1_Init(const unsigned long baud_rate);

Initializes hardware UART module 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.

Uart1_Init needs to be called before using other functions from UART Library.

This will initialize hardware UART and establish the communication at 2400 bps:

Uart1_Init(2400); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Uart1_Data_Ready

unsigned int Uart1_Data_Ready(void);

Prototype

Returns

Description

Requires

Example

Function returns 1 if data is ready or 0 if there is no data.

Use the function to test if data is ready for transmission.

UART HW module must be initialized and communication established before using this function. See

UART1_Init

.

int

receive;

...

if (Uart1_Data_Ready()) receive = Uart1_Read();

Uart1_Read

Prototype

Returns

Description

unsigned int Uart1_Read(void);

Returns the received byte. If byte is not received, returns 0.

Function receives a byte via UART. Use the function

UART1_Data_Ready to test if data is ready first.

Requires

UART HW module must be initialized and communication established before using this function. See

UART1_Init

.

Example

int receive;

...

if (Uart1_Data_Ready()) receive = Uart1_Read(); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Uart1_Write

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Uart1_Write(unsigned short data);

Prototype

Description

Requires

Example

Function transmits a byte (data) via UART.

UART HW module must be initialized and communication established before using this function. See

UART1_Init

.

int chunk = 0x1E;

...

Uart1_Write(chunk); /* send chunk via UART */

Uart2_Init

Prototype

Description

Requires

Example

void Uart2_Init(const unsigned long baud_rate);

Initializes hardware UART module 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.

Uart2_Init needs to be called before using other functions from UART Library.

This will initialize hardware UART and establish the communication at 2400 bps:

Uart2_Init(2400);

Uart2_Data_Ready

Prototype

unsigned int Uart2_Data_Ready(void);

Returns

Description

Requires

Example

Function returns 1 if data is ready or 0 if there is no data.

Use the function to test if data is ready for transmission.

UART HW module must be initialized and communication established before using this function. See

UART2_Init

.

int receive;

...

if (Uart2_Data_Ready()) receive = Uart1_Read(); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Uart2_Read

unsigned int Uart2_Read(void);

Prototype

Returns

Description

Returns the received byte. If byte is not received, returns 0.

Function receives a byte via UART. Use the function

UART2_Data_Ready to test if data is ready first.

Requires

Example

UART HW module must be initialized and communication established before using this function. See

UART2_Init

.

int receive;

...

if (Uart2_Data_Ready()) receive = Uart2_Read();

Uart2_Write

Prototype

Description

Requires

Example

void Uart2_Write(unsigned short data);

Function transmits a byte (data) via UART.

UART HW module must be initialized and communication established before using this function. See

UART2_Init

.

int chunk = 0x1E;

...

Uart2_Write(chunk); /* send chunk via UART */ page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The example demonstrates simple data exchange via UART. When dsPIC MCU receives data, it immediately sends the incremented data back. If dsPIC is connected to the PC (see the figure below), you can test the example from mikroC terminal for RS232 communication, menu choice Tools › Terminal.

unsigned rx1;

unsigned char uc1;

void main() {

Uart1_Init(19200);

U1MODEbits.ALTIO = 1; delay_ms(200);

Uart1_Write_Char('a');

while(1) {

}

}

}//~!

if (Uart1_Data_Ready()) { rx1 = Uart1_Read_Char();

Uart1_Write_Char(++rx1);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Hardware Connection

mikroC for dsPIC making it simple...

page

PC

RS-232

CON

1

6 9

5

CN3

SUB-D 9p

CONNECT

MCU TO PC

Receive data (Rx)

SERIAL

CABLE

RS-232

CON

VCC

C18

100nF

1

6 9

5

CONNECT

PC TO MCU

CN3

SUB-D 9p

Send

Data (Tx)

E9

10uF

E10

10uF

10

1

3

6

15

13

8

11

U6

R1 IN

R2 IN

T1 IN

T2 IN

C1+

C1-

V-

GND

R1 OUT

R2 OUT

T1 OUT

T2 OUT

C2+

C2-

V+

VCC

5

2

7

4

16

12

9

14

VCC

E11

10uF

E12

10uF

Rx

Tx

VCC

10 Mhz

11

12

13

14

VCC

GND

OSC1

OSC2

RF2

RF3

26

25

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

DSP (Digital Signal Processing) Library

mikroC includes a libraries for DSP engine.

Library Routines

FIR_Radix

IIR_Radix

FFT

BitReverseComplex

Vector_Set

VectorPower

Vector_Subtract

VectorScale

Vector_Negate

Vector_Multiply

Vector_Min

Vector_Max

Vector_Dot

Vector_Correlate

Vector_Convolve

Vector_Add

Matrix_Transponse

Matrix_Subtract

Matrix_Scale

Matrix_Multiply

Matrix_Add

FIR_Radix

Prototype

Description

Returns

unsigned FIR_Radix(unsigned FilterOrder, const unsigned

*ptrCoeffs, unsigned BuffLength, unsigned *ptrInput, unsigned

Index);

This function applies FIR filter to ptrInput. Input samples must be in Y data space.

FilterOrder is order of the filter + 1.

ptrCoeffs is address of filter coeffitients in program memory.

BuffLength represents number of samples ptrInput points to.

ptrInput is address of input samples.

Index index of current sample.

sum(k=0..N-1)(coef[k]*input[N-k]) - Current sample of processed signal(B[n])

N - buffer length k - Current index page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

IIR_Radix

Prototype

Description

Returns

unsigned FIR_Radix(unsigned FilterOrder, const unsigned

*ptrCoeffs,

unsigned BuffLength, unsigned *ptrInput, unsigned

Index);

This function applies IIR filter to ptrInput. Input and output samples must be in Y data space.

AScale A Scale factor

BScale B Scale factor

ptrB Address of B coefficients (In program memory)

ptrA Address of A coefficients (In program memory)

FilterOrder is order of the filter + 1.

ptrInput is address of input samples. Input_Len represents number of samples ptrInput points to.

ptrOutput is address of output samples. Output length is equal to Input length.

Index index of current sample.

y[n]=sum(k=0..N)(Acoef[k]*x[n-k]) - sum(k=1..M)(Bcoef[k]*y[n-k])

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

FFT

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Fft(unsigned log2N, const unsigned *TwiddleFactorsAddress,

unsigned *Samples);

Function applies FFT transformation to input samples, input samples must be in Y data space.

N - buffer length (must be the power of 2).

TwiddleFactorsAddress is address of costant array which contains complex twiddle factors.The array is expected to be in program memory.

Samples - array of input samples.

Upon completion complex array of FFT samples is placed in the Samples parameter.

Operation

Note

F(k) = 1/N*sum_n (f(n)*WN(kn)), WN(kn) = exp[-(j*2*pi*k*n)/N]

Fn - array of complex input samples n in {0, 1,... , N-1}, and k in {0, 1,... , N-1}, with N = 2^m, m element of Z.

WN - TwiddleFactors

The amplitude of current FFT sample is calculated as:

F[k]=sqrt(Re[k]^2+ Im[k]^2)

Complex array of FFT samples is placed in Samples parameter. Input Samples are arranged in manner Re,Im,Re,Im... (where Im is always zero). Output samples are arranged in the same manner but Im parts are different from zero. Output samples are symmetrical (First half of output samples (index from 0 to N/2) is identical as second half of output samples(index from N/2 to N).

Input data is a complex vector such that the magnitude of the real and imaginary parts of each of its elements is less than 0.5. If greater or equal to this value the results could produce saturation. Note that the output values are scaled by a factor of 1/N, with N the length of the FFT. input is expected in natural ordering, while output is produced in bit reverse ordering.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

BitReverseComplex

Prototype

void Vector_Set(unsigned *input, unsigned size, unsigned value);

Description

This function does Complex (in-place) Bit Reverse re-organization.

N - buffer length (must be the power of 2).

ReIm - Output Sample(from FFT).

Operation

Note f(k) = 1/N*sum_n (F(n)*WN(kn)), WN(kn) = exp[(j*2*pi*k*n)/N]

Fn - array of complex input samples n in {0, 1,... , N-1}, and k in {0, 1,... , N-1}, with N = 2^m, m element of Z.

WN - TwiddleFactors

Input samples must be in Y data space.

Vector_Set

Prototype

Description

void Vector_Set(unsigned *input, unsigned size, unsigned value);

Sets size elements of input to value, starting from the first element.

Size must be > 0. Length of input is limited by available ram.

VectorPower

Prototype

Description

unsigned VectorPower(unsigned N, unsigned *Vector);

Function returns result of power value (powVal) in radix point 1.15

Operation

Input

Note powVal = sum (srcV[n] * srcV[n]) with n in {0, 1,... , numElems-1}

Input samples must be in Y data space.

AccuA used, not restored

CORCON saved, used, restored page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Vector_Subtract

Prototype

Description

void Vector_Subtract(unsigned *dest, unsigned *v1, unsigned *v2,

unsigned numElems);

This procedure does substraction of two vectors. numElems must be less or equal to minimum size of two vectors.

v1 - First Vector

v2 - Second Vector

dest - Result Vector

Operation

Note dstV[n] = srcV1[n] - srcV2[n]

with n in {0, 1,... , numElems-1}

AccuA used, not restored.

CORCON saved, used, restored.

VectorScale

Prototype

void VectorScale(unsigned N, int ScaleValue, unsigned *SrcVector,

unsigned *DestVector);

Description

This procedure does vector scaling with scale value.

N - Buffer length

SrcVector - original vector

DestVector - scaled vector

ScaleValue - Scale Value

Operation

Note dstV[n] = sclVal * srcV[n],

with n in {0, 1,... , numElems-1}

AccuA used, not restored.

CORCON saved, used, restored page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Vector_Negate

Prototype

void Vector_Negate(unsigned *srcVector, unsigned *DestVector,

unsigned numElems);

Description

This procedure does negation of vector.

srcVector - Original vector

destVector - Result vector

numElems - Number of Elements

Operation

Note dstV[n] = (-1)*srcV1[n] + 0,

0 <= n < numElems

Negate of 0x8000 is 0x7FFF.

AccuA used, not restored.

CORCON saved, used, restored.

Vector_Multiply

Prototype

Description

void Vector_Multiply(unsigned *v1, unsigned *v2, unsigned *dest,

unsigned numElems);

This procedure does multiplication of two vectors.

numElems must be less or equal to minimum size of two vectors.

v1 - First Vector v2 - Second Vector dest - Result Vector

Operation

Note dstV[n] = srcV1[n] * srcV2[n]

with n in {0, 1,... , numElems-1}

AccuA used, not restored.

CORCON saved, used, restored page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Vector_Min

Prototype

Description

unsigned Vector_Min(unsigned *Vector, unsigned numElems, unsigned

*MinIndex);

This function find min. value in vector.

Vector - Original vector.

numElems - Number of elements

MinIndex - Index of minimum value

Operation

Returns minVal = min {srcV[n], n in {0, 1,...numElems-1}

if srcV[i] = srcV[j] = minVal, and i < j, then minIndex = j minimum value (minVal)

Vector_Max

Prototype

Description

unsigned Vector_Max(unsigned *Vector, unsigned numElems, unsigned

*MaxIndex);

This function find max. value in vector.

Vector - Original vector.

numElems - Number of elements

MaxIndex - Index of maximum value

Operation

Returns maxVal = max {srcV[n], n in {0, 1,...numElems-1} }

if srcV[i] = srcV[j] = maxVal, and i < j, then maxIndex = j maximum value (maxVal)

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Vector_Dot

Prototype

unsigned Vector_Dot(unsigned *v1, unsigned *v2, unsigned numElems);

Description

Procedure calculates vector dot product.

v1 - First vector.

v2 - Second vector

numElems - Number of elements

Operation

Note dotVal = sum (srcV1[n] * srcV2[n]),

with n in {0, 1,... , numElems-1}

AccuA used, not restored.

CORCON saved, used, restored.

Vector_Correlate

Prototype

void Vector_Correlate(unsigned *v1, unsigned *v2, unsigned *dest,

unsigned numElemsV1, unsigned numElemsV2);

Description

Procedure calculates Vector correlation (using convolution).

v1 - First vector.

v2 - Second vector

numElemsV1 - Number of first vector elements

numElemsV2 - Number of second vector elements

dest - Result vector

Operation r[n] = sum_(k=0:N-1){x[k]*y[k+n]},

where: x[n] defined for 0 <= n < N, y[n] defined for 0 <= n < M, (M <= N), r[n] defined for 0 <= n < N+M-1.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Vector_Convolve

Prototype

void Vector_Convolve(unsigned *v1, unsigned *v2, unsigned *dest,

unsigned numElemsV1, unsigned numElemsV2);

Description

Procedure calculates Vector using convolution.

v1 - First vector.

v2 - Second vector

numElemsV1 - Number of first vector elements

numElemsV2 - Number of second vector elements

dest - Result vector

Operation

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers y[n] = sum_(k=0:n){x[k]*h[n-k]}, 0 <= n < M y[n] = sum_(k=n-M+1:n){x[k]*h[n-k]}, M <= n < N y[n] = sum_(k=n-M+1:N-1){x[k]*h[n-k]}, N <= n < N+M-1

Note

AccuA used, not restored.

CORCON saved, used, restored.

Vector_Add

Prototype

void Vector_Add(unsigned *dest, unsigned *v1, unsigned *v2,

unsigned numElems);

Description

Procedure calculates vector addition.

v1 - First vector.

v2 - Second vector

numElemsV1 - Number of vector elements

dest - Result vector

Operation

Note

dstV[n] = srcV1[n] + srcV2[n], with n in {0, 1,... , numElems-1}

AccuA used, not restored.

CORCON saved, used, restored.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Matrix_Transponse

Prototype

void Matrix_Transpose(unsigned * src, unsigned * dest, unsigned num_rows,

unsigned num_cols);

Description

Procedure does matrix transposition.

src - Original matrix.

dest - Result matrix

numRows - Number of matrix rows

numCols - Number of matrix columns

Operation dstM[i][j] = srcM[j][i]

Matrix_Subtract

Prototype

void Matrix_Subtract(unsigned * src1, unsigned * src2, unsigned * dest, unsigned num_rows, unsigned num_cols);

Description

Procedure does matrix substraction.

src1 - First matrix.

src2 - Second matrix

dest - Result matrix

numRows - Number of matrix rows

numCols - Number of matrix columns

Operation

Note dstM[i][j] = srcM1[i][j] - srcM2[i][j]

AccuA used, not restored.

AccuB used, not restored.

CORCON saved, used, restored. page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Matrix_Scale

Prototype

void Matrix_Scale(unsigned scale_value, unsigned *src1, unsigned

*dest,

unsigned num_rows, unsigned num_cols);

Description

Procedure does matrix scale.

ScaleValue - Scale Value

src1 - Original matrix

dest - Result matrix

numRows - Number of matrix rows

numCols - Number of matrix columns

Operation

Note dstM[i][j] = srcM[j][i]

AccuA used, not restored.

CORCON saved, used, restored.

Matrix_Multiply

Prototype

Description

void Matrix_Multiply(unsigned * src1, unsigned * src2, unsigned * dest, unsigned numRows1, unsigned numCols2, unsigned numCols1Rows2);

Procedure does matrix multiply.

src1 - First Matrix

src2 - Second Matrix

dest - Result Matrix

numRows1 - Number of first matrix rows

numCols2 - Number of second matrix columns

numCols1Rows2 - Number of first matrix columns and second matrix rows

Operation

Note

dstM[i][j] = sum_k(srcM1[i][k]*srcM2[k][j]), with i in {0, 1, ..., numRows1-1} j in {0, 1, ..., numCols2-1} k in {0, 1, ..., numCols1Rows2-1}

AccuA used, not restored.

CORCON saved, used, restored. page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Matrix_Add

Prototype

void Matrix_Add(unsigned * src1, unsigned * src2, unsigned * dest,

unsigned numRows, unsigned numCols);

Description

Procedure does matrix addition.

src1 - First Matrix

src2 - Second Matrix

dest - Result Matrix

numRows1 - Number of first matrix rows

numCols2 - Number of second matrix columns

Operation

Note dstM[i][j] = srcM1[i][j] + srcM2[i][j]

AccuA used, not restored.

CORCON saved, used, restored. page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Util Library

Util library contains miscellaneous routines useful for project development.

Button

Prototype

Returns

Description

Example

unsigned short Button(unsigned short *port, unsigned short pin,

unsigned short time, unsigned short active_state);

Returns 0 or 255.

Function eliminates the influence of contact flickering upon pressing a button (debouncing).

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 milliseconds; parameter active_state can be either 0 or 1, and it determines if the button is active upon logical zero or logical one.

Example reads RB0, to which the button is connected; on transition from 1 to 0 (release of button), PORTD is inverted:

do {

if (Button(&PORTB, 0, 1, 1)) oldstate = 1;

if (oldstate && Button(&PORTB, 0, 1, 0)) {

PORTD = ~PORTD; oldstate = 0;

}

} while(1);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PrintOut

Description:

void PrintOut(void (*prntoutfunc)(char ch), const char * f,...);

Function formats a series of strings and numeric values and stores the resulting string in appropriate PrintHandler.

The fmtstr argument is a format string and may be composed of characters, escape sequences, and format specifications. Ordinary characters and escape sequences are copied to the

PrintHandler in the order in which they are interpreted. Format specifications always begin with a percent sign (%) and require additional arguments to be included in the function call.

The format string is read from left to right. The first format specification encountered references the first argument after fmtstr and converts and outputs it using the format specification. The second format specification accesses the second argument after fmtstr, and so on. If there are more arguments than format specifications, the extra arguments are ignored. Results are unpredictable if there are not enough arguments for the format specifications. Format specifications have the following format:

% [flags] [width] [.precision] [{ h | l | L }] conversion_type

Each field in the format specification can be a single character or a number which specifies a particular format option. The conversion_type field is where a single character specifies that the argument is interpreted as a character, a string, a number, or a pointer, as shown in the following table.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers p

% c s

E g

X e u o d

Conversion Type

int

Argument Type

unsigned int unsigned int x unsigned int double double double double int char * void * none

Output Format

Signed decimal number

Unsigned decimal number

Unsigned octal number

Unsigned hexadecimal number using

0123456789ABCEDF

Floating-point number using the format [-

]dddd.dddd

Floating-point number using the format [-

]d.dddde[-]dd

Floating-point number using the format [-

]d.ddddE[-]dd

Floating-point number using either e or f format, whichever is more compact for the specified value and precision

The int is converted to an unsigned char, and the resulting character is written

String with a terminating null character

Pointer value, the X format is used

A % is written. No argument is converted. The complete conversion specification shall be

%%.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

The flags field is where a single character is used to justify the output and to print

+/- signs and blanks, decimal points, and octal and hexadecimal prefixes, as shown in the following table.

Flags

Meaning

-

+

Left justify the output in the specified field width.

Prefix the output value with a + or - sign if the output is a signed type.

space (' ') Prefix the output value with a blank if it is a signed positive value.

Otherwise, no blank is prefixed

# Prefixes a non-zero output value with 0, 0x, or 0X when used with o, x, and X field types, respectively. When used with the e, E, f, g, and G field types, the # flag forces the output value to include a decimal point.

The # flag is ignored in all other cases.

* Ignore format specifier.

The width field is a non-negative number that specifies the minimum number of characters printed. If the number of characters in the output value is less than width, blanks are added on the left or right (when the - flag is specified) to pad to the minimum width. If width is prefixed with a 0, zeros are padded instead of blanks. The width field never truncates a field. If the length of the output value exceeds the specified width, all characters are output.

The precision field is a non-negative number that specifies the number of characters to print, the number of significant digits, or the number of decimal places. The precision field can cause truncation or rounding of the output value in the case of a floating-point number as specified in the following table.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flags

Meaning of precision field

d, u, o, x, X The precision field is where you specify the minimum number of digits that will be included in the output value. Digits are not truncated if the number of digits in the argument exceeds that defined in the precision field. If the number of digits in the argument is less than the precision field, the output value is padded on the left with zeros.

f The precision field is where you specify the number of digits to the right of the decimal point. The last digit is rounded.

e, E The precision field is where you specify the number of digits to the right of the decimal point. The last digit is rounded.

g c, C

The precision field is where you specify the maximum number of significant digits in the output value.

The precision field has no effect on these field types.

s The precision field is where you specify the maximum number of characters in the output value. Excess characters are not output.

The optional characters h and l or L may immediately precede the conversion_type to respectively specify short or long versions of the integer types d, i, u, o, x, and

X.

You must ensure that the argument type matches that of the format specification.

You can use type casts to ensure that the proper type is passed to printout.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PrintOut Example

void PrintHandler(char c){

Uart1_Write_Char(c);

}

void main(){

Uart1_Init(9600);

Delay_ms(100);

PrintOut(PrintHandler, "/*\r\n"

" * Project name:\r\n"

" PrintOutExample (Sample usage of PrintOut() function)\r\n"

" * Copyright:\r\n"

" (c) MikroElektronika, 2006.\r\n"

" * Revision History:\r\n"

" 20060710:\r\n"

" - Initial release\r\n"

" * Description:\r\n"

" Simple demonstration on usage of the PrintOut() function\r\n"

" * Test configuration:\r\n"

" MCU: dsPIC30F4013\r\n"

" Dev.Board: EASYdsPIC2\r\n"

" Oscillator: EC, %6.3fMHz\r\n"

" Ext. Modules: None.\r\n"

" SW: mikroC for dsPIC v2.0.0.0.\r\n"

" * NOTES:\r\n"

" None.\r\n"

" */\r\n", Get_Fosc_kHz()/1000.);

} page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ANSI C Ctype Library

mikroC for dsPIC provides a set of standard ANSI C library functions for testing and mapping characters.

Note: Not all of the standard functions have been included.

Note: Functions have been implemented according to the ANSI C standard, but certain functions have been modified in order to facilitate dsPIC programming. Be sure to at least skim through the description before using standard C functions.

Library Routines

isalnum isalpha iscntrl isdigit isgraph islower ispunct isspace isupper isxdigit toupper tolower

isalnum

Prototype

Description

unsigned int isalnum(unsigned int character);

Function returns 1 if the character is alphanumeric (A-Z, a-z, 0-9), otherwise returns zero.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

isalpha

unsigned int isalpha(unsigned int character);

Prototype

Description

Function returns 1 if the character is alphabetic (A-Z, a-z), otherwise returns zero.

iscntrl

Prototype

Description

unsigned int iscntrl(unsigned int character);

Function returns 1 if the character is a control character or delete (decimal 0-31 and

127), otherwise returns zero.

isdigit

Prototype

Description

unsigned int isdigit(unsigned int character);

Function returns 1 if the character is a digit (0-9), otherwise returns zero.

isgraph

Prototype

Description

unsigned int isgraph(unsigned int character);

Function returns 1 if the character is a printable character, excluding the space (decimal 32), otherwise returns zero.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

islower

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned int islower(unsigned int character);

Prototype

Description

Function returns 1 if the character is a lowercase letter (a-z), otherwise returns zero.

ispunct

Prototype

Description

unsigned int ispunct(unsigned int character);

Function returns 1 if the character is punctuation (decimal 32-47, 58-63, 91-96, 123-

126), otherwise returns zero.

isspace

Prototype

Description

unsigned int isspace(unsigned int character);

Function returns 1 if the character is white space (space, CR, HT, VT, NL, FF), otherwise returns zero.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

isupper

unsigned int isupper(unsigned int character);

Prototype

Description

Function returns 1 if the character is an uppercase letter (A-Z), otherwise returns 0.

isxdigit

Prototype

Description

unsigned int isxdigit(unsigned int character);

Function returns 1 if the character is a hex digit (0-9, A-F, a-f), otherwise returns zero.

toupper

Prototype

Description

unsigned int toupper(unsigned int character);

If the character is a lowercase letter (a-z), function returns an uppercase letter.

Otherwise, function returns an unchanged input parameter.

tolower

Prototype

Description

unsigned int tolower(unsigned int character);

If the character is an uppercase letter (A-Z), function returns a lowercase letter.

Otherwise, function returns an unchanged input parameter.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ANSI C Math Library

mikroC provides a set of standard ANSI C library functions for floating point math handling.

Note: Not all of the standard functions have been included.

Note: Functions have been implemented according to the ANSI C standard, but certain functions have been modified in order to facilitate PIC programming. Be sure to at least skim through the description before using standard C functions.

Library Routines

acos asin atan atan2 ceil cos cosh exp fabs floor frexp ldexp log log10 modf pow sin sinh sqrt tan tanh

acos

Prototype

Description

double acos(double x);

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).

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

asin

double asin(double x);

Prototype

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

Description

double atan(double x);

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

Description

double atan2(double y, double x);

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).

ceil

Prototype

Description

double ceil(double num);

Function returns value of parameter num rounded up to the next whole number.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

cos

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

double cos(double x);

Prototype

Description

Function returns the cosine of x in radians. The return value is from -1 to 1.

cosh

Prototype

Description

double cosh(double x);

Function returns the hyperbolic cosine of x

, defined mathematically as

(e x

+e

-x

)/2

. If the value of x is too large (if overflow occurs), the function fails.

exp

Prototype

Description

double exp(double x);

Function returns the value of e

— the base of natural logarithms — raised to the power of x

(i.e. e x

).

fabs

Prototype

Description

double fabs(double num);

Function returns the absolute (i.e. positive) value of num

.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

floor

double floor(double num);

Prototype

Description

Function returns value of parameter num rounded down to the nearest integer.

frexp

Prototype

Description

double frexp(double num, int *n);

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

Description

double ldexp(double num, int n);

Function returns the result of multiplying the floating-point number num by 2 raised to the power exp

(i.e. returns x*2 n

).

log

Prototype

Description

double log(double x);

Function returns the natural logarithm of x

(i.e. log e

(x)

).

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

log10

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

double log10(double x);

Prototype

Description

Function returns the base-10 logarithm of x

(i.e. log

10

(x)

).

modf

Prototype

Description

double modf(double num, double *whole);

Function returns the signed fractional component of num

, placing its whole number component into the variable pointed to by whole

.

pow

Prototype

Description

double pow(double x, double y);

Function returns the value of x raised to the power of y (i.e. x y

). If the x is negative, function will automatically cast the y into unsigned long

.

sin

Prototype

Description

double sin(double x);

Function returns the sine of x in radians. The return value is from -1 to 1.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

sinh

double sinh(double x);

Prototype

Description

Function returns the hyperbolic sine of x

, defined mathematically as

(e x

-e

-x

)/2

. If the value of x is too large (if overflow occurs), the function fails.

sqrt

Prototype

Description

double sqrt(double num);

Function returns the non negative square root of num

.

tan

Prototype

Description

double tan(double x);

Function returns the tangent of x in radians. The return value spans the allowed range of floating point in mikroC.

tanh

Prototype

Description

double tanh(double x);

Function returns the hyperbolic tangent of x

, defined mathematically as sinh(x)/cosh(x)

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ANSI C Stdlib Library

mikroC provides a set of standard ANSI C library functions of general utility.

Note: Not all of the standard functions have been included.

Note: Functions have been implemented according to the ANSI C standard, but certain functions have been modified in order to facilitate PIC programming. Be sure to at least skim through the description before using standard C functions.

Library Routines

abs atof atoi atol div ldiv labs max min rand srand xtoi

abs

Prototype

Description

atof

Prototype

Description

int abs(int num);

Function returns the absolute (i.e. positive) value of num

.

double atof(char *s)

Function converts the input string s into a double precision value, and returns the value.

Input string s should conform to the floating point literal format, with an optional whitespace at the beginning. The string will be processed one character at a time, until the function reaches a character which it doesn’t recognize (this includes a null character).

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

atoi

int atoi(char *s);

Prototype

Description

Function converts the input string s into an integer value, and returns the value. Input string s should consist exclusively of decimal digits, with an optional whitespace and a sign at the beginning. The string will be processed one character at a time, until the function reaches a character which it doesn’t recognize (this includes a null character).

atol

Prototype

Description

long atol(char *s)

Function converts the input string s into a long integer value, and returns the value.

Input string s should consist exclusively of decimal digits, with an optional whitespace and a sign at the beginning. The string will be processed one character at a time, until the function reaches a character which it doesn’t recognize (this includes a null character).

div

Prototype

Description

div_t div( int numer, int denom);

Function computes the result of the division of the numerator numer by the denominator denom

; function returns a structure of type div_t comprising quotient ( quot

) and remainder ( rem

).

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

ldiv

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers ldiv_t ldiv( long numer, long denom);

Prototype

Description

Function is similar to the div function, except that the arguments and the result structure members all have type long

.

Function computes the result of the division of the numerator numer by the denominator denom

; function returns a structure of type div_t comprising quotient ( quot

) and remainder ( rem

).

labs

Prototype

Description

long labs(long num);

Function returns the absolute (i.e. positive) value of a long integer num

.

max

Prototype

Description

int max(int a, int b);

Function returns greater of the two integers, a and b

.

min

Prototype

Description

int min(int a, int b);

Function returns lower of the two integers, a and b

.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

rand

int rand(void);

Prototype

Description

Function returns a sequence of pseudo-random numbers between 0 and 32767. Function will always produce the same sequence of numbers unless srand() is called to seed the starting point.

srand

Prototype

Description

void srand(unsigned seed);

Function uses the seed as a starting point for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand()

. No values are returned by this function.

xtoi

Prototype

Description

unsigned xtoi(register char *s);

Function converts the input string s consisting of hexadecimal digits into an integer value. Input parametes s should consist exclusively of hexadecimal digits, with an optional whitespace and a sign at the beginning. The string will be processed one character at a time, until the function reaches a character which it doesn’t recognize (this includes a null character).

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ANSI C String Library

mikroC provides a set of standard ANSI C library functions useful for manipulating strings and arrays of char.

Note: Not all of the standard functions have been included.

Note: Functions have been implemented according to the ANSI C standard, but certain functions have been modified in order to facilitate PIC programming. Be sure to at least skim through the description before using standard C functions.

Library Routines

memcmp memcpy memmove memset strcat strchr strcmp strcpy strlen strncat strncpy strspn strncmp memchr strstr strcspn strpbrk strrchr

memcmp

Prototype

Description

int *memcmp(void *s1, void *s2, int n);

Function compares the first n characters of objects pointed to by s1 and s2

, and returns zero if the objects are equal, or returns a difference between the first differing characters

(in a left-to-right evaluation). Accordingly, the result is greater than zero if the object pointed to by s1 is greater than the object pointed to by s2

, and vice versa.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

memcpy

void *memcpy(void *s1, void *s2, int n);

Prototype

Description

Function copies n characters from the object pointed to by s2 into the object pointed to by s1

. Objects may not overlap. Function returns the value of s1

.

memmove

Prototype

Description

void *memmove(void *s1, void *s2, register int n);

Function copies n characters from the object pointed to by s2 into the object pointed to by s1

. Unlike with memcpy()

, memory areas s1 and s2 may overlap. Function returns the value of s1

.

memset

Prototype

Description

void *memset(void *s, char c, int n)

Function copies the value of character c

(converted to char

) into each of the first n characters of the object pointed by s

. Function returns the value of s

.

strcat

Prototype

Description

char *strcat(char *s1, char *s2);

Function appends the string s2 to the string s1

, overwriting the null character at the end of s1

. Then, a terminating null character is added to the result. Strings may not overlap, and s1 must have enough space to store the result. Function returns a resulting string s1

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

strchr

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

char *strchr(char *s, unsigned int c);

Prototype

Description

Function locates the first occurrence of character c in the string s

. Function returns a pointer to the c

, or a null pointer if c does not occur in s

. The terminating null character is considered to be a part of the string.

strcmp

Prototype

Description

int strcmp(char *s1, char *s2);

Function compares strings s1 and s2

, and returns zero if the strings are equal, or returns a difference between the first differing characters (in a left-to-right evaluation).

Accordingly, the result is greater than zero if s1 is greater than s2

, and vice versa.

strcpy

Prototype

Description

char *strcpy(char *s1, char *s2);

Function copies the string s2 into the string s1

. If successful, function returns s1

. The strings may not overlap.

strlen

Prototype

Description

int strlen(char *s);

Function returns the length of the string s

(the terminating null character does not count against string’s length).

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

strncat

Prototype

char *strncat(char *s1, char *s2, int n);

Description

Function appends not more than n characters from the string s2 to s1

. The initial character of s2 overwrites the null character at the end of s1

. A terminating null character is always appended to the result. Function returns s1

.

strncpy

Prototype

Description

char *strncpy(char *s1, char *s2, int n);

Function copies not more than n characters from string s2 to s1

. The strings may not overlap. If s2 is shorter than n characters, then s1 will be padded out with null characters to make up the difference. Function returns the resulting string s1

.

strspn

Prototype

Description

int strspn(char *s1, char *s2);

Function returns the length of the maximum initial segment of s1 which consists entirely of characters from s2

. The terminating null character character at the end of the string is not compared.

Strncmp

Prototype

Description

int strncmp(char *s1, char *s2, char len);

Function lexicographically compares the first len words 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 words that differ in the strings being compared (within first len words).

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Strstr

Prototype

Description

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

char *strstr(char *s1, char *s2);

Function locates the first occurrence of the string s2 in the string s1

(excluding the terminating 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.

Memchr

Prototype

Description

void memchr(void *p, unsigned int n, unsigned int v);

Function locates the first occurrence of int n in the initial v words of memory area starting at the address p

. Function returns the offset of this occurrence from the memory address p or

$FFFF if the n was not found.

For parameter p you can use either a numerical value (literal/variable/constant) indicating memory address or a dereferenced value of an object, for example

&mystring or

&PORTB

.

Strcspn

Description

char *strcspn(char * s1, char *s2);

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.

Strpbrk

Prototype

Description

char *strpbrk(char * s1, char *s2);

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

.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Strrchr

Prototype

Description

char *strrchr(char * ptr, unsigned int chr);

Function searches the string ptr for the last occurrence of character chr. The null character terminating ptr is not included in the search. Function returns an index of the last chr found in ptr

; if no matching character was found, function returns

$FF

.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Conversions Library

mikroC 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 following routines:

ByteToStr

ShortToStr

WordToStr

IntToStr

LongToStr

LongWordToStr

FloatToStr

Following functions convert decimal values to BCD (Binary Coded Decimal) and vice versa:

Bcd2Dec

Dec2Bcd

Bcd2Dec16

Dec2Bcd16

ByteToStr

Prototype

void ByteToStr(unsigned short number, char *output);

Description

Function creates an output string out of a small unsigned number

(numerical value less than 0x100). Output string has fixed width of 3 characters; remaining positions on the left (if any) are filled with blanks.

Example

unsigned short t = 24;

char txt[3];

//...

ByteToStr(t, txt); // txt is " 24" (one blank here) page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

ShortToStr

void ShortToStr(short number, char *output);

Prototype

Description

Function creates an output string out of a small signed number

(numerical value less than 0x100). Output string has fixed width of 4 characters; remaining positions on the left (if any) are filled with blanks.

Example

short t = -24;

char txt[4];

//...

ByteToStr(t, txt); // txt is " -24" (one blank here)

WordToStr

Prototype

Description

void WordToStr(unsigned number, char *output);

Function creates an output string out of an unsigned number

(numerical value of unsigned type). Output string has fixed width of 5 characters; remaining positions on the left (if any) are filled with blanks.

Example

unsigned t = 437;

char txt[5];

//...

WordToStr(t, txt); // txt is " 437" (two blanks here)

IntToStr

Prototype

Description

void IntToStr(int number, char *output);

Function creates an output string out of a signed number

(numerical value of int type). Output string has fixed width of 6 characters; remaining positions on the left (if any) are filled with blanks.

Example

int j = -4220;

char txt[6];

//...

IntToStr(j, txt); // txt is " -4220" (one blank here) page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

LongToStr

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void LongToStr(long number, char *output);

Prototype

Description

Function creates an output string out of a large signed number

(numerical value of long type). Output string has fixed width of 11 characters; remaining positions on the left (if any) are filled with blanks.

Example

long jj = -3700000;

char txt[11];

//...

LongToStr(jj, txt); // txt is " -3700000" (three blanks here)

LongWordToStr

Prototype

void LongWordToStr(unsigned long input, char *output);

Description

Example

Function creates an output string out of a large unsigned long (numerical value of long type). Output string has fixed width of 11 (10+NULL) characters; remaining positions on the left (if any) are filled with blanks.

unsigned long jj = 3700000;

char txt[11];

//...

LongToStr(jj, txt);

// txt is " 3700000" (three blanks here)

FloatToStr

Prototype

Description

Example

void FloatToStr(float number, char *output);

Function creates an output string out of a floating-point number

. The output string contains a normalized format of the number (mantissa between 0 and 1) with sign at the first position. Mantissa has fixed format of six digits,

0.ddddd

; i.e. there will always be

5 digits following the dot. The output string must be at least 13 characters long.

float ff = -374.2;

char txt[13];

//...

FloatToStr(ff, txt); // txt is "-0.37420e3" page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Bcd2Dec

unsigned short Bcd2Dec(unsigned short bcdnum);

Prototype

Returns

Description

Example

Returns converted decimal value.

Converts 8-bit BCD numeral bcdnum to its decimal equivalent.

unsigned short a;

...

a = Bcd2Dec(0x52); // equals 52 mikroC for dsPIC making it simple...

Dec2Bcd

Prototype

Returns

Description

Example

unsigned short Dec2Bcd(unsigned short decnum);

Returns converted BCD value.

Converts 8-bit decimal value decnum to BCD.

unsigned short a;

...

a = Dec2Bcd(52); // equals 0x52

Bcd2Dec16

Prototype

Returns

Description

Example

unsigned Bcd2Dec16(unsigned bcdnum);

Returns converted decimal value.

Converts 16-bit BCD numeral bcdnum to its decimal equivalent.

unsigned a;

...

a = Bcd2Dec16(1234); // equals 4660 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Dec2Bcd16

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

unsigned Dec2Bcd(unsigned decnum);

Prototype

Returns

Description

Example

Returns converted BCD value.

Converts 16-bit decimal value decnum to BCD.

unsigned a;

...

a = Dec2Bcd16(4660); // equals 1234

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Trigonometry Library

mikroC implements fundamental trigonometry functions. These functions are implemented as lookup tables, and return the result as integer, multiplied by 1000 and rounded up.

Library Routines

SinE3

CosE3

SinE3

Prototype

Returns

Description

int SinE3(unsigned angle_deg);

Function returns the sine of input parameter, multiplied by 1000 (1E3) and rounded up to the nearest integer. The range of return values is from -1000 to 1000.

Function takes parameter angle_deg which represents angle in degrees, and returns its sine multiplied by 1000 and rounded up to the nearest integer. The function is implemented as a lookup table; maximum error obtained is ±1.

Example

res = SinE3(45); // result is 707

CosE3

Prototype

Returns

Description

int CosE3(unsigned angle_deg);

Function returns the cosine of input parameter, multiplied by 1000 (1E3) and rounded up to the nearest integer. The range of return values is from -1000 to 1000.

Function takes parameter angle_deg which represents angle in degrees, and returns its cosine multiplied by 1000 and rounded up to the nearest integer. The function is implemented as a lookup table; maximum error obtained is ±1.

Example

res = CosE3(196); // result is -193 page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Sprint Library

Library for sprint functions.

Note: In addition to ANSI C standard mikroC provides limited versions sprinti, sprintl that take a less ROM,RAM and may be convinient in some cases for dsPIC.

Library Routines

sprintf sprintl sprinti

sprintf

Description:

Function formats a series of strings and numeric values and stores the resulting string in buffer.

The fmtstr argument is a format string and may be composed of characters, escape sequences, and format specifications. Ordinary characters and escape sequences are copied to the buffer in the order in which they are interpreted. Format specifications always begin with a percent sign (%) and require additional arguments to be included in the function call.

The format string is read from left to right. The first format specification encountered references the first argument after fmtstr and converts and outputs it using the format specification. The second format specification accesses the second argument after fmtstr, and so on. If there are more arguments than format specifications, the extra arguments are ignored. Results are unpredictable if there are not enough arguments for the format specifications. Format specifications have the following format:

% [flags] [width] [.precision] [{ h | l | L }] conversion_type

Each field in the format specification can be a single character or a number which specifies a particular format option. The conversion_type field is where a single character specifies that the argument is interpreted as a character, a string, a number, or a pointer, as shown in the following table.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers mikroC for dsPIC making it simple...

p

% c s

E g

X e u o d

Conversion Type

int

Argument Type

unsigned int unsigned int x unsigned int double double double double int char * void * none

Output Format

Signed decimal number

Unsigned decimal number

Unsigned octal number

Unsigned hexadecimal number using

0123456789ABCEDF

Floating-point number using the format [-

]dddd.dddd

Floating-point number using the format [-

]d.dddde[-]dd

Floating-point number using the format [-

]d.ddddE[-]dd

Floating-point number using either e or f format, whichever is more compact for the specified value and precision

The int is converted to an unsigned char, and the resulting character is written

String with a terminating null character

Pointer value, the X format is used

A % is written. No argument is converted. The complete conversion specification shall be

%%.

page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

The flags field is where a single character is used to justify the output and to print

+/- signs and blanks, decimal points, and octal and hexadecimal prefixes, as shown in the following table.

Flags

Meaning

-

+

Left justify the output in the specified field width.

Prefix the output value with a + or - sign if the output is a signed type.

space (' ') Prefix the output value with a blank if it is a signed positive value.

Otherwise, no blank is prefixed

# Prefixes a non-zero output value with 0, 0x, or 0X when used with o, x, and X field types, respectively. When used with the e, E, f, g, and G field types, the # flag forces the output value to include a decimal point.

The # flag is ignored in all other cases.

* Ignore format specifier.

The width field is a non-negative number that specifies the minimum number of characters printed. If the number of characters in the output value is less than width, blanks are added on the left or right (when the - flag is specified) to pad to the minimum width. If width is prefixed with a 0, zeros are padded instead of blanks. The width field never truncates a field. If the length of the output value exceeds the specified width, all characters are output.

The precision field is a non-negative number that specifies the number of characters to print, the number of significant digits, or the number of decimal places. The precision field can cause truncation or rounding of the output value in the case of a floating-point number as specified in the following table.

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Flags

Meaning of precision field

d, u, o, x, X The precision field is where you specify the minimum number of digits that will be included in the output value. Digits are not truncated if the number of digits in the argument exceeds that defined in the precision field. If the number of digits in the argument is less than the precision field, the output value is padded on the left with zeros.

f The precision field is where you specify the number of digits to the right of the decimal point. The last digit is rounded.

e, E The precision field is where you specify the number of digits to the right of the decimal point. The last digit is rounded.

g c, C

The precision field is where you specify the maximum number of significant digits in the output value.

The precision field has no effect on these field types.

s The precision field is where you specify the maximum number of characters in the output value. Excess characters are not output.

The optional characters h and l or L may immediately precede the conversion_type to respectively specify short or long versions of the integer types d, i, u, o, x, and

X.

You must ensure that the argument type matches that of the format specification.

You can use type casts to ensure that the proper type is passed to sprintf. page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

sprintl

Prototype

Returns

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

int sprintl (

char *buffer, /* storage buffer */

const char *fmtstr, /* format string */

... ); /* additional arguments */

Function returns the number of characters actually written to buffer.

Description

Same as sprintf, except it doesn't support float-type numbers.

sprinti

Prototype

Returns

Description

int sprinti (

char *buffer, /* storage buffer */

const char *fmtstr, /* format string */

... ); /* additional arguments */

Function returns the number of characters actually written to buffer.

Same as sprintl, except it doesn't support long integer type numbers.

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

SPI Graphic LCD Library

mikroC for dsPIC provides a library for operating the Graphic LCD 128x64 via

SPI. These routines work with the common GLCD 128x64 (samsung ks0108).

Note: Be sure to designate port with GLCD as output, before using any of the following library procedures or functions.

Important: When using SPI Library routines, you are required to specify the actual SPI module, either SPI1 or SPI2 in

Spi_Glcd_Init

.

Library Routines

Basic routines:

Spi_Glcd_Init

Spi_Glcd_Disable

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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Spi_Glcd_Init

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void SPI_Glcd_Init(char DeviceAddress, unsigned int * rstport,

unsigned int rstpin, unsigned int * csport, unsigned int cspin);

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). spi_module

- Sets SPI1 or

SPI2 module to work with SPI expander. For modules that have only one SPI module this setting has no effect.

This procedure needs to be called before using other routines of SPI GLCD library.

Spi_Glcd_Init(PORTF, 0, PORTF, 1, 0, 1);

Spi_Glcd_Set_Side

Prototype

Description

Requires

Example

void SPI_Glcd_Set_Side(char x_pos);

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.

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Select_Side(0);

Spi_Glcd_Select_Side(10);

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Spi_Glcd_Set_Page

void Spi_Glcd_Set_Page(char page);

Prototype

Description

Requires

Example

Selects page of GLCD, technically a line on display; parameter page can be 0..7.

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Set_Page(5);

Spi_Glcd_Set_X

void SPI_Glcd_Set_X(char x_pos);

Prototype

Description

Requires

Example

Positions to x dots from the left border of GLCD within the given page.

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Set_X(25);

Spi_Glcd_Read_Data

Prototype

Returns

Description

Requires

Example

char Spi_Glcd_Read_Data();

One word from the GLCD memory.

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.

Reads data from from the current location of GLCD memory.

tmp = Spi_Glcd_Read_Data; page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Spi_Glcd_Write_Data

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Spi_Glcd_Write_Data(char data);

Prototype

Description

Requires

Example

Writes data to the current location in GLCD memory and moves to the next location.

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Write_Data(data)

Spi_Glcd_Fill

void Spi_Glcd_Fill(char pattern);

Prototype

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

Example

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Fill(0); // Clear screen

Spi_Glcd_Dot

Prototype

void Spi_Glcd_Dot(char x_pos, char y_pos, char color);

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

Example

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Dot(0, 0, 2); // Invert the dot in the upper left corner page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Spi_Glcd_Line

Prototype

Description

Requires

Example

void SPI_Glcd_Line(int x_start, int y_start, int x_end, int y_end, char color);

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).

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Line(0, 63, 50, 0, 2);

Spi_Glcd_V_Line

Prototype

Description

Requires

Example

void Spi_Glcd_V_Line(char y_start, char y_end, char x_pos, char color);

Draws a vertical line on the GLCD from (x, y1) to (x, y2). Parameter color determines the dot state: 0 draws an empty line (clear dots), 1 draws a solid line (put dots), and 2 draws a “smart” line (invert each dot).

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_V_Line(0, 63, 0, 1);

Spi_Glcd_H_Line

Prototype

Description

Requires

Example

void Spi_Glcd_H_Line(char x_start, char x_end, char y_pos, char color);

Draws a horizontal line on the GLCD from (x1, y) to (x2, y). Parameter color determines the dot state: 0 draws an empty line (clear dots), 1 draws a solid line (put dots), and 2 draws a “smart” line (invert each dot).

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_H_Line(0, 127, 0, 1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Spi_Glcd_Rectangle

Prototype

Description

Requires

Example

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void Spi_Glcd_Rectangle(char x_upper_left, char y_upper_left,

char x_bottom_right, char y_bottom_right, char color);

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” border (invert each dot).

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Rectangle(10, 0, 30, 35, 1);

Spi_Glcd_Box

Prototype

Description

Requires

Example

void Spi_Glcd_Box(char x_upper_left, char y_upper_left, char x_bottom_right,

char y_bottom_right, char color);

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).

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Box(10, 0, 30, 35, 1);

Spi_Glcd_Circle

Prototype

Description

void Spi_Glcd_Circle(int x_center, int y_center, int radius, char color);

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

Example

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Circle(63, 31, 25, 1); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Spi_Glcd_Set_Font

Prototype

Description

Requires

Example

void SPI_Glcd_Set_Font(const char * activeFont, char aFontWidth,

char aFontHeight, unsigned int aFontOffs);

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 following 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”.

GLCD needs to be initialized. See

Spi_Glcd_Init

.

// Use the custom 5x7 font "myfont" which starts with space (32):

Spi_Glcd_Set_Font(@myfont, 5, 7, 32);

Spi_Glcd_Write_Char

Prototype

Description

Requires

void SPI_Glcd_Write_Char(char chr1, char x_pos, char page_num,

char color);

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.

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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

Spi_Glcd_Write_Text

Prototype

Description

Requires

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

void SPI_Glcd_Write_Text(char text[], char x_pos, char page_num,

char color);

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.

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.

Spi_Glcd_Write_Text('Hello world!', 0, 0, 1);

Example

Spi_Glcd_Image

Prototype

void Spi_Glcd_Image(const char * image);

Description

Requires

Example

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.

GLCD needs to be initialized. See

Spi_Glcd_Init

.

Spi_Glcd_Image(my_image); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The example demonstrates how to communicate to KS0108 GLCD via SPI module, using serial to parallel convertor MCP23S17.

extern const unsigned short

truck_bmp[];

char ii;

unsigned int jj;

char *someText;

void delay2S() {

Delay_ms(2000);

}

void main() {

ADCON1 |= 0x0F;

Spi_Glcd_Init(0, &PORTF, 0, &PORTF, 1);

Spi_Glcd_Fill(0xAA); delay2S();

while(1) {

Spi_Glcd_Image( truck_bmp ); delay2S();

Spi_Glcd_Fill(0x00);

for(jj = 1; jj <= 40; jj++)

Spi_Glcd_Dot(jj,jj,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

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

}

//continues..

Spi_Glcd_Line(120, 12, 12,60, 1); delay2S();

Spi_Glcd_H_Line(5, 40, 6, 1); delay2S();

Spi_Glcd_Line(0, 12, 120, 60, 1);

Spi_Glcd_V_Line(7, 63, 127, 1); delay2S();

for(ii = 1; ii <= 10; ii++)

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();

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Hardware Connection

MCP23S17

D3

D4

D5

D0

D1

D2

D6

D7

9

10

RF1 11

7

8

RF6 12

RF3 13

RF2 14

4

5

6

1

2

3

GPB7

VDD

VSS

CS

SCK

SI

SO

GPB0

GPB1

GPB2

GPB3

GPB4

GPB5

GPB6

GPA0

INTA

INTB

RESET

A2

A1

A0

GPA7

GPA6

GPA5

GPA4

GPA3

GPA2

GPA1

18

17

16

15

23

22

21

20

19

28

27

26

25

24

RST

E

RW

RS

CS2

CS1

RF0

VCC

11

12

13

14

VCC

GND

OSC1

OSC2

10 MhZ

mikroC for dsPIC making it simple...

RF0

RF1

30

29

RF2

RF3

RF6

26

25

24

page

Vee

VCC

Contrast

Adjustment

Vo

P1

5K

VCC

20

1

mikroElektronika

EasydsPIC2

Development system

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Port Expander Library

The SPI Expander Library facilitates working with MCP23S17, Microchip’s SPI port expander. The chip connects to the dsPIC according to the scheme presented below.

Note: dsPIC need to have a hardware SPI module.

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

void Expander_Init(char ModuleAddress, unsigned int * rstport,

unsigned int rstpin, unsigned int * csport, unsigned int cspin);

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).

spi_module

- Sets SPI1 or SPI2 module to work with SPI expander. For modules that have only one SPI module this setting has no effect.

Requires

Example

This procedure needs to be called before using other routines of PORT Expander library.

Expander_Init(PORTB, 0, PORTB, 1, 0); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

PortExpanderSelect

Prototype

Description

Requires

Example

void PortExpanderSelect;

Selects current port expander.

PORT Expander must be initialized. See

Expander_Init

.

PortExpanderSelect;

PortExpanderUnSelect

Prototype

Description

Requires

Example

void PortExpanderUnSelect;

Un-Selects current port expader.

PORT Expander must be initialized. See

Expander_Init

.

PortExpanderUnSelect;

Expander_Read_Byte

Prototype

Returns

Description

Requires

Example

char Expander_Read_Byte(char ModuleAddress, char RegAddress);

Byte read from port expander.

Function reads byte from port expander on

ModuleAddress and port on

RegAddress

.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Read_Byte(0,1);

Expander_Write_Byte

Prototype

Returns

Description

Requires

Example

void Expander_Write_Byte(char ModuleAddress,char RegAddress, char

Data);

Nothing.

This routine writes data to port expander on

ModuleAddress and port on

RegAddress

.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Write_Byte(0,1,$FF); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Expander_Set_Mode

Prototype

void Expander_Set_Mode(char ModuleAddress, char Mode);

Returns

Description

Nothing.

Sets port expander mode on

ModuleAddress

.

Requires

Example

PORT Expander must be initialized. See

Expander_Init

.

Expander_Set_Mode(1,0);

Expander_Read_ArrayPortA

Prototype

void Expander_Read_ArrayPortA(char ModuleAddress, char NoBytes,

char DestArray[]);

Returns

Description

Nothing.

This routine reads array of bytes (

DestArray

) from port expander on

ModuleAddress and portA.

NoBytes represents number of read bytes.

Requires

Example

PORT Expander must be initialized. See

Expander_Init

.

Expander_Read_PortA(0,1,data);

Expander_Read_Array

Prototype

void Expander_Read_Array(char ModuleAddress, char StartAddress,

char NoBytes, char *DestArray);

Returns

Description

Nothing.

This routine reads array of bytes (

DestArray

) from port expander on

ModuleAddress and

StartAddress

.

NoBytes represents number of read bytes.

Requires

Example

PORT Expander must be initialized. See

Expander_Init

.

Expander_Read_Array(1,1,5,data); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Expander_Write_Array

Prototype

Returns

Description

Requires

Example

void Expander_Write_Array(char ModuleAddress, char StartAddress,

char NoBytes, char *SourceArray);

Nothing.

This routine writes array of bytes (

DestArray

) to port expander on

ModuleAddress and

StartAddress

.

NoBytes represents number of read bytes.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Write_Array(1,1,5,data);

Expander_Read_PortA

Prototype

char Expander_Read_PortA(char Address);

Returns

Description

Requires

Example

Read byte.

This routine reads byte from port expander on

Address and PortA.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Read_PortA(1); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Expander_Read_ArrayPortB

Prototype

Returns

Description

void Expander_Read_ArrayPortB(char ModuleAddress, char NoBytes,

char DestArray[]);

Nothing.

This routine reads array of bytes (

DestArray

) from port expander on

ModuleAddress and portB.

NoBytes represents number of read bytes.

Requires

Example

PORT Expander must be initialized. See

Expander_Init

.

Expander_Read_PortB(0,8,data);

Expander_Write_PortA

void Expander_Write_PortA(char ModuleAddress, char Data);

Prototype

Returns

Description

Requires

Example

Nothing.

This routine writes byte to port expander on

ModuleAddress and portA.

PORT Expander must be initialized. See

Expander_Init

.

Expander_write_PortA(3,$FF);

Expander_Write_PortB

void Expander_Write_PortB(char ModuleAddress, char Data);

Prototype

Returns

Description

Requires

Example

Nothing.

This routine writes byte to port expander on

ModuleAddress and portB.

PORT Expander must be initialized. See

Expander_Init

.

Expander_write_PortB(2,$FF); page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Expander_Set_DirectionPortA

Prototype

void Expander_Set_DirectionPortA(char ModuleAddress, char Data);

Description

Requires

Example

Set port expander PortA pin as input or output.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Set_DirectionPortA(0,$FF);

Expander_Set_DirectionPortB

Prototype

void Expander_Set_DirectionPortB(char ModuleAddress, char Data);

Description

Requires

Example

Set port expander PortB pin as input or output.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Set_DirectionPortB(0,$FF);

Expander_Set_PullUpsPortA

Prototype

void Expander_Set_PullUpsPortA(char ModuleAddress, char Data);

Description

Requires

Example

This routine sets port expander PortA pin as pullup or pulldown.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Set_PullUpsPortA(0,$FF);

Expander_Set_PullUpsPortB

Prototype

void Expander_Set_PullUpsPortB(char ModuleAddress, char Data);

Description

Requires

Example

This routine sets port expander PortB pin as pullup or pulldown.

PORT Expander must be initialized. See

Expander_Init

.

Expander_Set_PullUpsPortB(0,$FF); page

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Library Example

The example demonstrates how to communicate to port expander MCP23S17.

unsigned int

i;

void main(){

ADPCFG = 0xFFFF;

TRISB = 0x00;

LATB = 0xFF;

Delay_ms(2000);

Expander_Init(0, &PORTF, 0, &PORTF, 1); // 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) {

Expander_Write_PortA(0, i++); // write i to expander's porta

LATB = Expander_Read_PortB(0);

// read expander's portb and write it to dsPIC's LATB

if(i == 255) i = 0;

Delay_ms(20);

}

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er page

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Hardware Connection

MCP23S17

9

10

RF1 11

RF6 12

RF3 13

3

4

1

2

5

6

7

8

RF2 14

GPB0

GPB1

GPB2

GPB3

VSS

CS

SCK

SI

SO

GPB4

GPB5

GPB6

GPB7

VDD

GPA1

GPA0

INTA

INTB

RESET

A2

A1

A0

GPA7

GPA6

GPA5

GPA4

GPA3

GPA2

23

22

21

20

28

27

26

25

24

19

18 RF0

17

16

15

VCC

11

12

13

14

VCC

GND

OSC1

OSC2

10 MhZ

mikroC for dsPIC making it simple...

RF0

RF1

30

29

RF2

RF3

RF6

26

25

24

page

5

7

1

3

9

VCC

PORTB

2

4

6

8

10

5

7

1

3

9

VCC

PORTA

2

4

6

8

10

Miik ro le tr niik D ev lo me t oo s B oo ks C om piil er

mikroC for dsPIC making it simple...

miik ro fo r ds C - C Compiler for Microchip dsPIC microcontrollers

Contact us:

If you are experiencing problems with any of our products or you just want additional information, please let us know.

Technical Support for compiler

If you are experiencing any trouble with mikroC for dsPIC, 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 mikroC (dsPIC) 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 distribution 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: [email protected]

Website: www.mikroe.com

page

Miik ro le tr niik De ve op en to ol -- Bo ks C om piil er

Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement

Table of contents