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 - 0x02 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).

       [@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)