py-opc Documentationpy-opc Documentation, Release py-opc is a python module that enables one to use easily operate the Alphasense OPC-N2 optical particle counter through a Raspberry

py-opc DocumentationRelease

David H Hagan

January 04, 2016

Contents

1 Installation 3

2 Requirements 5

3 Setting Up the Raspberry Pi 7

4 Getting Help 9

5 Examples 115.1 Setting up the SPI Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.2 Initiating the OPCN2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115.3 Reading a Histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6 API Reference 136.1 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Python Module Index 17

i

ii

py-opc Documentation, Release

py-opc is a python module that enables one to use easily operate the Alphasense OPC-N2 optical particle counterthrough 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 aresupported will be added. If you own an OPC-N2 with a firmware version that has not been tested, please do so andsubmit as an issue on the GitHub repository.

Contents 1


2 Contents

CHAPTER 1

Installation

You can install this package using pip:

pip install py-opc

3


4 Chapter 1. Installation

CHAPTER 2

Requirements

The following packages are required:

• py-spidev

5

https://github.com/doceme/py-spidev


6 Chapter 2. Requirements

CHAPTER 3

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 powersource must be 5 VDC, and should power both the OPC and the RPi to avoid ground issues. The connections arestated below:

Pin Function OPC RPi1 Ground GND •

2 Chip Select /SS CE0 or CE13 Master Out Slave In SDI MOSI4 Clock SCK CLK5 Master In Slave Out SDO MISO6 Power VCC •

7

https://www.raspberrypi.org/documentation/hardware/raspberrypi/spi/

https://projects.drogon.net/understanding-spi-on-the-raspberry-pi/

http://www.brianhensley.net/2012/07/getting-spi-working-on-raspberry-pi.html


8 Chapter 3. Setting Up the Raspberry Pi

CHAPTER 4

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.

9

https://github.com/dhhagan/py-opc/issues/new

https://github.com/dhhagan/py-opc/issues/new


10 Chapter 4. Getting Help

CHAPTER 5

Examples

5.1 Setting up the SPI Connection

import spidevimport opc

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

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

5.2 Initiating the OPCN2

try:alpha = opc.OPCN2(spi)

except Exception as e:print ("Startup Error: {}".format(e))

5.3 Reading a Histogram

# Turn on the OPCalpha.on()

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

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

# Shut down the opcalpha.off()

11


12 Chapter 5. Examples

CHAPTER 6

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

13


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)


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 forbins 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.

14 Chapter 6. API Reference


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.OPCN2inherits 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.


fan_off()Turn the fan OFF.


fan_on()Turn the fan ON.


laser_off()Turn the laser OFF


laser_on()Turn the laser ON.


off()Turn OFF the OPC (fan and laser)


on()Turn ON the OPC (fan and laser)


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 withwrite_config_variables.


15


set_fan_power(value)Set only the Fan power.

Parameters value (int) – Fan power value as an integer between 0-255.


set_laser_power(value)Set the laser power only.

Parameters value (int) – Laser power as a value between 0-255.


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

6.1 Exceptions

exception opc.FirmwareErrorRaised under two circumstances:

1.Your firmware version is not supported

2.Your firmware version cannot be detected (usually due to a bad connection)

exception opc.SPIErrorRaised when there is an error with your SPI connection as created using py-spidev. An instance of spidev.SpiDevis expected.

16 Chapter 6. API Reference

Python Module Index

oopc, 13

17


18 Python Module Index

Index

Symbols_calculate_bin_boundary() (opc.OPC method), 13_calculate_float() (opc.OPC method), 13_calculate_mtof() (opc.OPC method), 13_calculate_pressure() (opc.OPC method), 13_calculate_temp() (opc.OPC method), 13_combine_bytes() (opc.OPC method), 14

Eenter_bootloader_mode() (opc.OPCN2 method), 15

Ffan_off() (opc.OPCN2 method), 15fan_on() (opc.OPCN2 method), 15FirmwareError, 16

Llaser_off() (opc.OPCN2 method), 15laser_on() (opc.OPCN2 method), 15

Ooff() (opc.OPCN1 method), 14off() (opc.OPCN2 method), 15on() (opc.OPCN1 method), 14on() (opc.OPCN2 method), 15OPC (class in opc), 13opc (module), 13OPCN1 (class in opc), 14OPCN2 (class in opc), 15

Pping() (opc.OPC method), 14

Rread_bin_boundaries() (opc.OPCN1 method), 14read_bin_particle_density() (opc.OPCN1 method), 14read_config_variables() (opc.OPCN2 method), 15read_gsc_sfr() (opc.OPCN1 method), 14read_histogram() (opc.OPCN1 method), 14read_histogram() (opc.OPCN2 method), 15

read_info_string() (opc.OPC method), 14

Ssave_config_variables() (opc.OPCN2 method), 15set_fan_power() (opc.OPCN2 method), 15set_laser_power() (opc.OPCN2 method), 16SPIError, 16

Wwrite_bin_particle_density() (opc.OPCN1 method), 14write_config_variables() (opc.OPCN2 method), 16write_gsc_sfr() (opc.OPCN1 method), 15

19

Documents

py-opc Documentationpy-opc Documentation, Release py-opc is a python module that enables one to use easily operate the Alphasense OPC-N2 optical particle counter through a Raspberry