« Close

Datasheets and User Guides

App Notes

Software & Driver

 
Table of Contents

5.2.12 - StreamData [U3 Datasheet]

After starting the stream, the data will be sent as available in the following format. Reads oldest data from buffer. Requires U3 hardware version 1.21 or higher.

Table 5.2.12-1. StreamData Response

Response:  
Byte  
0 Checksum8
1 0xF9
2 4 + SamplesPerPacket
3 0xC0
4 Checksum16 (LSB)
5 Checksum16 (MSB)
6-9 TimeStamp
10 PacketCounter
11 Errorcode
12-13 Sample0
62 (max) Backlog
63 (max) 0×00
  • SamplesPerPacket: From StreamConfig function.
  • TimeStamp: Not currently implemented during normal operation, but after auto-recovery bytes 6-7 reports the number of packets missed (1-65535).
  • PacketCounter: An 8-bit (0-255) counter that is incremented by one for each packet of data. Useful to make sure packets are in order and no packets are missing.
  • Sample#: Stream data is placed in a FIFO (first in first out) buffer, so Sample0 is the oldest data read from the buffer. The analog input reading is returned justified as a 16-bit value. Differential readings are signed, while single-ended readings are unsigned.
  • Backlog: When streaming, the processor acquires data at precise intervals, and transfers it to a FIFO buffer until it can be sent to the host. This value represents how much data is left in the buffer after this read. The value ranges from 0-255, where 256 would equal 100% full.

Stream mode on the U3 uses a feature called auto-recovery. If the stream buffer gets too full, the U3 will go into auto-recovery mode. In this mode, the U3 no longer stores new scans in the buffer, but rather new scans are discarded. Data already in the buffer will be sent until the buffer contains less samples than SamplesPerPacket, and every StreamData packet will have errorcode 59. Once the stream buffer contains less samples than SamplesPerPacket, the U3 will start to buffer new scans again. The next packet returned will have errorcode 60. This packet will have 1 dummy scan where each sample is 0xFFFF, and this scan separates new data from any pre auto-recovery data. Note that the dummy scan could be at the beginning, middle, or end of this packet, and can even extend to following packets. Also, the TimeStamp parameter in this packet contains the number of scans that were discarded, allowing correct time to be calculated. The dummy scan counts as one of the missing scans included in the TimeStamp value.

11 comments

Submitted by Sean (not verified) on Wed, 08/14/2013 - 10:01

Hello,

 

I have some questions about auto-recovery mode.

 

1) For StreamData packets that have errorcode 59: is the payload (that is, bytes 12-61) still valid data, from before overflow started to occur?

 

2a) doc say: "after auto-recovery bytes 6-7 reports the number of packets missed (1-65535)." Which of bytes 6 & 7 are the MSB and LSB?

 

2b) If more than 65535 packets are missed, does this counter wrap around, or saturate at 65535?

 

3) When the U3 starts to buffer again, I'll get a packet with errorcode=60.  Things become a bit unclear to me at this point. Doc say "This packet will have 1 dummy scan where each sample is 0xFFFF."  Can you define the nouns "scan" and "sample" in this context?  Also, is it 'exactly 1' or 'at least 1'?

Thanks,
Sean
Submitted by LabJack Support (not verified) on Thu, 08/15/2013 - 11:59

Hello,

 

1) Yes the data is still valid. The device has stopped collecting data, and data that is already in the buffer is still being sent to the host computer.

 

2a) The protocol is little-endian, so 6 is the LSB.

2b) The counter will wrap. This would require an extreme situation where stream isn't really feasible to begin with.

 

3) There is one and only one dummy scan.

 

Glossary:

Sample - One value from the analog system.

Scan - A stream scan is a set of readings. The number of readings is equal to the specified number of stream channels.

Submitted by Sean (not verified) on Thu, 08/15/2013 - 16:16

 

Thank you for the helpful answers.  My code currently naively assumes auto-recovery mode never happens, and I am updating it to deal with it properly.

 

If I pause my process in the debugger, I am able to force auto-recovery mode to occur.  When I resume my process, I then receive a packet with errorCode=60.  It has a reasonable timestamp value, proportional to how long my process was paused.  So far so good.

 

Next, a clarification regarding 'there is one and only one dummy scan'.  I have 3 channels.  My understanding is that bytes 12-61 of the packet are a sequence of int16s that represent ch1, ch2, ch3, and then wrap and repeat, right?  So in fact I would expect three 0xFFFFs, right?  And since SamplesPerPacket (25 for me) is not necessarily a multiple of the number of channels (3 for me) that explains the doc's comment "note that the dummy scan could be at the beginning, middle, or end of this packet, and can even extend to following packets".  The 3 0xFFFFs could start at the end of one packet and wrap to the beginning of another, yes?  In that case, does the second packet also have errorCode=60?

 

Submitted by LabJack Support (not verified) on Fri, 08/16/2013 - 04:37

Your interpretation is correct. And no, only one packet will report that auto-recover has ended (60).

I'm am concerned that you are doing all this work unnecessarily. We have already written stream support for a lot of languages. Do you prefer to do things low-level? Or did we miss the language that you are using?

Submitted by Sean on Fri, 08/16/2013 - 08:03

I am using this code from you https://github.com/labjack/exodriver.  Now that I look more closely, I see there is a u3Stream.c example, which I'll look at. I'm using C/C++/Objective-C on Mac OS X.

Submitted by Sean (not verified) on Thu, 08/29/2013 - 15:17

So I've got this working, except I often (though not always) see more 0xFFFF sequences than expected.  Again, I'm using 3 channels.  So as discussed, I should be seeing 3 0xFFFFs.  Often I see 6 instead of 3.  Have you ever seen that, or have any theories/explanations/ideas?  (I have seen this on several devices with several firmware versions.)

Submitted by LabJack Support (not verified) on Wed, 09/04/2013 - 11:47

I was not aware that double 0xFF scans were possible. I would think that would cause problems for our drivers.

Submitted by Sean on Wed, 01/13/2016 - 10:25

So it's been a couple of years :), but I am back to investigating this bug. :)

my code is basically the following:

while true

  call LJUSB_Stream()

  for (all packets)

    log PacketCount & Errorcode fields

    for (all samples 0 to 24)

      log sample value & especially note if it's FFFF

Here's some of my real output where things go as expected, namely I get an 0xFFFF for each of the 3 channels 

Starting packet: PacketCounter = 068; Errorcode = 59; Backlog = 1

Normal sample 0x6080: PacketCounter = 068; sample# = 00

Normal sample 0x50FC: PacketCounter = 068; sample# = 01

<...>

Normal sample 0x5080: PacketCounter = 068; sample# = 23

Normal sample 0x6080: PacketCounter = 068; sample# = 24

Starting packet: PacketCounter = 069; Errorcode = 60; Backlog = 0

Normal sample 0x50FC: PacketCounter = 069; sample# = 00

Normal sample 0x6080: PacketCounter = 069; sample# = 01

Normal sample 0x6080: PacketCounter = 069; sample# = 02

Normal sample 0x50FC: PacketCounter = 069; sample# = 03

Ignoring first dummy 0xFFFF: PacketCounter = 069; sample# = 04; lost = 1005

Ignoring next dummy 0xFFFF: PacketCounter = 069; sample# = 05

Ignoring next dummy 0xFFFF: PacketCounter = 069; sample# = 06

Normal sample 0x6080: PacketCounter = 069; sample# = 07

Normal sample 0x4080: PacketCounter = 069; sample# = 08

Normal sample 0x50FC: PacketCounter = 069; sample# = 09

<...>

Now here's some seconds later I get twice as many 0xFFFF as expected:

Starting packet: PacketCounter = 110; Errorcode = 59; Backlog = 2

Normal sample 0x50FC: PacketCounter = 110; sample# = 00

Normal sample 0x5080: PacketCounter = 110; sample# = 01

<...>

Normal sample 0x7080: PacketCounter = 110; sample# = 23

Normal sample 0x50FC: PacketCounter = 110; sample# = 24

Starting packet: PacketCounter = 111; Errorcode = 60; Backlog = 0

Normal sample 0x6080: PacketCounter = 111; sample# = 00

Normal sample 0x6080: PacketCounter = 111; sample# = 01

Normal sample 0x50FC: PacketCounter = 111; sample# = 02

Ignoring first dummy 0xFFFF: PacketCounter = 111; sample# = 03; lost = 450

Ignoring next dummy 0xFFFF: PacketCounter = 111; sample# = 04

Ignoring next dummy 0xFFFF: PacketCounter = 111; sample# = 05

Ignoring next dummy 0xFFFF: PacketCounter = 111; sample# = 06

Ignoring next dummy 0xFFFF: PacketCounter = 111; sample# = 07

Ignoring next dummy 0xFFFF: PacketCounter = 111; sample# = 08

Normal sample 0x6080: PacketCounter = 111; sample# = 09

Normal sample 0x6080: PacketCounter = 111; sample# = 10

Normal sample 0x50FC: PacketCounter = 111; sample# = 11

<...>

This latter case is unexpected if I understand the docs correctly, right?

Submitted by LabJack Support on Wed, 01/13/2016 - 17:30
LabJack Support's picture

We need to look into this further. With a 3 channels stream and when autorecovery ends I am seeing 1 or 2 dummy scans (3 or 6 0xFFFFs dummy samples) like you are on a Linux machine.

Submitted by Sean on Wed, 01/13/2016 - 19:50

I'm so happy that you can repro!  I wish I'd gotten further in my investigation a couple of years ago, you mighta had it fixed by now. :)

Submitted by LabJack Support on Fri, 01/15/2016 - 05:02
LabJack Support's picture

We found a condition that could cause more than one delimination scan to be produced. Beta firmware 1.50 has a fix: https://labjack.com/support/firmware/u3/beta

Copyright © 2001-2099 LabJack Corporation. All rights reserved.