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)