Repository files navigation

SPI serial bus access withNode.js on Linux boards like the RaspberryPi or BeagleBone. All methods have asynchronous and synchronous forms.

spi-device supports Node.js versions 10, 12, 14, 15 and 16.

• Installation
• Usage
• API Documentation

npm install spi-device

Determine the temperature using a TMP36 analog temperature sensor wired tochannel 5 on an MCP3008 SPI A/D converter.

constspi=require('spi-device');// The MCP3008 is on bus 0 and it's device 0constmcp3008=spi.open(0,0,err=>{// An SPI message is an array of one or more read+write transfersconstmessage=[{sendBuffer:Buffer.from([0x01,0xd0,0x00]),// Sent to read channel 5receiveBuffer:Buffer.alloc(3),// Raw data read from channel 5byteLength:3,speedHz:20000// Use a low bus speed to get a good reading from the TMP36}];if(err)throwerr;mcp3008.transfer(message,(err,message)=>{if(err)throwerr;// Convert raw value from sensor to celcius and log to consoleconstrawValue=((message[0].receiveBuffer[1]&0x03)<<8)+message[0].receiveBuffer[2];constvoltage=rawValue*3.3/1023;constcelcius=(voltage-0.5)*100;console.log(celcius);});});

spi-device enables low-level access to SPI devices. Often, high-level accessis required. When this is the case, high-level packages can be built usingspi-device. An example of such a package ismcp-spi-adc which provides a high-levelAPI for accessing an MCP3008 SPI A/D converter and will generally be moreuseful than the low-level demonstration code shown above.

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 thefirst argument is always reserved for an exception. If the operation wascompleted successfully, then the first argument will be null or undefined.

When using the synchronous form any exceptions are immediately thrown. You canuse try/catch to handle exceptions or allow them to bubble up.

• open(busNumber, deviceNumber[, options], cb)
• openSync(busNumber, deviceNumber[, options])

• device.transfer(message, cb)
• device.transferSync(message)
• device.getOptions(cb)
• device.getOptionsSync()
• device.setOptions(options, cb)
• device.setOptionsSync(options)
• device.close(cb)
• device.closeSync()

• MODE0
• MODE1
• MODE2
• MODE3

• busNumber - the number of the SPI bus to open, 0 for/dev/spidev0.n, 1 for/dev/spidev1.n, ...
• deviceNumber - the number of the SPI device to open, 0 for/dev/spidevn.0, 1 for/dev/spidevn.1, ...
• options - an optional object specifying deviceconfiguration options
• cb - completion callback

Asynchronous open. Returns a new SpiDevice object. The completion callback getsone argument (err). The SpiDevice object returned should not be used before thecompletion callback is called.

• busNumber - the number of the SPI bus to open, 0 for/dev/spidev0.n, 1 for/dev/spidev1.n, ...
• deviceNumber - the number of the SPI device to open, 0 for/dev/spidevn.0, 1 for/dev/spidevn.1, ...
• options - an optional object specifying deviceconfiguration options

Synchronous open. Returns a new SpiDevice object.

• message - an array of one or more read+write transfers
• cb - completion callback

Asynchronous message transfer. An SPImessage is an array of one ormore read+write transfers. The completion callback gets two arguments (err,message). Returns this.

• message - an array of one or more read+write transfers

Synchronous message transfer. An SPImessage is an array of one ormore read+write transfers. Returns this.

• cb - completion callback

Asynchronously read deviceconfiguration options.The completion callback gets two arguments (err, options) where options is anobject describing the device configuration options. Returns this.

Synchronously read deviceconfiguration options.Returns an object describing the device configuration options.

• options - an object specifying deviceconfiguration options
• cb - completion callback

Asynchronously write deviceconfiguration options.The completion callback gets one argument (err). Returns this.

• options - an object specifying deviceconfiguration options

Synchronously write deviceconfiguration options.Returns this.

• cb - completion callback

Asynchronous close. Frees system resources used by this instance. Thecompletion callback gets one argument (err). Returns null.

Synchronous close. Frees system resources used by this instance. Returns null.

SPI mode number 0.

SPI mode number 1.

SPI mode number 2.

SPI mode number 3.

An SPI message is an array of one or more read+write transfers. A transferis an object with the properties listed below. Most of the properties areoptional. Note that although both sendBuffer and receiveBuffer are optional,at least one one of them must be specified.

• byteLength - number, 32-bit, the number of bytes to transfer
• sendBuffer - optional Buffer, transmit data
• receiveBuffer - optional Buffer, receive data
• speedHz - optional number, 32-bit, override of the device's clock frequencyin Hertz
• microSecondDelay - optional number, 16-bit, delay after the last bit transferbefore optionally deselecting the device before the next transfer, default 0
• bitsPerWord - optional number, 8-bit, override of the device's wordsize
• chipSelectChange - optional boolean, true to deselect device before startingthe next transfer, default false

Device configuration options can be optionally specified when a device isopened with theopen oropenSync methods. They can also be specified at alater point with thesetOptions orsetOptionsSync methods. When callingthese methods, only the options that need to be set need to be specified in theoptions object passed to those methods. All options are optional and theappropriate defaults will be used for options that are not specified.

The options supported varies from system to system and will depend on thedevice drivers used on those systems.

Configurations options can be read with thegetOptions andgetOptionsSyncmethods.

IMPORTANT The semantics ofchipSelectHigh have changed with Linuxkernel 5. To the best of my knowledge, the chipSelectHigh option no longerserves any purpose when used from user space with Linux kernel 5 and shouldnot be used. With Linux kernel 5, the chip select is assumed to be active low.With Linux kernel 5, if an SPI device has has active high chip select, it'schip select must be controlled manually with a GPIO using a module such asonoff. The chipSelectHigh option has beencrossed out below but it's still available for usage on older kernels.

• mode - number, 2-bit, MODE0, MODE1, MODE2, or MODE3, default MODE0
• chipSelectHigh - boolean, true for active high chip select, default false
• lsbFirst - boolean, true for least significant bit first transfer, defaultfalse
• threeWire - boolean, true for shared MISO/MOSI signals, default false
• loopback - boolean, true for loopback mode, default false
• noChipSelect - boolean, true for 1 device per bus, no chip select, defaultfalse
• ready - boolean, true if device pulls low to pause, default false
• bitsPerWord - number, 8-bit, device word size, default 8
• maxSpeedHz - number, 32-bit, device clock frequency in Hertz, default systemspecific