i2c-bus
I2C serial bus access with Node.js on Linux boards like the Raspberry Pi,
C.H.I.P., BeagleBone or Intel Edison. All methods have asynchronous and
synchronous forms.
i2c-bus supports Node.js versions 4, 6, 8 and 9.
Contents
Installation
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:
Usage
Example Temperature Sensor Circuits
Some of the examples programs use a
DS1621 temperature sensor
to show how the i2c-bus package functions.
DS1621 temperature sensor connected to a Raspberry Pi
DS1621 temperature sensor connected to a BeagleBone Black
Example 1 - Determine Temperature Synchronously
Determine the temperature with a DS1621 temperature sensor Synchronously.
var i2c = require('i2c-bus'),
i2c1 = i2c.openSync(1);
var DS1621_ADDR = 0x48,
CMD_ACCESS_CONFIG = 0xac,
CMD_READ_TEMP = 0xaa,
CMD_START_CONVERT = 0xee;
function toCelsius(rawTemp) {
var halfDegrees = ((rawTemp & 0xff) << 1) + (rawTemp >> 15);
if ((halfDegrees & 0x100) === 0) {
return halfDegrees / 2;
}
return -((~halfDegrees & 0xff) / 2);
}
(function () {
var rawTemp;
i2c1.writeByteSync(DS1621_ADDR, CMD_ACCESS_CONFIG, 0x01);
while (i2c1.readByteSync(DS1621_ADDR, CMD_ACCESS_CONFIG) & 0x10) {
}
i2c1.sendByteSync(DS1621_ADDR, CMD_START_CONVERT);
while ((i2c1.readByteSync(DS1621_ADDR, CMD_ACCESS_CONFIG) & 0x80) === 0) {
}
rawTemp = i2c1.readWordSync(DS1621_ADDR, CMD_READ_TEMP);
console.log('temp: ' + toCelsius(rawTemp));
i2c1.closeSync();
}());
Example 2 - Determine Temperature Asynchronously
Determine the temperature with a DS1621 temperature sensor Asynchronously.
Example 2 does exactly the same thing as example 1, but uses the asynchronous
rather than the synchronous API.
var async = require('async'),
i2c = require('i2c-bus'),
i2c1;
var DS1621_ADDR = 0x48,
CMD_ACCESS_CONFIG = 0xac,
CMD_READ_TEMP = 0xaa,
CMD_START_CONVERT = 0xee;
function toCelsius(rawTemp) {
var halfDegrees = ((rawTemp & 0xff) << 1) + (rawTemp >> 15);
if ((halfDegrees & 0x100) === 0) {
return halfDegrees / 2;
}
return -((~halfDegrees & 0xff) / 2);
}
(function () {
async.series([
function (cb) {
i2c1 = i2c.open(1, cb);
},
function (cb) {
i2c1.writeByte(DS1621_ADDR, CMD_ACCESS_CONFIG, 0x01, cb);
},
function (cb) {
(function read() {
i2c1.readByte(DS1621_ADDR, CMD_ACCESS_CONFIG, function (err, config) {
if (err) return cb(err);
if (config & 0x10) return read();
cb(null);
});
}());
},
function (cb) {
i2c1.sendByte(DS1621_ADDR, CMD_START_CONVERT, cb);
},
function (cb) {
(function read() {
i2c1.readByte(DS1621_ADDR, CMD_ACCESS_CONFIG, function (err, config) {
if (err) return cb(err);
if ((config & 0x80) === 0) return read();
cb(null);
});
}());
},
function (cb) {
i2c1.readWord(DS1621_ADDR, CMD_READ_TEMP, function (err, rawTemp) {
if (err) return cb(err);
console.log('temp: ' + toCelsius(rawTemp));
cb(null);
});
},
function (cb) {
i2c1.close(cb);
}
], function (err) {
if (err) throw err;
});
}());
Example 3 - Accessing Multiple Devices Asynchronously and Concurrently
This example demonstrates concurrent asynchronous access to two devices on the
same bus, a DS1621 temperature sensor and an
Adafruit TSL2561 digital luminosity/lux/light sensor.
var i2c = require('i2c-bus'),
i2c1;
var DS1621_ADDR = 0x48,
DS1621_CMD_ACCESS_TH = 0xa1;
var TSL2561_ADDR = 0x39,
TSL2561_CMD = 0x80,
TSL2561_REG_ID = 0x0a;
i2c1 = i2c.open(1, function (err) {
if (err) throw err;
(function readTempHigh() {
i2c1.readWord(DS1621_ADDR, DS1621_CMD_ACCESS_TH, function (err, tempHigh) {
if (err) throw err;
console.log(tempHigh);
readTempHigh();
});
}());
(function readId() {
i2c1.readByte(TSL2561_ADDR, TSL2561_CMD | TSL2561_REG_ID, function (err, id) {
if (err) throw err;
console.log(id);
readId();
});
}());
});
API
All methods have asynchronous and synchronous forms.
The asynchronous 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.
Methods
Class Bus
-
Free resources
-
Information
-
Plain I2C
- bus.i2cRead(addr, length, buffer, cb)
- bus.i2cReadSync(addr, length, buffer)
- bus.i2cWrite(addr, length, buffer, cb)
- bus.i2cWriteSync(addr, length, buffer)
-
SMBus
- bus.readByte(addr, cmd, cb)
- bus.readByteSync(addr, cmd)
- bus.readWord(addr, cmd, cb)
- bus.readWordSync(addr, cmd)
- bus.readI2cBlock(addr, cmd, length, buffer, cb)
- bus.readI2cBlockSync(addr, cmd, length, buffer)
- bus.receiveByte(addr, cb)
- bus.receiveByteSync(addr)
- bus.sendByte(addr, byte, cb)
- bus.sendByteSync(addr, byte)
- bus.writeByte(addr, cmd, byte, cb)
- bus.writeByteSync(addr, cmd, byte)
- bus.writeWord(addr, cmd, word, cb)
- bus.writeWordSync(addr, cmd, word)
- bus.writeQuick(addr, bit, cb)
- bus.writeQuickSync(addr, bit)
- bus.writeI2cBlock(addr, cmd, length, buffer, cb)
- bus.writeI2cBlockSync(addr, cmd, length, buffer)
Class I2cFuncs
open(busNumber [, options], cb)
- busNumber - the number of the I2C bus/adapter to open, 0 for /dev/i2c-0, 1 for /dev/i2c-1, ...
- options - an optional options object
- cb - completion callback
Asynchronous open. Returns a new Bus object. The callback gets one argument (err).
The following options are supported:
- forceAccess - A boolean value specifying whether access to devices on the
I2C bus should be allowed even if they are already in use by a kernel
driver/module. Corresponds to I2C_SLAVE_FORCE on Linux. The valid values for
forceAccess are true and false. Optional, the default value is false.
openSync(busNumber [, options])
- busNumber - the number of the I2C bus/adapter to open, 0 for /dev/i2c-0, 1 for /dev/i2c-1, ...
- options - an optional options object
Synchronous open. Returns a new Bus object.
The following options are supported:
- forceAccess - A boolean value specifying whether access to devices on the
I2C bus should be allowed even if they are already in use by a kernel
driver/module. Corresponds to I2C_SLAVE_FORCE on Linux. The valid values for
forceAccess are true and false. Optional, the default value is false.
bus.close(cb)
Asynchronous close. The callback gets one argument (err).
bus.closeSync()
Synchronous close.
bus.i2cFuncs(cb)
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.
bus.i2cFuncsSync()
Determine functionality of the bus/adapter Synchronously. Returns a frozen
I2cFuncs
object describing the functionality available.
See also I2C functionality.
bus.scan([startAddr,] [endAddr,] cb)
- startAddr - an integer specifying the start address of the scan range, optional
- endAddr - an integer specifying the end addrerss of the scan range, optional
- cb - completion callback
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.scanSync([startAddr,] [endAddr])
- startAddr - an integer specifying the start address of the scan range, optional
- endAddr - an integer specifying the end addrerss of the scan range, optional
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.
bus.deviceId(addr, cb)
- addr - I2C device address
- cb - completion callback
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.
bus.deviceIdSync(addr)
- addr - I2C device address
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.
bus.i2cRead(addr, length, buffer, cb)
- addr - I2C device address
- length - an integer specifying the number of bytes to read
- buffer - the buffer that the data will be written to (must conatin at least length bytes)
- cb - completion callback
Asynchronous plain I2C read. The callback gets three argument (err, bytesRead, buffer).
bytesRead is the number of bytes read.
bus.i2cReadSync(addr, length, buffer)
- addr - I2C device address
- length - an integer specifying the number of bytes to read
- buffer - the buffer that the data will be written to (must conatin at least length bytes)
Synchronous plain I2C read. Returns the number of bytes read.
bus.i2cWrite(addr, length, buffer, cb)
- addr - I2C device address
- length - an integer specifying the number of bytes to write
- buffer - the buffer containing the data to write (must conatin at least length bytes)
- cb - completion callback
Asynchronous plain I2C write. The callback gets three argument (err, bytesWritten, buffer).
bytesWritten is the number of bytes written.
bus.i2cWriteSync(addr, length, buffer)
- addr - I2C device address
- length - an integer specifying the number of bytes to write
- buffer - the buffer containing the data to write (must conatin at least length bytes)
Synchronous plain I2C write. Returns the number of bytes written.
bus.readByte(addr, cmd, cb)
- addr - I2C device address
- cmd - command code
- cb - completion callback
Asynchronous SMBus read byte. The callback gets two arguments (err, byte).
bus.readByteSync(addr, cmd)
- addr - I2C device address
- cmd - command code
Synchronous SMBus read byte. Returns the byte read.
bus.readWord(addr, cmd, cb)
- addr - I2C device address
- cmd - command code
- cb - completion callback
Asynchronous SMBus read word. The callback gets two arguments (err, word).
bus.readWordSync(addr, cmd)
- addr - I2C device address
- cmd - command code
Synchronous SMBus read word. Returns the word read.
bus.readI2cBlock(addr, cmd, length, buffer, cb)
- addr - I2C device address
- cmd - command code
- length - an integer specifying the number of bytes to read (max 32)
- buffer - the buffer that the data will be written to (must conatin at least length bytes)
- cb - completion callback
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.
bus.readI2cBlockSync(addr, cmd, length, buffer)
- addr - I2C device address
- cmd - command code
- length - an integer specifying the number of bytes to read (max 32)
- buffer - the buffer that the data will be written to (must conatin at least length bytes)
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.
bus.receiveByte(addr, cb)
- addr - I2C device address
- cb - completion callback
Asynchronous SMBus receive byte. The callback gets two arguments (err, byte).
bus.receiveByteSync(addr)
- addr - I2C device address
Synchronous SMBus receive byte. Returns the byte received.
bus.sendByte(addr, byte, cb)
- addr - I2C device address
- byte - data byte
- cb - completion callback
Asynchronous SMBus send byte. The callback gets one argument (err).
bus.sendByteSync(addr, byte)
- addr - I2C device address
- byte - data byte
Synchronous SMBus send byte.
bus.writeByte(addr, cmd, byte, cb)
- addr - I2C device address
- cmd - command code
- byte - data byte
- cb - completion callback
Asynchronous SMBus write byte. The callback gets one argument (err).
bus.writeByteSync(addr, cmd, byte)
- addr - I2C device address
- cmd - command code
- byte - data byte
Synchronous SMBus write byte.
bus.writeWord(addr, cmd, word, cb)
- addr - I2C device address
- cmd - command code
- word - data word
- cb - completion callback
Asynchronous SMBus write word. The callback gets one argument (err).
bus.writeWordSync(addr, cmd, word)
- addr - I2C device address
- cmd - command code
- word - data word
Synchronous SMBus write word.
bus.writeQuick(addr, bit, cb)
- addr - I2C device address
- bit - bit to write (0 or 1)
- cb - completion callback
Asynchronous SMBus quick command. Writes a single bit to the device.
The callback gets one argument (err).
bus.writeQuickSync(addr, bit)
- addr - I2C device address
- bit - bit to write (0 or 1)
Synchronous SMBus quick command. Writes a single bit to the device.
bus.writeI2cBlock(addr, cmd, length, buffer, cb)
- addr - I2C device address
- cmd - command code
- length - an integer specifying the number of bytes to write (max 32)
- buffer - the buffer containing the data to write (must conatin at least length bytes)
- cb - completion callback
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.
bus.writeI2cBlockSync(addr, cmd, length, buffer)
- addr - I2C device address
- cmd - command code
- length - an integer specifying the number of bytes to write (max 32)
- buffer - the buffer containing the data to write (must conatin at least length bytes)
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.
funcs.i2c - boolean
Specifies whether or not the adapter handles plain I2C-level commands (Pure
SMBus adapters typically can not do these,
I2C_FUNC_I2C).
funcs.tenBitAddr - boolean
Specifies whether or not the adapter handles the 10-bit address extensions
(I2C_FUNC_10BIT_ADDR).
funcs.protocolMangling - boolean
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).
funcs.smbusPec - boolean
Specifies whether or not the adapter handles packet error checking
(I2C_FUNC_SMBUS_PEC).
funcs.smbusBlockProcCall - boolean
Specifies whether or not the adapter handles the SMBus block process call
command
(I2C_FUNC_SMBUS_BLOCK_PROC_CALL).
funcs.smbusQuick - boolean
Specifies whether or not the adapter handles the SMBus quick command
(I2C_FUNC_SMBUS_QUICK).
funcs.smbusReceiveByte - boolean
Specifies whether or not the adapter handles the SMBus receive byte command
(I2C_FUNC_SMBUS_READ_BYTE).
funcs.smbusSendByte - boolean
Specifies whether or not the adapter handles the SMBus send byte command
(I2C_FUNC_SMBUS_WRITE_BYTE).
funcs.smbusReadByte - boolean
Specifies whether or not the adapter handles the SMBus read byte command
(I2C_FUNC_SMBUS_READ_BYTE_DATA).
funcs.smbusWriteByte - boolean
Specifies whether or not the adapter handles the SMBus write byte command
(I2C_FUNC_SMBUS_WRITE_BYTE_DATA).
funcs.smbusReadWord - boolean
Specifies whether or not the adapter handles the SMBus read word command
(I2C_FUNC_SMBUS_READ_WORD_DATA).
funcs.smbusWriteWord - boolean
Specifies whether or not the adapter handles the SMBus write word command
(I2C_FUNC_SMBUS_WRITE_WORD_DATA).
funcs.smbusProcCall - boolean
Specifies whether or not the adapter handles the SMBus process call command
(I2C_FUNC_SMBUS_PROC_CALL).
funcs.smbusReadBlock - boolean
Specifies whether or not the adapter handles the SMBus read block command
(I2C_FUNC_SMBUS_READ_BLOCK_DATA).
funcs.smbusWriteBlock - boolean
Specifies whether or not the adapter handles the SMBus write block command
(I2C_FUNC_SMBUS_WRITE_BLOCK_DATA).
funcs.smbusReadI2cBlock - boolean
Specifies whether or not the adapter handles the SMBus read I2C block command
(I2C_FUNC_SMBUS_READ_I2C_BLOCK).
funcs.smbusWriteI2cBlock - boolean
Specifies whether or not the adapter handles the SMBus write i2c block command
(I2C_FUNC_SMBUS_WRITE_I2C_BLOCK).