Editing Index of sample code pages

This page is more of an idea than a finished product, we need help to fill it out.


These are short sections of code for particular tasks.  The first goal is to get code that works.  Later goals include:

*Easily modified code..
*Robust: failure resistant even with bad input.
*Fast
*Plays well when imbeded with other routines.
*Minimum resource use.

Because of the different goals we may have more than one sample in each category.


== [[The perfect second]] ==

Timing routines, showing how seconds can be counted.  Want high accuracy even with odd clock rates.

This dudes routines will *absolutely* blow your sox off. Really.
http://www.romanblack.com/one_sec.htm

== Using I2C Memory ==


[[Using I2C Memory]]

== Output to A Shift Register ==

Often used for port expansion. 

This seems to work for 8 bits to a 74HC/HCT164

     void shiftOutByte( unsigned char aData ) {
     
     	unsigned char ix;
     
     	for( ix = 0; ix < 7; ix++ )   {
     	
     		if ( aData.1 ) {
     			set_bit( SRPort, SRDataBit );
     		} else {
          		clear_bit( SRPort, SRDataBit );
     		}
     		
     		clear_bit( SRPort, SRClockBit );   // edge triggered low to high 
     		aData  >>= 1; // put here as delay 
     		set_bit( SRPort, SRClockBit );
     	
        }
     	return;

     }

== Software Circular Buffer ==

A place to store and retrieve data, say bytes.  First in First out.  Methods to add and remove data.

This technique requires 4 components:

buffer to store data

pointer to the start of data (head)

pointer to the end of data (tail)

size of data currently in the buffer

Typically these 4 are stored in a container like struct or class and all together define a circular buffer:

  #define BUF_LEN 64
  
  struct SCircularBuffer
  {
    unsigned char data[BUF_LEN]; //buffer to store data
    unsigned char head; //head pointer (not really a pointer but index where data starts)
    unsigned char tail; //tail
    unsigned char count; //number of data bytes currently in the buffer
  };

The rules to use such buffer are simple. When some data needs to be written into the buffer:

- when new data is written into the buffer it's written byte by byte at the head position and the head position is moved forward; 

- when head reaches end of the buffer it rolls back to zero;

- data counter is incremented each time a data byte is added to the buffer.

To read data from buffer:

- check if data counter isn't zero, if it's not zero there is some data in the buffer;

- read data starting from tail position and increment tail accordingly;

- when head reaches end of the buffer it rolls back to zero;

- data counter is decremented each time a data byte is read from the buffer.

  SCircularBuffer buf;
  
  void InitBuffer( void )
  {
    buf.count = 0;
    buf.head = 0;
    buf.tail = 0; 
  }
  
  void WriteData( unsigned char dat )
  {
    buf.count++;
    buf.data[buf.head] = dat;
    if( ++buf.head == sizeof(buf.data) )
        buf.head = 0;
  }
  
  unsigned char ReadData( void )
  {
    unsigned char ret = buf.data[buf.tail];
    if( ++buf.tail == sizeof(buf.data) )
        buf.tail = 0;
    buf.count--;
  }


To use these functions one needs to initialise the buffer first. This is done inside the InitBuffer call. After this buffer is ready to be used. There is one caveat though. ReadData doesn't check if there is any data in the buffer and such check must be done every time this function is called. 
  //Init the buffer
  InitBuffer();
  //Write one byte into the buffer
  WriteData( 0x24 );
  //Read one byte from buffer
  if( buf.count )
  {
    unsigned char dat = ReadData();
    ... //do something with the data
  }    

Such functionality fits very well into the C++ techniquest and with the help of BoostC++ can be implemented like a self contained class:

  class CCircularBuffer
  {
  public:
    CCircularBuffer()
    {
    }
  
    void WriteData( unsigned char dat )
    {
        count++;
        data[head] = dat;
        if( ++head == sizeof(data) )
            head = 0;
    }
  
    unsigned char ReadData( unsigned char &dat )
    {
        if( !count )
            return false;
        dat = data[tail];
        if( ++tail == sizeof(data) )
            tail = 0;
        count--;
        return true;
    }
  
  protected:
    unsigned char data[BUF_LEN]; //buffer to store data
    unsigned char head; //head pointer (not really a pointer but index where data starts)
    unsigned char tail; //tail
    unsigned char count; //number of data bytes currently in the buffer
  };

You may notice that data availability check as well as buffer initialisation have already been included into the circular buffer class so the code that uses it becomes a bit simplier:

  //Create a circular buffer
  CCircularBuffer buf;
  //Write one byte into the buffer
  buf.WriteData( 0x24 );
  //Read one byte from buffer
  unsigned char dat;
  if( buf.ReadData( dat ) )
  {
    ... //do something with the data
  }

Why bother? A circular buffer is a good solution when it's not known when data can be read from or be written into a buffer. A good example is an interrupt driven serial port. Interrupt code reads UART and stores read data in a circular buffer and main code reads data from this buffer and processes it. Take a look at the Novo.UART sample project from SourceBoost installation. It shows how to use a circular buffer and extends design described here by making it thread safe.

== [[read before write]] ==

Solving the issue of PIC16's pin state not being saved internally.    ''' Code still needed.'''

== Good Main Program Header ==

[[A C Program Header Example]]  A good header is a help to anyone who wants to use your code.

== Using #define to Configure Hardware ==


Suppose you are lighting an LED on PORTB.3.  If you use the following defines:

    #define   LED_PORT PORTB
    #define   LED_BIT  3

then   

     set_bit( LED_PORT, LED_BIT );

can be used instead of 

     set_bit( PORTB, 3 );

There are a couple of advantages to this:

* The code is easier to read and write.
* Reconfiguring the hardware can be done simply by just changing the #defines.
* Reading the #defines ( normally all at the top of the program ) often gives a good overview of the hardware assignment.

== Using #define to Support Multiple CPU Targets ==

The compiler ( actually I think the preprocessor ) always defines a symbol that contains the name of the target processor, for example _PIC16F877A_H_.  This means you can surround code with the following preprocessor commands:

     #ifdef  _PIC16F877A_H_
          TRISA = 0b00011111;
     #endif

it will only compile if the target is a 16f877A.  This way one file can contain code for a bunch of different processors.


If you want to include more than one processor you can use code like:

     
     #if ( defined ( _PIC16F877A_H_ ) || defined ( _PIC16F877_H_ ) )
          TRISA = 0b00011111;
     #endif

== Using #define for Magic Numbers ==

A magic number is a number, that for some reason, has a special meaning.  For example the maximum number for an 8 bit number is 255, but a reader of the program might not recognize this significance.  If you:

     #define MAX_8BIT = 255

then a test like 

     if ( a == MAX_8BIT ) ....

might be more meaningfull.  ( note this is not a great example, best I could come up with right now )  You could consider that port addresses are aqctually numbers ( and different for diffent processors ) and that symbols like PORTB are actually magic numbers defined differently for different processors.

== Counting Down with Unsigned Numbers ==

You are counting down and want to know when an unsigned number goes negative ( never ).  You could declare it signed, slowing everything down.  Instead check against FF.  This assumes you do not use FF on the positive side.  It also assumes you are counting down by one, else you could skip over FF.

   if ( 0xFF == ix ) ..

== Access Bytes Inside Another Type == 

Example use a union: 

     typedef union {
          unsigned int ui;
          unsigned char b[2];
     } noportable_int;
     
     //main program starts here.    
     void main()   {
     
          noportable_int n;
     
          n.ui        = 0x1234;
     
          n.b[0]      = tmr1l;
          n.b[1]      = tmr1h;
     
     }

idea from: [http://forum.sourceboost.com/index.php?showtopic=2673&pid=10321&mode=threaded&start=#entry10321]



[[Category:BoostC]][[Category:PIC]]