librpip

librpipTransactionMsgAdd

uint32_t librpipTransactionMsgAdd(struct librpip_tx* t, uint8_t dir, void* txbuf, uint16_t len);

Description

Adds a message segment to a transaction. A transaction is a series of message segments exchanged in one go with a device, and this function lets you add message segments.

How does one work out what is a message segment from the data sheet?

A very good question. Firstly each message segment can on be  a ‘read’, ‘write’ or ‘read+write” (SPI only). So a message segment has only one direction.  Now lets take I2C for example. A common way to access I2C devices is via registers, so to read from an I2C device you send the client, the register to read from and then the device sends back the contents of the register. – So two message segments are required.

If you need to pass multiple bytes to a device then generally speaking this is done by having multiple bytes in a single message segment rather than multiple message segments with a single byte.

Finally, some devices support a ‘command chain mode’ where multiple commands can be sent in one transaction (that is the CS line stays low between commands with SPI or start bits are sent after each commend with I2C) – So in this case your transaction could be quite long with many write & read message segments chained together (see the i2c-mpu6500 example in the distribution).

There are some variants on this function:

• librpipTransactionMsgAddRegRead() – read from a 8bit register
• librpipTransactionMsgAddRegWrite() – write to an 8bit register
• librpipTransactionMsgVarAdd() – create a message segment of unknown content and|or unknown length

Parameters

• struct librpip_tx* t
  A pointer to a transaction that is to have a message added. This will have been created from a previous librpipTransactionCreate().
• uint8_t dir
  The direction of the message. This should be passed as one of the LIBRPIP_TX_MSG_* constants. Note that only SPI transactions support LIBRPIP_TX_MSG_TXRX (simultaneous transmit and receive) messages. This is the nature of SPI.
• void* txbuf
  A pointer to an 8bit buffer of some sort containing data to send. LIBRPIP_TX_MSG_RX (receive) messages should pass a zero. Data provided is copied into an internal data structure so once this call has been made, txbuf can be freed, changed, zeroed etc.
• uint16_t len
  The length of the buffer. For LIBRPIP_TX_MSG_RX (receive) messages this is the length of the receive buffer.

Returns

0 on failure or 1 on success.

Example

Create a transaction to read some values from an I2C sensor, create a 2nd transaction to send/receive on SPI:

uint8_t buf,buf2[3];
struct librpip_tx* MySensor,My2ndSensor;
MySensor=librpipTransactionCreate(LIBRPIP_TX_MODE_I2C, 8);
My2ndSensor=librpipTransactionCreate(LIBRPIP_TX_MODE_SPI, 8);

buf = 0x10;
librpipTransactionMsgAdd(MySensor, LIBRPIP_TX_MSG_TX, &buf, 1);
librpipTransactionMsgAdd(MySensor, LIBRPIP_TX_MSG_RX, 0, 1);
buf = 0x11;
librpipTransactionMsgAdd(MySensor, LIBRPIP_TX_MSG_TX, &buf, 1);
librpipTransactionMsgAdd(MySensor, LIBRPIP_TX_MSG_RX, 0, 1);

buf2[0] = 0x10;
buf2[1] = 0xff;
buf2[2] = 0x00;
librpipTransactionMsgAdd(My2ndSensor, LIBRPIP_TX_MSG_TXRX, &buf2[0], 3);

{ ... do something with MySensor, and My2ndSensor ... }
librpipTransactionDestroy(MySensor); 
librpipTransactionDestroy(My2ndSensor); 
librpipClose();