Libraries

From Curuxa

Contents


Along with other Curuxa tools, you have a set of libraries written in C-language available to simplify the development of your programs for microcontrollers.

These libraries are designed to work with the SDCC compiler. They provide functions that execute very common and repetitive tasks, such as setting up digital inputs/outputs or analog-to-digital converters, simple names for variable types, stopping the program for a given amount of time...

For getting a full list of available libraries and functions, run Curuxa IDE and open the libraries. All functions include a short explanation about what they do.

Some libraries and functions require a basic setup before being used. For example, before using delays you have to indicate at which frequency your microcontroller is running at. This is usually done using #define and it's always explained inside each library.

Libraries might be easier to use, but if you want to have more freedom to customize your program and learn how everything works it's recommended to include the library for the PIC directly (#include <pic16fxxx.h>) and use all the snippets you need, instead of using these libraries.

Common features

Variable types

Type Size (bits) Values
bool 8 0 or 1
int8 8 -128 to 127
unsigned int8 8 0 to 255
int16 16 -32768 to 32767
unsigned int16 16 0 to 65535
int32 32 -2147483648 to 2147483647
unsigned int32 32 0 to 4294967295
float 32


Boolean variables

Boolean variables take 8 bits of RAM but are supposed to store a single 0 or 1. It wastes some memory but this way is much more efficient.

Valid usage:

bool MyVar;
MyVar = 0;
MyVar = 1;
MyVar = true;
MyVar = false;
MyVar = TRUE;
MyVar = FALSE;


Digital I/O setup on MBP8

//set all digital pins as inputs
TRISIO=AllDigitalInputs;
 
//set all digital pins as outputs
TRISIO=AllDigitalOutputs;
 
//set a single digital pin as input
SetDigitalInput(5); //set GP5 (pin number 2) as input
 
//set a single digital pin as output
SetDigitalOutput(5); //set GP5 (pin number 2) as output


Digital I/O setup on the rest of Main Boards

//configure all bits/pins of a digital I/O port as inputs
TRISA=AllDigitalInputs; //set all PORTA bits as inputs
 
//configure all bits/pins of a digital I/O port as outputs
TRISC=AllDigitalOutputs; //set all PORTC bits as outputs
 
//configure a single digital I/O as an input
TRISB3=DigitalInput; //set RB3 as intput
 
//configure a single digital I/O as an output
TRISD1=DigitalOutput; //set RD1 as output


Configuration bits

These are individual settings that change the low-level behavior of a microcontroller. They are not stored in RAM but they are not part of your program either. They are special settings you must define so they'll get programmed into the microcontroller while you are writing a program into it.

Each microcontroller supports its own config bits, so you need to check the microcontroller's library and see which ones you can configure.

Features you can usually set:

  • Use internal, external, fast or slow oscillator
  • Reset microcontroller when supply voltage is lower than a certain level
  • Use a certain pin as a reset or as a digital I/O
  • Protect program memory so it can't be read by third-parties after you have programmed it
  • Delay the beginning of your program after the microcontroller has been powered up to avoid errors
  • Enable or disable watchdog
  • ...and many more depending on the microcontroller


Sample usage:

//models with single configuration word
ConfigBits(_CPD_OFF & _CP_OFF & _BOD_OFF  & _MCLRE_OFF & _PWRTE_ON & _WDT_OFF & _INTOSCIO);
 
//models with multiple configuration words
ConfigBits1(_CP_OFF & _DEBUG_OFF & _CPD_OFF & _LVP_OFF & _BOR_OFF & _MCLRE_OFF & _PWRTE_ON & _WDT_OFF & _INTOSCIO);
ConfigBits2(_FCMEN_OFF  & _IESO_OFF);

If you don't know which ones you should choose, use the examples provided with each Main Board: MBP8, MBP14, MBP18, MBP40...


Binary operations

  • Set a bit to one/true/high
SetBit(MyVariable,3); //bit number 3 of MyVariable


  • Set a bit to zero/false/low (clear bit)
ClearBit(MyVariable, 5); //bit number 5 of MyVariable


  • On all Main Boards but MBP8 you can access single bits of digital I/O ports as Rxy, being x the PORT letter and y the bit number
RB3=1; //set bit 3 of PORTB to one/true/high
 
bool MyVar=RA4; //read bit 4 of PORTA


  • Instead of working with Rxx, bits, zeroes, ones... you can write more readable code by using #define
//example: we have an electronic circuit which turns on a motor by setting bit 6 of PORTC to one/true/high
//...(remember to setup PORTC6 as a digital output)...
#define Motor RC6
#define Run 1
#define Stop 0
 
Motor=Run;
[...]
Motor=Stop;

...you can check other examples, such as SISW-SPST, AO-SPK...


MBP8.h, MBP18.h, MBP40.h...

Libraries designed specifically for each Main Board. You must include the library of the Main Board you are using.

These libraries provide all previously explained common features, plus some more depending on which internal peripherals each Main Board supports (ADC, timers, USART...).

Usage example:

#include <MBP40.h>

Typical functions available (open the library to see the full list):

SetIntosc31kHz
Set the internal oscillator to 31.25kHz
SetIntosc8MHz()
Set the internal oscillator to 8MHz
AdcDisable()
Disable Analog-to-Digital converter
EnableAN3()
Set AN3 as analog input, and use it as the source for the ADC conversion
AdcMeasure()
Synchcronously get the analog value on the active analog input. It waits doing nothing until the measurement is done
AdcEnableInt()
Enable ADC interrupt. An interrupt will be thrown each time an analog-to-digital conversion is finished


Delays.h

Delays are functions that keep the microcontroller doing nothing, wasting time and energy.

They are usually very inefficient. They are never the best solution for anything, but they are very common because it's the simplest and easiest way to stop the execution for a given amount of time.

Use timers and interrupts if you want to execute something else while waiting.

These functions are very inexact. For better timing use internal timers. For precission timing use Real Time Clocks.

Before using this library you must define the frequency at which the microcontroller is running.

Example of microcontroller running at 8MHz:

#define OSC_8MHz
#include <Delays.h>


Sample usage:

//...it was doing something...
DelaySec(5); //stop execution for 5 seconds
//...keep running...


Some available functions:

Delay10us()
Delay the program for 10 microseconds
Delay(x)
Delay the program for a given amount of milliseconds
DelaySec(x)
Delay the program for a given amount of seconds
DelayMin(x)
Delay the program for a given amount of minutes


The entire list of available functions can be found inside the library itself.


L293.h

Library for controlling two direct-current motors using an L293, which is the integrated circuit used in MC2A, MC2B...

Before using this library, the following defines must be set to match the digital pins your L293 is plugged to: M1Enable, M1In1, M1In2, M2Enable, M2In1, M2In2

Example:

#define M1Enable RA2
#define M1In1 RA3
#define M1In2 RA4
#define M2Enable RA1
#define M2In1 RA0
#include <L293.h>


Some of the functions available in this library:

M1Fwd()
Move motor 1 forward
M1Brake()
Brake motor 1 electrically
M2Bck()
Move motor 2 backwards