Writing a driver for a serial connection based instrument

Many instruments which need only low-bandwidth connection use serial connection
to communicate with the host computer. Here are a few notes to help starting the
development of a Odemis driver for such instrument.

= Serial port =
In most cases the serial connection is physically done either over a null-modem
serial cable or, as is typical in recent instruments, over a USB cable which is
connected to a serial port converter. 

In Linux, the name of the port varies depending on the type of connection (as
viewed from the host computer). The actual serial ports in the host computer are
called /dev/ttyS* (where * is a number, usually 0). For USB-based connections, it
is called /dev/ttyUSB* (where * is a number, usually 0). 

In the case of a USB connection, the serial connector might not be recognized 
automatically. In such case you can use lsusb to check for the device. Many 
devices actually use a FTDI serial-USB converter with a special vendor/product 
number. Forcing the load of the ftdi driver can solve it:
sudo modprobe -q ftdi-sio product=0x1008 vendor=0x1a72

In case several instruments are connected to the computer, it can be difficult
to identify automatically which physical cable is under which name (and this
might change after a disconnection or a reboot). So it's recommended to try to
add a symlink to identify it easily. The most easy way to force a name to a
connection is to either link them by vendor/product IDs, or by physical USB
port. Here is a udev rule to automatically get a symlink as /dev/ttyPIE when the
cable with a specific vendor/product ID is plugged in:
SUBSYSTEMS=="usb", ATTRS{idProduct}=="1008", ATTRS{idVendor}=="1a72", KERNEL=="ttyUSB[0-9]*", SYMLINK="ttyPIE"

By default, in Ubuntu, the port is accessible for the group "dialout". So you might need to add your user to this group (and re-login) to access the port.

Another way to differentiate the instruments is to rely on the serial number
reported via the USB protocol. Check /sys/bus/usb/devices/*/serial.

= Trying manually =
As a first phase, it is recommended to try to change the instrument settings, or
recover the instrument data manually, i.e., by typing them in a terminal and
checking that they actually work.

The correct port settings and commands to type have to be found out either by reading the documentation, reading the source code of a working driver, or by tinkering. In most cases, the baudrate is 9600 or a higher one, with 8-bit, no parity, and one stop-bit. Be careful also to the newline, so devices expect CRLF (\r\n), while other expect only CR or only LF.

If you are completely in the dark as to what to type, a good start is the command "*IDN?" which seems supported by many different instruments and usually reports
the name of the device.

A simple and good terminal is the python miniterm. For example, to connect to a PI piezo controller C-867:
miniterm.py --lf -e -DD /dev/ttyUSB0 38400 
*IDN?
ERR?
Ctrl+D  (0x04)

Ctrl+] (To quit)

Note: Everything needs to be written fast (< 1s per character)