2.3 - Multiple Value Functions | LabJack
 
« Close

Datasheets and User Guides

App Notes

Software & Driver

 

2.3 - Multiple Value Functions

Summary

To access device data multiple values at once, use the following functions. See the Modbus map to see what values can be accessed. 

Name Functions

Name functions access data through a name, such as "AIN5" for analog input 5.  

Address Functions

Address functions access data through an address, such as 10 for analog input 5.

LJM automatically splits operations into multiple packets as needed

If an LJM multiple value function is passed a large enough number of read and/or write operations, it will split the reads and writes into separate packets. By default, LJM uses the custom Modbus Feedback command, which can perform both reads and writes.

If a multiple value function is split into multiple packets, it can affect the timing of samples and/or commands. It can also increase the latency of operations. For approximate data rates, see T-series Data Rates.

Maximum packet sizes per connection type:

Checking how many packets are required for a particular set of operations

You can use the LJM debug log with LJM_DEBUG_LOG_LEVEL set to LJM_PACKET or lower to check how LJM sends operations to the device.

To manually calculate how many packets will be sent:

  • Modbus Feedback takes 8 packet header bytes—for the command (to the device) as well as for the response (from the device).
  • Each Modbus Feedback command packet contains one or more frames:
    • Each command Feedback frame has 4 header bytes.
    • Within each command Feedback frame, each address being written has an appropriate number data bytes.
      • (Each 16-bit value being written consists of 2 data bytes; each 32-bit value being written consists of 4 bytes; etc.)
  • Each response has an appropriate number of data bytes.
    • (Each 16-bit address that was read consists of 2 data bytes; each 32-bit value that was read consists of 4 data bytes; etc.)
  • More information:

LJM compresses reads/writes of consecutive addresses

In addition, LJM will automatically "compress" multiple consecutive reads or writes. For example, if you read analog inputs 0 through 13 (in the ordering of AIN0, AIN1, ..., AIN13) and a write to DAC0, LJM will compress the reads into one Modbus Feedback read frame, which takes 4 frame header bytes. For a USB connection to T4s and T7s—which has a 64-byte maximum packet size—this set of operations would take one packet:

  • Command packet:
    • 8 header bytes
    • 4-byte frame header for reading 14 32-bit values starting at AIN0's address (AIN0 through AIN13)
    • 4-byte frame header for writing one 32-bit value at DAC0's address
    • 4-bytes of data for the value being written to DAC0
  • Response packet:
    • 8 header bytes
    • 56 bytes of data for the values read from AIN0 through AIN13

Without compression and a 64-byte maximum packet size, the above operations would take multiple packets—the 14 frames for reading AIN0 through AIN13 would need 56 bytes. After the header's 8 bytes, there would be no room left for the DAC0 bytes.

Large responses can cause multiple packets

If the response is larger than the maximum packet size, it causes the command to be split. For example, reading 15 contiguous analog inputs from a T4 via USB requires two command packets, each with a response:

  • First command/response:
    • Command packet:
      • 8 header bytes
      • 4-byte frame header for reading 14 32-bit values starting at AIN0's address (AIN0 through AIN13)
    • Response packet - 64 bytes total:
      • 8 header bytes
      • 56 bytes of data for the values read from AIN0 through AIN13
  • Second command/response:
    • Command packet:
      • 8 header bytes
      • 4-byte frame header for reading one 32-bit value at AIN14's address
    • Response packet:
      • 8 header bytes
      • 4 bytes of data for the value read from AIN14

LJM sends one command at a time

Each commands-response is synchronous with the next, so LJM sends one command packet and waits for the response before sending another command packet.

LJM follows the specified order of reads/writes

LJM will not reorder operations to minimize the number of packets sent. If AIN1 is read then AIN0 is read, LJM will not compress them into a single command frame because that would cause AIN0 to be read before AIN1.