decorative bevel

2.2 The Cerebellum 1.0 Library

Overview

The Cereb 1.0 Library is a collection of several CCS C header files designed to provide functions that are specifically tailored to the Cerebellum architecture. The Cerebellum Library v1.01, available in the downloads section, is comprised of the following files:
cereb104.h - Root file, encompasses basic functionality
cereb10-analog.h - Analog Input Functionality
cereb10-pwm.h - PWM and H-bridge functionality
cereb10-servo.h - Servo Routine Functionality
As we fix bugs and add new features, the root file will grow in version number(as may the sub-files). Download the latest version to have the most up to date functionality.

2.2.1 Basic Library Functions

inline void cereb_init(int flags)
     - You should call this function if you'd like to enable the built-in
       PWM, analog, and/or servo routines.  

Valid range of variable 'flags':
               0 will enable all routines (generally recommended)
  DISABLE_ANALOG will enable all routines except analog
  DISABLE_PWM    will enable all routines except PWM
  DISABLE_SERVO  will enable all routines except servo

You may use the '|' operator to combine multiple DISABLE flags.

Ex:
  cereb_init(0);                           -> normal operation, all routines enabled.
  cereb_init(DISABLE_ANALOG);              -> all routines except analog() will operate.
  cereb_init(DISABLE_PWM | DISABLE_SERVO); -> only analog routines will be available.


void set_led(int which, int value)
     - Turns an LED either on or off.

LEDon(int which)
     - Turns an LED on.
LEDoff(int which)
     - Turns an LED off.

Valid range of variable 'which':
             0 will operate on the Green LED.
	 GREEN will operate on the Green LED
      non-zero will operate on the Yellow LED.
        YELLOW will operate on the Yellow LED.

Valid range of variable 'value':
             0 will turn the relevant LED off.
      non-zero will turn the relevant LED on.

Ex:
  set_led(GREEN,1);			-> Turns the Green LED on.
  set_led(YELLOW,0);			-> Turns the Yellow LED off.
  LEDon(YELLOW);			-> Turns on the Yellow LED.
  LEDoff(GREEN);			-> Turns off the Green LED.


Buttons

int button(int which)
    - Returns the value of a button

inline void waitforbutton(int which)
    - Halts all normal program execution until a specific button is pressed

Valid range of variable 'which':
	    0 refers to BTN_A on the Cerebellum
	BTN_A refers to BTN_A on the Cerebellum
     non-zero refers to BTN_B on the Cerebellum
	BTN_B refers to BTN_B on the Cerebellum

Valid return value of int button:
            0 means that the relevant button is not pressed.
            1 means that the relevant button is pressed.

Note that waitforbutton() usually halts only the normal execution flow of the program;
interrupt routines still operate normally.  This may not be true if called from a subroutine
due to CCS Compiler limitations on interrupts and subroutines.
Note that the Button and LED pins may be overloaded - the operation of these functions is undefined when external circuits are connected to their pins. See section 3.7, User Devices, for more information. Also see section 3.1, Digital I/O, for information on overloading these pins.

2.2.2 Analog Library Functions

void analog_init()
     - Normally called by cereb_init, do not call unless you have bypassed cereb_init.

void analog_custom_init(byte ports, byte clock)
     - You may call this instead of analog_init() to setup different analog configurations.
       Refer to the CCS manual and the PIC16F877 documentation for more details.

More info on this function


unsigned int analog(int channel)
     - returns the 8-bit value read at the given channel.
       Under normal initialization, 0 corresponds to 0V, 255 to 5V, with a linear range in between.
       You must initialize the analog routine, either by calling cereb_init or analog_init, 
       before using this function.

Valid range of variable 'channel':
      0 refers to pin A0
     A0 refers to pin A0
      1 refers to pin A1
     A1 refers to pin A1
      2 refers to pin A2
     A2 refers to pin A2
      3 refers to pin A3
     A3 refers to pin A3
      4 refers to pin A5
     A5 refers to pin A5
      5 refers to pin E0
     E0 refers to pin E0
      6 refers to pin E1
     E1 refers to pin E1
      7 refers to pin E2
     E2 refers to pin E2
     
Note that analog returns an unsigned integer, in the range 0 - 255.  
A variable declared as an "int" will be signed and eight bit by default,
such that a value greater than 127 will read as a negative number.
Declare variables used for reading in analog values as "unsigned int".
For information on the hardware related to the analog input ports, see the Analog Hardware section.

2.2.3 PWM Library Functions

void pwm_init()
     - Normally called by cereb_init().  Don't call unless you have bypassed cereb_init().

set_pwm(int which,signed long int value) 
     - Sets a given h-bridge to a direction and pwm duty cycle

set_pwms(signed long int motor1_value,signed long int motor2_value)
     - Sets both h-bridges to individual directions and pwm duty cycles.

Valid range of variable 'which':
         0 Corresponds to MOT1 output pins
   MOTOR_1 Corresponds to MOT1 output pins
  non-zero Corresponds to MOT2 output pins
   MOTOR_2 Corresponds to MOT2 output pins

Valid range of variables 'value', 'motor1_value', 'motor2_value':
      -1023 Corresponds to full power on, backwards direction
          0 Corresponds to power off, backwards direction
       1023 Corresponds to full power on, forward direction
	H_MAX_SPEED corresponds to 1023.

All values in between the min and max are valid.  Any value larger in absolute
value than H_MAX_SPEED will automatically be truncated to +/- H_MAX_SPEED.
Note that the H-bridge must be jumper-configured to properly operate. See section 3.4, Motor reference, for more information. Also see 3.1, Digital I/O, for information on overloading the PWM pins.

2.2.4 Servo Library

inline void servo_init()
     - normally called by cereb_init, do not call unless you have bypassed cereb_init

void enable_servo(int which)
     - enable a specific servo

void disable_servo(int which)
     - disable a specific servo

set_servo(int which, unsigned int value)
     - set a specific servo to a given value
       A servo will not move unless it has been specifically enabled.

Valid range of variable 'which':
      0 correponds to a servo on PIN D0
      1 correponds to a servo on PIN D1
      2 correponds to a servo on PIN D2
      3 correponds to a servo on PIN D3
      4 correponds to a servo on PIN D4
      5 correponds to a servo on PIN D5
      6 correponds to a servo on PIN D6
      7 correponds to a servo on PIN D7
     >7 array out of bounds, please don't do this if you expect stability

Valid range of variable 'value':
      0 indicates that the servo should move to its minimum value
    255 indicates that the servo should move to its maximum value

Anything in between corresponds linearly.  The minimum and maximum values
may be calibrated through use of the calibration functions.


void set_servo_mask(byte mask)
     - quickly enable/disable all 8 servos in any combination

Ex:

set_servo_mask(0b00000000);              -> All D ports are normal digital I/O
set_servo_mask(0b11111111);              -> All D ports are servos
set_servo_mask(0b11110000);              -> D4-D7 servos, D3-D0 digital I/O
set_servo_mask(0b10100011);              -> D7, D5, D1, and D0 servos, rest digital I/O
 

void calibrate_servos(unsigned int offset, long int mult, long int div)
     - Set servo calibration to values as described:
    
  Servos are tuned to receive pulses.  By setting the value to 0-255,
  you achieve a range of pulse widths.  Different brands of servos sometimes
  behave differently, so it helps to be able to tune the pulses.

  The equation is as follows:

  pulse length = 6.7 us * (offset + mult*[value]/div)
  
  Using values of 82, 6, 5, you get a range of .55 ms to 2.5ms, which
  will drive a HS-311 servo in its entirety, plus a bit(avoid 253+ if you can).

  Using values of 150, 3, 5, you get a range of 1 ms to 2 ms, which is what servos
  usually get from a receiver.

  Use as necessary.  Use reset_servo_calibration() if necessary to restore to the defaults.


void reset_servo_calibration()
     - Reset to defaults
Note that the servo bus must be powered before servos will function - see the Servos section for more information.

Using Serial

The default serial settings used by the Cereb 1.04 library are Baud 115200, 8 bits, 1 stop bit, No Parity. If you'd like to change them, you'll need to use the CCS #use_serial directive. CCS supports a host of serial routines. Some of the more common ones are:
int kbhit()
Returns 1 if serial data is waiting in the buffer, 0 otherwise.
char getc()
Returns the character in the serial buffer, if any
void gets(char * arr, int len)
Fills a character array arr up to length len, or a newline
putc(char data)
Writes a single byte to the serial port
printf()
See the CCS manual for more information on printf().
Note that the serial may be configured as either TTL or RS-232 - see the Serial section for more information.

Using I2C

Before using I2C in your code, verify that the jumper is set correctly. Refer to the jumper section for more information.

In general, the PIC16F877 can be configured as an I2C master, an I2C slave, or both(multi-master mode). While we intend to create a reliable example of i2c for the examples section soon, for now, refer to the CCS documentation on the #use_i2c directive.

Timing

The PIC16F877 has several hardware timers available for use. When using the Cereb 1.04 Library, the TIMER0 module is used for accurate servo timing, and TIMER2 is used for PWM timing. This leaves the user with the most versatile timer, TIMER1.

While we intend to create a good example of a interrupt-based timer routine for the examples section soon, for now, refer to the CCS documentation about setup_timer1 and the #INT_TIMER1 directive.