NAME

       i2ctransfer - send user-defined I2C messages in one transfer

SYNOPSIS

       i2ctransfer [-f] [-y] [-v] i2cbus desc [data] [desc [data]] ...
       i2ctransfer -V

DESCRIPTION

       i2ctransfer  is  a  program to create I2C messages and send them combined as one transfer.
       For read messages, the contents of the received buffers are printed to  stdout,  one  line
       per read message.
       Please  note the difference between a transfer and a message here.  A transfer may consist
       of multiple messages and is started with a START condition and ends with a STOP  condition
       as  described  in  the  I2C  specification.  Messages within the transfer are concatenated
       using the REPEATED START condition which is described  there  as  well.   There  are  some
       advantages  of  having  multiple messages in one transfer.  First, some devices keep their
       internal states for REPEATED START but reset them after a STOP.  Second,  you  cannot  get
       interrupted  during  one  transfer,  but  it  might  happen  between  multiple  transfers.
       Interruption could happen on hardware level by another  I2C  master  on  the  bus,  or  at
       software  level  by  another  I2C user who got its transfer scheduled between yours.  This
       program helps you to create proper transfers for your needs.

OPTIONS

       -f     Force access to the device even if it is already  busy.   By  default,  i2ctransfer
              will  refuse  to  access  addresses  marked as reserved by the I2C standard or to a
              device which is already under the control of a kernel driver.  Using this  flag  is
              dangerous,  it  can  seriously  confuse the kernel driver in question.  It can also
              cause i2ctransfer to silently write to the wrong register.  So use at your own risk
              and only if you know what you're doing.

       -y     Disable  interactive  mode.   By  default, i2ctransfer will wait for a confirmation
              from the user before messing with the I2C bus.  When this flag  is  used,  it  will
              perform the operation directly.  This is mainly meant to be used in scripts.

       -v     Enable  verbose output.  It will print infos about all messages sent, i.e. not only
              for read messages but also for write messages.

       -V     Display the version and exit.

ARGUMENTS

       The first parameter i2cbus indicates the number or name of the I2C bus to be  used.   This
       number should correspond to one of the busses listed by i2cdetect -l.

       The next parameter is one or multiple desc blocks.  The number of blocks is limited by the
       Linux Kernel and defined by I2C_RDWR_IOCTL_MAX_MSGS (42 as of  v4.10).   desc  blocks  are
       composed like this:

       {r|w}<length_of_message>[@address]

       {r|w}  specifies if the message is read or write

       <length_of_message>
              specifies  the number of bytes read or written in this message.  It is parsed as an
              unsigned 16 bit integer, but note that the Linux Kernel applies an additional upper
              limit (8192 as of v4.10).

       [@address]
              specifies  the 7-bit address of the chip to be accessed for this message, and is an
              integer.  If omitted, reuse the previous address.  Normally, addresses outside  the
              range  of  0x03-0x77  and  addresses  with a kernel driver attached to them will be
              blocked.  With -f (force), all addresses can be used.  Be very careful  when  using
              that!  10-bit addresses are currently not supported at all.

       If  the I2C message is a write, then a data block with the data to be written follows.  It
       consists of <length_of_message> bytes which can be marked  with  the  usual  prefixes  for
       hexadecimal,  octal, etc.  To make it easier to create larger data blocks easily, the data
       byte can have a suffix.

       =      keep value constant until end of message (i.e. 0= means 0, 0, 0, ...)

       +      increase value by 1 until end of message (i.e. 0+ means 0, 1, 2, ...)

       -      decrease value by 1 until end of message (i.e. 0xff- means 0xff, 0xfe, 0xfd, ...)

       p      use value as seed for an 8 bit pseudo random sequence (i.e. 0p  means  0x00,  0x50,
              0xb0, ...)

EXAMPLES

       On  bus  0,  from  an  EEPROM at address 0x50, read 8 byte from offset 0x64 (first message
       writes one byte to set the memory pointer to 0x64, second  message  reads  from  the  same
       chip):
              # i2ctransfer 0 w1@0x50 0x64 r8

       For  the  same  EEPROM,  at offset 0x42 write 0xff 0xfe ... 0xf0 (one write message; first
       byte sets the memory pointer to 0x42, 0xff is the first  data  byte,  all  following  data
       bytes are decreased by one):

              # i2ctransfer 0 w17@0x50 0x42 0xff-

WARNING

       i2ctransfer  can  be extremely dangerous if used improperly.  It can confuse your I2C bus,
       cause data loss, or have more serious side effects.  Writing  to  a  serial  EEPROM  on  a
       memory  DIMM  (chip addresses between 0x50 and 0x57) may DESTROY your memory, leaving your
       system unbootable!  Be extremely careful using this program.

AUTHORS

       Wolfram Sang, based on i2cget by Jean Delvare

       This manual page was originally written by Wolfram Sang based on the manual for i2cset  by
       David Z Maze <dmaze@debian.org>.

SEE ALSO

       i2cdetect(8),i2cdump(8),i2cget(8),i2cset(8)

                                          February 2017                            i2ctransfer(8)