The i2c functions and macros to implement the i squared c,7-bit, standard-mode, master-mode protcol.For a description of i squared c, see "The i2c bus -and how to use it" by Philips Semiconductors.CONTENTS########1 Setting Up2 High-level Function and Macro Definitions3 Lower-level Function and Macro Definitions4 Examples1) Setting Up#############The file i2c.h should be #included into your sourcefiles. This file contains several macros which specifywhich port bits are to be used for the clock (SCL) andthe data line (SDA). These should be adjusted to suityour application. The bus time-out macro I2C_TM_SCL_TMOin i2c.h may need adjusting to suit the devices used.Some devices require relatively long time to processdata. A delay may be required in your code beforeattempting further access to these devices. If yourPIC crystal frequency is not 4MHz, you will have tomake the appropriate adjustments as detailed in delay.hfor the delays to be accurate.2) High-level Function and Macro Definitions############################################unsigned chari2c_WriteTo(unsigned char address)~~~~~~~~~~~This function is used to commence writing to a deviceon the bus. Specify the 7-bit address to which data isto be sent. The least significant bit of the argumentis ignored. The function generates a (re)start conditionand reads an acknowledge from the slave. The functionreturns TRUE if the slave did not acknowledge the addresstransfer or FALSE otherwise.unsigned chari2c_ReadFrom(unsigned char address)~~~~~~~~~~~~This function is used to commence reading from adevice on the bus. Specify the 7-bit address from whichdata is to be read. The least significant bit of theargument is ignored. The function generates a (re)startcondition and reads an acknowledge from the slave. Thefunction returns TRUE if the slave did not acknowledgethe address transfer or FALSE otherwise.signed chari2c_PutByte(unsigned char byte)~~~~~~~~~~~~This function is used to send a byte of data to thedevice which has been activated by i2c_WriteTo().The function checks the acknowledge bit returnedby the slave. The function returns I2C_ERROR if duringthe transfer a bus error occured, TRUE if the datawas not acknowledged, or FALSE if the transfer tookplace without error and was acknowledged.inti2c_GetByte(unsigned char more)~~~~~~~~~~~This function is used to read a byte of data fromthe device which has been activated by i2c_ReadFrom().The argument to this function is used to determine ifmore data is to be read from the activated device. Ifmore is I2C_LAST, or false, no acknowledge is sent, andno more data can be read from the activated deviceunless another i2c_ReadFrom() command is issued.If more is I2C_MORE, or any true value, an acknowledge issent and more data can be read from the activateddevice. The function returns the unsigned byte readfrom the activated device or I2C_ERROR if a bus erroroccured during the read operation.signed inti2c_PutString(const unsigned char *string,~~~~~~~~~~~~~       unsigned char str_len)This function is used to send a sequence of bytes tothe device which has been activated by i2c_WriteTo().The function attempts to send str_len bytes whichare read from string. If a bus error occures duringthe transfer, the function returns a negative int.The magnitude of this number is the number of byteswhich were not successfully transmitted. If theslaves fails to acknowledge a transfer, thetransmission is terminated and the functionreturns a positive number. The magnitude of thisnumber is the number of bytes which were notsuccessfully transmitted. The function returns FALSEif the all the bytes were transmitted without errorand they were all acknowledged by the slave.unsigned chari2c_GetString(unsigned char *string,~~~~~~~~~~~~~ unsigned char str_len)This function is used to obtain a sequence of bytesfrom the device which has been activated byi2c_ReadFrom(). The function attempts to read str_lenbytes which will be stored at string. If a bus erroroccurs during the transfer, the function terminatesand returns the number of bytes not successfully read.The function returns FALSE if all the data requestedwas read without error. This function indicates tothe slave that no more data is to be read aftersuccessfully reading the last byte. To read more dataafter using this function, activate the source deviceby using i2c_ReadFrom().I2C_MORE and I2C_LAST~~~~~~~~     ~~~~~~~~These macros may be used with i2c_GetByte() toindicate that more data is to be read or that thisis the last byte to be read, respectively.I2C_ERROR~~~~~~~~~This macro may be used with i2c_GetByte() andi2c_PutByte() to check for a bus error.3) Lower-level Function and Macro Definitions#############################################voidi2c_Stop(void)~~~~~~~~Sends a stop condition.voidi2c_Restart(void)~~~~~~~~~~~Sends a start condition.voidi2c_Start(void)~~~~~~~~~~~Sends a start condition. Functionally the sameas i2c_Restart().unsigned chari2c_SendByte(unsigned char byte)~~~~~~~~~~~~Sends an 8-bit number to the active device. Theacknowledge bit is not checked. Returns TRUE ifa bus error occured; FALSE otherwise.usigned chari2c_SendAddress(unsigned char address,~~~~~~~~~~~~~~~      unsigned char rw)Sends an 8-bit quantity representing a 7-bitaddress and a 1-bit read/write mode bit. ReturnsTRUE if a bus error occurred; FALSE otherwise.signed chari2c_ReadAcknowledge(void)~~~~~~~~~~~~~~~~~~~Reads the acknowledge bit from the slave.Returns I2C_ERROR if a bus error occurs, TRUE ifthe device did not acknowledge, or FALSEotherwise.inti2c_ReadByte(void)~~~~~~~~~~~~Reads an 8-bit quantity from the slave. Theacknowledge is not generated. Returns the byte orI2C_ERROR if a bus error occurred.voidi2c_SendAcknowledge(unsigned char status)~~~~~~~~~~~~~~~~~~~Sends an acknowledge if status is TRUE; sendsa ~acknowledge otherwise. A ~acknowledge is usedto indicate to the slave that no more data is tobe read and that it should release the bus so thatthe master can issue the next command.unsigned chari2c_Open(unsigned char address, unsigned char mode)~~~~~~~~Sends a 7-bit address and 1-bit read/write mode bit.Returns TRUE if the device did not acknowledge.unsigned chari2c_WaitForSCL(void)~~~~~~~~~~~~~~Waits for the clock line to be released by the slave.If the line is not released after I2C_TM_SCL_TMO microseconds, the function times out and a bus error isassumed. In this case, the function returns TRUE;FALSE otherwise.4) Examples###########i2c_WriteTo(0xAE);	/* talk to device 1010111w */i2c_PutByte(0x00);	/* send data 0x00 */i2c_ReadFrom(0xAE);	/* talk to device 1010111r */data1 = i2c_GetByte(I2C_MORE);	/* read one byte */data2 = i2c_GetByte(I2C_MORE);	/* read another */i2c_GetString(my_string, 10);	/* read 10 bytes *//* i2c_GetString() terminates reading, if more data * is required, re-address the device */i2c_ReadFrom(0xAE);data3 = i2c_GetByte(I2C_LAST);	/* last byte read *//* check for errors */if(i2c_PutByte(0xff))  my_error_routine();	/* bus error or ~ack */