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 #include "i2c_api.h"
00024 
00025 #if DEVICE_I2C_ASYNCH
00026 #include "CThunk.h"
00027 #include "dma_api.h"
00028 #include "FunctionPointer.h"
00029 #endif
00030 
00031 namespace mbed {
00032 
00033 /** An I2C Master, used for communicating with I2C slave devices
00034  *
00035  * Example:
00036  * @code
00037  * // Read from I2C slave at address 0x62
00038  *
00039  * #include "mbed.h"
00040  *
00041  * I2C i2c(p28, p27);
00042  *
00043  * int main() {
00044  *     int address = 0x62;
00045  *     char data[2];
00046  *     i2c.read(address, data, 2);
00047  * }
00048  * @endcode
00049  */
00050 class I2C {
00051 
00052 public:
00053     enum RxStatus {
00054         NoData,
00055         MasterGeneralCall,
00056         MasterWrite,
00057         MasterRead
00058     };
00059 
00060     enum Acknowledge {
00061         NoACK = 0,
00062         ACK   = 1
00063     };
00064 
00065     /** Create an I2C Master interface, connected to the specified pins
00066      *
00067      *  @param sda I2C data line pin
00068      *  @param scl I2C clock line pin
00069      */
00070     I2C(PinName sda, PinName scl);
00071 
00072     /** Set the frequency of the I2C interface
00073      *
00074      *  @param hz The bus frequency in hertz
00075      */
00076     void frequency(int hz);
00077 
00078     /** Read from an I2C slave
00079      *
00080      * Performs a complete read transaction. The bottom bit of
00081      * the address is forced to 1 to indicate a read.
00082      *
00083      *  @param address 8-bit I2C slave address [ addr | 1 ]
00084      *  @param data Pointer to the byte-array to read data in to
00085      *  @param length Number of bytes to read
00086      *  @param repeated Repeated start, true - don't send stop at end
00087      *
00088      *  @returns
00089      *       0 on success (ack),
00090      *   non-0 on failure (nack)
00091      */
00092     int read(int address, char *data, int length, bool repeated = false);
00093 
00094     /** Read a single byte from the I2C bus
00095      *
00096      *  @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
00097      *
00098      *  @returns
00099      *    the byte read
00100      */
00101     int read(int ack);
00102 
00103     /** Write to an I2C slave
00104      *
00105      * Performs a complete write transaction. The bottom bit of
00106      * the address is forced to 0 to indicate a write.
00107      *
00108      *  @param address 8-bit I2C slave address [ addr | 0 ]
00109      *  @param data Pointer to the byte-array data to send
00110      *  @param length Number of bytes to send
00111      *  @param repeated Repeated start, true - do not send stop at end
00112      *
00113      *  @returns
00114      *       0 on success (ack),
00115      *   non-0 on failure (nack)
00116      */
00117     int write(int address, const char *data, int length, bool repeated = false);
00118 
00119     /** Write single byte out on the I2C bus
00120      *
00121      *  @param data data to write out on bus
00122      *
00123      *  @returns
00124      *    '1' if an ACK was received,
00125      *    '0' otherwise
00126      */
00127     int write(int data);
00128 
00129     /** Creates a start condition on the I2C bus
00130      */
00131 
00132     void start(void);
00133 
00134     /** Creates a stop condition on the I2C bus
00135      */
00136     void stop(void);
00137 
00138 #if DEVICE_I2C_ASYNCH
00139 
00140     /** Start non-blocking I2C transfer.
00141      *
00142      * @param address   8/10 bit I2c slave address
00143      * @param tx_buffer The TX buffer with data to be transfered
00144      * @param tx_length The length of TX buffer
00145      * @param rx_buffer The RX buffer which is used for received data
00146      * @param rx_length The length of RX buffer
00147      * @param event     The logical OR of events to modify
00148      * @param callback  The event callback function
00149      * @param repeated Repeated start, true - do not send stop at end
00150      * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
00151      */
00152     int transfer(int address, 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);
00153 
00154     /** Abort the on-going I2C transfer
00155      */
00156     void abort_transfer();
00157 protected:
00158     void irq_handler_asynch(void);
00159     event_callback_t  _callback;
00160     CThunk<I2C> _irq;
00161     DMAUsage _usage;
00162 #endif
00163 
00164 protected:
00165     void aquire();
00166 
00167     i2c_t _i2c;
00168     static I2C  *_owner;
00169     int         _hz;
00170 };
00171 
00172 } // namespace mbed
00173 
00174 #endif
00175 
00176 #endif