I2C.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2015 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_I2C_H
00017 #define MBED_I2C_H
00018 
00019 #include "platform.h"
00020 
00021 #if DEVICE_I2C
00022 
00023 // for 100F6 not implemented (N.S.)
00024 #undef DEVICE_I2C_ASYNCH
00025 
00026 
00027 #include "i2c_api.h"
00028 
00029 #if DEVICE_I2C_ASYNCH
00030 #include "CThunk.h"
00031 #include "dma_api.h"
00032 #include "FunctionPointer.h"
00033 #endif
00034 
00035 namespace mbed {
00036 
00037 /** An I2C Master, used for communicating with I2C slave devices
00038  *
00039  * Example:
00040  * @code
00041  * // Read from I2C slave at address 0x62
00042  *
00043  * #include "mbed.h"
00044  *
00045  * I2C i2c(p28, p27);
00046  *
00047  * int main() {
00048  *     int address = 0x62;
00049  *     char data[2];
00050  *     i2c.read(address, data, 2);
00051  * }
00052  * @endcode
00053  */
00054 class I2C {
00055 
00056 public:
00057     enum RxStatus {
00058         NoData,
00059         MasterGeneralCall,
00060         MasterWrite,
00061         MasterRead
00062     };
00063 
00064     enum Acknowledge {
00065         NoACK = 0,
00066         ACK   = 1
00067     };
00068 
00069     /** Create an I2C Master interface, connected to the specified pins
00070      *
00071      *  @param sda I2C data line pin
00072      *  @param scl I2C clock line pin
00073      */
00074     I2C(PinName sda, PinName scl);
00075 
00076     /** Set the frequency of the I2C interface
00077      *
00078      *  @param hz The bus frequency in hertz
00079      */
00080     void frequency(int hz);
00081 
00082     /** Read from an I2C slave
00083      *
00084      * Performs a complete read transaction. The bottom bit of
00085      * the address is forced to 1 to indicate a read.
00086      *
00087      *  @param address 8-bit I2C slave address [ addr | 1 ]
00088      *  @param data Pointer to the byte-array to read data in to
00089      *  @param length Number of bytes to read
00090      *  @param repeated Repeated start, true - don't send stop at end
00091      *
00092      *  @returns
00093      *       0 on success (ack),
00094      *   non-0 on failure (nack)
00095      */
00096     int read(int address, char *data, int length, bool repeated = false);
00097 
00098     /** Read a single byte from the I2C bus
00099      *
00100      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00101      *
00102      *  @returns
00103      *    the byte read
00104      */
00105     int read(int ack);
00106 
00107     /** Write to an I2C slave
00108      *
00109      * Performs a complete write transaction. The bottom bit of
00110      * the address is forced to 0 to indicate a write.
00111      *
00112      *  @param address 8-bit I2C slave address [ addr | 0 ]
00113      *  @param data Pointer to the byte-array data to send
00114      *  @param length Number of bytes to send
00115      *  @param repeated Repeated start, true - do not send stop at end
00116      *
00117      *  @returns
00118      *       0 on success (ack),
00119      *   non-0 on failure (nack)
00120      */
00121     int write(int address, const char *data, int length, bool repeated = false);
00122 
00123     /** Write single byte out on the I2C bus
00124      *
00125      *  @param data data to write out on bus
00126      *
00127      *  @returns
00128      *    '1' if an ACK was received,
00129      *    '0' otherwise
00130      */
00131     int write(int data);
00132 
00133     /** Creates a start condition on the I2C bus
00134      */
00135 
00136     void start(void);
00137 
00138     /** Creates a stop condition on the I2C bus
00139      */
00140     void stop(void);
00141 
00142 #if DEVICE_I2C_ASYNCH
00143 
00144     /** Start non-blocking I2C transfer.
00145      *
00146      * @param address   8/10 bit I2c slave address
00147      * @param tx_buffer The TX buffer with data to be transfered
00148      * @param tx_length The length of TX buffer in bytes
00149      * @param rx_buffer The RX buffer which is used for received data
00150      * @param rx_length The length of RX buffer in bytes
00151      * @param event     The logical OR of events to modify
00152      * @param callback  The event callback function
00153      * @param repeated Repeated start, true - do not send stop at end
00154      * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
00155      */
00156     int transfer(int address, const char *tx_buffer, int tx_length, char *rx_buffer, int rx_length, const event_callback_t & callback, int event = I2C_EVENT_TRANSFER_COMPLETE, bool repeated = false);
00157 
00158     /** Abort the on-going I2C transfer
00159      */
00160     void abort_transfer();
00161 protected:
00162     void irq_handler_asynch(void);
00163     event_callback_t  _callback;
00164     CThunk<I2C> _irq;
00165     DMAUsage _usage;
00166 #endif
00167 
00168 protected:
00169     void aquire();
00170 
00171     i2c_t _i2c;
00172     static I2C  *_owner;
00173     int         _hz;
00174 };
00175 
00176 } // namespace mbed
00177 
00178 #endif
00179 
00180 #endif