Welcome to py-opc’s documentation!¶

py-opc is a python module that enables one to use easily operate the Alphasense OPC-N2 optical particle counter through a Raspberry Pi over the SPI bus. It was originally designed using a Rapsberry Pi 2 Model B and Python3.5; however, it should work on other versions as well.

There are a variety of OPC Models and firmware versions from Alphasense; a table documenting which ones are supported will be added. If you own an OPC-N2 with a firmware version that has not been tested, please do so and submit as an issue on the GitHub repository.

Installation¶

You can install this package using pip:

pip install py-opc

Requirements¶

The following packages are required:

py-spidev

Setting Up the Raspberry Pi¶

If you are not familiar with setting up a Raspberry Pi to be used as a SPI device, here are a couple of great tutorials: RPi, Drogon, and Hensley. A few important things to note:

The Alphsense OPC-N2 is a 3v3 logic SPI Mode 1 device

The OPC requires at least 250 mA, so powering directly through the RPi is not an option

To connect the RPi to the OPC-N2, there are four connections that must be made, plus ground and power. The power source must be 5 VDC, and should power both the OPC and the RPi to avoid ground issues. The connections are stated below:

Pin	Function	OPC	RPi
1	Ground	GND
2	Chip Select	/SS	CE0 or CE1
3	Master Out Slave In	SDI	MOSI
4	Clock	SCK	CLK
5	Master In Slave Out	SDO	MISO
6	Power	VCC

Getting Help¶

Still running into problems?

To report a problem with this documentation, contact the author.

Report an issue with the py-opc library on GitHub

Submit a feature request for py-opc on GitHub.

Examples¶

Setting up the SPI Connection¶

import spidev
import opc

# Open a SPI connection on CE0
spi = spidev.Spidev()
spi.open(0, 0)

# Set the SPI mode and clock speed
spi.mode = 1
spi.max_speed_hz = 500000

Initiating the OPCN2¶

try:
    alpha = opc.OPCN2(spi)
except Exception as e:
    print ("Startup Error: {}".format(e))

Reading a Histogram¶

# Turn on the OPC
alpha.on()

# Read the histogram and print to console
hist = alpha.read_histogram()

for key, value in hist.items():
    print ("Key: {}\tValue: {}".format(key, value))

# Shut down the opc
alpha.off()

API Reference¶

class opc.OPC(spi_connection, **kwargs)¶

Generic class for any Alphasense OPC. Provides the common methods and calculations for each OPC.

Parameters:	spi_connection (spidev.SpiDev) – spidev.SpiDev connection debug (boolean) – Set true to print data to console while running model (string) – Model number of the OPC (‘N1’ or ‘N2’) set by the parent class
Raises:	SPIError
Return type:	opc.OPC

_calculate_bin_boundary(val)¶

Calculates the bin boundary value in micrometers, assuming a 12-bit ADC with 17.5 um Full-Scale.

NOTE: This is incorrect!

Parameters:	val (int) – ADC Value
Returns:	float

_calculate_float(byte_array)¶

Returns an IEEE 754 float from an array of 4 bytes

Parameters:	byte_array (array) – Expects an array of 4 bytes
Returns:	float

_calculate_mtof(mtof)¶

Returns the average amount of time that particles in a bin took to cross the path of the laser [units -> microseconds]

Parameters:	mtof (float) – mass time-of-flight
Returns:	float

_calculate_pressure(vals)¶

Calculates the pressure in pascals

Parameters:	vals (array) – array of bytes
Returns:	float

_calculate_temp(vals)¶

Calculates the temperature in degrees celcius

Parameters:	vals (array) – array of bytes
Returns:	float

_combine_bytes(LSB, MSB)¶

Returns the combined LSB and MSB

Parameters:	LSB (byte) – Least Significant Byte MSB (byte) – Most Significant Byte
Returns:	16-bit unsigned int

ping()¶

Checks the connection between the Raspberry Pi and the OPC

Returns:	Boolean

read_info_string()¶

Reads the firmware information for the OPC

Returns:	string

class opc.OPCN1(spi_connection, **kwargs)¶

Create an instance of the Alphasene OPC-N1. opc.OPCN1 inherits from the opc.OPC parent class.

Parameters:	spi_connection (spidev.SpiDev) – The spidev instance for the SPI connection.
Return type:	opc.OPCN1
Raises:	FirmwareError

off()¶

Turn OFF the OPC (fan and laser)

Returns:	boolean success state

on()¶

Turn ON the OPC (fan and laser)

Returns:	boolean success state

read_bin_boundaries()¶

Return the bin boundaries.

Returns:	dictionary with 17 bin boundaries.

read_bin_particle_density()¶

Read the bin particle density

Returns:	float

read_gsc_sfr()¶

Read the gain-scaling-coefficient and sample flow rate.

Returns:	dictionary containing GSC and SFR

read_histogram()¶

Read and reset the histogram. The expected return is a dictionary containing the counts per bin, MToF for bins 1, 3, 5, and 7, temperature, pressure, the sampling period, the checksum, PM1, PM2.5, and PM10.

NOTE: The sampling period for the OPCN1 seems to be incorrect.

Returns:	dictionary

write_bin_particle_density()¶

Write the bin particle density values to memory. This method is currently a placeholder.

Returns:	None

write_gsc_sfr()¶

Write the gsc and sfr values

NOTE: This method is currently a placeholder.

class opc.OPCN2(spi_connection, **kwargs)¶

Create an instance of the Alphasene OPC-N2. Currently supported by firmware versions 14-17. opc.OPCN2 inherits from the opc.OPC parent class.

Parameters:	spi_connection (spidev.SpiDev) – The spidev instance for the SPI connection.
Return type:	opc.OPCN2
Raises:	FirmwareError

enter_bootloader_mode()¶

Enter bootloader mode. Must be issued prior to writing configuration variables to non-volatile memory.

Returns:	boolean success state

fan_off()¶

Turn the fan OFF.

Returns:	boolean success state

fan_on()¶

Turn the fan ON.

Returns:	boolean success state

laser_off()¶

Turn the laser OFF

Returns:	boolean success state

laser_on()¶

Turn the laser ON.

Returns:	boolean success state

off()¶

Turn OFF the OPC (fan and laser)

Returns:	boolean success state

on()¶

Turn ON the OPC (fan and laser)

Returns:	boolean success state

read_config_variables()¶

Read the configuration variables and returns them as a dictionary

Returns:	dictionary

read_histogram()¶

Read and reset the histogram.

Returns:	dictionary

save_config_variables()¶

Save the configuration variables in non-volatile memory. This method should be used in conjuction with write_config_variables.

Returns:	boolean success state

set_fan_power(value)¶

Set only the Fan power.

Parameters:	value (int) – Fan power value as an integer between 0-255.
Returns:	boolean success state

set_laser_power(value)¶

Set the laser power only.

Parameters:	value (int) – Laser power as a value between 0-255.
Returns:	boolean success state

write_config_variables(config_vars)¶

Write configuration variables to non-volatile memory.

NOTE: This method is currently a placeholder and is not implemented.

Parameters:	config_vars (dictionary) – dictionary containing the configuration variables

Exceptions¶

exception opc.FirmwareError¶

Raised under two circumstances:

Your firmware version is not supported
Your firmware version cannot be detected (usually due to a bad connection)

exception opc.SPIError¶: Raised when there is an error with your SPI connection as created using py-spidev. An instance of spidev.SpiDev is expected.