Measurements

The JII-MultispeQ package allows the direct connection to a MultispeQ using a python script, instead of using a separate application. In the following examples, it’s shown how to connect to a MultispeQ, use protocols or commands with the device and save the measurements to your local computer, as well as analyze them with custom functions and load them for a later analysis.

Important

The JII-MultispeQ package is for local measurements. If the measurements are intended to be saved with a project online, use the PhotosynQ, Inc. Desktop or Mobile app.

Connect a MultispeQ

Make sure your MultispeQ is powered on and connect it to your computer either using USB or Bluetooth®. After that, you have to open the connection by selecting the Serial port the device is connected to. Depending on the operating system used, the port names have different names.

Basic Serial Port Names depending on the OS

Operating system	USB	Bluetooth®
Windows	COM…	COM…
macOS	usbmodem…	Instrument-Name
Linux	ACM…	Not tested

Note

Connecting a Device

1. When connecting the device via USB, make sure the mirco-USB cable is designed for data transfer, not just charging.

2. When using Bluetooth®, the required pairing code is 1234.

Available Ports

Use the get_ports() to see the list of available ports on your computer. Make sure to use the port, not just the name when selecting your device’s port.

Example: Get a list of available serial ports and connected devices.

import jii_multispeq.device as _device

## View Ports
_device.get_ports( )

Example: Output of the jii_multispeq.device.get_ports() function (on macOS).

Port                             Name                        Description    Manufacturer    Product
-------------------------------  --------------------------  -------------  --------------  ----------
/dev/cu.debug-console            cu.debug-console            n/a
/dev/cu.Bluetooth-Incoming-Port  cu.Bluetooth-Incoming-Port  n/a
/dev/cu.usbmodem42949672951      cu.usbmodem42949672951      USB Serial     Teensyduino     USB Serial
/dev/cu.MultiSpeQ                cu.MultiSpeQ                n/a

Establish a Connection

Once the serial port is identified, use the following code to open the connection to your MultispeQ device. The returned connection (serial.serialposix.Serial) will be used with all other functions.

Example: Open a connection to a MultispeQ device.

import jii_multispeq.device as _device

## Establish connection
_connection = _device.connect( "/com1" )

Test the Connection

When the connection is established, it needs to be checked it the MultispeQ device is properly responding. The is_connected() checks if the connection is open and identifies the MultispeQ.

Example: Check if the connection is open and the MultispeQ is responding

## Test if connection is open and device is communicating
if _device.is_connected( _connection ):

---

Take a Measurement

If the MultispeQ device is connected and the connection is open, measurements can be run now. The example below shows how a single relative Chlorophyll (SPAD) measurement can be taken.

Example: Take a SPAD measurement with the MultispeQ

import jii_multispeq.measurement as _measurement
import jii_multispeq.device as _device

## MultispeQ Protocol
spad_protocol = [{
  "spad": [1]
}]

## MultispeQ Response Analysis
def spad_fn( _data ):
  output = {}
  output["SPAD"] = _data["spad"][0]
  return output

## Establish connection
_connection = _device.connect( "/com1" )

## Test if connection is open and device is communicating
if _device.is_connected( _connection ):

  data, crc32 = _measurement.measure( _connection, spad_protocol, 
                                     None, 
                                     'Single SPAD meaurement' )

  ## Run the analysis function
  data = _measurement.analyze( data, spad_fn )

  ## View response as a table
  _measurement.view( data )

## Close the connection
_device.disconnect( _connection )

Example: Output from a SPAD measurement with the MultispeQ

Parameter        Value                             Type
---------------  --------------------------------  ---------------
created_at       2024-12-21T10:38:11.498360+01:00  <class 'str'>
device_battery   95                                <class 'int'>
device_firmware  2.3465                            <class 'float'>
device_id        01:12:53:##                       <class 'str'>
device_name      MultispeQ                         <class 'str'>
device_version   2                                 <class 'str'>
md5_measurement  3565bc573416002424c6072bdfb033f2  <class 'str'>
md5_protocol     b133a7f804cd1d1608da0577b3d89f72  <class 'str'>
notes            Single SPAD meaurement            <class 'str'>
protocol         n/a                               <class 'list'>
SPAD             24.548                            <class 'float'>

Save Measurement to Disk

The jii_multispeq.measurement.measure() allows to save the data from the MultispeQ to the disk as well. The example below shows how to only return the data, setting the filename to None or returning the data and saving the output to a file by specifying the file name and a directory. If the filename is not set, or defined as auto, a filename is generated based on date and time (YYYY-MM-DD_HHmm). In case the directory is not set, files will automatically saved to the ./local directory.

If a defined directory doesn’t exists it will be created. Files will not be overwritten, to prevent data loss. In case a filename already exists, a number will be appended to the filename.

Example: Take a SPAD measurement with the MultispeQ and save to disk

## Only return data
data, crc32 = _measurement.measure( _connection, spad_protocol,
                                  None,
                                  'Single SPAD meaurement' )

## Save data to defined file and define directory
data, crc32 = _measurement.measure( _connection, spad_protocol,
                                  "SPAD",
                                  'Single SPAD meaurement',
                                  './chlorophyll-measurements' )

## Save data automatically
data, crc32 = _measurement.measure( _connection, spad_protocol,
                                  'Single SPAD meaurement' )

Note

Available Protocols

The JII-MultispeQ-Protocols package provides preset protocols for the MultispeQ. In addition, it provides a validation function for custom MultispeQ protocols, helping to identify potential issues with a protocol before running it.

Load Saved Measurement(s)

Saved measurement files can be loaded into a list of dictionaries (list[dict]) or they can be loaded into a pandas dataframe.

File Summary

It might be helpful to list files in the selected directory, to check what the content is without having to open individual files using the list_files() function of the measurement module. The filenames, the date and time the measurement was saved and also the notes are listed by individual directories.

Example: View all the files in a directory including all sub-directories

import jii_multispeq.measurement as _measurement

## View Files in Directories
_measurement.list_files('./local')

Load Files

Example: View all the files in a directory including all sub-directories

import jii_multispeq.measurement as _measurement

## Load Files Into a List
data = _measurement.load_files('./local')

## Load Files Into a Dataframe
df = _measurement.load_files_df('./local')

Recursive Loading

Example: View all the files in a directory including all sub-directories

## Load Files Into a List Using Recursive Search
data = _measurement.load_files('./local', True)

Example: Take a SPAD measurement with the MultispeQ and save to disk

MultispeQ/
├── local/
│   ├── Measurement.json
│   ├── Measurement - 1.json
│   ├── Measurement - 2.json
│   ├── Measurement - 3.json
│   ├── Measurement - 4.json
│   └── sub-directory/
│       ├── Measurement.json
│       ├── Measurement - 1.json
│       └── Measurement - 2.json
└── script.py

Process Data

Example: View all the files in a directory including all sub-directories

def fn( _data ):
  ## Data Processing here
  return _data

## Load Files and Apply Function on File Content
data = _measurement.load_files('./local', fn=fn)

TL;DR

The following functions are available in the applications and probably more convinient to use.

Send a Command

Example: Sending a command to a connected MultispeQ device.

import jii_multispeq.device as _device

## Establish connection
_connection = _device.connect( "/com1" )

## Test if connection is open and device is communicating
if _device.is_connected( _connection ):

  ## Send the command for device settings (memory)
  response = _device.send_command( _connection, "print_memory" )

  ## View response
  print( response )

## Close the connection
_device.disconnect( _connection )

Example: Response from connected MultispeQ device for command print_memory.

{
  "device_name": "MultispeQ",
  "device_version": 2,
  "device_id": "01:12:53:##",
  "firmware": 2.3465,
  "compiled": [ "Aug  2 2021", "16:00:28" ],
  "calTimes": [ 1627920106, 1065353216, 1627920743, 1627920666, 1627920788, 0, -1050673152, 0 ],
  "device_mod": 0,
  "mag_address": 14,
  "mag_x_scale": 800.0,
  "mag_y_scale": 837.0,
  "mag_z_scale": 694.0,
  "max_PAR": [ 351, 4095, 3054, 4095, 4095, 4095, 1859, 4095, 4095, 4095 ],
  "light_slope_all": [ 0.362 ],
  "light_slope_r": [ -0.235 ],
  "light_slope_g": [ -0.136 ],
  "light_slope_b": [ -0.01 ],
  "light_yint": [ 0.0 ],
  "bleed3": [
    [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ],
    [ 31.0, 173.0, 360.0, 401.0, 476.0, 726.0, 860.0, 986.0 ],
    [ 7.0, 19.0, 33.0, 39.0, 63.0, 134.0, 178.0, 230.0 ],
    [ 9.0, -48.0, -48.0, -46.0, -48.0, -141.0, -118.0, -123.0 ],
    [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ],
    [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ],
    [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ],
    [ -10.0, 44.0, 41.0, 84.0, 125.0, 206.0, 312.0, 420.0 ],
    [ 6.0, 10.0, -2.0, -5.0, 1.0, 6.0, -11.0, 7.0 ],
    [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ]
  ],
  "thickness_a": 68202.516,
  "thickness_b": -6.395,
  "thickness_c": 149665.172,
  "mag_orientation": 0.0,
  "open_position": 39965.0,
  "closed_position": 41634.0,
  "spad_scale": 45.829,
  "spad_offset": -100.0,
  "spad_yint": 6.805,
  "blink_mode": 0,
  "pilot_blink": 0,
  "status_blink": 1,
  "shutdown_time (s)": 1800,
  "usb_on": 0,
  "pix_pin": 14,
  "par_map": [
    [ 58, 95, 131, 203, 351, 351, 351 ],
    [ 64, 101, 136, 206, 348, 771, 1477 ],
    [ 39, 248, 455, 870, 1699, 3054, 3054 ],
    [ 127, 371, 615, 1101, 2075, 4995, 9862 ],
    [ 150, 177, 203, 257, 363, 683, 1217 ],
    [ 150, 417, 683, 1217, 2283, 4095, 4095 ],
    [ 73, 127, 180, 286, 497, 1132, 1859 ],
    [ 150, 283, 417, 683, 1217, 2817, 4095 ],
    [ 150, 417, 683, 1217, 2283, 4095, 4095 ],
    [ 150, 283, 417, 683, 1217, 2817, 4095 ]
  ],
  "detector_offsets": [ 8.0, 0.0, -84.0, 0.0 ],
  "par_tweak": 0.749
}

Get Device Settings

The device’s settings can be viewed using the print_memory command like in the example above, but there is also a dedicated function for it. The code example below shows how to use this function.

In addition, the view() of the measurement module is used to print it out in a more convinient way.

Example: Getting the device settings from a connected MultispeQ device.

import jii_multispeq.device as _device
import jii_multispeq.measurement as _measurement

## Establish connection
_connection = _device.connect( "/com1" )

## Test if connection is open and device is communicating
if _device.is_connected( _connection ):

  ## Send the command for device settings (memory)
  response, crc32 = _device.get_memory( _connection )

  ## View response as a table
  _measurement.view( response )

## Close the connection
_device.disconnect( _connection )

Example: Settings from a connected MultispeQ device.

Parameter          Value        Type
-----------------  -----------  ---------------
bleed3             n/a          <class 'list'>
blink_mode         0            <class 'int'>
calTimes           n/a          <class 'list'>
closed_position    41634.0      <class 'float'>
compiled           n/a          <class 'list'>
detector_offsets   n/a          <class 'list'>
device_id          01:12:53:##  <class 'str'>
device_mod         0            <class 'int'>
device_name        MultispeQ    <class 'str'>
device_version     2            <class 'int'>
firmware           2.3465       <class 'float'>
light_slope_all    n/a          <class 'list'>
light_slope_b      n/a          <class 'list'>
light_slope_g      n/a          <class 'list'>
light_slope_r      n/a          <class 'list'>
light_yint         n/a          <class 'list'>
mag_address        14           <class 'int'>
mag_orientation    0.0          <class 'float'>
mag_x_scale        800.0        <class 'float'>
mag_y_scale        837.0        <class 'float'>
mag_z_scale        694.0        <class 'float'>
max_PAR            n/a          <class 'list'>
open_position      39965.0      <class 'float'>
par_map            n/a          <class 'list'>
par_tweak          0.749        <class 'float'>
pilot_blink        0            <class 'int'>
pix_pin            14           <class 'int'>
shutdown_time (s)  1800         <class 'int'>
spad_offset        -100.0       <class 'float'>
spad_scale         45.829       <class 'float'>
spad_yint          6.805        <class 'float'>
status_blink       1            <class 'int'>
thickness_a        68202.516    <class 'float'>
thickness_b        -6.395       <class 'float'>
thickness_c        149665.172   <class 'float'>
usb_on             0            <class 'int'>