Fork me on GitHub

SPI

This library provides Serial Peripheral Interface Bus (SPI) hardware access interface.

C API Reference mgos_spi.h

#include "mgos_spi.h"

See on GitHub: mgos_spi.h, mgos_spi.c


struct mgos_spi *mgos_spi_create(const struct sys_config_spi *cfg);

Initialize SPI master

bool mgos_spi_configure(struct mgos_spi *spi, const struct sys_config_spi *cfg);

(Re)configure existing SPI interface.

struct mgos_spi_txn {
  /* Which CS line to use, 0, 1 or 2. use -1 to not assert any CS
   * during transaction, it is assumed to be done externally.
   * Note: this is not a GPIO number, mapping from cs to GPIO is set by
   * mgos_spi_configure. */
  int cs;
  /* Mode, 0-3. This controls clock phase and polarity. */
  int mode;
  /* Clock frequency to use. 0 means don't change. */
  int freq;
  union {
    /*
     * Half-duplex SPI transaction proceeds in phases: transmit, wait and
     * receive.
     *  - First, tx_len bytes from *tx_data are transmitted
     *  - Optionally, a number of dummy cycles are inserted (in multiples of 8)
     *  - Then rx_len bytes are received into *rx_data.
     * Either tx_len or rx_len can be 0, in which case corresponding pointer can
     * be
     * NULL too.
     */
    struct {
      /* Data to transmit, number of bytes and buffer pointer. Can be 0 and
       * NULL. */
      size_t tx_len;
      const void *tx_data;
      /* Insert the specified number of dummy bytes (multiples of 8 cycles). */
      size_t dummy_len;
      /* Number of bytes and destination buffer for the data. Can be 0 and NULL.
       */
      size_t rx_len;
      void *rx_data;
    } hd;
    /*
     * In a full-duplex SPI transaction data is sent and received at the same
     * time:
     * for every byte sent from *tx_data a byte is stored into *rx_data.
     * Passing the same pointer for tx_data nd rx_data is ok.
     * rx_data may also be NULL, in which case this effectively becomes a simple
     * tx-only transaction.
     */
    struct {
      size_t len;
      const void *tx_data;
      void *rx_data;
    } fd;
  };

bool mgos_spi_run_txn(struct mgos_spi *spi, bool full_duplex,
                      const struct mgos_spi_txn *txn);

Execute a half-duplex transaction.

void mgos_spi_close(struct mgos_spi *spi);

bool mgos_spi_init(void);

struct mgos_spi *mgos_spi_get_global(void);

JAVASCRIPT API Reference api_spi.js

load("api_spi.js");


SPI.get()

Get SPI bus handle. Return value: opaque pointer.

SPI.runTransaction(spi, param)

Run SPI transaction, which might be a half-duplex or a full-duplex one.

Half-duplex transaction includes one or more of the following:

  • Writing data,
  • Waiting for dummy bytes,
  • Reading data.

Full-duplex transaction performs writing and reading at the same time.

Whether the transaction is half-duplex or full-duplex is determined by given params: if "fd" property is set, it's a full-duplex transaction; otherwise "hd" property should be set (see details below).

spi is an SPI instance, e.g. the one returned by SPI.get(). param is an object with the following parameters:

{
  // Which CS line to use, 0, 1 or 2. use -1 to not assert any CS
  // during transaction, it is assumed to be done externally.
  // Note: this is not a GPIO number, mapping from cs to GPIO is set in
  // the device configuration.
  cs: 0,

  // Mode, 0-3. This controls clock phase and polarity.
  mode: 0,

  // Clock frequency to use. 0 means don't change.
  freq: 2000000,

  // Half-duplex transaction parameters
  hd: {
    // A string with data to transmit. If undefined, no data is transmitted.
    tx_data: "foobar",

    // Number of bytes in tx_data to transmit. If undefined,
    // tx_data.length is assumed.
    tx_len: 4,

    // Number of dummy bytes to wait for. If undefined, 0 is assumed.
    dummy_len: 1,

    // Number of bytes to read.
    rx_len: 3,
  },

  // Full-duplex transaction parameters
  fd: {
    // Number of bytes to write and to read.
    len: 3,

    // A string with data to transmit.
    tx_data: "foobar",
  },
}

Return value: a string with the data read (an empty string if no read was requested), or false in case of an error.