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.
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 | 5 VDC | VCC | |
2 | Serial Clock | SCK | CLK |
3 | Master In Slave Out | SDO | MISO |
4 | Master Out Slave In | SDI | MOSI |
5 | Chip Select | /SS | CE0 or CE1 |
6 | Ground | GND |
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: -
_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.