Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Safer i2c #125

Open
wants to merge 12 commits into
base: master
Choose a base branch
from
56 changes: 37 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,22 +27,24 @@ Examples of *[device libraries](#libraries)* and *[complete projects](#awesome-


##### Content:
- [Summary](#summary)
- [Content:](#content)
- [Supported Boards](#supported-boards)
- [Installation](#installation)
- [Your First Project: Blinking Leds And Sensors](#your-first-project-blinking-leds-and-sensors)
- [Your First Project: Blinking leds and sensors](#your-first-project-blinking-leds-and-sensors)
- [Usage](#usage)
- [GPIO](#gpio)
- [SPI](#spi)
- [I2C](#i2c)
- [PWM](#pwm)
- [Pattern-based signal generator via PWM](#pattern-based-signal-generator-via-pwm)
- [UART](#uart)
- [1-Wire](#1-wire)
- [GPIO](#gpio)
- [SPI](#spi)
- [I2C](#i2c)
- [PWM](#pwm)
- [Pattern-based signal generator via PWM](#pattern-based-signal-generator-via-pwm)
- [UART](#uart)
- [1-Wire](#1-wire)
- [Examples](#examples)
- [Built with SwiftyGPIO](#built-with-swiftygpio)
- [Device Libraries](#libraries)
- [Awesome Projects](#awesome-projects)
- [Support Libraries](#support-libraries)
- [Libraries](#libraries)
- [Awesome Projects](#awesome-projects)
- [Support libraries](#support-libraries)
- [Additional documentation](#additional-documentation)


Expand Down Expand Up @@ -311,7 +313,23 @@ func readByte(_ address: Int) -> UInt8
func readByte(_ address: Int, command: UInt8) -> UInt8
func readWord(_ address: Int, command: UInt8) -> UInt16
func readData(_ address: Int, command: UInt8) -> [UInt8]
func readI2CData(_ address: Int, command: UInt8) -> [UInt8]
func readI2CData(_ address: Int, command: UInt8, length: UInt8) -> [UInt8]
func readRaw(_ address: Int, length: Int) -> [UInt8]
func writeAndRead(_ address: Int, write: [UInt8], readLength: UInt) -> [UInt8]

```

There are also versions of the read functions that throw an error to indicate a read failure:

```swift
func tryReadByte(_ address: Int) throws -> UInt8
func tryReadByte(_ address: Int, command: UInt8) throws -> UInt8
func tryReadWord(_ address: Int, command: UInt8) throws -> UInt16
func tryReadData(_ address: Int, command: UInt8) throws -> [UInt8]
func tryReadI2CData(_ address: Int, command: UInt8, length: UInt8) throws -> [UInt8]
func tryReadRaw(_ address: Int, length: Int) throws -> [UInt8]
func tryWriteAndRead(_ address: Int, write: [UInt8], readLength: UInt) throws -> [UInt8]

```

Reading and writing data blocks supports two modes, a standard SMBus mode (`readData` and `writeData`) that prepends the length of the block before the actual data, and an old style I2C mode (`readI2CData` and `writeI2CData`) that just send the data without additional metadata. Depending on the device, only one of the two modes will be supported.
Expand All @@ -322,16 +340,16 @@ Let's suppose that we want to read the seconds register (id 0) from a DS1307 RTC
print(i2c.readByte(0x68, command: 0)) //Prints the value of the 8bit register
```

You should choose the same way one of the write functions available, just note that `writeQuick` is used to perform quick commands and does not perform a normal write. SMBus's quick commands are usually used to turn on/off devices or perform similar tasks that don't require additional parameters.
You should choose the same way one of the write functions available, just note that `writeQuick` is used to perform quick commands and does not perform a normal write. SMBus's quick commands are usually used to turn on/off devices or perform similar tasks that don't require additional parameters. The write functions return `true` on success and `false` on failure.

```swift
func writeQuick(_ address: Int)
func writeQuick(_ address: Int) -> Bool

func writeByte(_ address: Int, value: UInt8)
func writeByte(_ address: Int, command: UInt8, value: UInt8)
func writeWord(_ address: Int, command: UInt8, value: UInt16)
func writeData(_ address: Int, command: UInt8, values: [UInt8])
func writeI2CData(_ address: Int, command: UInt8, values: [UInt8])
func writeByte(_ address: Int, value: UInt8) -> Bool
func writeByte(_ address: Int, command: UInt8, value: UInt8) -> Bool
func writeWord(_ address: Int, command: UInt8, value: UInt16) -> Bool
func writeData(_ address: Int, command: UInt8, values: [UInt8]) -> Bool
func writeI2CData(_ address: Int, command: UInt8, values: [UInt8]) -> Bool
```

While using the I2C functionality doesn't require additional software to function, the tools contained in `i2c-tools` are useful to perform I2C transactions manually to verify that everything is working correctly.
Expand Down
Loading