I2CDETECT(8)

💖 i2cdetect — a.k.a. the I2CDETECT(8) page, but make it make sense 💖

okay bestie, so this is i2cdetect, and it lives in section 8 of the System Manager's Manual, which is the "sysadmin commands" section, iykyk. it is the little icon that goes out and asks every address on an I2C bus "hey. hello. is anybody home?" and then prints you a whole table of who answered. it is genuinely iconic and also genuinely capable of ruining your afternoon, so let's get into it. 🫶

---

✨ NAME ✨

i2cdetect — detect I2C chips

like. that's the whole job. detect the chips. 💅

---

✨ SYNOPSIS ✨

i2cdetect [-y] [-a] [-q|-r] i2cbus [first last]
i2cdetect -F i2cbus
i2cdetect -V
i2cdetect -h
i2cdetect -l

that's five whole shapes this command can take. pick your fighter. 🌈

---

✨ DESCRIPTION ✨

so i2cdetect is a userspace program that scans an I2C bus for devices. it hands you a table listing every device it detected on the bus you told it to look at. 🎀

i2cbus is the number or the name of the I2C bus you want scanned, and it needs to match one of the busses that i2cdetect -l showed you. don't just make one up, bestie, it won't go well.

the optional params first and last narrow down the scanning range. and because defaults are a thing, if you don't give them, it scans from 0x08 to 0x77. that's the whole default range. no cap. ✨

okay here's the lore: there is no standard I2C detection command, so i2cdetect has to make stuff up, and it does that by using arbitrary SMBus commands — specifically SMBus quick write and SMBus receive byte — to probe for devices. by default, the command it uses for each address is the one believed to be the safest for that address. if you want to mess with that behavior, that's what -q and -r are for. (spoiler: they're not recommended. we'll get there. 😭)

also i2cdetect can be used to ask a bus what it's even capable of, functionality-wise — that's option -F. 👑

---

💀 WARNING 💀

This program can confuse your I2C bus, cause data loss and worse!

not me writing a whole warning section and it being one sentence. it's giving "short but devastating". "and worse" is doing so much heavy lifting there. please be careful, bestie. 🙈

---

🔍 INTERPRETING THE OUTPUT 🔍

every single cell in the output table is one of these symbols, and you will need to know which is which:

• "--" — the address got probed but no chip answered. it's giving empty apartment, nobody's home. 💀
• "UU" — probing was skipped, because this address is currently in use by a driver. this strongly suggests there is a chip at this address. someone's already living there. 👑
• an address number in hexadecimal, like "2d" or "4e" — a chip was found at this address. slay, we found one. 🎉

---

✨ OPTIONS ✨

• -y — disable interactive mode. normally i2cdetect will wait for you to confirm before it starts messing with the I2C bus (because, see WARNING above). with this flag it just goes for it, directly. this is mostly meant for scripts, where nobody's sitting there to type "yes". 🤖
• -a — force scanning of non-regular addresses. not recommended.
• -q — use the SMBus "quick write" command for probing. not recommended. this is known to corrupt the Atmel AT24RF08 EEPROM found on many IBM Thinkpad laptops. so like. don't. 😭
• -r — use the SMBus "receive byte" command for probing. not recommended. this is known to lock SMBus on various write-only chips, most notably clock chips at address 0x69. also don't. 🙈
• -F — display the list of functionalities implemented by the adapter, then exit. ✨
• -V — display the version, then exit.
• -h — display the help, then exit.
• -l — output a list of installed busses. your starting point, fr fr. 🦋

---

🌸 EXAMPLES 🌸

list all available I2C busses:

# i2cdetect -l

immediately scan the standard addresses on I2C bus 9 (i2c-9), using the default method for each address, and with no user confirmation:

# i2cdetect -y 9

query the functionalities of I2C bus 1 (i2c-1):

# i2cdetect -F 1

scan addresses 0x10 to 0x17 on the I2C bus named "SMBus I801 adapter at efa0", using the "receive byte" method, after user confirmation:

# i2cdetect -r "SMBus I801 adapter at efa0" 0x10 0x17

see how that last one uses the name instead of a number? that's the "or name" from DESCRIPTION earning its keep. 💅

---

🐛 BUGS 🐛

found a bug, or you wrote a fix and wanna send it? please write to the Linux I2C mailing list <linux-i2c@vger.kernel.org> with a Cc to the current maintainer: Jean Delvare <jdelvare@suse.de>. be nice, send a Cc, that's the whole etiquette. 🫶

---

👀 SEE ALSO 👀

i2cdump(8), i2cget(8), i2cset(8), i2ctransfer(8), sensors-detect(8)

the whole i2c friend group. go say hi to the rest of them. 🌈

---

💜 AUTHOR 💜

Frodo Looijaard, Mark D. Studebaker and Jean Delvare

this manual page was originally written by Aurelien Jarno <aurel32@debian.org>, for the Debian GNU/Linux system.

---

and that's the whole page!! 🎀 this version comes to you from May 2022, it's the i2cdetect(8) page from the System Manager's Manual, and honestly? iconic. go probe responsibly, bestie. 💖✨🦋