Mistake on this page?
Report an issue in GitHub or email us
I2C.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef MBED_I2C_H
18 #define MBED_I2C_H
19 
20 #include "platform/platform.h"
21 #include "hal/gpio_api.h"
22 
23 #if DEVICE_I2C || defined(DOXYGEN_ONLY)
24 
25 #include "hal/i2c_api.h"
26 #include "platform/SingletonPtr.h"
27 #include "platform/PlatformMutex.h"
28 #include "platform/NonCopyable.h"
29 
30 #if DEVICE_I2C_ASYNCH
31 #include "platform/CThunk.h"
32 #include "hal/dma_api.h"
33 #include "platform/Callback.h"
34 #endif
35 
36 namespace mbed {
37 /** \defgroup drivers-public-api-i2c I2C
38  * \ingroup drivers-public-api
39  */
40 
41 /**
42  * \defgroup drivers_I2C I2C class
43  * \ingroup drivers-public-api-i2c
44  * @{
45  */
46 
47 /** An I2C Master, used for communicating with I2C slave devices
48  *
49  * @note Synchronization level: Thread safe
50  *
51  * Example:
52  * @code
53  * Read temperature from LM75BD
54  * #include "mbed.h"
55  * I2C i2c(I2C_SDA , I2C_SCL);
56  * const int addr7bit = 0x48; // 7-bit I2C address
57  * const int addr8bit = 0x48 << 1; // 8-bit I2C address, 0x90
58  *
59  * int main() {
60  * char cmd[2];
61  * while (1) {
62  * cmd[0] = 0x01;
63  * cmd[1] = 0x00;
64  *
65  * // read and write takes the 8-bit version of the address.
66  * // set up configuration register (at 0x01)
67  * i2c.write(addr8bit, cmd, 2);
68  *
69  * ThisThread::sleep_for(500);
70  *
71  * // read temperature register
72  * cmd[0] = 0x00;
73  * i2c.write(addr8bit, cmd, 1);
74  * i2c.read( addr8bit, cmd, 2);
75  *
76  * float tmp = (float((cmd[0]<<8)|cmd[1]) / 256.0);
77  * printf("Temp = %.2f\n", tmp);
78  * }
79  * }
80  * @endcode
81  */
82 class I2C : private NonCopyable<I2C> {
83 
84 public:
85  enum RxStatus {
86  NoData,
87  MasterGeneralCall,
88  MasterWrite,
89  MasterRead
90  };
91 
92  enum Acknowledge {
93  NoACK = 0,
94  ACK = 1
95  };
96 
97  /** Create an I2C Master interface, connected to the specified pins
98  *
99  * @param sda I2C data line pin
100  * @param scl I2C clock line pin
101  */
102  I2C(PinName sda, PinName scl);
103 
104  /** Create an I2C Master interface, connected to the specified pins
105  *
106  * @param static_pinmap reference to structure which holds static pinmap.
107  */
108  I2C(const i2c_pinmap_t &static_pinmap);
109  I2C(const i2c_pinmap_t &&) = delete; // prevent passing of temporary objects
110 
111  /** Set the frequency of the I2C interface
112  *
113  * @param hz The bus frequency in hertz
114  */
115  void frequency(int hz);
116 
117  /** Read from an I2C slave
118  *
119  * Performs a complete read transaction. The bottom bit of
120  * the address is forced to 1 to indicate a read.
121  *
122  * @param address 8-bit I2C slave address [ addr | 1 ]
123  * @param data Pointer to the byte-array to read data in to
124  * @param length Number of bytes to read
125  * @param repeated Repeated start, true - don't send stop at end
126  * default value is false.
127  *
128  * @returns
129  * 0 on success (ack),
130  * nonzero on failure (nack)
131  */
132  int read(int address, char *data, int length, bool repeated = false);
133 
134  /** Read a single byte from the I2C bus
135  *
136  * @param ack indicates if the byte is to be acknowledged (1 = acknowledge)
137  *
138  * @returns
139  * the byte read
140  */
141  int read(int ack);
142 
143  /** Write to an I2C slave
144  *
145  * Performs a complete write transaction. The bottom bit of
146  * the address is forced to 0 to indicate a write.
147  *
148  * @param address 8-bit I2C slave address [ addr | 0 ]
149  * @param data Pointer to the byte-array data to send
150  * @param length Number of bytes to send
151  * @param repeated Repeated start, true - do not send stop at end
152  * default value is false.
153  *
154  * @returns
155  * 0 on success (ack),
156  * nonzero on failure (nack)
157  */
158  int write(int address, const char *data, int length, bool repeated = false);
159 
160  /** Write single byte out on the I2C bus
161  *
162  * @param data data to write out on bus
163  *
164  * @returns
165  * '0' - NAK was received
166  * '1' - ACK was received,
167  * '2' - timeout
168  */
169  int write(int data);
170 
171  /** Creates a start condition on the I2C bus
172  */
173  void start(void);
174 
175  /** Creates a stop condition on the I2C bus
176  */
177  void stop(void);
178 
179  /** Acquire exclusive access to this I2C bus
180  */
181  virtual void lock(void);
182 
183  /** Release exclusive access to this I2C bus
184  */
185  virtual void unlock(void);
186 
187  virtual ~I2C()
188  {
189  // Do nothing
190  }
191 
192 #if DEVICE_I2C_ASYNCH
193 
194  /** Start nonblocking I2C transfer.
195  *
196  * This function locks the deep sleep until any event has occurred
197  *
198  * @param address 8/10 bit I2C slave address
199  * @param tx_buffer The TX buffer with data to be transferred
200  * @param tx_length The length of TX buffer in bytes
201  * @param rx_buffer The RX buffer, which is used for received data
202  * @param rx_length The length of RX buffer in bytes
203  * @param event The logical OR of events to modify
204  * @param callback The event callback function
205  * @param repeated Repeated start, true - do not send stop at end
206  * default value is false.
207  *
208  * @returns Zero if the transfer has started, or -1 if I2C peripheral is busy
209  */
210  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);
211 
212  /** Abort the ongoing I2C transfer
213  */
214  void abort_transfer();
215 
216 #if !defined(DOXYGEN_ONLY)
217 protected:
218  /** Lock deep sleep only if it is not yet locked */
219  void lock_deep_sleep();
220 
221  /** Unlock deep sleep only if it has been locked */
222  void unlock_deep_sleep();
223 
224  void irq_handler_asynch(void);
225  event_callback_t _callback;
226  CThunk<I2C> _irq;
227  DMAUsage _usage;
228  bool _deep_sleep_locked;
229 #endif
230 #endif
231 
232 #if !defined(DOXYGEN_ONLY)
233 protected:
234 
235  i2c_t _i2c;
236  int _hz;
238  PinName _sda;
239  PinName _scl;
240 
241 private:
242  /** Recover I2C bus, when stuck with SDA low
243  * @note : Initialization of I2C bus is required after this API.
244  *
245  * @param sda I2C data line pin
246  * @param scl I2C clock line pin
247  *
248  * @returns
249  * '0' - Successfully recovered
250  * 'I2C_ERROR_BUS_BUSY' - In case of failure
251  *
252  */
253  int recover(PinName sda, PinName scl);
254 #endif
255 };
256 
257 /** @}*/
258 
259 } // namespace mbed
260 
261 #endif
262 
263 #endif
void frequency(int hz)
Set the frequency of the I2C interface.
virtual void lock(void)
Acquire exclusive access to this I2C bus.
int write(int address, const char *data, int length, bool repeated=false)
Write to an I2C slave.
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)
Start nonblocking I2C transfer.
Asynch I2C HAL structure.
Definition: i2c_api.h:49
An I2C Master, used for communicating with I2C slave devices.
Definition: I2C.h:82
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:162
void start(void)
Creates a start condition on the I2C bus.
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
void stop(void)
Creates a stop condition on the I2C bus.
void abort_transfer()
Abort the ongoing I2C transfer.
Class for created a pointer with data bound to it.
Definition: CThunk.h:45
int read(int address, char *data, int length, bool repeated=false)
Read from an I2C slave.
Definition: ATHandler.h:46
virtual void unlock(void)
Release exclusive access to this I2C bus.
I2C(PinName sda, PinName scl)
Create an I2C Master interface, connected to the specified pins.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.