Backend API Reference
python-seabreeze provides two backend interfaces that allow you to communicate with your spectrometers:
cseabreeze
The cseabreeze backend is a wrapper around the seabreeze library provided by Ocean Optics and is the default backend interface used by python-seabreeze. But it’s hard to extend if you’re unfamiliar with C++ and cython.
pyseabreeze
The pyseabreeze backend uses pyUSB to communicate with the spectrometer and implements
the whole communication layer for Ocean Optics spectrometers. (It implements the
Ocean Optics Interface (???)
and the Ocean Binary Protocol
) While pyseabreeze is
not as feature complete as cseabreeze it should be a lot easier to extend for someone
familiar with python.
cseabreeze
The C++ libseabreeze API is fully wrapped and exposed to python. If you intend to
directly use it you start with a SeaBreezeAPI
instance
and retrieve SeaBreezeDevice
instances via
SeaBreezeAPI.list_devices()
. These instances offer all feature functionality via their
features
property or their shorthand f
property for easy access.
SeaBreezeAPI
- class seabreeze.cseabreeze.SeaBreezeAPI
SeaBreeze API interface
- list_devices()
returns available SeaBreezeDevices
list all connected Ocean Optics devices supported by libseabreeze.
- Returns
devices (list of SeaBreezeDevice) – connected Spectrometer instances
- add_rs232_device_location(device_type, bus_path, baudrate)
add RS232 device location
- add_ipv4_device_location(device_type, ip_address, port)
add ipv4 device location
- initialize()
initialize the api backend
normally this function does not have to be called directly by the user
- shutdown()
shutdown the api backend
normally this function does not have to be called directly by the user
SeaBreezeDevice
- class seabreeze.cseabreeze.SeaBreezeDevice
SeaBreezeDevice class for handling all spectrometers
This is the default cseabreeze class interface for all supported spectrometers. Users don’t instantiate it directly, but retrieve instances via
seabreeze.cseabreeze.SeaBreezeAPI.list_devices()
- model
- serial_number
- close()
close the spectrometer usb connection
- Returns
None
- f
convenience assess to features via attributes
this allows you to access a feature like this:
# via .features device.features['spectrometer'][0].get_intensities() # via .f device.f.spectrometer.get_intensities()
- features
return a dictionary of all supported features
this returns a dictionary with all supported Features of the spectrometer
- Returns
features (dict [str, seabreeze.cseabreeze.SeaBreezeFeature])
- get_model()
return the model string of the spectrometer
- Returns
model (str)
- get_serial_number()
return the serial number string of the spectrometer
- Returns
serial_number (str)
- is_open
returns if the spectrometer device usb connection is opened
- Returns
bool
- open()
open the spectrometer usb connection
- Returns
None
SeaBreezeFeatures
Hint
SeaBreezeFeature
classes are not instantiated directly, but provided via
SeaBreezeDevice.features
or SeaBreezeDevice.f
. Their individual
class interfaces are documented here:
Summary of all features
BaseClass for SeaBreezeFeatures |
|
Feature class interfaces
- class seabreeze.cseabreeze.SeaBreezeFeature
BaseClass for SeaBreezeFeatures
defines the minimum class interface for all features
- get_feature_class_registry()
return a class registry dictionary internal use only
creates a dictionary of all derived classes of SeaBreezeFeature and returns a {SeaBreezeFeature.identifier: DerivedSeabreezeFeature} mapping.
- feature_id
assigned feature id for cseabreeze feature internal use only
- class seabreeze.cseabreeze.SeaBreezeRawUSBBusAccessFeature
- raw_usb_read(endpoint, buffer_length)
read raw data from usb
- class seabreeze.cseabreeze.SeaBreezeSpectrometerFeature
- get_electric_dark_pixel_indices()
returns the electric dark pixel indices for the spectrometer
This returns a list of indices of the pixels that are electrically active but optically masked (a.k.a. electric dark pixels). Note that not all detectors have optically masked pixels; in that case, an empty list is returned
- Returns
dark_pixel_idxs (list of int)
- get_integration_time_micros_limits()
returns the smallest and largest valid integration time setting, in microseconds
- Returns
micros_low (int) – smallest supported integration time
micros_high (int) – largest supported integration time
- get_intensities()
acquires a spectrum and returns the measured intensities
In this mode, auto-nulling should be automatically performed for devices that support it.
- Returns
intensities (np.ndarray)
- get_maximum_intensity()
returns the maximum pixel intensity for the spectrometer
- Returns
max_intensity (float)
- get_wavelengths()
computes the wavelengths for the spectrometer
- Returns
wavelengths (np.ndarray)
- class seabreeze.cseabreeze.SeaBreezePixelBinningFeature
- property binning_factor
gets the pixel binning factor on the device
- Returns
binning_factor (int)
- property default_binning_factor
gets the default pixel binning factor on the device
- Returns
binning_factor (int)
- get_binning_factor()
gets the pixel binning factor on the device
- Returns
binning_factor (int)
- get_default_binning_factor()
gets the default pixel binning factor on the device
- Returns
binning_factor (int)
- get_max_binning_factor()
gets the max pixel binning factor on the device
- Returns
binning_factor (int)
- property max_binning_factor
gets the max pixel binning factor on the device
- Returns
binning_factor (int)
- set_binning_factor(factor)
sets the pixel binning factor on the device
- Returns
None
- class seabreeze.cseabreeze.SeaBreezeThermoElectricFeature
- enable_tec(state)
enables the TEC feature on the device
- Parameters
state (bool) – on or off
- Returns
None
- read_temperature_degrees_celsius()
reads the actual temperature of the TEC in degrees Celsius
- Returns
temperature (float) – tec temperature in degrees Celsius
- set_temperature_setpoint_degrees_celsius(temperature)
sets the target (setpoint) TEC temperature
- Returns
None
- class seabreeze.cseabreeze.SeaBreezeIrradCalFeature
- has_collection_area()
checks for an irradiance collection area
- Returns
has_area (bool)
- read_calibration()
- Returns
irrad_calibration (np.ndarray)
- read_collection_area()
reads an irradiance collection area from the spectrometer
- Returns
area (float)
- write_calibration(calibration_array)
- Parameters
calibration_array (np.ndarray) –
- Returns
None
- write_collection_area(area)
writes an irradiance collection area to the spectrometer
- Returns
None
- class seabreeze.cseabreeze.SeaBreezeEthernetConfigurationFeature
- get_gbe_enable_status(interface_index)
reads the GbE enable status from the device’s internal memory
- Parameters
interface_index (int) –
- Returns
gbe_enabled (bool)
- get_mac_address(interface_index)
get mac address of interface
- Parameters
interface_index (int) –
- Returns
mac_address (str)
- set_gbe_enable_status(interface_index, enable_state)
writes the GbE enable status to the spectrometer’s internal memory
- class seabreeze.cseabreeze.SeaBreezeMulticastFeature
- class seabreeze.cseabreeze.SeaBreezeIPv4Feature
- add_ipv4_address(interface_index, ipv4_address)
add a ipv4 address
- delete_ipv4_address(interface_index, address_index)
delete a ipv4 address
- get_default_gateway(interface_index)
get gateway address
- Parameters
interface_index (int) –
- Returns
gateway_address (str)
- get_dhcp_enable_state(interface_index)
get dhcp enable state
- Parameters
interface_index (int) –
- Returns
enabled (bool)
- get_ipv4_address(interface_index, address_index)
get ipv4 address
- get_number_of_ipv4_addresses(interface_index)
get number of ipv4 addresses for interface
- Parameters
interface_index (int) –
- Returns
num_addresses (int)
- set_default_gateway(interface_index, default_gateway_address)
set default gateway
- class seabreeze.cseabreeze.SeaBreezeDHCPServerFeature
- get_address(interface_index)
get dhcp server address
- Parameters
interface_index (int) –
- Returns
server_address (str) – format xxx.xxx.xxx.xxx/nm
- get_enable_state(interface_index)
get dhcp server enable state
- Parameters
interface_index (int) –
- Returns
enabled (bool)
- set_address(interface_index, server_address)
set dhcp server address
- class seabreeze.cseabreeze.SeaBreezeNetworkConfigurationFeature
- get_network_interface_connection_type(interface_index)
get the network interface connection type
- Parameters
interface_index (int) –
- Returns
network_type (int) – {0: ‘loopback’, 1: ‘wired ethernet’, 2: ‘wifi’, 3: ‘cdc ethernet (usb)’}
- get_network_interface_enable_state(interface_index)
get network interface enable state
- Parameters
interface_index (int) –
- Returns
enabled (bool)
- get_number_of_network_interfaces()
return the number of network interfaces
- Returns
num_interfaces (int)
- run_network_interface_self_test(interface_index)
run network interface self test
- Parameters
interface_index (int) –
- Returns
passed_test (bool)
- class seabreeze.cseabreeze.SeaBreezeWifiConfigurationFeature
- get_wifi_mode(interface_index)
get wifi configuration mode
- Parameters
interface_index (int) –
- Returns
wifi_mode (int) – mode {0: ‘client’, 1: ‘access point’}
- get_wifi_security_type(interface_index)
get wifi security type
- Parameters
interface_index (int) –
- Returns
security_type (int) – security_type {0: ‘open’, 1: ‘WPA2’}
- set_wifi_mode(interface_index, wifi_mode)
set wifi mode
- set_wifi_pass_phrase(interface_index, pass_phrase)
set wifi pass phrase
- set_wifi_security_type(interface_index, security_type)
set wifi security type
- class seabreeze.cseabreeze.SeaBreezeGPIOFeature
- get_egpio_available_modes(pin_number)
return all available modes for the specific egpio pin
see SeaBreezeGPIOFeature.modes for all possible modes
- Parameters
pin_number (int) –
- Returns
available_modes (set of int)
- get_egpio_current_mode(pin_number)
get the current egpio mode for a pin
see SeaBreezeGPIOFeature.modes
- Parameters
pin_number (int) –
- Returns
mode (int)
- get_egpio_output_vector_vector()
return the egpio output vector
- Returns
output_vector (int)
- get_egpio_value(pin_number)
return the value of an egpio pin
- Parameters
pin_number (int) –
- Returns
value (float) – egpio value between 0.0 and 1.0
- get_gpio_output_enable_vector()
return the current gpio output enable vector
- Returns
output (unsigned int)
- get_gpio_value_vector()
get gpio value vector
- Returns
output (int)
- get_number_of_egpio_pins()
return the number of egpio pins on the device
- Returns
num_egpio_pins (int)
- get_number_of_gpio_pins()
number of gpio pins on device
- Returns
num_gpio_pins (int)
- set_egpio_mode(pin_number, mode, value)
set the egpio mode for a specific pin
- set_egpio_output_vector(output_vector, bit_mask)
set the egpio output vector
allows to set multiple pins at once
- set_egpio_value(pin_number, value)
set the value of an egpio pin
- set_gpio_output_enable_vector(output_enable_vector, bit_mask)
set the current gpio output enable vector
- class seabreeze.cseabreeze.SeaBreezeEEPROMFeature
- class seabreeze.cseabreeze.SeaBreezeLightSourceFeature
- get_count()
returns the total number of light sources available
This function gets the number of light sources that are represented by the given featureID. Such light sources could be individual LEDs, light bulbs, lasers, etc. Each of these light sources may have different capabilities, such as programmable intensities and enables, which should be queried before they are used.
- Returns
number_of_light_sources (int)
- get_intensity(light_source_index)
queries the normalized intensity level of the indicated light source
- Parameters
light_source_index (int) –
- Returns
intensity (float) – The intensity is normalized over the range [0, 1], with 0 as the minimum and 1 as the maximum.
- has_enable(light_source_index)
returns if light source can be enabled
Queries whether the indicated light source within the given feature instance has a usable enable/disable control.
- Parameters
light_source_index (int) –
- Returns
has_enable (bool)
- has_variable_intensity(light_source_index)
returns if light source has variable intensity
- Parameters
light_source_index (int) –
- Returns
is_enabled (bool)
- is_enabled(light_source_index)
returns if light source is enabled
- Parameters
light_source_index (int) –
- Returns
is_enabled (bool)
- set_enable(light_source_index, enable)
enable or disable the light source
Attempts to enable or disable the indicated light source. Not all light sources have an enable/disable control, and this capability can be queried with has_enable(). Note that an enabled light source should emit light according to its last (or default) intensity setting which might be the minimum; in this case, the light source might appear to remain off.
- class seabreeze.cseabreeze.SeaBreezeStrobeLampFeature
- class seabreeze.cseabreeze.SeaBreezeContinuousStrobeFeature
- class seabreeze.cseabreeze.SeaBreezeShutterFeature
- class seabreeze.cseabreeze.SeaBreezeNonlinearityCoefficientsFeature
- get_nonlinearity_coefficients()
reads out nonlinearity coefficients from the device’s internal memory
- Returns
nonlinearity_coefficients (list of float) – nonlinearity coefficients
- class seabreeze.cseabreeze.SeaBreezeTemperatureFeature
- count_temperatures()
reads out an the number of indexed temperatures available
- Returns
num_temperatures (int)
- read_temperature(index)
read a specific temperature
- Parameters
index (int) – index of the temperature to be received
- Returns
temperature (double)
- temperature_get_all()
read all available temperatures
- Returns
temperatures (tuple of float)
- class seabreeze.cseabreeze.SeaBreezeIntrospectionFeature
- get_active_pixel_ranges()
return the active pixel indices of a device
- Returns
output (tuple of int)
- get_electric_dark_pixel_ranges()
return the electric dark pixel indices of a device
- Returns
output (tuple of int)
- get_optical_dark_pixel_ranges()
return the optical dark pixel indices of a device
- Returns
output (tuple of int)
- number_of_pixels()
read the number of detector pixels available
- Returns
num_pixels (int)
- class seabreeze.cseabreeze.SeaBreezeSpectrumProcessingFeature
- set_boxcar_width(boxcar_width)
- Returns
None
- class seabreeze.cseabreeze.SeaBreezeRevisionFeature
- hardware_revision()
returns the hardware revision
- Returns
revision (int)
- revision_firmware_get()
returns the firmware revision
- Returns
output (int)
- class seabreeze.cseabreeze.SeaBreezeOpticalBenchFeature
- get_coating()
return the bench coating
- Returns
coating (str)
- get_fiber_diameter_microns()
return the fiber diameter in micrometers
- Returns
fiber_diameter (int)
- get_filter()
return the bench filter
- Returns
filter (str)
- get_grating()
return the bench grating
- Returns
output (int)
- get_id()
return the bench id
- Returns
bench_id (str)
- get_serial_number()
return the serial number
- Returns
serial_number (str)
- get_slit_width_microns()
return the slit width in micrometers
- Returns
slit_width (int)
- class seabreeze.cseabreeze.SeaBreezeStrayLightCoefficientsFeature
- get_stray_light_coefficients()
reads out stray light coefficients from the device’s internal memory
- Returns
stray_light_coefficients (list of float) – the stray light coefficients stored on the device
- class seabreeze.cseabreeze.SeaBreezeDataBufferFeature
- clear()
clear the data buffer
- Returns
None
- get_buffer_capacity()
get the present limit of how many data elements will be retained by the buffer.
This value can be changed with set_buffer_capacity
- Returns
buffer_capacity (int)
- get_buffer_capacity_maximum()
get the maximum possible configurable size for the data buffer
- Returns
max_capacity (int)
- get_buffer_capacity_minimum()
get the minimum possible configurable size for the data buffer
- Returns
min_capacity (int)
- get_number_of_elements()
get the number of data elements currently in the buffer
- Returns
num_elements (int)
- class seabreeze.cseabreeze.SeaBreezeFastBufferFeature
- get_buffering_enable()
returns the fast buffer enable state
- Returns
state (bool)
- get_consecutive_sample_count()
returns the number of consecutive samples
- Returns
num_samples (int)
- class seabreeze.cseabreeze.SeaBreezeAcquisitionDelayFeature
- property delay_microseconds
get the acquisition delay in microseconds
- Returns
delay (int)
- get_delay_increment_microseconds()
get the acquisition delay increment in microseconds
- Returns
delay increment (int)
- get_delay_microseconds()
get the acquisition delay in microseconds
- Returns
delay (int)
- get_maximum_delay_microseconds()
get the maximum acquisition delay in microseconds
- Returns
maximum_delay (int)
- get_minimum_delay_microseconds()
get the minimum acquisition delay in microseconds
- Returns
minimum_delay (int)
pyseabreeze
pyseabreeze is a compatible pure python implementation of cseabreeze. If you intend to
directly use it you start with a SeaBreezeAPI
instance
and retrieve SeaBreezeDevice
instances via
SeaBreezeAPI.list_devices()
. These instances offer all feature functionality via their
features
property or their shorthand f
property for easy access.
SeaBreezeAPI
- class seabreeze.pyseabreeze.SeaBreezeAPI(*args, **kwds)[source]
SeaBreeze API interface
- list_devices() list[_SeaBreezeDevice] [source]
returns available SeaBreezeDevices
list all connected Ocean Optics devices supported by libseabreeze.
- Returns
devices – connected Spectrometer instances
- add_rs232_device_location(device_type: str, bus_path: str, baudrate: int) None [source]
add RS232 device location
- add_ipv4_device_location(device_type: str, ip_address: str, port: int) None [source]
add ipv4 device location
SeaBreezeDevice
- class seabreeze.pyseabreeze.SeaBreezeDevice(raw_device: Any = None)[source]
- model
- serial_number
- property f: SeaBreezeFeatureAccessor
convenience access to features via attributes
this allows you to access a feature like this:
# via .features device.features['spectrometer'][0].get_intensities() # via .f device.f.spectrometer.get_intensities()
- property features: dict[str, list[SeaBreezeFeature]]
return a dictionary of all supported features
this returns a dictionary with all supported Features of the spectrometer
- Returns
features (dict [str, seabreeze.cseabreeze.SeaBreezeFeature])
SeaBreezeFeatures
Hint
SeaBreezeFeature
classes are not instantiated directly, but provided via
SeaBreezeDevice.features
or SeaBreezeDevice.f
. Their individual
class interfaces are documented here:
Summary of all features
Feature class interfaces
- class seabreeze.pyseabreeze.SeaBreezeFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeRawUSBBusAccessFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
Reading and writing raw usb
Example usage
>>> import struct # needed for packing binary data into bytestrings >>> from seabreeze.spectrometers import Spectrometer >>> spec = Spectrometer.from_first_available() # features need to be accessed on the spectrometer instance via spec.f or spec.features # the data you provide needs to packed into a bytestring via struct.pack >>> spec.f.raw_usb_bus_access.raw_usb_write(data=struct.pack('<B', 0xFE), endpoint='primary_out') # when reading via the raw_usb feature you can easily block the spectrometer. # so make sure to only read when you expect new data (after you sent a command) # and only read as many bytes as the command returns >>> output = spec.f.raw_usb_bus_access.raw_usb_read(endpoint='primary_in', buffer_length=16) >>> print(output) b'\x00\x08p\x17\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x80U' # extract by providing the data format from the developer datasheet and `output` to struct.unpack
- class seabreeze.pyseabreeze.SeaBreezeSpectrometerFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezePixelBinningFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeThermoElectricFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeIrradCalFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeEthernetConfigurationFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeMulticastFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeIPv4Feature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeDHCPServerFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeNetworkConfigurationFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeWifiConfigurationFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeGPIOFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeEEPROMFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeLightSourceFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeStrobeLampFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeContinuousStrobeFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeShutterFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeNonlinearityCoefficientsFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeTemperatureFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeIntrospectionFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeSpectrumProcessingFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeRevisionFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeOpticalBenchFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeStrayLightCoefficientsFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeDataBufferFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]
- class seabreeze.pyseabreeze.SeaBreezeFastBufferFeature(protocol: PySeaBreezeProtocol, feature_id: int, **kwargs: Any)[source]