Wire API Documentation Examples

Example Path: examples/I2C/Wire/DocExamples

Wire API Documentation Examples

Supported Platforms: SOMRT1061 MODRT1171 MODM7AE70 SBE70LC MOD5441X NANO54415

Overview

Every code example shown in the Wire Interface documentation appears in this application as working code you can build, load and run.

If you have read the TwoWire or TwoWireObject documentation and want to try one of the examples, this is the quickest way to do it without writing a project from scratch. Each example is a function you can call, modify, or copy into your own application.

Structure

The functions named DocExample_* are the documented examples. Each is wrapped in a function and given the variables the example assumes, and is otherwise unchanged from the documentation:

• DocExample_IsValid() checking a pin pair at startup
• DocExample_WriteTransaction() writing a register with beginTransmission(), write() and endTransmission()
• DocExample_RequestFrom() reading bytes with requestFrom(), available() and read()
• DocExample_SixteenBitAddress() sending a 16-bit register address by hand
• DocExample_BusScan() scanning the bus with ping()
• DocExample_WriteRegNLongForm() the long form that writeRegN() is equivalent to
• DocExample_RegisterHelpers() readRegN() and writeRegN()
• DocExample_AddressWidth() setNumAddressBytes() for 8-bit and 16-bit registers
• DocExample_TwoWireObject() binding a TwoWireObject to one device address

These use illustrative device addresses such as 0x48 and 0x68, which will not all be present on your board, so the application does not run them automatically. Call the ones you want, with addresses that match your hardware.

What it does when you run it

The application scans the bus and then runs a set of checks against whatever devices actually responded, printing a PASS or FAIL line for each:

• a bus scan using the documented ping() loop
• readRegN() against a device that is present
• readRegN() against an address nothing answers, confirming it fails cleanly and leaves the bus usable for the next transaction
• setNumAddressBytes(0) for a device with no register pointer, then back to the default of 1
• a TwoWireObject agreeing with the TwoWire it wraps
• an object built from an invalid pin pair reporting isValid() as false and staying inert rather than faulting

If nothing responds, those checks are skipped with a message. Connect an I2C device to the bus to run them.

Expected output

On a SOMRT1061 development board with a Microchip PicKit Serial I2C Demo Board attached to the default I2C pins:

=== I2C Wire Doc Examples on SOMRT1061 ===
Every example from the Wire API documentation, as working code.
 
Hardware checks:
   bus scan found 13 device(s): 0x10,0x20,0x48,0x49,0x4D,0x50,0x51,0x52,0x53,0x54,0x55,0x56,0x57
   scan completed without hanging                 PASS
   readRegN on a present device                   PASS  addr 0x10 reg 0x00 = 0xFF, rc 0
   readRegN on an absent address fails cleanly    PASS
   bus still usable after a failed transaction    PASS  0x10 again = 0xFF
   width 0 plain read accepted                    PASS  rc 0
   width restored to 1, reads match               PASS
   TwoWireObject::ping finds the same device      PASS
   TwoWireObject::readReg8 agrees with TwoWire    PASS
   bad pin pair reports isValid() false           PASS
   begin() on an unbound object is safe           PASS
   ping() on an unbound object returns false      PASS
 
=== 0 failure(s) ===

Address 0x10 is the PAC193x power monitor on the development board itself. The remaining addresses are the PicKit board, where 0x50 through 0x57 are all the 24LC02B EEPROM, which acknowledges the whole block of eight addresses.

Building for a different platform

The object directory is shared between platforms. Run make clean before building for a different platform, otherwise the link fails with Relocations in generic ELF because objects from the previous architecture are still present.