Editing A Really Basic Guide to the PIC Microprocessor and BoostC

A Really Basic Guide to the PIC Microprocessor and BoostC



Draft, not quite done, but should be useful even at this state -- still fixing formatting, adding images........


== About this Document ==

This is meant to be a more introductory guide to the PIC microprocessor and BoostC ( http://www.sourceboost.com/home.html ) than any I have been able to find on the web. Additionally I assume that you have only limited knowledge of electronics and other microprocessors. I will not take you very far down the path of using PIC processors, if you more or less master this material you should be ready for many of the other excellent guides on the web. See the section on links below.

== Overview ==

This guide will take you through the steps to make your first PIC project. It is very basic, but will open you up to the world of PIC projects. Most beginners use assembly language for this, but assembler is, I think, unnecessarily difficult. This guide uses a language called C which has almost all the power of assembler but much has much shorter and simpler to read ( and write ) programs. There are several different choices of development environments that use C. The one I use and think is best fitted for this tutorial is BoostC from Source Boost ( http://www.sourceboost.com/home.html ). Some nice features of the compiler include: free version for small programs and the compiler is built into an integrated development environment ( which combines the functions of editing, building, and debugging into one user interface ). The debugging environment is particurlary good, unlike some environments the debugging is in C not assembler. There is also support for external events and output devices like LED's. You need never work in assembler with this environment, but if you wish you can include C inline, and get full assembler listings of your code. The Boost C compiler comes in a reasonably priced version with unlimited code size, so it is not a dead end for more advanced work.

Before plunging in you may wish to check out these three appendices:

Appendix: What you Need for this Project
Appendix: Other Documents You Should Reference
Appendix: Notes on Power Supply
Note
In the following I make many statements that are not completely accurate, for example I may say that PICs run on 5 volts were actually there is a range of voltages that might work, depending somewhat on the PIC and the circuit it is in. If you catch me in an error you may know enough to not need this tutorial. If so congratulations. Expect to find mistakes like this this when you become more advanced.

Other documents that you should get and read are listed in an appendix at the end of this document.

== What is a PIC? ==

A PIC is a small computer all of which fits on a single chip. There are many different versions of PICs. Hobbyist style PICs usually cost under 10 dollars. For most Hobbyist a so-called flash part is the one to get. It can be programmed over and over again, which is not true for some other parts. PICs also come in different packages, the easiest to use are the “dual in line” or “dip” parts. Surface mount parts let you build a really small circuit, but are very hard to work with.

In this discussion I will focus on the 16F877 ( or 16f877A, a slightly more modern revision). I like this part because it is big from a computer point of view ( compared to other PIC's ), and physically large so that wiring it up does not require a microscope or tiny hands.

PICs are digital devices that often run off of 5 volts at currents ( for the entire circuit ) on the order of 100 ma ( less for low power applications, more for high power applications ). In this digital world a voltage near 5 volts is a computer 1 a voltage near 0 volts is a computer 0. PICs can deal in data either as bits, bytes ( 8 bits ) or multiple bytes. The basic operations, however, are mostly oriented around bytes and thus PICs are called 8 bit computers ( 8 bits = 1 byte ). The amount of data in the chip is a few hundred bytes of data. Unlike most computers the program is not kept in data memory but in a separate program memory. The 16F877 has a 8K instruction memory. Data bytes are worked with by using an address ( internally a number ), in C these bytes are normally given a name, the C compiler keeps track of the numeric address. Bytes that have special purposes ( and other ) are often called registers.

== The pins on a PIC: ==

This PIC has 40 pins. The PIC has some pins just to get power, typically +5 volts and 0 volts or ground. Additionally there are 2 pins where a quartz crystal is attached to provide a basic “pulse” or clock for the PIC. 4 mega Hertz is a frequency that is often used. These pins normally do not do much for the hobbyist, but are required to make the PIC work. There is also a pin that can be used to “reset” the PIC, this makes it start over at the beginning of its program, particularly useful if something goes wrong in a program. Cycling the power on and off will also reset the PIC.

The next pins to consider are IO ( input output ) lines. Each line is part of a byte in the PIC, called a port. The ports are called PortA, PortB..... The details of each port is found in the manual for the chip. Each port also has a configuration register ( another byte ) called the TRIS register. Putting a 1 in the TRIS register makes the corresponding port bit an input ( as a memory aid the 1 looks like an I as in input ) putting a 0 in this port makes the corresponding port bit an output ( as a memory aid the 0 looks like an O as in output ). Other configuration registers ( bytes ) may also be associated with the port. Usually if you do not need more advanced functions you can ignore these registers. There is an exception on the 16F877 some ports can do analog to digital functions and these must be turned off to use the ports as straight I/O. 

== What is a PIC peripheral? ==

I suppose an input/output port is a peripheral, but normally the term is used for something more complicated. A counter/timer is one example. A counter is connected to some source ( a pin for example ) and each time the pin changes from a 0 to a 1 the counter increase by 1. Some counters are 8 bit, some 16 bits( this is the number of bits for the highest number the counter can count to ).. 

Other peripherals are: PWM outputs ( pulse with modulation ) Serial communications, Analog to digital converters.

All the peripherals discussed so far are built right into the chip, they are called internal peripherals, peripherals can also be outside the PIC chip, these are external peripherals. 

Fancier computers like PCs have peripherals as well, but not normally as part of the central processing chip. Having them in the chip can make things really simple, compare to using an external peripheral or doing the operation in software, but the peripherals can also make things more complicated, Too complicated for me to discuss much here.

PICs can also have external peripherals, these are normally connected to the I/O ports.

What do I connect a PIC to?

A PIC that is not connected to something is pretty much useless. It could be finding the answer to the ultimate question, but how would you know? The more electronics you know the more things you may figure out to connect them to. This tutorial will deal only with the simplest connections. 

=== A LED ===

A LED is just a small light that lights up with voltages and currents that work pretty well with the PIC. Here are two typical circuits:

[[Image:LED1.jpg | LED Circuit]]


And the second circuit:

[[Image:LED2.jpg | LED Circuit]]


R_CURRENT_LIMIT limits the current through the LED, 200 or so ohms usually works fine.

VPLUS_VDD is the positive power to the PIC, typically 5 volts.

=== A Push Button Switch ===

Normally used with a pull up ( or down ). The switch is often a single pole momentary switch, that is the switch is closed only when it is pushed, it pops back open when the button is released. Many keyboards or keypads are arrays of push button switches. Some circuits are as follows:


[[Image:PBPullDown.jpg | Push Button]]



PIC_PORT_INPUT a pic I/O port pin, configured as an input.

R_PULLUP should be about 1k to 100 k.

VPLUS_VDD is the positive power to the PIC, typically 5 volts.


Notes on a pull up ( or down ) resistors

Pull up or pull down resistor are used, normally on input pins, to force the pin to either a 1 ( pull up ) or 1 or a 0 ( pull down). Often there is another connection like the push button which is stronger than the pull up ( or down ) that can change the condition on the pin. Input pins should always be connected to something, if you have nothing better use a pull up ( down ) resistor. Connecting to “nothing” is called floating and is bad. The pin acts like an antenna connected to a high impedance input, the voltage can vary due to all sorts of stray effects. If you set all pins as outputs you can let the pins float ( actually they do not float, the PIC puts a well defined voltage on them. Outputting a 1 to a grounded connection, or a 0 to a V+ connection is bad, it can destroy the PIC since the PIC is not as “strong” as the power supply or ground.

Using a transistor to drive a LED ( also useful for other components which use more power than a PIC output port can supply, or to lessen the load on the PIC )


[[Image:LEDTrans.jpg | Transistor Drive ]]


PIC_PORT_OUTPUT a pic I/O port pin, configured as an output.

Q1 a 2N3565 ( or similar ) npn transistor

R_CURRENT_LIMIT should be about 200 ohms.

VPLUS_VDD is the positive power to the PIC, typically 5 volts.

=== The Crystal Clock Circuit ===

The PIC has two pins that we are going to connect to a 4 mega Hz crystal. This will make the PIC run at 4 mega Hz. There are other ways to “clock” the PIC, but a nice feature of a crystal is that the frequency is very precise, usually a small fraction of a percent, so you can use the PIC for quite precise timing. Here is the circuit.

[[Image:Crystal.jpg | Crystal]]

CRYSTAL_PIN_1 The PIC pin for the crystal connection OSC1 pin xx on the PIC877

CRYSTAL_PIN_2 The PIC pin for the crystal connection OSC2 pin xx on the PIC877

CAP_1 A 30 pf capacitor

CAP_2 A 30 pf capacitor

GND Ground, or 0 volts, sometimes called Vss.

=== Reseting the Processor, MCLR ===

A final circuit can be used to reset the processor – this is basically making it start at the beginning of the program. This is done with a pin that is set to 0 to reset, left at 5 volts to let the processor run. You can leave out the pushbutton if you do not want to use the reset, but keep the resistor in the circuit or the processor might reset when you least expect it.

[[Image:MCLR.jpg | Master Clear]]


MCLR the master clear or reset pin on the PIC.

R_PULLUP should be about 1k to 100 k.

VPLUS_VDD is the positive power to the PIC, typically 5 volts.

GND Ground, or 0 volts, sometimes called Vss.

== Software: A Beginning Program ==

For software we will focus on the C language and in particular on a “lite” and free version from Source Boost. Before beginning this section it would be a good idea to download and install the BoostC compiler. You can find the download page at: http://www.sourceboost.com/Products/BoostC/Download.html A complete list of what you need to both write and run the program is in an appendix at the end of this document.

== The Hello World LED blinker Program ==

It is traditional in PIC programming to make your first program just blink an LED on and off and on and off ....... So that is what we are going to do. The purpose of this is that while the program is as simple as it can get, it takes you through the full cycle of writing and running a PIC program. Also to really run it you need to build a basic circuit with the PIC.

First we need to determine a bit of the hardware we plan to use. Pick a PIC port and a bit on it and connect a LED to it using the circuit above. I will use bit 0 on portb. Later you can build the circuit or we can simulate it in the BoostC IDE.

Before starting the SourceBoost decide where you want to keep your program files and in particular the files for this project. I picked MyDocuments\PIC\HelloWorld Use Explorer or what ever file management program you use to create this directory ( you need to create this directory because the sourceBoost IDE cannot create directories )

Startup the SourceBoost IDE

We will use the “wizard” for starting a project. The wizard only works for some types of PICs but fortunately the 16F877 ( use this even if you chip is a 16F877A ) is one of them. 

From the menu bar select: Project->Wizard...

The wizard is a dialog box that has some places for data, when the data is filled out and you press the <OK> button the wizard will generate a C source code file for you. This file does not do much, but has the right basic structure of a program for this processor. Fill out the blanks in

Path fill in the name you picked above, for me:
MyDocuments\PIC\HelloWorld, to avoid any problems
with typos in the file click into the field then press the <...> button to browse to the directory.
Project Name HelloWorld
Target 16F877 ( or 16F877A if that is what you are using )

Everything else can be skipped. Then press the <OK> button. Your window should now have a display on the left that looks like:


Double click on HelloWorld.c, the program should open in the panel on the right. The panel is a text editor ( a simple word processor ) for editing the program, it is much like notepad or wordpad, or even word. You should be able to operate it just by looking at the menus and a little experimentation. If you cannot figure it out try a friend.

Now that we have the program we will look at it and then finish it up to make the PIC blink the LED. Before we do this lets make sure the program so far is ok. We will “Build” the program which involves all the processes to get it ready to download into the PIC. From the menu bar select Build -> Build. In the lower pane of the IDE you should see some messages documenting the build process. Eventually it should produce the message Success followed by a couple of file names and then “Done”. If you get errors or messages like “failure” then something has gone wrong. I would start again.

Now lets read through the program and add some comments ( I could give you this program with the comments, but if you add the notes yourself it will mean more to you ) First line:

  '''#include <system.h>'''

( note I will use the font above for all lines in the C source file ) Start all programs with this statement, it adds the contents of the file system.h to your project, and most BoostC programs want this file. It makes the symbolic names ( like portb ) for PortB available to the compiler. To add a note about this to the file start the line with //. So you might add:

  '''// start all BoostC programs with this include.'''

A line like the above is called a comment and is ignored by the compiler, but can give the human reader useful information. Use comments, if you do not even you will not understand your code at a later date.

By the way note that C is case sensitive, do not change that capitalizations, also there are conventions on capitalization that you should follow, I will mention them later. Now read down to the line:

  '''#pragma DATA _CONFIG, _PWRTE_OFF & _BODEN_OFF & _WDT_OFF & _LVP_OFF & _CPD_OFF & _DEBUG_OFF & _XT_OSC & _CP_OFF'''

this line does some set up of the compiler and the chip. There is a section in the manual about this, the are normally called configuration fuses. Setting them up the wrong way can be a real problem, learning all about them can take awhile. Leave them as they are until you learn more. Now the line:

  '''#pragma CLOCK_FREQ 4000000'''

This tell the compiler how fast your clock will be. For this chip this is the frequency of the crystal you are using. ( we are planning a 4 mega Hz clock and crystal. This is important because the compiler will generate some programs for delaying the computer for a time. To do this it needs to know how fast the clock is.

  '''void interrupt( void ) {'''

this line begins a subroutine that handles processor interrupts ( whatever they are ). For now you will not be using them, but for now leave the code in. If you have an interrupt by some mistake you program will work better with this in.

This subroutine ends at the matching }. To find it highlight the { ( clicking just to the left of the { will do this ) It will turn a darker blue, and so will the matching }.

Next look at: 

  '''void main( void ) {'''

this is the so called main program, when the PIC starts up it starts here. What does this code do? Lets take a look:

  '''//Configure port A
  trisa = 0x00;'''

this line sets the control register for port a: called trisa to all 0's ( every bit = 0 ). 0 makes the bit an output bit, that is the pin connected to port pin is an output pin. To find what pins this is on the chip look in the 877 manual The 0x means that the number is expressed in hexadecimal or base 16. You can also use regular decimal, or binary. In binary you can clearly see each bit.
0x0 is 0b0 in binary or 0b00000000 the last notation showing all 8 bits in the byte. 

The code continues working through other ports setting them all to output. The code then continues setting up some other configuration stuff that I would rather not explain. Pretty much all this stuff is safe, that is it will not do anything bad. The exception to this is the line:

  '''intcon = 0xA0;'''

this will turn on the interrupts which we would rather have off. Change it to 

  '''intcon = 0b0;'''

this will have the interrupts off. Also fix the comment just above this line so it is correct.

Now we are almost done: we have next

  '''while( 1 ) ;'''

This is a loop that runs forever doing nothing.

Change this to:

  '''while( 1 ) {
  }'''

This is still a loop that runs forever doing nothing but the difference is that the loop begins at the { and extends to the }. Writing it this way gives us a place to add code to the loop so that it will do something. Note that this is typical for a PIC program to have a loop like this, but normally doing something. Start up, set up, and do something forever. Just a note about a loop if you are not familiar with the term. A loop in a program is a bit like running in a circle, you go around and around. Since the program is written as sequential lines this means we start at some line, the beginning of the loop, work down to a lower line, the end of the loop, and then go back to the beginning of the loop. Most loops ( unless the purpose is just to take up time ) do something each time the loop, perhaps count from 0 to 99. Many loops in fact count just to determine how many times to execute the code in the loop, this may be done to delay the program a bit. At the end of the count they “drop out of the bottom” of the loop.

Finally we have the final

  '''}'''

which ends the routine main, and since main is also where the program starts it ends the whole thing. Also since the loop never ends we never get through this point.

Adding some code:

Now lets add some code to make the LED's blink. There are 2 key ideas for this.

* One you need to change the value of a port back and froth from 0 to 1.
* Second you need to do it slowly enough so that the human eye can see the blink.

There are a lot of ways to do this. I am going to take what I think is the simplest to understand. This method uses a few functions that are documented in the BoostC compiler manual. ( Read it to get an idea of what you can do, also read the section on programming in C. You will not understand it all the first, second, or third time through, but each time you will understand more, and at least be able to look things up more quickly. )

* set_bit( ) is used to set one bit of a variable or port to 1.
* clear_bit( ) is used to set one bit of a variable or port to 0.
* delay_ms() is used to just delay the program by a number of milli seconds ( thousands of a second ).

We can put this together like this:

  '''while( 1 ) {'''
   
      '''set_bit( portb, 0 ); // connect the led to port B,''' 
      '''// bit 0 this is RB0 or pin33''' 
      '''// the led will turn on'''
      '''delay_ms( 250 ); // just wait for ¼ of a second'''
  
      '''clear_bit( portb, 0 ); // the led will turn off'''
  
      '''delay_ms( 250 ); // just wait for ¼ of a second'''
  
  
  '''}'''

The led should cycle through on, then off, all in one half of a second.

Note: In the code above each line of code ends with a semicolon, then I have added a comment after the semicolon.

Check your program by building it ( on the menu Build -> Build ). A successful build does not mean that the program works, only that it is a program that the compiler can understand. To really test it you need to assemble the hardware, program the chip, and try it out. A short cut that can help is to simulate the program.

=== Using the simulator to check the program ===

The simulator ( also known as the debugger ) lets the PC run the program as if it were a PIC. You can also look at values of variables, registers, and ports as the program runs. This is really useful in determining if the program is working correctly, understanding how PICs run, and fixing mistakes in the program.

Build the program.
Press Debug Icon, A bug, usually next to last icon on the icon bar. 
Debugging.... should show in lower panel, a green bar should appear in the edition across 

  '''trisa = 0x00;'''

the first line of the main program. The program has started running and then has stopped on this line in the program.
Press the “step over” icon, ( one line down from debug icon, first on row, “hover” will show “step over” ). 
The green line will advance by one, the debugger has just executed the prior line of code and stopped again. Use the menu: View -> Watch Bar A Panel will open on the right, it is called the Watch Panel, at the top it say “Watch”.
Right click in the Watch Panel a popup menu will appear, select add, in the dialog box type “portb” and click <ok>. portb will appear in the watch panel. Put the mouse on portb in the watch panel and right click, in the popup menu select binary. This will change the display of portb to binary. This is good so you can see each bit of the port ( although 0 bits left will not be displayed ) We are going to look in particular at bit 3 ( oddly this is the fourth bit from the left, the first bit is bit 0, not bit one.
Use the step over icon until the program gets down to the line portc = 0x00; by this time the watch window should show portb as 0.
Stepping a line at a time is tedious, a short cut is to set a “breakpoint”. When a running program reaches a breakpoint it stops running and you get a chance to look around the program and think a bit. Set a breakpoint: to do this go down to the line: delay_ms( 250 ); ( the first occurrence ) Right click on the line, select Toggle Breakpoint... A red triangle should appear in the border to the left of the line. The triangle indicates that the breakpoint is set. ( You clear the breakpoint in a similar way )
Do the same thing as the step above on the second line delay_ms( 250 ); When we later run the program it will stop when it comes to a breakpoint.
Run the program: When in the debug mode ( the debug icon as explained above ) press the run icon ( same tool bar as the “step over” icon ). 
Not much will seem to happen, but the green bar will advance through the program until it come to one on the breakpoints and then stop on the breakpoint. It will stay stopped until you start it again. Look at the watch window for the value of portc. 
Run the program again ( you are already in the debug mode, do not turn it off, or the program will restart from the beginning, just press the run icon again). The green bar should advance ( but the program is a loop so advance may seem to be like backing up ) to the next delay. Look at the value of portc again. Each time you run the program you should see the value of the port bit for the led change from a 1 to a 0.
Keep running or stepping until you feel comfortable that the program is working correctly. If it is not working correctly try to find the problem. 

There a lot more functions of the debugger. You can explore the debug toolbar and read the documentation to find out more.


=== Running the program for Real ===

To really run the program you will need to complete 2 additional steps, build the circuit, program the chip and finally power it up.

Building the circuit

I recommend that you build the circuit on a poto or breadboard. The board has many connections prewired and allows many components and wires to simply be pushed in holes in the board to make the connections. Here is a picture:

    still need to upload the picture

I normally use the connections marked in red ( all connected together on the top, all connected together on the bottom, but top and bottom not connected together ) as +5 volts and the blue as 0 volts or ground. Use jumper wires to connect the red top line to the red bottom line, and similarly for the blue.

Plug the PIC in so that it bridges the mid line separation of the board this will leave more holes showing on the top of the PIC or the bottom of the PIC. I normally leave more holes showing on the side of the chip that has the crystal connections as I usually have more trouble fitting the crystal and its components in than other components. Also plug the PIC in about the middle ( left to right ) to give lots of room 

Build rest of the circuit:

See Appendix: Notes on Power Supply -- I always use a regulator, but I often skip the diode and some of the capacitors. You should however have 2 .1 micro F caps from plus to ground ( Vdd to Vss ) near each of the PIC power pins.

Connect the PIC power pins, note that there are 4, 2 plus Vdd ( pins 11,32 ) and 2 ground Vss ( pins 12, 31 )

See above : A LED -- You need to know which port to use for the LED, since the software uses RB3 use that here too. Light the LED when the port bit = 1. 

See above: MCLR – You can skip the pushbutton. The PIC will reset when you first turn the power on.


Use a reference guide to proto boards if you have not used the boards before ( there are a couple listed in the parts appendix below, Google will find you more ).

You may also find the PIC reference manual useful. 

Here is the resulting circuit for me ( with unused pins not connected, but configured as outputs in the code )

    still need the picture

== Programming the Chip  ==

If you have written the program, and built it, and built the circuit for the PIC you are ready to try the program for real on the PIC circuit you built. There are two more items you will need. One is a little circuit that you connect to your computer, it is called a PIC programmer. The other is a program for the PC to control the programmer, it too is often called a programmer ( even though for this project you are actually the programmer )

Programmers differ quite a bit, so you should use the directions with your programmer. Generally you:

Install the software.
Connect the programmer with the appropriate cable to the appropriate port on your PC.
Your software may need some setup, in almost all cases this includes the chip that you are programming ( the 16F877 is not the same as the 16F877A from the programmers point of view.
You need to load the output file of the compiler, this should be in the same directory as the rest of your project, its extension will be .hex.
Check the fuses or configuration of the PIC in the programmer, at a minimum you want to make sure that:

the watch dog timer ( WDT ) is off
the ..........

<Need more here.....>

Run the programmer, it may or may not have lights to indicate that something is happening. Most programmers automatically verify the work of the programmer and give a message to that effect. If not see if you programmer has a function for this and if so use it.

The real thing.

Now take the chip out of the programmer and insert it into your circuit ( with the power off ). Turn the power on and watch the LED. This is the moment of truth.

It did not work, now what, some things to try:

Check the Hardware

Make sure the voltage at the chip power pins is correct.
The LED may be connected backwards, if there is any doubt try reversing it.
If you have a oscilloscope that is up to it see if the voltage on the oscillator pins is oscillating at the correct frequency, us the x10 input or the scope can kill the oscillations even if it were ok before connecting the scope.

Check the Software

Recheck everything from beginning to end.
Did you select the right target chip at each chance that you got? Sometimes you will have only the PIC16F877 as a choice, other times you will also have the PIC16F877A, use the closest match to your chip.
If you did not do it already run the software through the simulator.

Still not working? Get another pair of eyes to go over your work.


== Appendix: Some Notes on the C language  ==

The SourceBoost Manual “BoostC Compiler Help” ( available from the IDE help menu ) should be read.

C statements end with a ; do not leave it out. Somewhat confusingly it does not end all lines just statements. Normally they do not appear at the end of “#define” or “#pragma” lines. Also the “if” line of an “if” statement does not end with a ;. In a “for” loop however there are normally three semicolon on the first line. Try to base your code on examples you know are right.

C is case sensitive. “If” is not “if” errors in capitalization can cause error messages that are not helpful in finding the error.

Testing for equality is not done with an equal sign, two equal signs are used. if ( x = y ) is almost always an error and should be if ( x == y ). 

Variables in C must be declared. This means you must give the name of the variable and say what type of variable it is before you use it. This is most simply done near the top of your file before you begin any subroutines ( this makes the variable global, whatever that is ). Most of your variables should be of type “unsigned char” On the PIC in BoostC this makes the variable an 8 bit, one byte, variable the type the PIC handles with the greatest of ease. It can have a low value of 0 and a high value of 255. 255 + 1 = 0 for an unsigned char. If you make it a “signed char” it has a range from about -127 to +127 and your program runs slower. “unsigned int” have a range of 0 to about 65,000. but are over twice as slow as “unsigned char” use them only if you need them.

Programs should be indented to show structure. The compiler does not care, but you will when you try to use your own program or someone else's. Imitate what you see in other good programs ( and yes do read other programs to get an idea of what is going on ).

<put a sample here>

Capitalization conventions are use to make programs easier to understand. A few of these are:

Subroutines begin with lower case letters, word are separated using caps: doReset().
Variables begin with caps and words are separated with caps: char MyTemperature.
#define symbols are all upper case and words are separated with underscores: 
#define MOTOR_PORT portb
Volatile variables like I/O registers are all lower case: porta

If you look in the following files ( for the 16f877 and similar for other processors ) you will find register names you should use for programming.

...\SourceBoost\include\p16f877.h
...\SourceBoost\include\PIC16F877.h

they will be very close match ( except for case ) to the names you will find in the manual for your processor. You do not declare these variables, the .h files are used to do that for you.

For all but the shortest programs learn how to write your own subroutines.

BoostC has a bunch of built in subroutines for lots of things including dealing with peripherals. Read the manual to see what they are.

== Appendix: Error Messages and Some Gotchas ==


Going to the source of the error messages in your code:

If you double click on an error message in the bottom pane the editor will move to the line where the compiler “thinks” the error is ( even if you have edited the file ?? ). Beware that the actual location of the error can be far away from what the compiler “thinks”. 

What do error messages mean:

Error messages are one of the weaknesses of the compiler. I have also not been able to find a comprehensive listing of the messages and their meanings.

If you do get an error you do not understand, get the exact wording and use Google advanced search to search the SourceBoost forum website at: [http://forum.sourceboost.com/ | Source Boost Forum ]

Some errors that have cost me a good bit of time


{| class="wikitable"
|-valign="top"	
|Cause
|Error message
|Comment


|-valign="top"
|If ( ... ) instead of if( ... )
|
|Capitalization matters.
<!-------------------------------->
|-valign="top"
|Forgetting to put the semicolon at the end of a line.
|Missing semicolon
|Normally it is just missing at the end of the line listed by the error message, but not always.  Sometimes you get this message when a missing semicolon is not the problem.  Just to fake you out.
<!-------------------------------->
|-valign="top"
|set-bit instead of set_bit
|failure
HelloWorld.c(100): error: missing semicolon
HelloWorld.c(100): error: missing right paren
HelloWorld.c(37): error: failure
|Set-bit is subtraction not the name of a subroutine or function. Note that the error message is “wrong”. I think I have gotten other error messages for the same error. You might want to do a search on set-bit and clear-bit to make sure you have not used them.
<!-------------------------------->
|-valign="top"
|“Equal sign” instead of “is equal sign”:  = instead of ==
|Normally none! no error message.
|Inside an if statement as in if( a = b ) then equal sign is almost always wrong, if you are testing for equality you want if ( a == b ).
<!-------------------------------->
|-valign="top"
|Low voltage programming on
|None, but port b 3 does not work.
|Turn off LVP ( low voltage programming ) to use this port.
<!-------------------------------->
|-valign="top"
|Analog input enabled
|None but porta I/O will not work.
|Simulator may catch this error.
<!--------------------------------
|-valign="top"
|
|
|
<!--------------------------------
|-valign="top"
|
|
|
<!--------------------------------
|-valign="top"
|
|
|
<!--------------------------------
|-valign="top"
|
|
|
<!--------------------------------
|-valign="top"
|
|
|
<!-------------------------------->

|}

== Appendix: Other Documents You Should Reference ==


I would get these electronically and not print them, generally searching them on line is quicker than dealing with all the paper. If this does not work for you try printing them.

PIC midrange manual from the microchip web site:
need link

PIC16F87XA Datasheet:
http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1335&dDocName=en010242 under datasheets at the right hand panel on the page

BoostC Compiler Help: 
from the help menu in the IDE


Lots of PIC Links [[PIC Links]] use page search on PICIntro, and/or Tutorial, and/or Info for more or less instructional materials.


More help with C on the web:


LEARN PROGRAMMING 123 your resources to programming and free tutition http://www.geocities.com/learnprogramming123/C.html

Programming in C http://www.scit.wlv.ac.uk/cbook/

Programming in C: A Tutorial - Brian W. Kernighan - Bell Laboratories, Murray Hill, N. J. http://www.lysator.liu.se/c/bwk-tutor.html

== Appendix: What you Need for this Project  ==

A PIC processor, in particular a 16F877 or 16F877A in the 40 pin dip package. This chip is overkill for the blinking LED but has lots of power for more advanced projects.
Crystal for the PIC Clock and 2 caps. I recommend a 4 megahertz crystal with 30 pf caps. If you go faster than 4 mega Hz you may have problems because of stray capacitance and coupling on the proto board
A board on which to build the project. ( I would use a proto board or breadboard, but other circuit boards which may require soldering will also work, do not solder the PIC in the circuit, if you have to solder get a socket for the PIC ).
A Light Emitting Diode and 200 to 500 ohm current limiting resistor.
A low voltage power supply of at least 5 volts. If it is close to 5 volts you are fine, if more ( for example a 9 v battery ) you should set up a regulator circuit using a 3 terminal regulator circuit perhaps based on the LM7805 or 78L05. – there is a appendix below on power sources.
Wire for the hookup of the board/circuits.
A Windows PC ( other operating systems can be used for PIC projects, but they are not covered by this document ).
A C compiler or development environment. We recommend and give explicit directions for the SourceBoost BoostC IDE. A “light” version is free and is a good place to start. The upgrade the standard version is not too bad at $70 or so ( compared to other compilers ). See:

http://www.sourceboost.com/CommonDownload.html

I have V6.70, get the “exe” version unless you know how to work with zip files.
A PIC programmer and software for same ( I got a JDM programmer on ebay for under $50. read the descriptions of several and compare. The programmer will probably need a cable to connect to your PC. This may or may not come with the programmer. Likewise the power supply for the programmer may or may not come with the programmer. A friend or club that has the programmer may eliminate your need to own one.
Links that can help you find these parts if you are having trouble finding them. 

Most parts are carried by Futulec: http://www.futurlec.com/
I got my programmer on ebay it is a so-called “jdm programmer”.
Not sure what a proto board or breadboard is? see: http://www.instructables.com/id/E4JEGTYF23XWM5Y/?ALLSTEPS or http://www.doctronics.co.uk/prototyp.htm


== Appendix: Notes on Power Supply  ==

If you have access to a 5 volt power supply, great. If you do not then you may want to add a voltage regulator to your project, then you can use almost any source of DC power from 7 volts to 30 volts. You may find that you have a “brick” or “wall wart” power supply from some old device lying around. They almost always have the voltage ( and maximum current ) marked on them. The voltage may not be accurate using one over 7 volts with a regulator may work better than using one marked 5 volts ( which would be fine if accurate ). With the regulator you can use a small 9 volt “transistor” battery. Here is the circuit for the regulator:





POWER_IN_+ The positive connection to your power source, wall wart, battery.....
POWER_IN_- The negative connection to your power source.
D4 This diode protects the circuit against being connected backwards to the power at POWER_IN_+ and -, omit it if you are very careful with your connections. If CPWR is a large enough value ( 500 micro F ? ) then the circuit can work on ac power.
GND the common ground for the entire circuit.
VREG A three terminal voltage regulator with 5 volt output. The LM7805 is one of many parts that will work.
POWER_OUT The regulated 5 volt power to the rest of the circuit.
CPWR This capacitor helps smooth out ripple and noise in the input. About 100 micro F should do. Depending on the input source ( which may already have a capacitor in place it may be omitted.
CF1 This capacitor helps smooth out ripple and noise in the output. 50 micro F should do.
CF2 This capacitor helps smooth out high frequency in the output. Normally capacitors like this are placed close to the power pins of each integrated circuit. A ceramic capacitor of .1 or .01 micro F should serve.
@@ Line 42: / Line 42: @@
 I suppose an input/output port is a peripheral, but normally the term is used for something more complicated. A counter/timer is one example. A counter is connected to some source ( a pin for example ) and each time the pin changes from a 0 to a 1 the counter increase by 1. Some counters are 8 bit, some 16 bits( this is the number of bits for the highest number the counter can count to )..
-Other peripherals are: PWM outputs ( pulse width modulation ) Serial communications, Analog to digital converters.
+Other peripherals are: PWM outputs ( pulse with modulation ) Serial communications, Analog to digital converters.
 All the peripherals discussed so far are built right into the chip, they are called internal peripherals, peripherals can also be outside the PIC chip, these are external peripherals.
@@ Line 200: / Line 200: @@
 this is the so called main program, when the PIC starts up it starts here. What does this code do? Lets take a look:
-   '''//Configure port B
+   '''//Configure port A
-   trisb = 0x00;'''
+   trisa = 0x00;'''
-this line sets the control register for port b: called trisb to all 0's ( every bit = 0 ). 0 makes the bit an output bit, that is the pin connected to port pin is an output pin. To find what pins this is on the chip look in the 877 manual The 0x means that the number is expressed in hexadecimal or base 16. You can also use regular decimal, or binary. In binary you can clearly see each bit.
+this line sets the control register for port a: called trisa to all 0's ( every bit = 0 ). 0 makes the bit an output bit, that is the pin connected to port pin is an output pin. To find what pins this is on the chip look in the 877 manual The 0x means that the number is expressed in hexadecimal or base 16. You can also use regular decimal, or binary. In binary you can clearly see each bit.
 x0 is 0b0 in binary or 0b00000000 the last notation showing all 8 bits in the byte.
@@ Line 502: / Line 502: @@
-Lots of PIC Links use page search on PICIntro, and/or Tutorial, and/or Info for more or less instructional materials.
+Lots of PIC Links [[PIC Links]] use page search on PICIntro, and/or Tutorial, and/or Info for more or less instructional materials.
-* [[PIC Links]]
-* [[Use C for PIC Programming!]]
-* [[BoostC tiny Wiki]]
-* [[BitWacker PIC and Other Microcontroller to Java Communications]]
-* [[A Tutorial on PIC interrupts using BoostC including Example Programs]]
-* [[PIC Programmers, In Circuit Programming and BootLoaders]]
@@ Line 519: / Line 513: @@
 Programming in C: A Tutorial - Brian W. Kernighan - Bell Laboratories, Murray Hill, N. J. http://www.lysator.liu.se/c/bwk-tutor.html
-* [[Microcontroller]]
 == Appendix: What you Need for this Project  ==
@@ Line 561: / Line 553: @@
 CF1 This capacitor helps smooth out ripple and noise in the output. 50 micro F should do.
 CF2 This capacitor helps smooth out high frequency in the output. Normally capacitors like this are placed close to the power pins of each integrated circuit. A ceramic capacitor of .1 or .01 micro F should serve.
-[[category:Microcontroller]][[category:PIC]]