SPI

[rwaldron]

Define a generic API for SPI that can be implemented across all platforms

[nebrius]

FWIW, here's the documentation for SPI in the C++ library I use for raspi-io: http://wiringpi.com/reference/spi-library/. Specifically, you specify a channel and a clock rate in initialization, and reading/writing is batched together (since SPI slaves can only write while the master is also sending data)

[natevw]

xref: rwaldron/johnny-five#624 (comment)

Also, you could check out my https://github.com/natevw/pi-spi as an example simple wrapper around the Linux spidev interface if that's relevant for such a backend.

[soundanalogous]

I'm also looking into this spi module for Linux: https://www.npmjs.com/package/spi. I'll try both once I get a compatible board.

[soundanalogous]

One of the bigger issues I'm facing in defining a protocol is how to handle the CS pin and any secondary CS-type pins. On the Firmata side there is an advantage to specifying the CS pin and any CS-like pins in the config message, then managing them on the firmware side to avoid having to send too many messages over Serial (especially for SPI devices that require toggling CS between every byte read - not yet sure if that's even a case worth supporting). However for Linux implementations (Pi, BeagleBone, Galileo, etc) it may be better to handle the CS pin separately since there is far less latency involved (I'm assuming).

[natevw]

Yes, another thing to consider along with related pins is transactions that need to hold the SPI bus. I forget the exact situation but there was an avoidable need with https://github.com/tessel/sdcard to "lock out" SPI communications with other chips during some operations (i.e. a CSN pin had to remain down even between individual SPI transfers) — there are likely other types of devices that are are SPI "compatible" but need similar coddling.

This is how Tessel ended up exposing such a feature at the API level: https://github.com/tessel/docs/blob/master/tutorials/raw-spi.md (via https://tessel.io/docs/hardwareAPI#api-spi-lock-callback)

[nebrius]

I remember in college doing some SPI work where I had something like 4 SS pins (ne CS, ne CSN, ne why the hell are there so many names for this pin) on the master that would essentially "toggle" between slaves to avoid needing more than one SPI port.

If we want to support these types of use cases, would it make sense to start by having the SS just be "automagic" for now and handled on the firmata side, and provide a flag for saying "no, I'm going to handle SS myself"?

[natevw]

Right, sharing a bus is the usual SPI situation (see http://www.dorkbotpdx.org/blog/paul/better_spi_bus_design_in_3_steps for "protips" on the hardware side) but there's some devices (SD Card for one I'm familiar with) that are mostly SPI-compatible but don't really follow that "standard" and use the select pin for signaling more than just "I am talking with you via the other three pins". In the SD case, after you issue a read/write request you need to hold its CSN equivalent "active" (i.e. low) and during that time you want to make sure no other SPI usage happens.

That's what the "lock" is for, so that you can reserve the SPI bus against other traffic. A more mundane use case is when you run out of hardware pins and start using random other GPIO pins for CSN…that pin state needs to be coordinated with the SPI transfer the same sort of mutex/fifo can facilitate that.

[nebrius]

TIL

[soundanalogous]

My current thoughts (incorporating feedback from Nate and Bryan):

configuration options

// I'm working this out for the Firmata protocol at the same time so that is why you
// see the number of bits here... for J5 each config value would be separate, for node-firmata
// they will need to be packed (arrangement TBD) prior to TX to the Arduino
channel          for Linux: "/dev/spidev0.0", etc; TBD for other multi SPI port HW
deviceId         (enum from 0) used to identify the specific SPI device (could use CS pin instead)
bitOrder         (1 bits)  MSB (default?) | LSB
dataMode         (2 bits)  (0 | 1 | 2 | 3)
clockSpeed       (32 bits)

// by default handle the CS pin automatically by pulling it to the active state at the
// beginning of a transfer and releasing it at the end of the transfer
// the user can set this bit to 0 to handle CS (and any CS-like pins) manually
handleCSPin      (1 bit)  1 if CS pin should be handled automatically
  csActive       (1 bit)  default = 0 (LO)
  csToggle       (1 bit)  1 if toggle CS pin should be toggled 
                          between transferred word (this is a rare case)
  csPin          (7 bits) default = 0

// the following may be useful. We'd default to 8 bit words, but with an option for
// the user to set 1 to 16 bit word lengths
// I'm not sure what the smallest word size is but have seen documentation for devices
// as small as 3 bit words
wordSize         (4 bits) (1 to 16 bit) value + 1 (default = 8)

methods

// the idea here is that each device would have its own SPI instance
// someone please  correct me if I'm wrong but it seems this is already the case for
// many Linux SPI interfaces. Otherwise if there is only a single SPI instance (per SPI
// port on a device if multiple) then options will need to be set on the spi object
// instance before each transaction with a different device

// constructor (see options above)
// a setter could also be provided for each option
var spi = new SPI(options)

// when you need to write and read in a single transaction (most common use case)
// The implementation must ensure that the number of words written equals the
// number of words received. If a written word does not return data, 0 should be returned
spi.transfer(txBuffer, cb(err, rxBuffer))

// writes 0 for each byte requested
// length is number of words (see words option above)
spi.read(length, cb(err, rxBuffer))

// for write only transactions
spi.write(txBuffer, cb(err))

[soundanalogous]

For node-firmata applications we'll also need spi.end()

[nebrius]

Just a thought: what do you think about making txBuffer optional in spi.transfer? This way, read and write are just direct aliases to transfer, and can be literally implemented as:

SPI.prototype.transfer = SPI.prototype.read = SPI.prototype.write = function() ...

[soundanalogous]

The separation is necessary for the following reasons:

• For spi.read a length needs to be supplied to indicate how many bytes to clock in
• spi.write indicates to the underlying implementation that no data is expected in return
• spi.transfer indicates that for each word sent a word should be returned

spi.write and spi.transfer could be consolidated but it would take an additional parameter to specify whether or not to return data. I think having separate write and transfer methods is cleaner.