Sept. 15, 2015

What's New In the 2015 Ring Buffer Library

Contents

• What's new
• The Requirement
• The Solution
• The Result
• Install
• Try Client/Server
• Develop a Program

What's new

"RingBuffer" is the new name for the BioSemi library that was formerly called "Labview_DLL". The new name was chosen to remove any inference that the library comes from or, is dependent on, the National Instruments "LabVIEW" product.

The most important new feature in RingBuffer library 2015 is support for remote access to the Usb sample stream.

While continuing to support all previous (i.e. Labview_DLL) API calls, the 2015 version of the library has the ability to stream samples from the Usb ring buffer through a Tcp socket to a client program.

Streaming is initiated by a client program and is handled on the server entirely by the library. No participation by the server application itself is required other than to maintain the flow of samples from the Usb interface into the ring buffer.

The impetus for this change was to give tablets and smartphones the ability to tap into acquisition sessions running on Windows, Linux or OSX systems for remote signal monitoring or data analysis.

The Requirement

To be useful four changes were seen as desireable:

• The streaming service should require no change to existing applications.
  
  Since most applications running an acquisition use the RingBuffer (formerly Labview_DLL) library to control sample input, the streaming service could be implemented entirely in this library. Placed there it could be transparent to the application running the acquisition. The library would need only to define a Tcp "listen_port" port that would be monitored for streaming service requests.


• The remote client should be able to dynamically choose what is streamed.
  
  Since the server application itself is not providing the streaming service, the client would have to have full control over what is streamed.


• The client should be able to detect data overrun and other transmission problems.
  
  To detect synchronization problems the existing sync and status words that preceed every set of Usb samples should be part of the transmission. This requirement re-inforces the need for the next requirement - transmitting multiple channels. The stream server should also alert the client if the new sample insertion point in the ring buffer laps the stream output point. This happens when samples cannot be streamed as quickly as new samples arrive from the Usb.


• The ability to transmit multiple channels simultaneously should be possible.
  
  Having multiple simultaneous channels would allow for more ambitious signal monitoring and/or data analysis.

The Solution

To implement these items, the following changes were made in the RingBuffer library:

• When READ_MULTIPLE_SWEEPS is called, a thread is created to perform the streaming operation.


• Once Usb sampling has started, the thread listens on the Tcp "listen_port" for a client connection request.


• When a connection request arrives, the server replies with 2 items:
  
  • The number of channels being sampled.
  • The approximate rate the Usb buffer is being filled, in samples per channel per second. This is a close approximation to the actual sampling rate.


• The client is expected to reply with channel numbers or ranges of channel numbers wanted.


• The server selects a starting point in its ring buffer (i.e. on a sync/status word boundary) and starts the streaming operation. Samples for the channels requested are packed into an output buffer, compressed and transmitted. This selection, compression and transmission repeats continuously as long as new samples become available and the client connected is not closed.


• If the client closes the Tcp connection, the streaming thread resumes waiting for a new connection and new set of channel numbers.


• If the stream server finds that it can't stream samples as fast as new samples arrive, the server will close the connection. The client can immediately re-connect to re-sync with the interrupted transmission but will have missed some channel sets.

The Result

Two methods were used to test and to illustrate the use of this new feature:

• An Android App, BSChannelViewer, was written as a stream client and is included in this download package.

  The App plots sample traces from any channel being sampled on the server on demand. The client re-syncs as necessary whenever internet bandwidth is low.

• Changes were made to the RingBuffer library itself to enable it to act as a stream client as well as a stream server.

  When used as a stream client, the ring buffer is filled with samples from a Tcp socket instead of a Usb interface. This change allows most existing Usb acquisition applications (e.g. ActiView) to be used without modification as remote Tcp acquisition clients.

  The mode, client or server, is determined when the application calls "OPEN_DRIVER". If no unclaimed BioSemi Usb Receiver is found and if an IP address for a potential sample server has been declared in the ringbuffer.ini file, an attempt is made to connect via a Tcp socket to that server's address before declaring an "open failure".

  The client and server programs can be running on the same or different computers.

Install

For a first time install on a Windows computer see Install-Windows .

To update an existing Windows installation (e.g. ActiView or other program), replace all previous RingBuffer.dll (or Labview_DLL.dll) library files with the new version. If using an application that requires the Labview_DLL.dll library, copy and rename the RingBuffer.dll file and use that instead. Be careful to use the bit-width library file that matches the application's bit-width.

The Merging with ActiView or Other Existing Program section of Install-Windows describes in more detail how to prepare an existing program for use with the new RingBuffer library.

For a first time install on a Linux computer see Install-Linux.

To update an existing Linux installation (e.g. an ActiView or other program), replace all previous libRingBuffer (or liblabview_dll) and libusb-1.0 library files with the new versions. If using an application that requires the liblabview_dll library, copy and rename the libRingBuffer file and use that instead. Be careful to use bit-width library files that match the application's bit-width. The "file" command can be used to determine a program's bit-width.

The Merging with ActiView or Other Existing Application section of Install-Linux describes in more detail how to prepare an existing program for use with the new RingBuffer library.

For a first time install on an OSX computer see Install-OSX.

To update an existing OSX installation (e.g. an ActiView or other program), replace all previous libRingBuffer (or liblabview_dll), libusb library files and BioSemi-Ringbuffer (or BioSemi-Labview_DLL) framework files with the new versions. If using an application that requires the liblabview_dll library, copy and rename the libRingBuffer file and use that instead. Be careful to use bit-width files that match the application's bit-width. The "file" command can be used to determine a program's bit-width. If you use the OSX ActiView Application itself (not the .vi's) to run, the National Instruments LabVIEW Application Builder must be used to update the Application - individual components cannot be updated.

The Merging with ActiView or Other Existing Application section of Install-OSX describes in more detail how to prepare an existing program for use with the new RingBuffer library.

Try Client/Server

For step-by-step instructions, see Try Client/Server.

Develop a Program

To develop your own client or server program using the RingBuffer library, see RingBufferLibrary-API for a description of the API's available.

To develop a client program without using the RingBuffer library to receive samples (e.g. as a tablet or smartphone App), see RingBufferLibrary-TransferProtocol for a description of the Tcp transfer protocol used.