Command line interface

A short manual for the CLI

The command line interface (CLI) exists in two versions. The SPI-enabled CLI, and the UART-enabled CLI. Needless to say, the communication protocol of the CLI must match that of firmware.

Both CLIs send user input to the STM32F401RE and return the collected data in a file.

The UART-CLI takes the following user input:

  • ICG- and SH-period
  • integrations to average
  • tty-device
  • output file name

for example:

./Otterly-CCD-CLI -i 200000 -s 50000 -n 4 -t ttyACM1 -o output1.dat

The SPI-CLI takes the following user input:

  • ICG- and SH-period
  • Master clock frequency in Hz
  • output file name

for example:

./Otterly-rpiCLI -i 200000 -s 50000 -f 1400000 -o output1.dat

ICG- and SH-period

To give the user full control of the CCD, the input parameters do not include integration time, which would probably be the intuitive choice. The integration time is derived from the SH-period.

The timer controlling the SH-pulse has a clock identical to the CCD’s master clock (fM), which is configurable only at compile time of the firmware. If you have not changed anything in main.h or simply used the precompiled binary, fM is 2.0 MHz.

The integration time and the SH-period are related like this:

t_int = SH-period / fM = 50000 / 2.0 MHz = 25 ms

the minimum integration time for the TCD1304 is 10 µs.

For reasons unknown to me, odd SH-periods cause periodic noise, so I recommend you stick with even numbers for the SH-period.

The ICG-pulse together with the SH-pulse, defines the moment when the CCD shifts the pixels to the output. The timer controlling the ICG-pulse runs with a clock identical to fM, and because there are 3694 pixels and it takes 4 fM-cycles to move a pixel, the minimum ICG-period becomes 4·3694 = 14776.

However, to fullfil the timing requirements of the CCD, the ICG-pulse must coincide with an SH-pulse (but not necessarily all of them), so the ICG-period must be keept to an integer multiple of the SH-period:

ICG-period = n·SH-period ≥ 14776

if n = 1, the CCD runs in normal mode, if n > 1 the CCD runs in electronic shutter mode.

The ICG-period is passed on to the CLI with the -i option, and the SH-period with the -s option.

TTY-device (UART-only)

On linux (Debian Jessie) the nucleo board is – most often – attached to:


This is the default value for the CLI. Only if the nucleo is attached to something else, is the -t option needed. Check the contents of /dev/ or run dmesg if the CLI returns an error related to the tty-port.

On macOS I really have no idea what the nucleo attaches to by default – I think there is no default, so the -t option is mandatory. I’ve had success with:


Check the contents of /dev/ to figure out what XXX should be.

NB: The /dev/ prefix should be omitted when passing the -t option.

Master clock frequency (SPI-only)

Because of something(!?), the SPI-controller on the Raspberry Pi must be master. This means the nucleo cannot just transmit the collected data when it’s ready, it must wait for the master to initiate communication.

For this reason, the CLI needs to know when it can expect the nucleo to have data ready for transmission, and to calculate this the CLI needs to know the CCD master clock (fM).

fM is passed on to the CLI with the -f option and must be stated in Hz. The default value is 2.0 MHz. The -f option is only needed if the firmware has been compiled with a different fM.

Average (UART-only)

Transmission of a dataset takes more than 640 ms over UART, regardless of the integration time which for many applications of the CCD is only a few ms or less.

However, the UART -firmware is capable of collecting 1-15 integrations and average them before sending the data back to the computer.

The number of integrations to average is passed with the -n option. If -n is not specified the firmware will perform one integration.

Output file

The default output filename is output.dat

To specify another output filename use the -o option.

The output file has the following format:

1    3920
2    3915
3    3922
..     ..
234  2155
235  2134
..     ..
3694 3905

The first column is the pixel number, the second is the pixel value. The first 32 and the last 14 pixels are dummies.

The pixel values are dictated by the resolution and range of the ADC. The resolution is 12-bit so the maximum value is 2¹²-1 = 4095. The range is 0-3.3V  meaning the pixels will have values in the range of app. 1500-3900 when using the typical drive circuit.

Pixel values higher than 4095 indicate problems with the communication.