Elements¶

Basic Protocol¶

A basic protocol can used for quick and simple measurements.

Example: Basic protocol structure¶

[
  {
     # Measurement instructions
  }
]

Complex Protocol (Sets)¶

A complex protocol can measure different measurement types defined in a set.

Example: Complex protocol structure¶

[
   {
      "v_arrays": [
         # Arrays with variables
         [100,5,10]
      ]
      "_protocol_sets_": [
         {
           # measurement Instructions
           # for the first Part
           "label": "PAM"
         },
         {
           # measurement Instructions
           # for the second Part
           "label": "ECS"
         }
      ]
   }
]

Measuring Lights¶

Measuring lights are controlled by defining pulses. Three parameters are required in order to work with pulses. The number of pulses, the distance between them and the length of pulses.

Single Light Source¶

Example: Controlling a single measurement light source¶

{
  "pulses": [
    20, 50, 20              # Sets of pulses
  ],
"pulse_distance": [
    10000, 10000, 10000     # Distance between pulses
  ],
"pulse_length": [
    [ 30 ], [ 30 ], [ 30 ]  # Duration of the pulse
  ]
}

(png, hires.png, pdf)

_images/plot-pulses-1-light.png — *Figure:* Measurement Pulses using a single Light Source and the resulting pulse sequence¶

Multiple Light Sources¶

Example: Controlling two measurement light sources¶

{
  "pulses": [
    20, 50, 20
  ],
  "pulse_distance": [
    10000, 10000, 10000
  ],
  "pulse_length": [
    [ 30, 15 ], [ 30, 15 ], [ 30, 15 ]
  ]
}

(png, hires.png, pdf)

_images/plot-pulses-n-light.png — *Figure:* Measurement Pulses using two Light Sources and the resulting pulse sequence¶

Detectors¶

The MultispeQ has two detectors arragend opposite of each other. One to measure within the visible light spectrum covered by a BG-18 filter, the other detects light in the IR spectrum. Each pulse defined in pulses also needs a corresponding detector.

The signal from the detectors is returned as an array called data_raw.

Example: Setting up the detectors for measuing lights¶

{
  "pulses": [
    20, 50, 20
  ],
  "pulse_distance": [
    10000, 10000, 10000
  ],
  "pulse_length": [
    [ 30 ], [ 30 ], [ 30 ]
  ],
  "detectors": [
    [ 1 ], [ 1 ], [ 1 ]
  ]
}

If there is more than one detector per pulse set, the data_raw array needs to be deconvoluted to extract the separate signals.

Structure of `data_raw` array depending on pulse and detector settings¶
Pulses pulses	Detectors detectors	Output data_raw
`[ 2 ]`	`[ [0] ]`	`[ ]`
`[ 2 ]`	`[ [1] ]`	`[ 1, 1 ]`
`[ 2, 1 ]`	`[ [1], [1] ]`	`[ 1, 1, 1 ]`
`[ 2, 1 ]`	`[ [3], [1] ]`	`[ 3, 3, 1 ]`
`[ 2 ]`	`[ [1, 3] ]`	`[ 1, 3, 1, 3 ]`
`[ 2, 1 ]`	`[ [1, 3], 1 ]`	`[ 1, 3, 1, 3, 1 ]`
`[ 2 ]`	`[ [1, 3, 1] ]`	`[ 1, 3, 1, 1, 3, 1 ]`

Gain Settings¶

When taking a measurement, the signal quality depends amongst other factors on the brightness of the measuring light as well as the duration of the measuring pulse. Instead of making these settings manually, the autogain function can be used to automatically determine the ideal settings.

Example: Using auto-gain settings in a protocol to determine pulse duration and brightness¶

{
   # Defining the autogain settings
   "autogain": [
     # index, led, detector, pulse length, target intensity
     [ 1, 3, 1, 30, 3000 ]
   ],
   # using the auto_duration<index> for the pulse length
   "pulse_length": [
     [ "auto_duration1" ]
   ],
   "pulsed_lights": [
     [ 3 ]
   ],
   # using the auto_bright<index> for the measuring light brightness
   "pulsed_lights_brightness": [
     [ "auto_bright1" ]
   ],
   # using the detector, already used in the autogain
   "detectors": [
     [ 1 ]
   ]
}

Sample Pre-Illumination¶

The pre-illumination allows to adapt a sample to a set light intensity before starting the actual measurement.

Example: Pre-Illumination of a sample using one or two LEDs¶

## Single LED
"pre_illumination": [ 2, 200, 60000 ] # LED 2, 200 uE, 1 min

## Combination of LEDs
"pre_illumination": [
  [2, 200, 60000], # LED 2, 200 uE, 1 min
  [4, 300, 60000]  # LED 4, 300 uE, 1 min
]

Environmental Sensors¶

The MultispeQ device has several sensors enabling it to record environmental parameters. Here is an overview of what information is returned by the available commands.

Example: Adding environmental sensors to a protocol¶

"environmentals": [
   [ "light_intensity" ],
   [ "temperature_humidity_pressure" ],
   [ "contactless_temp" ]
]

Environmental Sensors and the returned data¶
Command	Returned
`light_intensity`	Light intensity in µmol photons × s⁻¹ × m⁻² (PAR)
`previous_light_intensity`	Light intensity from previous measurement (only in _protocols_set_)
`temperature_humidity_pressure`, `thp`	Temperature (℃), rel. humidity (%), barometric pressure (mbar) - (sensor #1)
`temperature_humidity_pressure2`, `thp2`	Temperature (℃), rel. humidity (%), barometric pressure (mbar) - (sensor #2)
`contactless_temp`	Contactless Temperature (℃)
`thickness`	Thickness (µm - microns)
`thickness_raw`	Thickness (raw values)
`compass_and_angle`	Roll, pitch, angle and cardinal direction or the Instrument

Ambient Light Intensity (PAR)¶

Using the light_intensity command in a protocol, allows the measured ambient light intensity to be used by the protocol to replicate the light by the

Example: Using the ambient light intensity to control an LED¶

"_protocol_set_": [
  {
    "environmental": [
      [ "light_intensity" ]
    ],
    "nonpulsed_lights": [
      [ 2 ], [ 2 ]
    ],
    "nonpulsed_lights_brightness": [
      ## Use the ambient light intensity measured by the PAR sensor
      [ "light_intensity" ], [ "light_intensity" ]
    ]
  },
  {
    "nonpulsed_lights": [
      [ 2 ], [ 2 ]
    ],
    "nonpulsed_lights_brightness": [
      ## Use the ambient light intensity from the previous protocol
      [ "previous_light_intensity" ], [ "previous_light_intensity" ]
    ]
  }
  },
  {
    "set_light_intensity": 500,
    "nonpulsed_lights": [
      [ 2 ], [ 2 ]
    ],
    "nonpulsed_lights_brightness": [
      ## Use a set light intensity
      [ "light_intensity" ], [ "light_intensity" ]
    ]
  }
]

Repeats¶

Repeats can be a powerful tool when writing protocols. They allow you to define instructions once and then repeat them, reducing complexity and making the protocol easier to write.

Repeats can be especially useful when combined with protocol sets, as they can help minimize the size of the overall protocol.

Example:* How to use different types of repeats in a protocol, including variables¶

 ## Using fixed repeat values
 [
   {
     # Repeat the entire set
     "set_repeats": 2,
     "_protocol_set_": [
       {
           "label": "Protocol 1",
           # Repeat this protocol within each set repeat
           "protocol_repeats": 3
       },
       {
           "label": "Protocol 2"
       }
     ]
   }
 ]

 ## Using repeats based on variables
 [
   {
     "v_arrays": [ [ 1, 2 ], [ 1, 2, 3 ] ],
     # Repeat the entire set based on the number of elements in the first v_array
     "set_repeats": "#l0",
     "_protocol_set_": [
       {
           "label": "Protocol 1",
           # Repeat this protocol within each set repeat (second v_array)
           "protocol_repeats": "#l1"
       },
       {
           "label": "Protocol 2"
       }
     ]
   }
 ]

Variables (v_arrays)¶

The v_arrays can hold up to 4 arrays, each with a maximum of 10 numbers. You can add values to these arrays to use them in your protocol. The selector for a single value, would look like this @n0:1. To access a value based on a protocol or protocol-set repeat, you can use @p0 for a protocol repeat or @s0 for a protocol-set repeat.

Example: Using the variables array to define values that can be accessed inside a protocol¶

[
  {
    # The variable array
    "v_arrays": [
      [ 100, 200, 400]    # define values
    ],
    "set_repeats": "#3",   # repeat the whole set n times
    "_protocol_sets_": [
      {
        # Define the lights brightness using a variable @s0
        "non_pulsed_lights_brightness": [ "@s0" ],

        # repeat the procol set n time
        "protocol_repeats": 3
      }
    ]
  }
]

Accessing the variable array using different commands¶
Variable	Example	Function
`@s<array>`	`[ "@s0" ]`	Set Repeat: With every protocol set repeat the next position in the array is selected and the value used in the protocol
`@p<array>`	`[ "@p0" ]`	Protocol Repeat: With every protocol repeat the next position in the array is selected and the value used in the protocol
`@n<array>:<value>`	`[ "@n0:0", "@n0:1" ]`	Single Value: A specific value is used in the protocol

Note

Timeout A timeout can be defined to prevent the protocol wait forever for an input through the leaf clamp. Use max_hold_time to set the wait period before the protocol continues. The default is 15 sec ( 15000 ms ).

Protocol Flow Control¶

When starting a measurement with the MultispeQ it starts right away. This might not be usefull outside of a laboratory setting, so flow controll helps to wait for user input to start the measurement, using the leaf clamp as the input.

Example: Using the par_led_start_on_close to controll the measurement start and LED inside the instrument¶

[
  {
   ## Without LED control
   "start_on_open_close": 1

   ## Controling a PAR LED
   "par_led_start_on_close": 2
  }
]

Comands to use flow control, either with or without LED control¶
Command	Input	Summary
`start_on_open`	0,1	If set to 1 or higher, it will wait until the clamp is opened, then proceed with the rest of the experiment. If the value is set to zero, the command will be ignored.
`start_on_close`	0,1	If set to 1, will wait until the clamp is closed, then proceed with the rest of the experiment. If set to 0, will be ignored.
`start_on_open_close`	0,1	If set to 1, will wait until the clamp is opened then closed, then proceed with the rest of the experiment. If set to 0, will be ignored.
`par_led_start_on_open`	0-10 (LED)	If set to 1 or higher, it will wait until the clamp is opened, then proceed with the rest of the experiment. If set to 0, light intensity is set to 0.
`par_led_start_on_close`	0-10 (LED)	If set to 1, will wait until the clamp is closed, then proceed with the rest of the experiment. If set to 0, light intensity is set to 0.
`par_led_start_on_open_close`	0-10 (LED)	If set to 1, will wait until the clamp is opened then closed, then proceed with the rest of the experiment. If set to 0, light intensity is set to 0.

Indicator Light¶

The MultispeQ v2 has an indicator light that can be controlled with a protocol to provide information about measurement progress or the device status. The table provides a few example colors, but you can find or generate more on W3School. The White channel is not used an needs to be set to 0.

Indicator Light Example Colors¶
Name	Red, Green, Blue, White
◉ White	`[255, 255, 255, 0]`
◉ Red	`[255, 0, 0, 0]`
◉ Green	`[0, 255, 0, 0]`
◉ Blue	`[0, 0, 255, 0]`
◉ Yellow	`[255, 255, 0, 0]`
◉ Cyan	`[0, 255, 255, 0]`
◉ Magenta	`[255, 0, 255, 0]`
◉ Turn Light Off	`[0, 0, 0, 0]`