NAME

       i2ctransfer - send user-defined I2C messages in one transfer

SYNOPSIS

       i2ctransfer [-f] [-y] [-v] [-a] 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  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.

       -a     Allow using addresses between 0x00 - 0x07 and 0x78 - 0x7f. Not recommended.

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).  For read messages to targets which support  SMBus  Block
              transactions, it can also be '?', then the target will determine the length.

       [@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  0x08-0x77  and  addresses  with a kernel driver attached to them will be
              blocked.  This can be overridden with -a (all) or -f (force).  Be very careful when
              using these!  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.

BUGS

       To report bugs or send  fixes,  please  write  to  the  Linux  I2C  mailing  list  <linux-
       i2c@vger.kernel.org> with Cc to the current maintainer: Jean Delvare <jdelvare@suse.de>.

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)