Thor Hall / mbed-dev_mbed_lib_v125

This fork captures the mbed lib v125 for ease of integration into older projects.

Fork of mbed-dev by mbed official

api/I2C.h@187:92cbb9eec47b, 2018-07-20 (annotated)

Committer:
apluscw
Date:
Fri Jul 20 21:24:42 2018 +0000
Revision:
187:92cbb9eec47b
Mbed library with source code from mbed lib v125. Posted to ease integration with some older projects.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
apluscw 187:92cbb9eec47b 1 /* mbed Microcontroller Library
apluscw 187:92cbb9eec47b 2 * Copyright (c) 2006-2015 ARM Limited
apluscw 187:92cbb9eec47b 3 *
apluscw 187:92cbb9eec47b 4 * Licensed under the Apache License, Version 2.0 (the "License");
apluscw 187:92cbb9eec47b 5 * you may not use this file except in compliance with the License.
apluscw 187:92cbb9eec47b 6 * You may obtain a copy of the License at
apluscw 187:92cbb9eec47b 7 *
apluscw 187:92cbb9eec47b 8 * http://www.apache.org/licenses/LICENSE-2.0
apluscw 187:92cbb9eec47b 9 *
apluscw 187:92cbb9eec47b 10 * Unless required by applicable law or agreed to in writing, software
apluscw 187:92cbb9eec47b 11 * distributed under the License is distributed on an "AS IS" BASIS,
apluscw 187:92cbb9eec47b 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
apluscw 187:92cbb9eec47b 13 * See the License for the specific language governing permissions and
apluscw 187:92cbb9eec47b 14 * limitations under the License.
apluscw 187:92cbb9eec47b 15 */
apluscw 187:92cbb9eec47b 16 #ifndef MBED_I2C_H
apluscw 187:92cbb9eec47b 17 #define MBED_I2C_H
apluscw 187:92cbb9eec47b 18
apluscw 187:92cbb9eec47b 19 #include "platform.h"
apluscw 187:92cbb9eec47b 20
apluscw 187:92cbb9eec47b 21 #if DEVICE_I2C
apluscw 187:92cbb9eec47b 22
apluscw 187:92cbb9eec47b 23 #include "i2c_api.h"
apluscw 187:92cbb9eec47b 24 #include "SingletonPtr.h"
apluscw 187:92cbb9eec47b 25 #include "PlatformMutex.h"
apluscw 187:92cbb9eec47b 26
apluscw 187:92cbb9eec47b 27 #if DEVICE_I2C_ASYNCH
apluscw 187:92cbb9eec47b 28 #include "CThunk.h"
apluscw 187:92cbb9eec47b 29 #include "dma_api.h"
apluscw 187:92cbb9eec47b 30 #include "FunctionPointer.h"
apluscw 187:92cbb9eec47b 31 #endif
apluscw 187:92cbb9eec47b 32
apluscw 187:92cbb9eec47b 33 namespace mbed {
apluscw 187:92cbb9eec47b 34
apluscw 187:92cbb9eec47b 35 /** An I2C Master, used for communicating with I2C slave devices
apluscw 187:92cbb9eec47b 36 *
apluscw 187:92cbb9eec47b 37 * @Note Synchronization level: Thread safe
apluscw 187:92cbb9eec47b 38 *
apluscw 187:92cbb9eec47b 39 * Example:
apluscw 187:92cbb9eec47b 40 * @code
apluscw 187:92cbb9eec47b 41 * // Read from I2C slave at address 0x62
apluscw 187:92cbb9eec47b 42 *
apluscw 187:92cbb9eec47b 43 * #include "mbed.h"
apluscw 187:92cbb9eec47b 44 *
apluscw 187:92cbb9eec47b 45 * I2C i2c(p28, p27);
apluscw 187:92cbb9eec47b 46 *
apluscw 187:92cbb9eec47b 47 * int main() {
apluscw 187:92cbb9eec47b 48 * int address = 0x62;
apluscw 187:92cbb9eec47b 49 * char data[2];
apluscw 187:92cbb9eec47b 50 * i2c.read(address, data, 2);
apluscw 187:92cbb9eec47b 51 * }
apluscw 187:92cbb9eec47b 52 * @endcode
apluscw 187:92cbb9eec47b 53 */
apluscw 187:92cbb9eec47b 54 class I2C {
apluscw 187:92cbb9eec47b 55
apluscw 187:92cbb9eec47b 56 public:
apluscw 187:92cbb9eec47b 57 enum RxStatus {
apluscw 187:92cbb9eec47b 58 NoData,
apluscw 187:92cbb9eec47b 59 MasterGeneralCall,
apluscw 187:92cbb9eec47b 60 MasterWrite,
apluscw 187:92cbb9eec47b 61 MasterRead
apluscw 187:92cbb9eec47b 62 };
apluscw 187:92cbb9eec47b 63
apluscw 187:92cbb9eec47b 64 enum Acknowledge {
apluscw 187:92cbb9eec47b 65 NoACK = 0,
apluscw 187:92cbb9eec47b 66 ACK = 1
apluscw 187:92cbb9eec47b 67 };
apluscw 187:92cbb9eec47b 68
apluscw 187:92cbb9eec47b 69 /** Create an I2C Master interface, connected to the specified pins
apluscw 187:92cbb9eec47b 70 *
apluscw 187:92cbb9eec47b 71 * @param sda I2C data line pin
apluscw 187:92cbb9eec47b 72 * @param scl I2C clock line pin
apluscw 187:92cbb9eec47b 73 */
apluscw 187:92cbb9eec47b 74 I2C(PinName sda, PinName scl);
apluscw 187:92cbb9eec47b 75
apluscw 187:92cbb9eec47b 76 /** Set the frequency of the I2C interface
apluscw 187:92cbb9eec47b 77 *
apluscw 187:92cbb9eec47b 78 * @param hz The bus frequency in hertz
apluscw 187:92cbb9eec47b 79 */
apluscw 187:92cbb9eec47b 80 void frequency(int hz);
apluscw 187:92cbb9eec47b 81
apluscw 187:92cbb9eec47b 82 /** Read from an I2C slave
apluscw 187:92cbb9eec47b 83 *
apluscw 187:92cbb9eec47b 84 * Performs a complete read transaction. The bottom bit of
apluscw 187:92cbb9eec47b 85 * the address is forced to 1 to indicate a read.
apluscw 187:92cbb9eec47b 86 *
apluscw 187:92cbb9eec47b 87 * @param address 8-bit I2C slave address [ addr | 1 ]
apluscw 187:92cbb9eec47b 88 * @param data Pointer to the byte-array to read data in to
apluscw 187:92cbb9eec47b 89 * @param length Number of bytes to read
apluscw 187:92cbb9eec47b 90 * @param repeated Repeated start, true - don't send stop at end
apluscw 187:92cbb9eec47b 91 *
apluscw 187:92cbb9eec47b 92 * @returns
apluscw 187:92cbb9eec47b 93 * 0 on success (ack),
apluscw 187:92cbb9eec47b 94 * non-0 on failure (nack)
apluscw 187:92cbb9eec47b 95 */
apluscw 187:92cbb9eec47b 96 int read(int address, char *data, int length, bool repeated = false);
apluscw 187:92cbb9eec47b 97
apluscw 187:92cbb9eec47b 98 /** Read a single byte from the I2C bus
apluscw 187:92cbb9eec47b 99 *
apluscw 187:92cbb9eec47b 100 * @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
apluscw 187:92cbb9eec47b 101 *
apluscw 187:92cbb9eec47b 102 * @returns
apluscw 187:92cbb9eec47b 103 * the byte read
apluscw 187:92cbb9eec47b 104 */
apluscw 187:92cbb9eec47b 105 int read(int ack);
apluscw 187:92cbb9eec47b 106
apluscw 187:92cbb9eec47b 107 /** Write to an I2C slave
apluscw 187:92cbb9eec47b 108 *
apluscw 187:92cbb9eec47b 109 * Performs a complete write transaction. The bottom bit of
apluscw 187:92cbb9eec47b 110 * the address is forced to 0 to indicate a write.
apluscw 187:92cbb9eec47b 111 *
apluscw 187:92cbb9eec47b 112 * @param address 8-bit I2C slave address [ addr | 0 ]
apluscw 187:92cbb9eec47b 113 * @param data Pointer to the byte-array data to send
apluscw 187:92cbb9eec47b 114 * @param length Number of bytes to send
apluscw 187:92cbb9eec47b 115 * @param repeated Repeated start, true - do not send stop at end
apluscw 187:92cbb9eec47b 116 *
apluscw 187:92cbb9eec47b 117 * @returns
apluscw 187:92cbb9eec47b 118 * 0 on success (ack),
apluscw 187:92cbb9eec47b 119 * non-0 on failure (nack)
apluscw 187:92cbb9eec47b 120 */
apluscw 187:92cbb9eec47b 121 int write(int address, const char *data, int length, bool repeated = false);
apluscw 187:92cbb9eec47b 122
apluscw 187:92cbb9eec47b 123 /** Write single byte out on the I2C bus
apluscw 187:92cbb9eec47b 124 *
apluscw 187:92cbb9eec47b 125 * @param data data to write out on bus
apluscw 187:92cbb9eec47b 126 *
apluscw 187:92cbb9eec47b 127 * @returns
apluscw 187:92cbb9eec47b 128 * '1' if an ACK was received,
apluscw 187:92cbb9eec47b 129 * '0' otherwise
apluscw 187:92cbb9eec47b 130 */
apluscw 187:92cbb9eec47b 131 int write(int data);
apluscw 187:92cbb9eec47b 132
apluscw 187:92cbb9eec47b 133 /** Creates a start condition on the I2C bus
apluscw 187:92cbb9eec47b 134 */
apluscw 187:92cbb9eec47b 135
apluscw 187:92cbb9eec47b 136 void start(void);
apluscw 187:92cbb9eec47b 137
apluscw 187:92cbb9eec47b 138 /** Creates a stop condition on the I2C bus
apluscw 187:92cbb9eec47b 139 */
apluscw 187:92cbb9eec47b 140 void stop(void);
apluscw 187:92cbb9eec47b 141
apluscw 187:92cbb9eec47b 142 /** Acquire exclusive access to this I2C bus
apluscw 187:92cbb9eec47b 143 */
apluscw 187:92cbb9eec47b 144 virtual void lock(void);
apluscw 187:92cbb9eec47b 145
apluscw 187:92cbb9eec47b 146 /** Release exclusive access to this I2C bus
apluscw 187:92cbb9eec47b 147 */
apluscw 187:92cbb9eec47b 148 virtual void unlock(void);
apluscw 187:92cbb9eec47b 149
apluscw 187:92cbb9eec47b 150 virtual ~I2C() {
apluscw 187:92cbb9eec47b 151 // Do nothing
apluscw 187:92cbb9eec47b 152 }
apluscw 187:92cbb9eec47b 153
apluscw 187:92cbb9eec47b 154 #if DEVICE_I2C_ASYNCH
apluscw 187:92cbb9eec47b 155
apluscw 187:92cbb9eec47b 156 /** Start non-blocking I2C transfer.
apluscw 187:92cbb9eec47b 157 *
apluscw 187:92cbb9eec47b 158 * @param address 8/10 bit I2c slave address
apluscw 187:92cbb9eec47b 159 * @param tx_buffer The TX buffer with data to be transfered
apluscw 187:92cbb9eec47b 160 * @param tx_length The length of TX buffer in bytes
apluscw 187:92cbb9eec47b 161 * @param rx_buffer The RX buffer which is used for received data
apluscw 187:92cbb9eec47b 162 * @param rx_length The length of RX buffer in bytes
apluscw 187:92cbb9eec47b 163 * @param event The logical OR of events to modify
apluscw 187:92cbb9eec47b 164 * @param callback The event callback function
apluscw 187:92cbb9eec47b 165 * @param repeated Repeated start, true - do not send stop at end
apluscw 187:92cbb9eec47b 166 * @return Zero if the transfer has started, or -1 if I2C peripheral is busy
apluscw 187:92cbb9eec47b 167 */
apluscw 187:92cbb9eec47b 168 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);
apluscw 187:92cbb9eec47b 169
apluscw 187:92cbb9eec47b 170 /** Abort the on-going I2C transfer
apluscw 187:92cbb9eec47b 171 */
apluscw 187:92cbb9eec47b 172 void abort_transfer();
apluscw 187:92cbb9eec47b 173 protected:
apluscw 187:92cbb9eec47b 174 void irq_handler_asynch(void);
apluscw 187:92cbb9eec47b 175 event_callback_t _callback;
apluscw 187:92cbb9eec47b 176 CThunk<I2C> _irq;
apluscw 187:92cbb9eec47b 177 DMAUsage _usage;
apluscw 187:92cbb9eec47b 178 #endif
apluscw 187:92cbb9eec47b 179
apluscw 187:92cbb9eec47b 180 protected:
apluscw 187:92cbb9eec47b 181 void aquire();
apluscw 187:92cbb9eec47b 182
apluscw 187:92cbb9eec47b 183 i2c_t _i2c;
apluscw 187:92cbb9eec47b 184 static I2C *_owner;
apluscw 187:92cbb9eec47b 185 int _hz;
apluscw 187:92cbb9eec47b 186 static SingletonPtr<PlatformMutex> _mutex;
apluscw 187:92cbb9eec47b 187 };
apluscw 187:92cbb9eec47b 188
apluscw 187:92cbb9eec47b 189 } // namespace mbed
apluscw 187:92cbb9eec47b 190
apluscw 187:92cbb9eec47b 191 #endif
apluscw 187:92cbb9eec47b 192
apluscw 187:92cbb9eec47b 193 #endif