HydraFW I2C guide

HydraFW Bus I2C (Inter-Integrated Circuit)

This guide is updated towards firmware release HydraFW v0.11 and later

Bus: I2C (Inter-Integrated Circuit)
Connections: two pins (SDA/SCL) and ground
Output types: open drain/open collector
Pull-up resistors: pull-ups always required (2K - 10K ohms)
Pull-up/down resistors Integrated in MCU: Between 30 to 50K (Typical 40K).
Maximum voltage: 5.5volts (5volt safe)

I2C is a common 2-wire bus for low speed interfaces.

• I2C clock stretching Implemented commit 0038d20 (30 Dec 2022)
  • See https://training.ti.com/i2c-clock-stretching
  • See solved issue https://github.com/hydrabus/hydrafw/issues/141

Actual firmware does not support following I2C/SMBus/PMBus special features

• I2C multi-controllers/multi-master Arbitration using SDA
• Arbitration in SMBus
• Arbitration in PMBus

Protocol configuration syntax description:

• show Show I2C parameters or show pins Show pins used in this mode

• pull with parameter up or down or floating to choose internal MCU pull up/down or no pull/external

• frequency with floating frequency value: support k (for kHz), m (for MHz) suffix or no suffix (for Hz)

  • Frequencies available: 50khz, 100khz, 400khz, 1mhz

• clock-stretch with maximum clock stretch tick count. (0 = Disabled, n = Ticks)

  • The tick count duration depends of the frequency used
    • It can be displayed using show command

• scan search I2C device(s) from address 0x01 to address 0x77

  • Returned scan hexadecimal value corresponds to 7bits I2C address(range 0x01 to 0x77) and also contains 8bits W or R address to be used.
  • Value to be used with HydraFW I2C Console commands are always 8bits I2C address Example: 0x78(Write) or 0x79(Read)
    • See https://github.com/hydrabus/hydrafw/issues/102 for more details
  • Example:
    • scan returns: Device found at address: 0x3C (0x78 W / 0x79 R)

• sniff sniff I2C bus data See below

• exit to exit I2C mode

Note default value: 
> i2c
GPIO resistor: pull-up
Frequency: 100khz (50khz, 400khz, 1mhz)

Configuration options:

Hardware Informations:

i2c1> show pins
SCL: PB6
SDA: PB7

Protocol configuration example:

Configuration of I2C1 400KHz(using internal MCU pull up):

> i2c
GPIO resistor: pull-up
Frequency: 100khz (50khz, 400khz, 1mhz)

i2c1> frequency 400k show
GPIO resistor: pull-up
Frequency: 400khz (50khz, 100khz, 1mhz)

Protocol interaction syntax description:

Bus interaction commands

trigger configures the trigger mode

start or [ Send I2C Start or Re-Start condition.

stop or ] Send I2C Stop condition.

Protocol interaction example usage I2C1 write/read:

i2c1> [ 0x01 0xFF 0 1 0x80 0x55 0xAA 0xFF 0x11:4 [ 0x00 r:4 ]
I2C START
WRITE: 0x01 ACK 0xFF ACK 0x00 ACK 0x01 ACK 0x80 ACK 0x55 ACK 0xAA ACK 0xFF ACK 0x11 ACK 0x11 ACK 0x11 ACK 0x11 ACK
I2C START
WRITE: 0x00 ACK
READ: 0x00 ACK
READ: 0x00 ACK
READ: 0x00 ACK
READ: 0x00 NACK
I2C STOP

I2C sniffer

I2C sniffer allows to spy an I2C bus. The sniffer is working for buses up to 100kHz.

Syntax is the following :

• [ : Start condition
• ] : Stop condition
• 0x.. byte value send on the bus. Followed by + when an ACK was read or a - if a NACK was read.

Example :

i2c1> sniff 
Interrupt by pressing user button.

[0x80+0x00+0x00+]
[0x80+0x0c+0xaa+]
[0x80+0x0d+0xaa+]
[0x80+0xe2+0xff+0x00+0x00+0x00+0x00+0x00+0x00+0x00+]

Additional informations about I2C

ACK/NACK management is same as BusPirate I2C see chapter ACK/NACK management: http://dangerousprototypes.com/docs/I2C

I2C Pull-up Resistors: It is recommended to use external Pull-Up resistors (for I2C > 100KHz, like 10K for 100KHz and <1.77K for 400KHz/1MHz).

• Recommended resistor for Fast-mode I2C is 1.6K (min 967 Ohms and max 1.77K with Cb=200 pF, VCC=3.3 V).
  • See https://e2e.ti.com/cfs-file/__key/communityserver-discussions-components-files/6/I2C-Bus-Pullup-Resistor-Calculation.pdf
• If and When Do I²C Pull-Up Values Matter? -- Workbench Wednesdays 83: https://community.element14.com/challenges-projects/element14-presents/workbenchwednesdays/w/documents/28424/if-and-when-do-i2c-pull-up-values-matter----workbench-wednesdays-83

For more details see:

• Wikipedia
  • https://en.wikipedia.org/wiki/I%C2%B2C
• Electronics Design Network
  • https://www.edn.com/design-calculations-for-robust-i2c-communications/
• Texas Instruments
  • Application Note: A Basic Guide to I2C https://www.ti.com/lit/pdf/sbaa565
• https://i2cdevices.org