AceWire 0.3.2 Unified interface for selecting different I2C implementations on Arduino platforms

Public Member Functions | List of all members
ace_wire::TwoWireInterface< T_WIRE > Class Template Reference

A thin wrapper around an I2C `TwoWire` class and its `Wire` object. More...

`#include <TwoWireInterface.h>`

## Public Member Functions
| TwoWireInterface (T_WIRE &wire)
| Constructor. More...
void | begin ()
| Initial the interface. More...
void | end ()
| End the interface. More...
uint8_t | beginTransmission (uint8_t addr)
| Prepare the write buffer to accept a sequence of data, and save the addr for transmission when `endTransmission()` is called. More...
uint8_t | write (uint8_t data)
| Write data into the write buffer. More...
uint8_t | endTransmission (bool sendStop)
| Send the data in the buffer, with a STOP condition if `sendStop` is true. More...
uint8_t | endTransmission ()
| Same as endTransmission(bool) but always send STOP condition.
uint8_t | requestFrom (uint8_t addr, uint8_t quantity, bool sendStop)
| Read bytes from the slave and store in buffer owned by T_WIRE and send a STOP condition if `sendStop` is true. More...
uint8_t | requestFrom (uint8_t addr, uint8_t quantity)
| Read bytes from the slave and store in buffer owned by T_WIRE, and always send a STOP condition. More...
uint8_t | read ()
| Read byte from buffer.
| TwoWireInterface (const TwoWireInterface &)=default
TwoWireInterface & | operator= (const TwoWireInterface &)=default

## Detailed Description

### template<typename T_WIRE>
class ace_wire::TwoWireInterface< T_WIRE >

A thin wrapper around an I2C `TwoWire` class and its `Wire` object.

This is a template class to avoid including the `<Wire.h>` header file, which increases flash memory on AVR by about 1000 byte even if the `Wire` object is never used.

This wrapper can also be used with alternative implementations of I2C (software or hardware) so long as they implement some basic API of the `TwoWire` class: specifically the `beginTransmission()`, `write()` and `endTransmission() methods. Since`TwoWireInterface` is a template, the alternative implementation classes do not need to inherit from the `TwoWire` class.

Template Parameters

  T_WIRE | underlying class that implements the I2C protocol, usually `TwoWire` from the pre-installed Wire library, but can be used with other third party libraries that look like `TwoWire`

Definition at line 50 of file TwoWireInterface.h.

## Constructor & Destructor Documentation

## ◆ TwoWireInterface()

template<typename T_WIRE >

ace_wire::TwoWireInterface< T_WIRE >::TwoWireInterface | ( | T_WIRE & | wire | ) |
| inline explicit

Constructor.

Parameters

  wire | instance of `T_WIRE`. If the pre-installed Wire.h is used, then T_WIRE is `TwoWire` and `wire` is the precreated `Wire` object

Definition at line 58 of file TwoWireInterface.h.

## Member Function Documentation

## ◆ begin()

template<typename T_WIRE >

void ace_wire::TwoWireInterface< T_WIRE >::begin | ( |  | ) |
| inline

Initial the interface.

Currently does nothing.

Definition at line 61 of file TwoWireInterface.h.

## ◆ beginTransmission()

template<typename T_WIRE >

uint8_t ace_wire::TwoWireInterface< T_WIRE >::beginTransmission | ( | uint8_t | addr | ) |
| inline

Prepare the write buffer to accept a sequence of data, and save the addr for transmission when `endTransmission()` is called.

For unbuffered implementations, immediately send the address byte on the I2C bus with the Write bit set.

Returns
  always returns 0 to indicate success because the `addr` is simply written into a buffer

Definition at line 75 of file TwoWireInterface.h.

## ◆ end()

template<typename T_WIRE >

void ace_wire::TwoWireInterface< T_WIRE >::end | ( |  | ) |
| inline

End the interface.

Currently does nothing.

Definition at line 64 of file TwoWireInterface.h.

## ◆ endTransmission()

template<typename T_WIRE >

uint8_t ace_wire::TwoWireInterface< T_WIRE >::endTransmission | ( | bool | sendStop | ) |
| inline

Send the data in the buffer, with a STOP condition if `sendStop` is true.

For unbuffered implementations, just send the STOP condition.

Returns the value returned by the underlying T_WIRE::endTransmission() method. For the preinstalled Wire library, the status value definitions are buried in the twi_writeTo() function:

- 0: success
- 1: length too long for buffer
- 2: address send, NACK received
- 3: data send, NACK received
- 4: other twi error (lost bus arbitration, bus error, ..)

Definition at line 106 of file TwoWireInterface.h.

## ◆ requestFrom() [1/2]

template<typename T_WIRE >

uint8_t ace_wire::TwoWireInterface< T_WIRE >::requestFrom | ( | uint8_t | addr,
|  | uint8_t | quantity
| ) |  |
| inline

Read bytes from the slave and store in buffer owned by T_WIRE, and always send a STOP condition.

Some I2C implementations do not provide a 3-argument version of requestFrom(), so we need to provide an explicit 2-argument versions instead of using a default argument of `sendStop = true`.

Returns
  the value returned by the underlying T_WIRE::requestFrom() method, which will normally be 'quantity' or 0 if an error is encountered.

Definition at line 140 of file TwoWireInterface.h.

## ◆ requestFrom() [2/2]

template<typename T_WIRE >

uint8_t ace_wire::TwoWireInterface< T_WIRE >::requestFrom | ( | uint8_t | addr,
|  | uint8_t | quantity,
|  | bool | sendStop
| ) |  |
| inline

Read bytes from the slave and store in buffer owned by T_WIRE and send a STOP condition if `sendStop` is true.

Returns
  the value returned by the underlying T_WIRE::requestFrom() method, which will normally be 'quantity'. Some implementations, particularly the unbuffered ones, will return 0 to indicate a NACK response from the slave device.

Definition at line 124 of file TwoWireInterface.h.

## ◆ write()

template<typename T_WIRE >

uint8_t ace_wire::TwoWireInterface< T_WIRE >::write | ( | uint8_t | data | ) |
| inline

Write data into the write buffer.

For unbuffered implementations, immediately send the address byte on the I2C bus with the Write bit set.

Returns
  the number of bytes written into buffer, will always be 1. For unbuffered implementations, 0 can be returned if the device responds with a NACK

Definition at line 88 of file TwoWireInterface.h.

The documentation for this class was generated from the following file:

- /home/brian/src/AceWire/src/ace_wire/TwoWireInterface.h