Command line interface

The previous version of this page

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.

The UART-CLI is compatible with both UART- and USB-firmwares, regardless of the MCU employed.

Both CLIs send user input to the STM32 and return the collected data in a file/files.

The UART-CLI is dependent on gnuplot-x11 and takes the following user input:

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

for example:

./Otterly-CCD-CLI -p -i 200000 -s 500 -n 4 -t ttyACM1 -o outputfile

The SPI-CLI requires root priviledges to be able to access the GPIOs of the raspberry pi. The program takes the following user input:

  • ICG- and SH-period
  • Integrations to collect
  • output file name

for example:

sudo ./Otterly-rpiCLI -i 200000 -s 50000 -n 32 -o outputfile

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 in the UART-fw and 4.0 MHz in the SPI-fw, and 800 kHz for the STM32F103-fw.

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 with the STM32F4 firmwares, 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.

To avoid overwriting data before it has been stored in RAM, the following should be observed, when using the -n option with the UART-fw:

ICG-period = n·SH-period ≥ 30 000

To avoid overwriting data before it has been transmitted to the rpi, the following should be observed, when using the -n option with the SPI-fw:

ICG-period = n·SH-period ≥ 32 000

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

NB: The overhead considerations above are for the STM32F4. I have not measured with the STM32F103. Keep also in mind, that the SH- and ICG-period cannot exceed 65536 when using the STM32F103, as the MCU has no 32-bit timers.

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.


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.

To ensure that the firmware has time to store the individual integrations, the following conditions should be met:

ICG-period = n·SH-period ≥ 30 000

NB: The overhead considerations above is for the STM32F4. I have not measured with the STM32F103.

Integrations (SPI-only)

The SPI-fw can collect and transmit up to 65 535 integrations with a single command.

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

Each integration is stored in it own file, named according to the following scheme:


The temporal spacing of the integrations is defined by the ICG-period, with one integration performed after each ICG-pulse, eg:

Δt = ICG-period / fM = 400 000 / 4.0 MHz = 0.10 s

Collection and transmission of a complete dataset takes 3.7 ms and 4.2 ms respectively, so to avoid overwriting data before it has been transmitted, the ICG-period should be at least 8 ms, ie.

ICG-period = n·SH-period ≥ 32 000

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.

Plot (UART-only)

When passed the -p flag, the command line interface will open a gnuplot-x11 window and plot the collected data.

The UART-CLI uses the gnuplot_i library written by N.Devillard.