Renato Grottesi / mbed-dev-bin

Microbit as a BLE gamepad

Dependents:   microbit-dal

Fork of mbed-dev-bin by Lancaster University

i2c_api.h@4:bb4b3734941b, 2017-01-30 (annotated)

Committer:
rengro01
Date:
Mon Jan 30 08:23:23 2017 +0000
Revision:
4:bb4b3734941b
Parent:
0:e1a608bb55e8 
Microbit as a BLE gamepad

Who changed what in which revision?

UserRevisionLine numberNew contents of line
jamesadevine 0:e1a608bb55e8 1 /* mbed Microcontroller Library
jamesadevine 0:e1a608bb55e8 2 * Copyright (c) 2006-2015 ARM Limited
jamesadevine 0:e1a608bb55e8 3 *
jamesadevine 0:e1a608bb55e8 4 * Licensed under the Apache License, Version 2.0 (the "License");
jamesadevine 0:e1a608bb55e8 5 * you may not use this file except in compliance with the License.
jamesadevine 0:e1a608bb55e8 6 * You may obtain a copy of the License at
jamesadevine 0:e1a608bb55e8 7 *
jamesadevine 0:e1a608bb55e8 8 * http://www.apache.org/licenses/LICENSE-2.0
jamesadevine 0:e1a608bb55e8 9 *
jamesadevine 0:e1a608bb55e8 10 * Unless required by applicable law or agreed to in writing, software
jamesadevine 0:e1a608bb55e8 11 * distributed under the License is distributed on an "AS IS" BASIS,
jamesadevine 0:e1a608bb55e8 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
jamesadevine 0:e1a608bb55e8 13 * See the License for the specific language governing permissions and
jamesadevine 0:e1a608bb55e8 14 * limitations under the License.
jamesadevine 0:e1a608bb55e8 15 */
jamesadevine 0:e1a608bb55e8 16 #ifndef MBED_I2C_API_H
jamesadevine 0:e1a608bb55e8 17 #define MBED_I2C_API_H
jamesadevine 0:e1a608bb55e8 18
jamesadevine 0:e1a608bb55e8 19 #include "device.h"
jamesadevine 0:e1a608bb55e8 20 #include "buffer.h"
jamesadevine 0:e1a608bb55e8 21
jamesadevine 0:e1a608bb55e8 22 #if DEVICE_I2C
jamesadevine 0:e1a608bb55e8 23
jamesadevine 0:e1a608bb55e8 24 /**
jamesadevine 0:e1a608bb55e8 25 * @defgroup I2CEvents I2C Events Macros
jamesadevine 0:e1a608bb55e8 26 *
jamesadevine 0:e1a608bb55e8 27 * @{
jamesadevine 0:e1a608bb55e8 28 */
jamesadevine 0:e1a608bb55e8 29 #define I2C_EVENT_ERROR (1 << 1)
jamesadevine 0:e1a608bb55e8 30 #define I2C_EVENT_ERROR_NO_SLAVE (1 << 2)
jamesadevine 0:e1a608bb55e8 31 #define I2C_EVENT_TRANSFER_COMPLETE (1 << 3)
jamesadevine 0:e1a608bb55e8 32 #define I2C_EVENT_TRANSFER_EARLY_NACK (1 << 4)
jamesadevine 0:e1a608bb55e8 33 #define I2C_EVENT_ALL (I2C_EVENT_ERROR | I2C_EVENT_TRANSFER_COMPLETE | I2C_EVENT_ERROR_NO_SLAVE | I2C_EVENT_TRANSFER_EARLY_NACK)
jamesadevine 0:e1a608bb55e8 34
jamesadevine 0:e1a608bb55e8 35 /**@}*/
jamesadevine 0:e1a608bb55e8 36
jamesadevine 0:e1a608bb55e8 37 #if DEVICE_I2C_ASYNCH
jamesadevine 0:e1a608bb55e8 38 /** Asynch i2c hal structure
jamesadevine 0:e1a608bb55e8 39 */
jamesadevine 0:e1a608bb55e8 40 typedef struct {
jamesadevine 0:e1a608bb55e8 41 struct i2c_s i2c; /**< Target specific i2c structure */
jamesadevine 0:e1a608bb55e8 42 struct buffer_s tx_buff; /**< Tx buffer */
jamesadevine 0:e1a608bb55e8 43 struct buffer_s rx_buff; /**< Rx buffer */
jamesadevine 0:e1a608bb55e8 44 } i2c_t;
jamesadevine 0:e1a608bb55e8 45
jamesadevine 0:e1a608bb55e8 46 #else
jamesadevine 0:e1a608bb55e8 47 /** Non-asynch i2c hal structure
jamesadevine 0:e1a608bb55e8 48 */
jamesadevine 0:e1a608bb55e8 49 typedef struct i2c_s i2c_t;
jamesadevine 0:e1a608bb55e8 50
jamesadevine 0:e1a608bb55e8 51 #endif
jamesadevine 0:e1a608bb55e8 52
jamesadevine 0:e1a608bb55e8 53 enum {
jamesadevine 0:e1a608bb55e8 54 I2C_ERROR_NO_SLAVE = -1,
jamesadevine 0:e1a608bb55e8 55 I2C_ERROR_BUS_BUSY = -2
jamesadevine 0:e1a608bb55e8 56 };
jamesadevine 0:e1a608bb55e8 57
jamesadevine 0:e1a608bb55e8 58 #ifdef __cplusplus
jamesadevine 0:e1a608bb55e8 59 extern "C" {
jamesadevine 0:e1a608bb55e8 60 #endif
jamesadevine 0:e1a608bb55e8 61
jamesadevine 0:e1a608bb55e8 62 /**
jamesadevine 0:e1a608bb55e8 63 * \defgroup GeneralI2C I2C Configuration Functions
jamesadevine 0:e1a608bb55e8 64 * @{
jamesadevine 0:e1a608bb55e8 65 */
jamesadevine 0:e1a608bb55e8 66
jamesadevine 0:e1a608bb55e8 67 /** Initialize the I2C peripheral. It sets the default parameters for I2C
jamesadevine 0:e1a608bb55e8 68 * peripheral, and configure its specifieds pins.
jamesadevine 0:e1a608bb55e8 69 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 70 * @param sda The sda pin
jamesadevine 0:e1a608bb55e8 71 * @param scl The scl pin
jamesadevine 0:e1a608bb55e8 72 */
jamesadevine 0:e1a608bb55e8 73 void i2c_init(i2c_t *obj, PinName sda, PinName scl);
jamesadevine 0:e1a608bb55e8 74
jamesadevine 0:e1a608bb55e8 75 /** Configure the I2C frequency.
jamesadevine 0:e1a608bb55e8 76 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 77 * @param hz Frequency in Hz
jamesadevine 0:e1a608bb55e8 78 */
jamesadevine 0:e1a608bb55e8 79 void i2c_frequency(i2c_t *obj, int hz);
jamesadevine 0:e1a608bb55e8 80
jamesadevine 0:e1a608bb55e8 81 /** Send START command.
jamesadevine 0:e1a608bb55e8 82 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 83 */
jamesadevine 0:e1a608bb55e8 84 int i2c_start(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 85
jamesadevine 0:e1a608bb55e8 86 /** Send STOP command.
jamesadevine 0:e1a608bb55e8 87 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 88 */
jamesadevine 0:e1a608bb55e8 89 int i2c_stop(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 90
jamesadevine 0:e1a608bb55e8 91 /** Blocking reading data.
jamesadevine 0:e1a608bb55e8 92 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 93 * @param address 7-bit address (last bit is 1)
jamesadevine 0:e1a608bb55e8 94 * @param data The buffer for receiving
jamesadevine 0:e1a608bb55e8 95 * @param length Number of bytes to read
jamesadevine 0:e1a608bb55e8 96 * @param stop Stop to be generated after the transfer is done
jamesadevine 0:e1a608bb55e8 97 * @return Number of read bytes
jamesadevine 0:e1a608bb55e8 98 */
jamesadevine 0:e1a608bb55e8 99 int i2c_read(i2c_t *obj, int address, char *data, int length, int stop);
jamesadevine 0:e1a608bb55e8 100
jamesadevine 0:e1a608bb55e8 101 /** Blocking sending data.
jamesadevine 0:e1a608bb55e8 102 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 103 * @param address 7-bit address (last bit is 0)
jamesadevine 0:e1a608bb55e8 104 * @param data The buffer for sending
jamesadevine 0:e1a608bb55e8 105 * @param length Number of bytes to wrte
jamesadevine 0:e1a608bb55e8 106 * @param stop Stop to be generated after the transfer is done
jamesadevine 0:e1a608bb55e8 107 * @return Number of written bytes
jamesadevine 0:e1a608bb55e8 108 */
jamesadevine 0:e1a608bb55e8 109 int i2c_write(i2c_t *obj, int address, const char *data, int length, int stop);
jamesadevine 0:e1a608bb55e8 110
jamesadevine 0:e1a608bb55e8 111 /** Reset I2C peripheral. TODO: The action here. Most of the implementation sends stop().
jamesadevine 0:e1a608bb55e8 112 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 113 */
jamesadevine 0:e1a608bb55e8 114 void i2c_reset(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 115
jamesadevine 0:e1a608bb55e8 116 /** Read one byte.
jamesadevine 0:e1a608bb55e8 117 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 118 * @param last Acknoledge
jamesadevine 0:e1a608bb55e8 119 * @return The read byte
jamesadevine 0:e1a608bb55e8 120 */
jamesadevine 0:e1a608bb55e8 121 int i2c_byte_read(i2c_t *obj, int last);
jamesadevine 0:e1a608bb55e8 122
jamesadevine 0:e1a608bb55e8 123 /** Write one byte.
jamesadevine 0:e1a608bb55e8 124 * @param obj The i2c object
jamesadevine 0:e1a608bb55e8 125 * @param data Byte to be written
jamesadevine 0:e1a608bb55e8 126 * @return 1 if NAK was received, 0 if ACK was received, 2 for timeout.
jamesadevine 0:e1a608bb55e8 127 */
jamesadevine 0:e1a608bb55e8 128 int i2c_byte_write(i2c_t *obj, int data);
jamesadevine 0:e1a608bb55e8 129
jamesadevine 0:e1a608bb55e8 130 /**@}*/
jamesadevine 0:e1a608bb55e8 131
jamesadevine 0:e1a608bb55e8 132 #if DEVICE_I2CSLAVE
jamesadevine 0:e1a608bb55e8 133
jamesadevine 0:e1a608bb55e8 134 /**
jamesadevine 0:e1a608bb55e8 135 * \defgroup SynchI2C Synchronous I2C Hardware Abstraction Layer for slave
jamesadevine 0:e1a608bb55e8 136 * @{
jamesadevine 0:e1a608bb55e8 137 */
jamesadevine 0:e1a608bb55e8 138
jamesadevine 0:e1a608bb55e8 139 /** Configure I2C as slave or master.
jamesadevine 0:e1a608bb55e8 140 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 141 * @return non-zero if a value is available
jamesadevine 0:e1a608bb55e8 142 */
jamesadevine 0:e1a608bb55e8 143 void i2c_slave_mode(i2c_t *obj, int enable_slave);
jamesadevine 0:e1a608bb55e8 144
jamesadevine 0:e1a608bb55e8 145 /** Check to see if the I2C slave has been addressed.
jamesadevine 0:e1a608bb55e8 146 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 147 * @return The status - 1 - read addresses, 2 - write to all slaves,
jamesadevine 0:e1a608bb55e8 148 * 3 write addressed, 0 - the slave has not been addressed
jamesadevine 0:e1a608bb55e8 149 */
jamesadevine 0:e1a608bb55e8 150 int i2c_slave_receive(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 151
jamesadevine 0:e1a608bb55e8 152 /** Configure I2C as slave or master.
jamesadevine 0:e1a608bb55e8 153 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 154 * @return non-zero if a value is available
jamesadevine 0:e1a608bb55e8 155 */
jamesadevine 0:e1a608bb55e8 156 int i2c_slave_read(i2c_t *obj, char *data, int length);
jamesadevine 0:e1a608bb55e8 157
jamesadevine 0:e1a608bb55e8 158 /** Configure I2C as slave or master.
jamesadevine 0:e1a608bb55e8 159 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 160 * @return non-zero if a value is available
jamesadevine 0:e1a608bb55e8 161 */
jamesadevine 0:e1a608bb55e8 162 int i2c_slave_write(i2c_t *obj, const char *data, int length);
jamesadevine 0:e1a608bb55e8 163
jamesadevine 0:e1a608bb55e8 164 /** Configure I2C address.
jamesadevine 0:e1a608bb55e8 165 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 166 * @param idx Currently not used
jamesadevine 0:e1a608bb55e8 167 * @param address The address to be set
jamesadevine 0:e1a608bb55e8 168 * @param mask Currently not used
jamesadevine 0:e1a608bb55e8 169 */
jamesadevine 0:e1a608bb55e8 170 void i2c_slave_address(i2c_t *obj, int idx, uint32_t address, uint32_t mask);
jamesadevine 0:e1a608bb55e8 171
jamesadevine 0:e1a608bb55e8 172 #endif
jamesadevine 0:e1a608bb55e8 173
jamesadevine 0:e1a608bb55e8 174 /**@}*/
jamesadevine 0:e1a608bb55e8 175
jamesadevine 0:e1a608bb55e8 176 #if DEVICE_I2C_ASYNCH
jamesadevine 0:e1a608bb55e8 177
jamesadevine 0:e1a608bb55e8 178 /**
jamesadevine 0:e1a608bb55e8 179 * \defgroup AsynchI2C Asynchronous I2C Hardware Abstraction Layer
jamesadevine 0:e1a608bb55e8 180 * @{
jamesadevine 0:e1a608bb55e8 181 */
jamesadevine 0:e1a608bb55e8 182
jamesadevine 0:e1a608bb55e8 183 /** Start i2c asynchronous transfer.
jamesadevine 0:e1a608bb55e8 184 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 185 * @param tx The buffer to send
jamesadevine 0:e1a608bb55e8 186 * @param tx_length The number of words to transmit
jamesadevine 0:e1a608bb55e8 187 * @param rx The buffer to receive
jamesadevine 0:e1a608bb55e8 188 * @param rx_length The number of words to receive
jamesadevine 0:e1a608bb55e8 189 * @param address The address to be set - 7bit or 9 bit
jamesadevine 0:e1a608bb55e8 190 * @param stop If true, stop will be generated after the transfer is done
jamesadevine 0:e1a608bb55e8 191 * @param handler The I2C IRQ handler to be set
jamesadevine 0:e1a608bb55e8 192 * @param hint DMA hint usage
jamesadevine 0:e1a608bb55e8 193 */
jamesadevine 0:e1a608bb55e8 194 void i2c_transfer_asynch(i2c_t *obj, const void *tx, size_t tx_length, void *rx, size_t rx_length, uint32_t address, uint32_t stop, uint32_t handler, uint32_t event, DMAUsage hint);
jamesadevine 0:e1a608bb55e8 195
jamesadevine 0:e1a608bb55e8 196 /** The asynchronous IRQ handler
jamesadevine 0:e1a608bb55e8 197 * @param obj The I2C object which holds the transfer information
jamesadevine 0:e1a608bb55e8 198 * @return event flags if a transfer termination condition was met or 0 otherwise.
jamesadevine 0:e1a608bb55e8 199 */
jamesadevine 0:e1a608bb55e8 200 uint32_t i2c_irq_handler_asynch(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 201
jamesadevine 0:e1a608bb55e8 202 /** Attempts to determine if I2C peripheral is already in use.
jamesadevine 0:e1a608bb55e8 203 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 204 * @return non-zero if the I2C module is active or zero if it is not
jamesadevine 0:e1a608bb55e8 205 */
jamesadevine 0:e1a608bb55e8 206 uint8_t i2c_active(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 207
jamesadevine 0:e1a608bb55e8 208 /** Abort ongoing asynchronous transaction.
jamesadevine 0:e1a608bb55e8 209 * @param obj The I2C object
jamesadevine 0:e1a608bb55e8 210 */
jamesadevine 0:e1a608bb55e8 211 void i2c_abort_asynch(i2c_t *obj);
jamesadevine 0:e1a608bb55e8 212
jamesadevine 0:e1a608bb55e8 213 #endif
jamesadevine 0:e1a608bb55e8 214
jamesadevine 0:e1a608bb55e8 215 /**@}*/
jamesadevine 0:e1a608bb55e8 216
jamesadevine 0:e1a608bb55e8 217 #ifdef __cplusplus
jamesadevine 0:e1a608bb55e8 218 }
jamesadevine 0:e1a608bb55e8 219 #endif
jamesadevine 0:e1a608bb55e8 220
jamesadevine 0:e1a608bb55e8 221 #endif
jamesadevine 0:e1a608bb55e8 222
jamesadevine 0:e1a608bb55e8 223 #endif