QSB Linux Demo

DESCRIPTION
-----------

The file streamQSB.c is provided as a demonstration c program of how to 
communicate with the QSB in a Linux environment. It was tested using 
Ubuntu 22.04.3 LTS (jammy) but should work similarly in other Debian-
based distributions. 

The program opens a USB serial port and configures is to communicate with a
QSB device at 230400 Baud, 8 data bits, no-parity, 1 stop bit. The QSB is then
configured to read an encoder in quadrature mode, X4 counter mode, index 
disabled, modulo-N, counter enabled, and the counter preset register set to 
1999.  This will allow the counter to count up to 2000 pulses before 
restarting at 0. The streaming interval is set to 0, enabling the QSB to 
stream as fast as possible. The program can be modified to stream at other 
interval rates divisible by 1.95 milliseconds.  The Threshold register is
set to 1 so that streaming output occurs when the encoder value changes by 1.

The program displays the streamed count value and a timestamp to the terminal
until the user presses ESC or Ctrl-C.  The timestamp displayed is the QSB's
timer counter that internally updates at a 1.95 ms interval.  The display units
are in seconds. The timestamp counter starts at 0 when the device is powered on or
when the QSB receives a reset timestamp request. The demo resets the timestamp 
after configuring the device.

FINDING THE QSB
---------------

The program depends on a hot/cold-plugging mechanism like udev to map the 
QSB to a USB-to-serial device. The code assumes that no other USB tty 
device is present and tries to open /dev/ttyUSB0. This may be a problem in 
systems where other USB devices are present that also act as UARTs. Linux 
is not deterministic in assigning node files to the scanned devices upon 
boot; there is also a possibility that the QSB is plugged later on, when 
an unknown number of devices may have been connected to the computer.

CREATING A SYMBOLIC LINK
------------------------
One way to deal with this issue is by creating a symbolic link in the /dev 
directory with a  predetermined node name that the code can safely use. 
For example, /dev/qsb could be a predetermined link that refers to the 
actual device assigned by the Kernel. The specific ways to do this vary 
by distribution and by hot-plugging mechanism and are out of the scope 
of this demo.

An example rules configuration file has been included called 99-usb-serial.rules.
This file should be placed in the /etc/udev/rules.d directory.
It is used to map a usb device that have been added to the system with a 
specific idVendor of 0403 and idProduct of 6001 to a symbolic link call QSB-DEVICE.
The demo program assigns the SERIAL_PORT to the QSB-DEVICE symbolic link.

When a QSB device is plugged in, you should see ttyUSB0 and the symbolic link 
QSB-DEVICE show up in the /dev directory.  
Type cd /dev to switch to the /dev directory and ls to list the content of the directory.

For information on using udev to create the link automatically at boot or 
at plug-in time, check the following resources:

  - en.wikipedia.org/wiki/udev
  - reactivated.net/writing_udev_rules.html
  - ubuntuforums.org/showthread.php?t=168221

The following values for the QSB may be useful when configuring the 
hot-plugging mechanism:

  - Vendor ID: 0403
  - Product ID: 6001
  
PERMISSIONS
-----------
You may run into permission issues accessing the device.  Rather than granting execute
permissions to ttyUSB0 or QSB-DEVICE, which comes and goes as the device is plugged
or unplugged, add yourself to the permission group the ttyUSB0 device belongs to.

To see the groups you are in, type: groups

To see all available groups, type: compgen -g
We are looking for the groups, tty and dialout. 

To add yourself to the tty group, type: sudo usermod -a -G tty username
To add yourself to the dialout group, type: sudo usermod -a -G dialout username

RUNNING THE DEMO
----------------

The code is self-contained and does not need anything beyond stdlibc, so 
the compilation should be straightforward:

	gcc -o streamQSB streamQSB.c

Make sure to plug in the QSB before running the demo to avoid errors due to
a missing dev node. Depending on your particular setup, some modifications 
to the code may be necessary.

If you prefer and integrated development environment, download and install VS Code.
https://code.visualstudio.com/Download. 
