Skip to main content
Skip table of contents

LJM Stream Configs

The LJM Library stream configurations are described in the following sections. See the LJM stream functions for more info about stream.

LJM_STREAM_AIN_BINARY

Sets whether LJM_eStreamRead will return calibrated or uncalibrated (binary) data.

Below, ScansPerRead is a parameter of LJM_eStreamStart.

LJM_STREAM_AIN_BINARY = 0 (default)

  • LJM_eStreamRead will return calibrated data.

LJM_STREAM_AIN_BINARY = 1

  • LJM_eStreamRead will return uncalibrated (binary) data.

The constant LJM_STREAM_AIN_BINARY can be used interchangeably with the string "LJM_STREAM_AIN_BINARY".

Remarks

LJM_STREAM_AIN_BINARY does not affect currently running or already initialized streams.

Relevant Functions

To read LJM_STREAM_AIN_BINARY, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_AIN_BINARY, use LJM_WriteLibraryConfigS orLJM_LoadConfigurationFile.

LJM_STREAM_AIN_BINARY affects the behavior of LJM_eStreamRead.

For more LJM configurations, see Library Configuration Functions.

LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED

Requires LJM 1.2000 or later

LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED is a numerical readable and writable LJM library configuration which sets how LJM handles auto-recovery when the first channel is not firmware-protected from returning 0xFFFF as a valid data value.

The constant LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED can be used interchangeably with the string "LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED".

Values

0 (default) - Error detection is enabled:

If auto-recovery happens and the first channel is not firmware-protected from returning 0xFFFF (see list below), stream will be stopped and LJM_eStreamRead will return the error LJME_DIGITAL_AUTO_RECOVERY_ERROR_DETECTED (errorcode 1320).

1 - Error detection is disabled:

LJM assumes the user has configured the first stream channel to not return 0xFFFF. However, if auto-recovery occurs and the first stream channel returns 0xFFFF, LJM may insert dummy scans in the wrong location in stream.

How to Eliminate LJME_DIGITAL_AUTO_RECOVERY_ERROR_DETECTED (Errorcode 1320)

There are three ways to get rid of LJME_DIGITAL_AUTO_RECOVERY_ERROR_DETECTED.

  1. Easiest solution: Set the first channel in stream to a channel that never returns 0xFFFF. See the list of channels that never return 0xFFFF, below. Simply do this, and you don't need to concern yourself with anything on this page.

  2. Make sure auto-recovery never happens. See these options for reducing auto-recovery.

  3. If you must use a channel that is capable of returning 0xFFFF as the first channel, you should take precautions to make sure it won't return 0xFFFF (by jumpering 1 digital input to GND, for example). Then, set LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED = 1. If you can't guarantee the first channel will never return 0xFFFF, you can still set LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED = 1, but dummy scans may be inserted by LJM at the wrong place.

Channels that never return 0xFFFF during stream:

  • Analog inputs (AIN0, AIN1, ...)

  • FIO_STATE

  • EIO_STATE

  • CIO_STATE

  • MIO_STATE

  • EIO_CIO_STATE

  • CIO_MIO_STATE

Individual DIO registers like DIO2 also will never return 0xFFFF, but _STATE registers should be used instead because they're generally more efficient for communication bandwidth. LJM versions 1.2100 and prior mistakenly do not treat individual DIO registers as if they never return 0xFFFF.

Channels capable of returning 0xFFFF include:

  • FIO_EIO_STATE

  • DIO#(0:22)_EF_READ_A

  • DIO#(0:22)_EF_READ_A_AND_RESET

  • DIO#(0:22)_EF_READ_B

  • CORE_TIMER

  • SYSTEM_TIMER_20HZ

  • STREAM_DATA_CAPTURE_16

Details

Setting a new LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED value will not affect stream sessions that are already in progress.

Rationale

The low level streaming protocol uses one or more 0xFFFF values to indicate a gap in stream data. Such a gap happens because the device scan buffer ran out of space. LJM adds dummy scans to fill this gap. Some channels return 0xFFFF as a valid data value, so LJME_DIGITAL_AUTO_RECOVERY_ERROR_DETECTED (errorcode 1320) happens when three conditions are true:

  • Auto-recovery happens (the device scan buffer ran out of space)

  • The first channel is not firmware-protected from returning 0xFFFF

  • LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED is 0

When those conditions are true, LJME_DIGITAL_AUTO_RECOVERY_ERROR_DETECTED (errorcode 1320) is returned because dummy scans could be inserted at the wrong spot in the stream data.

Relevant Functions

To read LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED, use LJM_WriteLibraryConfigS or LJM_LoadConfigurationFile.

Example

Read LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED then set it to 1.

C 
char ErrorString[LJM_MAX_NAME_SIZE];
double value;

int LJMError = LJM_ReadLibraryConfigS(LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED, &value);
if (LJMError != 0) {
    LJM_ErrorToString(LJMError, ErrorString);
    printf("LJM_ReadLibraryConfigS error: %s\n", ErrorString);
}
printf("The default for LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED is %.00f\n", value);

value = 1;
printf("Setting LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED to %.00f\n", value);
LJMError = LJM_WriteLibraryConfigS(LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED, value);
if (LJMError != 0) {
    LJM_ErrorToString(LJMError, ErrorString);
    printf("LJM_WriteLibraryConfigS error: %s\n", ErrorString);
}

Output:

The default for LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED is 0
Setting LJM_STREAM_DIGITAL_AUTO_RECOVERY_ERROR_DETECTION_DISABLED to 1

For more LJM configurations, see Library Configuration Functions.

LJM_STREAM_PROCESS_PRIORITY_MODE

Requires LJM 1.2100 or later. Windows-only.

On Linux, chrt can be used to increase process priority: chrt --rr 1 ./my_test

Sets whether or not LJM elevates the process priority temporarily during stream.

LJM_STREAM_PROCESS_PRIORITY_ELEVATED = 1 (default)

  • Elevates the process priority when LJM_eStreamStart or LJM_StreamBurst is successfully called. When LJM_eStreamStop is called or when LJM_StreamBurst ends, process priority is reset back to what it was essentially when the first LJM call was made (or NORMAL_PRIORITY_CLASS if the initial call to GetPriorityClass() failed).

  • Windows: Elevates process priority to REALTIME_PRIORITY_CLASS.

  • Linux/macOS: Not implemented.

LJM_STREAM_PROCESS_PRIORITY_UNALTERED = 2

  • The priority of the process is not altered.

The constant LJM_STREAM_PROCESS_PRIORITY_MODE can be used interchangeably with the string "LJM_STREAM_PROCESS_PRIORITY_MODE".

Remarks

LJM_STREAM_PROCESS_PRIORITY_MODE does not affect currently running or already initialized streams.

If process priority cannot be set, a debug log message is generated.

See also the related LJM_STREAM_THREADS_PRIORITY_MODE, which sets priority for threads instead of for the process.

Relevant Functions

To read LJM_STREAM_PROCESS_PRIORITY_MODE, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_PROCESS_PRIORITY_MODE, use LJM_WriteLibraryConfigS or LJM_LoadConfigurationFile.

LJM_STREAM_SCANS_RETURN

Sets how LJM_eStreamRead will return data.

Below, ScansPerRead is a parameter of LJM_eStreamStart.

LJM_STREAM_SCANS_RETURN_ALL = 1 (default)

  • A mode that will cause LJM_eStreamRead to sleep until the full ScansPerRead scans are collected by LJM.

  • This mode may not be appropriate for stream types that are not consistently timed, such as externally clocked stream mode.

LJM_STREAM_SCANS_RETURN_ALL_OR_NONE = 2

  • A mode that will cause LJM_eStreamRead to never sleep, and instead either:

  • consume ScansPerRead scans and return LJME_NOERROR, or

  • consume no scans and return LJME_NO_SCANS_RETURNED.

The constant LJM_STREAM_SCANS_RETURN can be used interchangeably with the string "LJM_STREAM_SCANS_RETURN".

Remarks

LJM_STREAM_SCANS_RETURN does not affect currently running or already initialized streams.

Relevant Functions

To read LJM_STREAM_SCANS_RETURN, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_SCANS_RETURN, use LJM_WriteLibraryConfigS or LJM_LoadConfigurationFile.

LJM_STREAM_SCANS_RETURN affects the behavior of LJM_eStreamRead.

Example

Set the LJM_STREAM_SCANS_RETURN mode to LJM_STREAM_SCANS_RETURN_ALL_OR_NONE.

C 
char ErrorString[LJM_MAX_NAME_SIZE];
int LJMError = 0;
LJMError = LJM_WriteLibraryConfigS(
     LJM_STREAM_SCANS_RETURN,
     LJM_STREAM_SCANS_RETURN_ALL_OR_NONE
);
if (LJMError != 0) {
    LJM_ErrorToString(LJMError, ErrorString);
    printf("LJM_WriteLibraryConfigS error: %s\n", ErrorString);
}

For more LJM configurations, see Library Configuration Functions.

LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE

Requires LJM 1.2000 or later

Sets the TCP receive buffer size for LJM's stream data collection. This can reduce the frequency of auto-recovery. Behavior varies by platform.

For a background on the receive buffer, see LJM_GetStreamTCPReceiveBufferStatus.

Writing 0 to LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE will use the OS default receive buffer size, which probably includes auto-tuning. This is appropriate for most use cases. The default LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE is 0.

Writing a non-zero value to LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE will manually set the receive buffer size. Internally, setsockopt is called with SO_RCVBUF as the option parameter.

Since behavior for setting the receive buffer size varies by platform, you should try out different values of LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE until you find the maximum. For example, you should start with a small value like 65535 (which doesn't require window scaling) and exponentially increase it until an error occurs. Your test program should set LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE, then start stream and call LJM_GetStreamTCPReceiveBufferStatus, ensuring that the ReceiveBufferBytesSize is equivalent to your intended stream receive buffer size.

You may also wish to use Wireshark to capture packets to see what the maximum window size your host computer reports the window size to be. To do so, you can start a new capture with a filter like ip.addr == 192.168.1.207, where 192.168.1.207 is your LabJack's IP address, then find the first packet addressed to 192.168.1.207 with port 702. The window size and window scaling of that packet determines the window size as reported to the LabJack device.

Here are some known platform differences:

  • A Windows 10 computer was shown to be able to increase the receive buffer size until about 2147483647, which is the maximum number that Windows' recv function can take as the len parameter (due to the len parameter being a signed 32-bit integer). After this point, LJM will return LJME_NEGATIVE_RECEIVE_BUFFER_SIZE (errorcode 1321).

  • A macOS computer was shown to be able to increase the receive buffer size until about 7400000, when LJM_eStreamStart returns LJME_SOCKET_LEVEL_ERROR.

  • Linux may accept any receive buffer size and silently reduce it to adhere to system configurations.

The constant LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE can be used interchangeably with the string "LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE".

Remarks

LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE does not affect currently running or already initialized streams.

Relevant Functions

To read LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE, use LJM_WriteLibraryConfigS orLJM_LoadConfigurationFile.

LJM_STREAM_TCP_RECEIVE_BUFFER_SIZE affects the behavior of LJM_eStreamStart.

For more LJM configurations, see Library Configuration Functions.

LJM_STREAM_THREADS_PRIORITY_MODE

Requires LJM 1.2100 or later.

Determines how LJM sets processor priority for LJM's internal stream threads.

LJM_STREAM_THREADS_PRIORITY_AUTO_ELEVATED = 1 (default)

  • LJM sets elevated priority on internal stream threads as they are created.

  • Device data collection thread:

  • Windows: THREAD_PRIORITY_TIME_CRITICAL

  • Linux/macOS: Real-time SCHED_FIFO, priority 90

  • Other LJM stream threads, including any callback threads (see LJM_SetStreamCallback):

  • Windows: THREAD_PRIORITY_HIGHEST

  • Linux/macOS: Real-time SCHED_RR, priority 50

LJM_STREAM_THREADS_PRIORITY_UNALTERED = 2

  • LJM's internal stream threads inherit priority.

The constant LJM_STREAM_THREADS_PRIORITY_MODE can be used interchangeably with the string "LJM_STREAM_THREADS_PRIORITY_MODE".

Remarks

LJM_STREAM_THREADS_PRIORITY_MODE does not affect currently running or already initialized streams.

If thread priority cannot be set, a debug log message is generated.

See also the related LJM_STREAM_PROCESS_PRIORITY_MODE, which sets priority for the process instead of for threads.

Relevant Functions

To read LJM_STREAM_THREADS_PRIORITY_MODE, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_THREADS_PRIORITY_MODE, use LJM_WriteLibraryConfigS or LJM_LoadConfigurationFile.

LJM_STREAM_TRANSFERS_PER_SECOND

LJM_STREAM_TRANSFERS_PER_SECOND is a numerical readable and writable LJM library configuration which sets how many times per second LJM's stream thread attempts to receive stream packet(s) from the device.

The constant LJM_STREAM_TRANSFERS_PER_SECOND can be used interchangeably with the string "LJM_STREAM_TRANSFERS_PER_SECOND".

Details

LJM_STREAM_TRANSFERS_PER_SECOND is an advanced configuration. Modifying it is not recommended for most users.

Increasing LJM_STREAM_TRANSFERS_PER_SECOND to a higher value will allow for less latency in receiving stream data, since LJM will receive data from the device more often (in smaller quantities). Increasing the LJM_STREAM_TRANSFERS_PER_SECOND too much will cause the data contained in each packet to decrease, which will cause unnecessary overhead and potentially cause scans to be missed.

You can enable debug logging with LJM_TRACE as the LJM_DEBUG_LOG_LEVEL to see how stream is set up. After running a test stream, search the log file for the term "streaming initialized" to see what effects LJM_STREAM_TRANSFERS_PER_SECOND has on stream setup. Make sure to disable debug logging for your real stream sessions after finding settings for stream setup that looks reasonable, since debug logging consumes a significant amount of processing. LJM's stream setup is deterministic, so given the same parameters to LJM_eStreamStart and the same stream configurations, stream will be set up the same way every time.

Decreasing LJM_STREAM_TRANSFERS_PER_SECOND to a lower value will theoretically cause less overhead in stream, since LJM will receive data from the device less often (in larger quantities), but may have little to no effect. When decreasing LJM_STREAM_TRANSFERS_PER_SECOND, it is recommended to increase the size of the stream buffer on the device. See the Modbus register STREAM_BUFFER_SIZE_BYTES (address: 4012).

Setting a new LJM_STREAM_TRANSFERS_PER_SECOND value will not affect stream threads that are already in progress.

Relevant Functions

To read LJM_STREAM_TRANSFERS_PER_SECOND, use LJM_ReadLibraryConfigS.

To write LJM_STREAM_TRANSFERS_PER_SECOND, use LJM_WriteLibraryConfigS or LJM_LoadConfigurationFile.

Example

Read LJM_STREAM_TRANSFERS_PER_SECOND then set it to 100.

C 
char ErrorString[LJM_MAX_NAME_SIZE];
double value;

int LJMError = LJM_ReadLibraryConfigS(LJM_STREAM_TRANSFERS_PER_SECOND, &value);
if (LJMError != 0) {
    LJM_ErrorToString(LJMError, ErrorString);
    printf("LJM_ReadLibraryConfigS error: %s\n", ErrorString);
}
printf("The default for LJM_STREAM_TRANSFERS_PER_SECOND is %.00f\n", value);

value = 100;
printf("Setting LJM_STREAM_TRANSFERS_PER_SECOND to %.00f\n", value);
LJMError = LJM_WriteLibraryConfigS(LJM_STREAM_TRANSFERS_PER_SECOND, value);
if (LJMError != 0) {
    LJM_ErrorToString(LJMError, ErrorString);
    printf("LJM_WriteLibraryConfigS error: %s\n", ErrorString);
}

Possible output:

The default for LJM_STREAM_TRANSFERS_PER_SECOND is 25
Setting LJM_STREAM_TRANSFERS_PER_SECOND to 100

For more LJM configurations, see Library Configuration Functions.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close