Appendix F. CCS C Program Function Reference

This is a summary of the more commonly used functions available in CCS C Version 4 (January 2007). For more details on how to use the listed functions and others not included here, visit www.ccsinfo.com for a current manual download.

The following apply to all the following tables:

1. All functions require a header file, e.g., 16F877A.H.

Table F.1. Port Input and Output (Requires Chip Header File Only, e.g., 16F877A.H)

Function	Description	Example	Comment
WRITE BYTE	Write all bits with 8-bit integer	output_A(255);	A replaced by B, C, D, or E
SET BIT	Write output bit high using pin label	output_high(PIN_A0);	A0 replaced by A1, A2, . . ., A7, B0, . . ., B7, etc.
CLEAR BIT	Write output bit low using pin label	output_low(PIN_A0);	A0 replaced by A1, A2,. . ., A7, B0, . . ., B7, etc.
READ BYTE	Read input as 8-bit integer	abyte = input_A();	A replaced by B, C, D, or E
READ BIT	Read input bit using pin label	abit = input(PIN_A0);	A0 replaced by A1, A2, . . ., A7, B0, . . ., B7, etc.
READ DIRECTION	Check port data direction register	ddra = get_tris_a();	Any parallel port ddr code can be checked
CHECK BIT	Read input bit	abit = input_state(PIN_D0);	Gets I/O bit value
BIT TOGGLE	Toggle output bit	output_toggle(PIN_D0);	Invert the logic level at the specified pin
BIT OUTPUT	Change port bit to output	output_drive(PIN_D0);	Does not change the existing bit value
FLOAT OUTPUT	Set output pin to high impedance	output_float(PIN_D0);	Allows an external source to control the line
SET PULLUPS	Switch input pull-ups on or off	port_a_pullups(TRUE);	Input floats to high value, port A or B only
SET DIRECTION	Initialize port bits for input or output	set_tris_a(0x0F);	Explicitly sets up data direction register

Table F.2. Analog Inputs (Requires #DEVICE ADC=nn)

Function	Description	Example	Comment
SETUP	Initialize ADC	setup_adc(ADC_CLOCK_INTERNAL);	All modes listed in device header file
PINS SETUP	Initialize ADC pins	setup_adc_ports(RA0_ANALOG);	All modes listed in device header file
CHANNEL SELECT	Select ADC input	set_adc_channel(0);	Channels 0–7 selected via multiplexer
READ	Read analog input	inval = read_adc();	8-bit read 0–255, 10-bit read 0–1024 (#device option)

Table F.3. Timers (Requires Chip Header File Only, e.g., 16F877A.H)

Function	Description	Example	Comment
TIMERX SETUP	Set up the timer mode	setup_timer0(RTCC_INTERNAL | RTCC_DIV_8 );	Clock source and prescale ratio
TIMERX READ	Read a timer register (8 or 16 bits)	count0 = get_timer0();	Timer numbers (0–5) valid as fitted
TIMERX WRITE	Preload a timer register (8 or 16 bits)	set_timer0(126);	Timer numbers (0–5) valid as fitted
TIMER CCP SETUP	Select PWM, Capture, or Compare mode	setup_ccp1(ccp_pwm);	See CCS manual for CCP options
TIMER PWM DUTY	Set PWM duty cycle	set_pwm1_duty(512);	512=mark count=50%

Table F.4. RS232 Serial Port (Requires #USE RS232, #USE DELAYS (Clock=nnnnnnnn))

Function	Description	Example	Comment
SET BAUD RATE	Set hardware RS232 port baud rate	setup_uart(19200);	Applies to hardware serial port only
SEND BYTE	Write a character to the default port	putc(65)	Writes ASCII data or control code to serial output
SEND SELECT	Write a character to selected port	s = fputc(“A”,01);	As preceding, but stream identifier given
PRINT SERIAL	Write a mixed message	printf(“Answer:%4.3d”,n);	Write fixed strings and formatted variable values
PRINT SELECT	Write string to selected serial port	fprintf(01,“Message”);	As preceding, but stream identifier given
PRINT STRING	Print a string and write it to array	sprintf(astr,“Ans=%d”,n);	Print and copy output to character array
RECEIVE BYTE	Read a character to an integer	n = getc();	Waits for ASCII code from serial input
RECEIVE STRING	Read an input string to character array	gets(spoint);	Reads characters into an array at address
RECEIVE SELECT	Read an input string to character array	astring = fgets(spoint,01);	As preceding, but string and stream identifier given
CHECK SERIAL	Check for serial input activity	s = kbhit();	Checks for serial input data but does not wait
PRINT ERROR	Write programmed error message	assert(a<3);	Generates an error message if condition is FALSE

Table F.5. SPI Serial Port (spi Can Be Replaced by spi2)

Function	Description	Example	Comment
SPI SETUP	Initialize SPI serial port	setup_spi(spi_master);	See CCS manual for full list of options
SPI READ	Receives data byte from SPI port	inbyte = spi_read();	Waits for 8-bit data to arrive
SPI WRITE	Sends data byte via SPI port	spi_write(outbyte);	Writes 8-bit data to SPI serial line
SPI TRANSFER	Send and receive via SPI	inbyte = spi_xfer (outbyte);	See CCS manual for variations
SPI RECEIVED	Check if SPI data received	done = spi_data_is_in();	Returns 0 for not done, 1 if done

Table F.6. I2C Serial Port (#USE I2C() If Hardware Peripheral Fitted, #DEFINE for Software Interface)

Function	Description	Example	Comment
I2C START	Issue start command in master mode	i2c_start();	Start a data transmission
I2C WRITE	Send a single byte	i2c_write(outbyte);	Send a data byte
I2C READ	Read a received byte	inbyte = i2c_read();	Read a data byte
I2C STOP	Issue a stop command in master mode	i2c_stop();	Stop the data transmission
I2C POLL	Check to see if byte received	sbit = i2c_poll();	Returns 1 if byte waiting

Table F.7. Parallel Slave Port

Function	Description	Example	Comment
PSP ENABLE	Enable or disable PSP	setup_psp(PSP_ENABLED);	PSP_DISABLED to switch offSET.
SET DIRECTION	Set the PSP data direction	set_tris_e(0);	For input arg.=0xFF, or mixed mode
OUTPUT READY	Checks if output byte is ready to go	pspo = psp_output_full();	Byte ready: pspo = 1 To write the PSP: PSP_DATA = outbyte;
INPUT READY	Checks if input byte is ready to read	pspi = psp_input_full();	Byte ready: pspi = 1 To read the PSP: inbyte = PSP_DATA;
PSP OVERFLOW	Checks for data overwrite error	pspv = psp_overflow();	Check to prevent loss of data due to external mistiming

Table F.8. LCD Control (Requires Chip Header File Only, e.g., 16F877A.H)

Function	Description	Example	Comment
LCD SETUP	Set up LCD internal control	setup_lcd(LCD_MUX12,1);	Number of control lines, clock prescale
LCD LOAD	Send display data block to LCD	lcd_load(lcddata,0,16);	Pointer, offset, number of bytes
LCD SYMBOL	Send segment bits	lcd_symbol(lcddata,dig1)	Specify segments individually

Table F.9. Register Manipulation

Function	Description	Example	Comment
REGISTER BIT SET	Set a selected bit	bit_set(num,1);	Sets bit b in integer num (8, 16, or 32 bits)
REGISTER BIT CLEAR	Clear a selected bit	bit_clear(num,2);	Clears bit b in integer num (8, 16, or 32 bits)
REGISTER BIT TEST	Test a selected bit	flag = bit_test(num,4);	Tests bit b in integer num (8, 16, or 32 bits)
REGISTER SWAP	Swap nibbles in a byte variable	swap(abyte);	Result not returned by function

Table F.10. Block Rotate

Function	Description	Example	Comment
BLOCK ROTATE LEFT	Rotates bits of structure left	rotate_left(&lobyte,6);	Address of low byte and number of bytes
BLOCK ROTATE RIGHT	Rotates bits of structure right	rotate_right(&lobyte,10);	Address of low byte and number of bytes
BLOCK SHIFT LEFT	Shift bit left into low bit of structure	shift_left(&lobyte,4,1);	Address of low byte, number of bytes, bit in
BLOCK SHIFT RIGHT	Shift bit right into high bit of structure	shift_left(&lobyte,4,1);	Address of low byte, number of bytes, bit in

Table F.11. Math Functions (#INCLUDE MATH.H)

Function	Description	Example	Comment
ABSOLUTE VALUE	Absolute value of integer	abres = abs(x);	Returns unsigned positive value of signed integer
LONG ABSOLUTE	Absolute value of long integer	longres = labs(x);	Returns unsigned positive value of 16-bit integer
FLOAT ABSOLUTE	Absolute value of float	flores = fabs(x);	Returns unsigned positive value of signed float
FLOAT CEILING	Round a float up to integer	roundup = ceil(afloat);	Returns integer from float
FLOAT FLOOR	Round a float down to integer	roundown = floor(afloat);	Returns integer from float
INTEGER DIVIDE	Integer divide	divres = div(numer,denom);	Returns a structure of quotient and remainder
LONG DIVIDE	Long integer divide	lonres = ldiv(lnumer,ldenom);	Returns a structure of quotient and remainder
EXPONENTIAL	Exponential function	expres = exp(x);	Returns exp where x is a float
LOG BASE 10	Logarithm base-10 function	logres = log10(x);	Returns log10(x) where x is a float
LOG BASE E	Logarithm base-e function	lnres = log(x);	Returns ln(x) where x is a float
DIVISION MODULUS	Modulus (remainder) of division	modres = fmod(numer,denom);	Returns remainder of float division
FRACTION MODULUS	Break up float into integer and fraction	modfres = modf(afloat,&whole);	Returns fractional part, stores integer
FRACTION EXPAND	Break up float into integer and fraction	fexres = frexp(afloat,&whole);	Returns fractional part
BINARY EXPAND	Multiply a float by integral power of 2	lexres = ldexp(afloat,sint);	Returns a float, sint is a signed integer
RAISE TO POWER	Raise float to a power	powres == pow(afloat,apower);	Returns a float raised to a power
SQUARE ROOT	Calculate the square root of a float	sqrres = sqrt(afloat);	Returns positive root
RANDOM NUMBER	Generates a pseudorandom number	any1 = rand();	Returns a random integer from sequence
RANDOM SEED	Start value for the “random” sequence	srand(seed);	seed is a new start point in the sequence

Table F.12. Trigonometric Functions (#INCLUDE MATH.H)

Function	Description	Example	Comment
SIN	Sine function	num1 = sin(a);	Returns sine of angle a given in radians
COS	Cosine function	num2 = cos(a);	Returns cosine of angle a given in radians
TAN	Tangent function	num3 = tan(a);	Returns tangent of angle a given in radians
ASIN	Arc sine function	ang1 = asin(n);	Returns the angle in radians whose sine is float n
ACOS	Arc cosine function	ang2 = acos(n);	Returns the angle in radians whose cosine is float n
ATAN	Arc tangent function	ang3 = atan(n);	Returns the angle in radians whose tangent is float n
SINH	Hyperbolic sine function	hyp1 = sinh(x);	Returns hyperbolic sine of float x
COSH	Hyperbolic cosine function	hyp2 = cosh(x);	Returns hyperbolic cosine of float x
TANH	Hyperbolic tangent function	hyp3 = tanh(x);	Returns hyperbolic tangent of float x

Table F.13. Make Integers

Function	Description	Example	Comment
MAKE BYTE	Extract a byte from long integer	mybyte = make8(num,3);	Extracts byte from 16- or 32-bit integer
MAKE WORD	Make a 16-bit integer	myword = make16(byte1,byte0);	Combine separate bytes into one integer
MAKE LONG	Make a 32-bit integer	mylong=make32(byte3,byte2,byte1,byte0);	Combine 4 bytes or two 16-bit integers

Table F.14. Type Conversions (#INCLUDE STDLIB.H)

Function	Description	Example	Comment
ASCII TO FLOAT	ASCII to float conversion	num0 == atof(decstring);	Converts a decimal number as string into float
ASCII TO INTEGER	ASCII to 8-bit integer conversion	num1 = atoi(intstring1);	Converts an integer given as string into an 8-bit integer
ASCII TO LONG	ASCII to 16-bit integer conversion	num2 = atol(intstring2);	Converts an integer given as string into a 6-bit integer
ASCII TO 32 BIT	ASCII to 32-bit integer conversion	num3 = atoi32(intstring3);	Converts an integer given as string into a 32-bit integer

Table F.15. Character Test (#INCLUDE CTYPE.H)

Function	Description	Example	Comment
ALPHANUMERIC?	Test for alphanumeric character	test = isalnum(acode);	Returns 1 if character code is in ranges 0–9, A–Z, a–z
NUMBER DIGIT?	Test for numerical digit character	test = isdigit(acode);	Returns 1 if character code is in range 0–9
LOWER CASE?	Test for lower case alphanumeric	test = islower(acode);	Returns 1 if character code is in range a–z
SPACE?	Test for space character	test = isspace(acode);	Returns 1 if character code is a space
UPPER CASE?	Test for upper case alphanumeric	test = isupper(acode);	Returns 1 if character code is in ranges A–Z
HEX DIGIT?	Test for hexadecimal digit	test = isxdigit(acode);	Returns 1 if character code is in ranges 0–9, A–F, a–f
CONTROL?	Test for control character	test = iscntrl(acode);	Returns 1 if character code is control code (00 – 1F)
GRAPHIC?	Test for printable character	test = isgraph(acode);	Returns 1 if character code is graphical (21 – 7E)
PRINTABLE?	Test for printable or space character	test = isprint(acode);	Returns 1 if character code is printable (20 – 7E)
PUNCTUATION?	Test for punctuation character	test = ispunct(acode);	Returns 1 if character code is a punctuation code

Table F.16. Search and Sort (#INCLUDE STDLIB.H)

Function	Description	Example	Comment
BINARY SEARCH	Search for given value in a data array	bsearch(k,a1,n,w,compit)	Find value k in array a1 of n elements of width w
QUICK SORT	Sort an array into ascending order	qsort(a1,n,w,sort1)	Sort array a1 of n elements of width w using function sortit

Table F.17. Processor Controls (Requires Chip Header File Only, e.g., 16F877A.H)

Function	Description	Example	Comment
GET ENVIRONMENT	Gets information about the MCU	chip = getenv(device);	Peripheral hardware, memory, configuration, etc.
GOTO ADDRESS	Jump to program memory location	goto_address(0x1FF0);	Jump in ROM, use with caution
LABEL ADDRESS	Check address of program label	labloc = label_address(start);	Labels should be used only in exceptional cases
RESET CPU	Restarts the program from 0	reset_cpu();	No return
RESTART CAUSE	Returns cause of last reset	message =restart_cause();	Messages defined in MCU header file
RESTART WATCHDOG	Clear watchdog timer	restart_wdt();	Periodical operation to prevent MCU watchdog reset
SETUP OSCILLATOR	Select internal clock mode	setup_oscillator();	MCUs with internal clock
SLEEP	Stops program and waits for reset	sleep();	Wake up on specific events

Table F.18. Interrupts (Requires Chip Header File, e.g., 16F877A.H & #INT_XXXX)

Function	Description	Example	Comment
INTERRUPT DISABLE	Disables peripheral interrupt	disable_interrupts(int_timer0);	Interrupt labels defined in device header file
INTERRUPT ENABLE	Enables peripheral interrupt	enable_interrpts(int_timer0);	Interrupt labels defined in device header file
INTERRUPT CLEAR	Clears peripheral interrupt	clear_interrupt(int_timer0);	Interrupt labels defined in device header file
INTERRUPT ACTIVE	Checks if interrupt flag is set	interrupt_active(int_timer0);	Interrupt labels defined in device header file
INTERRUPT EDGE	Selects interrupt trigger edge	ext_int_edge(H_TO_L);	Rising (L_TO_H) or falling (H_TO_L) edge
INTERRUPT JUMP	Jump to address of ISR	jump_to_isr(isr_loc);	Use to service multiple interrupts

Table F.19. Memory Read and Write

Function	Description	Example	Comment
READ RAM BANK	Read a RAM location directly	abyte = read_bank(3,0x20);	Alternative variable access
WRITE RAM BANK	Write a byte into user RAM	write_bank(3,0x20,0xFF);	Write to bank 3, address 0x20, data 0xFF
READ DATA EEPROM	Read an EEPROM location	abyte = read_eeprom(0x00);	Get byte at given address
WRITE DATA EEPROM	Write a byte into EEPROM	write_eeprom(0x1F,0x9A);	Write to nonvolatile memory address, data
READ PROGRAM ROM	Read code from program ROM	read_program_memory(0x100,copy,4);	Get block from program address, copy in RAM

Table F.20. Memory Allocation (#INCLUDE STDLIBM.H)

Function	Description	Example	Comment
MEMORY BLOCK ALLOCATE	Reserves a block of memory	ap1 = calloc(25,4);	Allocated block=25×5 bytes
MEMORY BLOCK DEALLOCATE	Releases a memory block	free(ap1);	Previously allocated at address pointer ap1
MEMORY BYTES ALLOCATE	Reserves a number of bytes	ap1 = malloc(14);	Allocated block=14 bytes
MEMORY BLOCK COPY	Copy a given number of bytes	memcpy(ap1,ap2,n);	Copy n bytes from ap1 to ap2
MEMORY BLOCK MOVE	Move a given number of bytes	memmove(ap1,ap2,n);	Move n bytes from ap1 to ap2
MEMORY BLOCK SET	Initialize locations with a given value	memset(ap1,val1, numofb);	Loads integer val1 into numof locations from ap1

Table F.21. Special Setup (Requires Chip Header File Only, e.g., 16F877A.H)

Function	Description	Example	Comment
SETUP WATCHDOG TIMER	Initialize watchdog time-out	setup_wdt(wdt_1152ms);	Time-out options from 18 ms to 2.304 sec
RESET WATCHDOG TIMER	Clear watchdog timer within the program loop	restart_wdt();	Watchdog timer is normally reset before time-out
SETUP COMPARATORS	Connection of analog comparators	setup_comparator(A0_A3_A1_A2);	Selected MCUs only
VOLTAGE REFERENCE	Specify the comparator ref. voltage	setup_vref(vref_low|10);	Options in device header file
SETUP OPAMP	Enable built in op-amp where fitted	setup_opamp1(1);	Selected MCUs only
SETUP SLEEP	Sets sleep delay time	sleep_ulpwl(time_in_us);	Selected MCUs only
LOW VOLTS DETECT	Triggers interrupt if supply low	setup_low_volt_detect(lvd_33);	Selected MCUs only

2. The numerous CAN and USB functions are not included since these interfaces are not typically available in 16 series MCUs.

3. Alternative functions for the same operation:

putc() == putchar()

getc() == getch() == getchar()

output_bit(PIN_XX,1) == output_high(PIN_XX)

output_bit(PIN_XX,0) == output_low(PIN_XX)

get_timer0() == get_rtcc();

set_timer0(nnn) == set_rtcc(nnn);

pow() == pwr()