I2C serial bus access with Node.js on Linux boards like the Raspberry Pi or BeagleBone. The i2c-bus API supports promises and async/await, asynchronous callbacks and synchronous execution.
i2c-bus supports Node.js versions 10, 12, 14, 16, 18 and 20.
npm install i2c-bus
The way in which I2C is configured varies from board to board. Sometimes no configuraton is required, but sometimes it is:
The example programs below show how to use a MCP9808 I2C temperature sensor to determine the temperature.
MCP9808 I2C temperature sensor connected to a Raspberry Pi
Determine the temperature with a MCP9808 I2C temperature sensor using promises.
const i2c = require('i2c-bus');
const MCP9808_ADDR = 0x18;
const TEMP_REG = 0x05;
const toCelsius = rawData => {
rawData = (rawData >> 8) + ((rawData & 0xff) << 8);
let celsius = (rawData & 0x0fff) / 16;
if (rawData & 0x1000) {
celsius -= 256;
}
return celsius;
};
i2c.openPromisified(1).
then(i2c1 => i2c1.readWord(MCP9808_ADDR, TEMP_REG).
then(rawData => console.log(toCelsius(rawData))).
then(_ => i2c1.close())
).catch(console.log);
Determine the temperature with a MCP9808 I2C temperature sensor using promises, plain I2C and Buffer objects.
const i2c = require('i2c-bus');
const MCP9808_ADDR = 0x18;
const TEMP_REG = 0x05;
const toCelsius = rawData => {
let celsius = (rawData & 0x0fff) / 16;
if (rawData & 0x1000) {
celsius -= 256;
}
return celsius;
};
const wbuf = Buffer.from([TEMP_REG]);
const rbuf = Buffer.alloc(2);
i2c.openPromisified(1).
then(i2c1 => i2c1.i2cWrite(MCP9808_ADDR, wbuf.length, wbuf).
then(_ => i2c1.i2cRead(MCP9808_ADDR, rbuf.length, rbuf)).
then(data => console.log(toCelsius(data.buffer.readUInt16BE()))).
then(_ => i2c1.close())
).catch(console.log);
Determine the temperature with a MCP9808 I2C temperature sensor using asynchronous callbacks.
const i2c = require('i2c-bus');
const MCP9808_ADDR = 0x18;
const TEMP_REG = 0x05;
const toCelsius = rawData => {
rawData = (rawData >> 8) + ((rawData & 0xff) << 8);
let celsius = (rawData & 0x0fff) / 16;
if (rawData & 0x1000) {
celsius -= 256;
}
return celsius;
};
const i2c1 = i2c.open(1, err => {
if (err) throw err;
i2c1.readWord(MCP9808_ADDR, TEMP_REG, (err, rawData) => {
if (err) throw err;
console.log(toCelsius(rawData));
i2c1.close(err => {
if (err) throw err;
});
});
});
Determine the temperature with a MCP9808 I2C temperature sensor using synchronous methods.
const i2c = require('i2c-bus');
const MCP9808_ADDR = 0x18;
const TEMP_REG = 0x05;
const toCelsius = rawData => {
rawData = (rawData >> 8) + ((rawData & 0xff) << 8);
let celsius = (rawData & 0x0fff) / 16;
if (rawData & 0x1000) {
celsius -= 256;
}
return celsius;
};
const i2c1 = i2c.openSync(1);
const rawData = i2c1.readWordSync(MCP9808_ADDR, TEMP_REG);
console.log(toCelsius(rawData));
i2c1.closeSync();
All methods in class Bus have asynchronous callback and synchronous forms. For promise support see class PromisifiedBus.
The asynchronous callback form always take a completion callback as its last argument. The arguments passed to the completion callback depend on the method, but the first argument is always reserved for an exception. If the operation was completed successfully, then the first argument will be null or undefined.
When using the synchronous form any exceptions are immediately thrown. You can use try/catch to handle exceptions or allow them to bubble up.
Free resources
Information
Plain I2C
SMBus
Promises
All methods in class PromisifiedBus have the asynchronous promise form. For asynchronous callback and synchronous forms see class Bus.
Free resources
Information
Plain I2C
SMBus
Asynchronous callbacks and synchronous execution
Asynchronous open. Returns a new Bus object. The callback gets one argument (err).
The following options are supported:
Synchronous open. Returns a new Bus object.
The following options are supported:
Asynchronous open. Returns a Promise that, when resolved, yields a PromisifiedBus object.
The following options are supported:
Asynchronous close. Frees system resources used by this instance. The callback gets one argument (err).
Synchronous close. Frees system resources used by this instance.
Determine functionality of the bus/adapter asynchronously. The callback gets two argument (err, funcs). funcs is a frozen I2cFuncs object describing the functionality available. See also I2C functionality.
Determine functionality of the bus/adapter Synchronously. Returns a frozen I2cFuncs object describing the functionality available. See also I2C functionality.
bus.scan(cb) - scan for I2C devices in address range 0x03 through 0x77
bus.scan(addr, cb) - scan for an I2C device at address addr
bus.scan(startAddr, endAddr, cb) - scan for I2C devices in address range startAddr through endAddr
Scans the I2C bus asynchronously for devices. The default address range 0x03
through 0x77 is the same as the default address range used by the i2cdetect
command line tool. The callback gets two arguments (err, devices). devices is
an array of numbers where each number represents the I2C address of a device
which was detected.
bus.scan() - scan for I2C devices in address range 0x03 through 0x77
bus.scan(addr) - scan for an I2C device at address addr
bus.scan(startAddr, endAddr) - scan for I2C devices in address range startAddr through endAddr
Scans the I2C bus synchronously for devices. The default address range 0x03
through 0x77 is the same as the default address range used by the i2cdetect
command line tool. Returns an array of numbers where each number represents
the I2C address of a device which was detected.
Asynchronous I2C device Id. The callback gets two arguments (err, id). id is
an object with the properties manufacturer, product and if known a human
readable name for the associated manufacturer. manufacturer and product
are numbers, name is a string.
Synchronous I2C device Id. Returns an object with the properties
manufacturer, product and if known a human readable name for the
associated manufacturer. manufacturer and product are numbers, name is a
string.
Asynchronous plain I2C read. The callback gets three argument (err, bytesRead, buffer). bytesRead is the number of bytes read.
Synchronous plain I2C read. Returns the number of bytes read.
Asynchronous plain I2C write. The callback gets three argument (err, bytesWritten, buffer). bytesWritten is the number of bytes written.
Synchronous plain I2C write. Returns the number of bytes written.
Asynchronous SMBus read byte. The callback gets two arguments (err, byte). byte is an unsigned integer in the range 0 to 255.
Synchronous SMBus read byte. Returns the byte read. byte is an unsigned integer in the range 0 to 255.
Asynchronous SMBus read word. The callback gets two arguments (err, word). word is an unsigned integer in the range 0 to 65535.
Synchronous SMBus read word. Returns the word read. word is an unsigned integer in the range 0 to 65535.
Asynchronous I2C block read (not defined by the SMBus specification). Reads a block of bytes from a device, from a designated register that is specified by cmd. The callback gets three arguments (err, bytesRead, buffer). bytesRead is the number of bytes read.
Synchronous I2C block read (not defined by the SMBus specification). Reads a block of bytes from a device, from a designated register that is specified by cmd. Returns the number of bytes read.
Asynchronous SMBus receive byte. The callback gets two arguments (err, byte). byte is an unsigned integer in the range 0 to 255.
Synchronous SMBus receive byte. Returns the byte received. byte is an unsigned integer in the range 0 to 255.
Asynchronous SMBus send byte. The callback gets one argument (err).
Synchronous SMBus send byte.
Asynchronous SMBus write byte. The callback gets one argument (err).
Synchronous SMBus write byte.
Asynchronous SMBus write word. The callback gets one argument (err).
Synchronous SMBus write word.
Asynchronous SMBus quick command. Writes a single bit to the device. The callback gets one argument (err).
Synchronous SMBus quick command. Writes a single bit to the device.
Asynchronous I2C block write (not defined by the SMBus specification). Writes a block of bytes to a device, to a designated register that is specified by cmd. The callback gets three argument (err, bytesWritten, buffer). bytesWritten is the number of bytes written.
Synchronous I2C block write (not defined by the SMBus specification). Writes a block of bytes to a device, to a designated register that is specified by cmd.
Return the PromisifiedBus instance for this Bus instance.
Asynchronous close. Returns a Promise that will be resolved with no arguments once the underlying resources have been released, or will be rejected if an error occurs while closing.
Determine functionality of the bus/adapter asynchronously. Returns a Promise that on success will be resolved with a frozen I2cFuncs object describing the functionality available. The returned Promise will be rejected if an error occurs. See also I2C functionality.
bus.scan() - scan for I2C devices in address range 0x03 through 0x77
bus.scan(addr) - scan for an I2C device at address addr
bus.scan(startAddr, endAddr) - scan for I2C devices in address range startAddr through endAddr
Scans the I2C bus asynchronously for devices. The default address range 0x03
through 0x77 is the same as the default address range used by the i2cdetect
command line tool. Returns a Promise that on success will be resolved with an
array of numbers where each number represents the I2C address of a device
which was detected. The returned Promise will be rejected if an error occurs.
Asynchronous I2C device Id. Returns a Promise that will be resolved with an id
object on success, or will be rejected if an error occurs. id is an object
with the properties manufacturer, product and if known a human readable
name for the associated manufacturer. manufacturer and product are
numbers, name is a string.
Asynchronous plain I2C read. Returns a Promise that on success will be resolved with an object with a bytesRead property identifying the number of bytes read, and a buffer property that is a reference to the passed in buffer argument. The returned Promise will be rejected if an error occurs.
Asynchronous plain I2C write. Returns a Promise that on success will be resolved with an object with a bytesWritten property identifying the number of bytes written, and a buffer property that is a reference to the passed in buffer argument. The returned promise will be rejected if an error occurs.
Asynchronous SMBus read byte. Returns a Promise that will be resolved with a number representing the byte read on success, or will be rejected if an error occurs. byte is an unsigned integer in the range 0 to 255.
Asynchronous SMBus read word. Returns a Promise that will be resolved with a number representing the word read on success, or will be rejected if an error occurs. word is an unsigned integer in the range 0 to 65535.
Asynchronous I2C block read (not defined by the SMBus specification). Reads a block of bytes from a device, from a designated register that is specified by cmd. Returns a Promise that on success will be resolved with an object with a bytesRead property identifying the number of bytes read, and a buffer property that is a reference to the passed in buffer argument. The returned Promise will be rejected if an error occurs.
Asynchronous SMBus receive byte. Returns a Promise that will be resolved with a number representing the byte received on success, or will be rejected if an error occurs. byte is an unsigned integer in the range 0 to 255.
Asynchronous SMBus send byte. Returns a Promise that will be resolved with no arguments on success, or will be rejected if an error occurs.
Asynchronous SMBus write byte. Returns a Promise that will be resolved with no arguments on success, or will be rejected if an error occurs.
Asynchronous SMBus write word. Returns a Promise that will be resolved with no arguments on success, or will be rejected if an error occurs.
Asynchronous SMBus quick command. Writes a single bit to the device. Returns a Promise that will be resolved with no arguments on success, or will be rejected if an error occurs.
Asynchronous I2C block write (not defined by the SMBus specification). Writes a block of bytes to a device, to a designated register that is specified by cmd. Returns a Promise that on success will be resolved with an object with a bytesWritten property identifying the number of bytes written, and a buffer property that is a reference to the passed in buffer argument. The returned promise will be rejected if an error occurs.
Return the Bus instance for this PromisifiedBus instance.
Specifies whether or not the adapter handles plain I2C-level commands (Pure SMBus adapters typically can not do these, I2C_FUNC_I2C).
Specifies whether or not the adapter handles the 10-bit address extensions (I2C_FUNC_10BIT_ADDR).
Specifies whether or not the adapter knows about the I2C_M_IGNORE_NAK, I2C_M_REV_DIR_ADDR and I2C_M_NO_RD_ACK flags (which modify the I2C protocol! I2C_FUNC_PROTOCOL_MANGLING).
Specifies whether or not the adapter handles packet error checking (I2C_FUNC_SMBUS_PEC).
Specifies whether or not the adapter handles the SMBus block process call command (I2C_FUNC_SMBUS_BLOCK_PROC_CALL).
Specifies whether or not the adapter handles the SMBus quick command (I2C_FUNC_SMBUS_QUICK).
Specifies whether or not the adapter handles the SMBus receive byte command (I2C_FUNC_SMBUS_READ_BYTE).
Specifies whether or not the adapter handles the SMBus send byte command (I2C_FUNC_SMBUS_WRITE_BYTE).
Specifies whether or not the adapter handles the SMBus read byte command (I2C_FUNC_SMBUS_READ_BYTE_DATA).
Specifies whether or not the adapter handles the SMBus write byte command (I2C_FUNC_SMBUS_WRITE_BYTE_DATA).
Specifies whether or not the adapter handles the SMBus read word command (I2C_FUNC_SMBUS_READ_WORD_DATA).
Specifies whether or not the adapter handles the SMBus write word command (I2C_FUNC_SMBUS_WRITE_WORD_DATA).
Specifies whether or not the adapter handles the SMBus process call command (I2C_FUNC_SMBUS_PROC_CALL).
Specifies whether or not the adapter handles the SMBus read block command (I2C_FUNC_SMBUS_READ_BLOCK_DATA).
Specifies whether or not the adapter handles the SMBus write block command (I2C_FUNC_SMBUS_WRITE_BLOCK_DATA).
Specifies whether or not the adapter handles the SMBus read I2C block command (I2C_FUNC_SMBUS_READ_I2C_BLOCK).
Specifies whether or not the adapter handles the SMBus write i2c block command (I2C_FUNC_SMBUS_WRITE_I2C_BLOCK).
TypeScript type definitions for i2c-bus can be found in the Definitely Typed repository at https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/i2c-bus.
FAQs
I2C serial bus access with Node.js
We found that i2c-bus demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Snyk's use of malicious npm packages for research raises ethical concerns, highlighting risks in public deployment, data exfiltration, and unauthorized testing.
Research
Security News
Socket researchers found several malicious npm packages typosquatting Chalk and Chokidar, targeting Node.js developers with kill switches and data theft.
Security News
pnpm 10 blocks lifecycle scripts by default to improve security, addressing supply chain attack risks but sparking debate over compatibility and workflow changes.