Forums

Dummy C18 question re using header files

Started by DTJ October 10, 2014
Hopefully someone can point me in the right direction without too much 
mirth......


I'm using an generic 4x16 LCD with a Pic + MPLAB +  C18 free compiler.

I need to use the xlcd.h header file.

The xlcd.h file is supplied with the C18 package and seems to be where 
pins for the LCD control etc are defined.




Do I simply copy this file into the project directory and edit it?


It would seem foolish to edit the supplied xlcd.h file and leave it in 
the the MCC18/h folder right?

On 10/9/2014 11:57 PM, DTJ wrote:
> I'm using an generic 4x16 LCD with a Pic + MPLAB + C18 free compiler. > > I need to use the xlcd.h header file. > > The xlcd.h file is supplied with the C18 package and seems to be where pins for > the LCD control etc are defined. > > Do I simply copy this file into the project directory and edit it?
Why do you want to edit it? Are the definitions contained therein inappropriate to your design? Or, do you want to *augment* them?
> It would seem foolish to edit the supplied xlcd.h file and leave it in the the > MCC18/h folder right?
Yes. Unless you have found a problem in the "original", best bet is to leave it pristine. If you *have* found a problem (i.e., error), then that would be the right place to correct it. But, do so in a manner that preserves the original "error" as a commentary with suitable documentation to indicate why *your* fix is correct. Also, report it to the Microchip folks (who may take the opportunity to correct you on YOUR correction! :> )
On 10-Oct-14 3:26 PM, Don Y wrote:
> On 10/9/2014 11:57 PM, DTJ wrote: >> I'm using an generic 4x16 LCD with a Pic + MPLAB + C18 free compiler. >> >> I need to use the xlcd.h header file. >> >> The xlcd.h file is supplied with the C18 package and seems to be where >> pins for >> the LCD control etc are defined. >> >> Do I simply copy this file into the project directory and edit it? > > Why do you want to edit it? Are the definitions contained therein > inappropriate to your design? Or, do you want to *augment* them? > >> It would seem foolish to edit the supplied xlcd.h file and leave it in >> the the >> MCC18/h folder right? > > Yes. Unless you have found a problem in the "original", best bet is to > leave > it pristine. > > If you *have* found a problem (i.e., error), then that would be the right > place to correct it. But, do so in a manner that preserves the original > "error" as a commentary with suitable documentation to indicate why *your* > fix is correct. > > Also, report it to the Microchip folks (who may take the opportunity to > correct you on YOUR correction! :> ) > >
Below is a sample from the C18 xlcd.h file: Looking at it I figured I had to edit the file to change the pin allocations etc. Can I avoid this by using the following definitions for the data port and RW lines etc after the include for the xlcd.h? #define DATA_PORT PORTn //<< put my port here #define RW_PIN LATnbits.LATnx /* PORT for RW */ #define TRIS_RW TRISnbits.TRISnx /* TRIS for RW */ My apologies if this is as clear as mud! Thanks. // SAMPLE FROM XLCD.H FILE BELOW /* When in 4-bit interface define if the data is in the upper * or lower nibble. For lower nibble, comment the #define UPPER */ /* #define UPPER */ /* DATA_PORT defines the port to which the LCD data lines are connected */ #define DATA_PORT PORTC #define TRIS_DATA_PORT TRISC /* CTRL_PORT defines the port where the control lines are connected. * These are just samples, change to match your application. */ #define RW_PIN LATBbits.LATB4 /* PORT for RW */ #define TRIS_RW TRISBbits.TRISB4 /* TRIS for RW */ #define RS_PIN LATBbits.LATB5 /* PORT for RS */ #define TRIS_RS TRISBbits.TRISB5 /* TRIS for RS */ #define E_PIN LATBbits.LATB3 /* PORT for D */ #define TRIS_E TRISBbits.TRISB3 /* TRIS for E */
DTJ, your puzzlement is well-founded.
Let me try to help...

Microchip's headers and software stacks for various devices are not at all like libraries most software engineers expect. They do not have clear interfaces, nor well-encapsulated configuration parameters. Those subsystems where they've attempted to provide encapsulation for easy integration into differing chips and configurations don't do so consistently.

For example: The USB stack needs configuration for port, pins, hardware features implemented - but does not provide any consistency of naming, nor does it parameterize things like buffer size for CDC character buffers.

So... You'll usually need to make copies of the provided (just-for-guidance claims the manufacturer) software and edit it. And heaven help you when the next release shows up with bug-fixes you'll want.

This state of affairs is not unique to Microchip ;-( Because of the extreme non-regularity of peripheral interfaces, it is hard to make this stuff easily parameterizable. Quick - where are the bits controlling interrupts for serial port 3? Sorry, no relation to those for serial port 2. Good luck making simply parameterized driver code.

Really, you're not losing your mind, its rather a muddle you're wading into...

Hope that helps!
Best Regards, Dave
On 10/10/2014 1:54 AM, DTJ wrote:
> On 10-Oct-14 3:26 PM, Don Y wrote: >> On 10/9/2014 11:57 PM, DTJ wrote: >>> I'm using an generic 4x16 LCD with a Pic + MPLAB + C18 free compiler. >>> >>> I need to use the xlcd.h header file. >>> >>> The xlcd.h file is supplied with the C18 package and seems to be where >>> pins for >>> the LCD control etc are defined. >>> >>> Do I simply copy this file into the project directory and edit it? >> >> Why do you want to edit it? Are the definitions contained therein >> inappropriate to your design? Or, do you want to *augment* them? >> >>> It would seem foolish to edit the supplied xlcd.h file and leave it in >>> the the >>> MCC18/h folder right? >> >> Yes. Unless you have found a problem in the "original", best bet is to >> leave >> it pristine. >> >> If you *have* found a problem (i.e., error), then that would be the right >> place to correct it. But, do so in a manner that preserves the original >> "error" as a commentary with suitable documentation to indicate why *your* >> fix is correct. >> >> Also, report it to the Microchip folks (who may take the opportunity to >> correct you on YOUR correction! :> ) > > Below is a sample from the C18 xlcd.h file: > > Looking at it I figured I had to edit the file to change the pin allocations etc.
Yes. This is not describing something *intrinsic* to a particular MCU. E.g., if there was a port that had specific hardware capabilities (like an A/DC, for example) then the constants used to define and access it would be invariant across all "applications" using that MCU. In this case, they are just showing an example of how you *could* connect a particular device (LCD in this case) to some *generic* port on the MCU. As such, if you choose to attach the LCD in YOUR design to some other port, then obviously the definitions that they have settled upon would not apply. In this case, you should make a copy of the original file -- in some *local* directory (specific to your application) -- and modify it to reflect the hardware configuration that you have settled upon. Leaving the original in its original form and location allows any examples built with *those* assumptions to remain intact.
> Can I avoid this by using the following definitions for the data port and RW > lines etc after the include for the xlcd.h? > > #define DATA_PORT PORTn //<< put my port here > > #define RW_PIN LATnbits.LATnx /* PORT for RW */ > #define TRIS_RW TRISnbits.TRISnx /* TRIS for RW */
Just use a copy of the original as a *template*. Then, be sure to specify YOUR "local" xlcd.h (perhaps "mylcd.h") to ensure the compiler doesn't silently drag in the ORIGINAL file, instead! In which case, you would be left scratching your head wondering why your code doesn't work (unless you were REALLY observant and looked at the actual code being executed to determine that the "wrong" port was being accessed -- i.e., avoid debugging your sources unless you know that the object truly reflects them... and not what you *think*!)
> My apologies if this is as clear as mud! Thanks. > > // SAMPLE FROM XLCD.H FILE BELOW > > > /* When in 4-bit interface define if the data is in the upper > * or lower nibble. For lower nibble, comment the #define UPPER > */ > /* #define UPPER */ > > /* DATA_PORT defines the port to which the LCD data lines are connected */ > #define DATA_PORT PORTC > #define TRIS_DATA_PORT TRISC
You would adjust these values ("PORTC" and "TRISC") to reflect the actual port onto whcih you have hung YOUR device. In your LOCAL copy of this file!
> /* CTRL_PORT defines the port where the control lines are connected. > * These are just samples, change to match your application.
------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> */ > #define RW_PIN LATBbits.LATB4 /* PORT for RW */ > #define TRIS_RW TRISBbits.TRISB4 /* TRIS for RW */ > > #define RS_PIN LATBbits.LATB5 /* PORT for RS */ > #define TRIS_RS TRISBbits.TRISB5 /* TRIS for RS */ > > #define E_PIN LATBbits.LATB3 /* PORT for D */ > #define TRIS_E TRISBbits.TRISB3 /* TRIS for E */
Similarly. You might find it helpful to add some textual commentary at the start of this file wherein you explain (in casual language) what the hardware looks like: "pin 7 (Read/Write) of the LCD is connected to pin 23 (PortB.7) of the MCU. It indicates the direction of data transfered." So, if you encounter problems with the hardware appearing unresponsive, you can go back and double check your schematic against the notes; and, the notes against your #define's. Typos always seem to slip in despite your best intentions.
Dave Nadler <drn@nadler.com> wrote in
news:1da5804c-367a-4f8f-b8f9-1b6cde58905c@googlegroups.com: 

> DTJ, your puzzlement is well-founded. > Let me try to help... > > Microchip's headers and software stacks for various devices are not at > all like libraries most software engineers expect. They do not have > clear interfaces, nor well-encapsulated configuration parameters. > Those subsystems where they've attempted to provide encapsulation for > easy integration into differing chips and configurations don't do so > consistently. > > For example: The USB stack needs configuration for port, pins, > hardware features implemented - but does not provide any consistency > of naming, nor does it parameterize things like buffer size for CDC > character buffers. > > So... You'll usually need to make copies of the provided > (just-for-guidance claims the manufacturer) software and edit it. And > heaven help you when the next release shows up with bug-fixes you'll > want. > > This state of affairs is not unique to Microchip ;-( Because of the > extreme non-regularity of peripheral interfaces, it is hard to make > this stuff easily parameterizable. Quick - where are the bits > controlling interrupts for serial port 3? Sorry, no relation to those > for serial port 2. Good luck making simply parameterized driver code. > > Really, you're not losing your mind, its rather a muddle you're wading > into... >
Its worse than that for the XLCD files. The pin allocations are compiled into the library so you either have to modify the original xlcd.h and rebuild the library every time you change the hardware or copy all the XLCD source and header files into your project and patch all of them to use the xlcd.h from your project folder. There's an open topic at the moment on the Microchip forum for XLCD with Xc8: <http://www.microchip.com/forums/m825533.aspx> The situation with C18 will be similar, but the details of what must be done to avoid having to duplicate everything will differ.
On Friday, October 10, 2014 9:16:03 PM UTC+2, Ian Malcolm wrote:
> Dave Nadler wrote in > news:1da5804c-367a-4f8f-b8f9-1b6cde58905c@googlegroups.com: > > DTJ, your puzzlement is well-founded. > > Let me try to help... > > > > Microchip's headers and software stacks for various devices are not at > > all like libraries most software engineers expect. They do not have > > clear interfaces, nor well-encapsulated configuration parameters. > > Those subsystems where they've attempted to provide encapsulation for > > easy integration into differing chips and configurations don't do so > > consistently. > > > > For example: The USB stack needs configuration for port, pins, > > hardware features implemented - but does not provide any consistency > > of naming, nor does it parameterize things like buffer size for CDC > > character buffers. > > > > So... You'll usually need to make copies of the provided > > (just-for-guidance claims the manufacturer) software and edit it. And > > heaven help you when the next release shows up with bug-fixes you'll > > want. > > > > This state of affairs is not unique to Microchip ;-( Because of the > > extreme non-regularity of peripheral interfaces, it is hard to make > > this stuff easily parameterizable. Quick - where are the bits > > controlling interrupts for serial port 3? Sorry, no relation to those > > for serial port 2. Good luck making simply parameterized driver code. > > > > Really, you're not losing your mind, its rather a muddle you're wading > > into... > > Its worse than that for the XLCD files. The pin allocations are compiled > into the library so you either have to modify the original xlcd.h and > rebuild the library every time you change the hardware or copy all the > XLCD source and header files into your project and patch all of them to > use the xlcd.h from your project folder. > > There's an open topic at the moment on the Microchip forum for XLCD with > Xc8: <http://www.microchip.com/forums/m825533.aspx> > The situation with C18 will be similar, but the details of what must be > done to avoid having to duplicate everything will differ.
Right - Change all function names and globals to something distinct (add a prefix), to avoid anything in the library getting dragged in. Actually best if you completely avoid their libraries other than RTL. Staggering lack of software development understanding over there... Don't bother to complain; they'll just tell you these software components are only for illustration. Other manufacturers aren't much better. I'll spare you the current crop of villains on my desk! One notable GOOD implementation of support software I've used is drivers built into ROM in NXP's M0 devices; used without the slightest excitement. Now if only they'd document things like: - Are these functions thread-safe? - Reentrant? - Interrupt-safe? Dream on I guess... Hope all this helps, Best Regards, Dave
<snipped>

> > Yes. This is not describing something *intrinsic* to a particular MCU. > E.g., if there was a port that had specific hardware capabilities > (like an A/DC, for example) then the constants used to define and access > it would be invariant across all "applications" using that MCU. > > In this case, they are just showing an example of how you *could* connect > a particular device (LCD in this case) to some *generic* port on the MCU. > As such, if you choose to attach the LCD in YOUR design to some other > port, then obviously the definitions that they have settled upon would > not apply. > > In this case, you should make a copy of the original file -- in some > *local* > directory (specific to your application) -- and modify it to reflect the > hardware configuration that you have settled upon. > > Leaving the original in its original form and location allows any examples > built with *those* assumptions to remain intact. > >> Can I avoid this by using the following definitions for the data port >> and RW >> lines etc after the include for the xlcd.h? >> >> #define DATA_PORT PORTn //<< put my port here >> >> #define RW_PIN LATnbits.LATnx /* PORT for RW */ >> #define TRIS_RW TRISnbits.TRISnx /* TRIS for RW */ > > Just use a copy of the original as a *template*. Then, be sure to specify > YOUR "local" xlcd.h (perhaps "mylcd.h") to ensure the compiler doesn't > silently drag in the ORIGINAL file, instead! In which case, you would > be left scratching your head wondering why your code doesn't work (unless > you were REALLY observant and looked at the actual code being executed to > determine that the "wrong" port was being accessed -- i.e., avoid debugging > your sources unless you know that the object truly reflects them... and not > what you *think*!) > >> My apologies if this is as clear as mud! Thanks. >> >> // SAMPLE FROM XLCD.H FILE BELOW >> >> >> /* When in 4-bit interface define if the data is in the upper >> * or lower nibble. For lower nibble, comment the #define UPPER >> */ >> /* #define UPPER */ >> >> /* DATA_PORT defines the port to which the LCD data lines are >> connected */ >> #define DATA_PORT PORTC >> #define TRIS_DATA_PORT TRISC > > You would adjust these values ("PORTC" and "TRISC") to reflect the > actual port onto whcih you have hung YOUR device. > > In your LOCAL copy of this file! > >> /* CTRL_PORT defines the port where the control lines are connected. >> * These are just samples, change to match your application. > ------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ >> */ >> #define RW_PIN LATBbits.LATB4 /* PORT for RW */ >> #define TRIS_RW TRISBbits.TRISB4 /* TRIS for RW */ >> >> #define RS_PIN LATBbits.LATB5 /* PORT for RS */ >> #define TRIS_RS TRISBbits.TRISB5 /* TRIS for RS */ >> >> #define E_PIN LATBbits.LATB3 /* PORT for D */ >> #define TRIS_E TRISBbits.TRISB3 /* TRIS for E */ > > Similarly. > > You might find it helpful to add some textual commentary at the start > of this file wherein you explain (in casual language) what the hardware > looks like: > "pin 7 (Read/Write) of the LCD is connected to pin 23 (PortB.7) of > the MCU. It indicates the direction of data transfered." > So, if you encounter problems with the hardware appearing unresponsive, > you can go back and double check your schematic against the notes; and, > the notes against your #define's. Typos always seem to slip in despite > your best intentions. >
Many thanks for the reply and suggestions Don.
On 11-Oct-14 3:51 AM, Dave Nadler wrote:
> On Friday, October 10, 2014 9:16:03 PM UTC+2, Ian Malcolm wrote: >> Dave Nadler wrote in >> news:1da5804c-367a-4f8f-b8f9-1b6cde58905c@googlegroups.com: >>> DTJ, your puzzlement is well-founded. >>> Let me try to help... >>> >>> Microchip's headers and software stacks for various devices are not at >>> all like libraries most software engineers expect. They do not have >>> clear interfaces, nor well-encapsulated configuration parameters. >>> Those subsystems where they've attempted to provide encapsulation for >>> easy integration into differing chips and configurations don't do so >>> consistently. >>> >>> For example: The USB stack needs configuration for port, pins, >>> hardware features implemented - but does not provide any consistency >>> of naming, nor does it parameterize things like buffer size for CDC >>> character buffers. >>> >>> So... You'll usually need to make copies of the provided >>> (just-for-guidance claims the manufacturer) software and edit it. And >>> heaven help you when the next release shows up with bug-fixes you'll >>> want. >>> >>> This state of affairs is not unique to Microchip ;-( Because of the >>> extreme non-regularity of peripheral interfaces, it is hard to make >>> this stuff easily parameterizable. Quick - where are the bits >>> controlling interrupts for serial port 3? Sorry, no relation to those >>> for serial port 2. Good luck making simply parameterized driver code. >>> >>> Really, you're not losing your mind, its rather a muddle you're wading >>> into... >> >> Its worse than that for the XLCD files. The pin allocations are compiled >> into the library so you either have to modify the original xlcd.h and >> rebuild the library every time you change the hardware or copy all the >> XLCD source and header files into your project and patch all of them to >> use the xlcd.h from your project folder. >> >> There's an open topic at the moment on the Microchip forum for XLCD with >> Xc8: <http://www.microchip.com/forums/m825533.aspx> >> The situation with C18 will be similar, but the details of what must be >> done to avoid having to duplicate everything will differ. > > Right - Change all function names and globals to something distinct (add a prefix), to avoid anything in the library getting dragged in. Actually best > if you completely avoid their libraries other than RTL. Staggering lack > of software development understanding over there... Don't bother to complain; > they'll just tell you these software components are only for illustration. > > Other manufacturers aren't much better. > I'll spare you the current crop of villains on my desk! > > One notable GOOD implementation of support software I've used is > drivers built into ROM in NXP's M0 devices; used without the > slightest excitement. Now if only they'd document things like: > - Are these functions thread-safe? > - Reentrant? > - Interrupt-safe? > Dream on I guess... > > Hope all this helps, > Best Regards, Dave >
Many thanks for your suggestions Dave and Ian. The microchip forum thread makes interesting reading. It sounds like there are issues with the 4 bit mode (which I'm trying to use). It might be worth bit-banging it all myself. Cheers gentlemen.