1i2ctransfer(8) System Manager's Manual i2ctransfer(8)
2
6 i2ctransfer - send user-defined I2C messages in one transfer
7
10 i2ctransfer [-f] [-y] [-v] [-a] i2cbus desc [data] [desc [data]] ...
11 i2ctransfer -V
12
15 i2ctransfer is a program to create I2C messages and send them combined
16 as one transfer. For read messages, the contents of the received buf‐
17 fers are printed to stdout, one line per read message.
18 Please note the difference between a transfer and a message here. A
19 transfer may consist of multiple messages and is started with a START
20 condition and ends with a STOP condition as described in the I2C speci‐
21 fication. Messages within the transfer are concatenated using the
22 REPEATED START condition which is described there as well. There are
23 some advantages of having multiple messages in one transfer. First,
24 some devices keep their internal states for REPEATED START but reset
25 them after a STOP. Second, you cannot get interrupted during one
26 transfer, but it might happen between multiple transfers. Interruption
27 could happen on hardware level by another I2C master on the bus, or at
28 software level by another I2C user who got its transfer scheduled
29 between yours. This program helps you to create proper transfers for
30 your needs.
31
34 -f Force access to the device even if it is already busy. By
35 default, i2ctransfer will refuse to access a device which is
36 already under the control of a kernel driver. Using this flag
37 is dangerous, it can seriously confuse the kernel driver in
38 question. It can also cause i2ctransfer to silently write to
39 the wrong register. So use at your own risk and only if you
40 know what you're doing.
41 -y Disable interactive mode. By default, i2ctransfer will wait for
43 a confirmation from the user before messing with the I2C bus.
44 When this flag is used, it will perform the operation directly.
45 This is mainly meant to be used in scripts.
46 -v Enable verbose output. It will print infos about all messages
48 sent, i.e. not only for read messages but also for write mes‐
49 sages.
50 -V Display the version and exit.
52 -a Allow using addresses between 0x00 - 0x02 and 0x78 - 0x7f. Not
54 recommended.
55
58 The first parameter i2cbus indicates the number or name of the I2C bus
59 to be used. This number should correspond to one of the busses listed
60 by i2cdetect -l.
61 The next parameter is one or multiple desc blocks. The number of
64 blocks is limited by the Linux Kernel and defined by
65 I2C_RDWR_IOCTL_MAX_MSGS (42 as of v4.10). desc blocks are composed
66 like this:
67 {r|w}<length_of_message>[@address]
69 {r|w} specifies if the message is read or write
72 <length_of_message>
74 specifies the number of bytes read or written in this message.
75 It is parsed as an unsigned 16 bit integer, but note that the
76 Linux Kernel applies an additional upper limit (8192 as of
77 v4.10).
78 [@address]
80 specifies the 7-bit address of the chip to be accessed for this
81 message, and is an integer. If omitted, reuse the previous
82 address. Normally, addresses outside the range of 0x03-0x77 and
83 addresses with a kernel driver attached to them will be blocked.
84 With -f (force), all addresses can be used. Be very careful
85 when using that! 10-bit addresses are currently not supported
86 at all.
87 If the I2C message is a write, then a data block with the data to be
90 written follows. It consists of <length_of_message> bytes which can be
91 marked with the usual prefixes for hexadecimal, octal, etc. To make it
92 easier to create larger data blocks easily, the data byte can have a
93 suffix.
94 = keep value constant until end of message (i.e. 0= means 0, 0, 0,
97 ...)
98 + increase value by 1 until end of message (i.e. 0+ means 0, 1, 2,
100 ...)
101 - decrease value by 1 until end of message (i.e. 0xff- means 0xff,
103 0xfe, 0xfd, ...)
104 p use value as seed for an 8 bit pseudo random sequence (i.e. 0p
106 means 0x00, 0x50, 0xb0, ...)
107
110 On bus 0, from an EEPROM at address 0x50, read 8 byte from offset 0x64
111 (first message writes one byte to set the memory pointer to 0x64, sec‐
112 ond message reads from the same chip):
113 # i2ctransfer 0 w1@0x50 0x64 r8
114 For the same EEPROM, at offset 0x42 write 0xff 0xfe ... 0xf0 (one write
116 message; first byte sets the memory pointer to 0x42, 0xff is the first
117 data byte, all following data bytes are decreased by one):
118 # i2ctransfer 0 w17@0x50 0x42 0xff-
119
122 i2ctransfer can be extremely dangerous if used improperly. It can con‐
123 fuse your I2C bus, cause data loss, or have more serious side effects.
124 Writing to a serial EEPROM on a memory DIMM (chip addresses between
125 0x50 and 0x57) may DESTROY your memory, leaving your system unbootable!
126 Be extremely careful using this program.
127
130 Wolfram Sang, based on i2cget by Jean Delvare
131 This manual page was originally written by Wolfram Sang based on the
133 manual for i2cset by David Z Maze <dmaze@debian.org>.
134
137 i2cdetect(8),i2cdump(8),i2cget(8),i2cset(8)
138 February 2017 i2ctransfer(8)