Merge pull request #19 from dhhagan/dev

Dev

README.md

@@ -33,6 +33,132 @@ Connect according to the table below, and as seen in the figure below.
 | 5 (CLK) | A3 |
 | 6 (VCC) | VIN |
 
+![Alphasense OPC-N2](https://github.com/dhhagan/opcn2/blob/master/opcn2-photon-wiring.png)
 
+# Documentation
 
-![Alphasense OPC-N2](https://github.com/dhhagan/opcn2/blob/master/opcn2-photon-wiring.png)
+A brief overview of the functionality of this package follows below. For a more thorough overview,
+please check out the [python version of this code][1].
+
+### `class OPCN2(uint8_t chip_select)`
+
+> **chip_select**: Chip Select pin for SPI communication.
+
+> *Returns*: An instance of the OPCN2 class.
+
+#### `bool ping()`
+
+> Issues the `check_status` command and returns true if a connection is good.
+
+#### `bool on()`
+
+> Turn on the OPC laser and fan. Returns `true` if it works.
+
+#### `bool off()`
+
+> Turn off the OPC laser and fan. Returns `true` if it works.
+
+#### `bool write_config_variables( byte values[] )`
+
+> **NOT IMPLEMENTED (yet)**
+
+#### `bool write_config_variables2( byte values[] )`
+
+> **NOT IMPLEMENTED (yet)**
+
+#### `bool write_serial_number_string( byte values[] )`
+
+> **NOT IMPLEMENTED (yet)**
+
+#### `bool save_config_variables()`
+
+> Saves the configuration variables once changed. To be used in conjunction with
+> `enter_bootloader`.
+
+> *Returns:* boolean (true if successfull).
+
+#### `bool enter_bootloader()`
+
+> Enter into the bootloader to make permanent changes to configuration variables.
+> Use only if you know what you're doing!
+
+> *Returns:* boolean (true if successfull).
+
+#### `bool set_fan_power( uint8_t value )`
+
+> **value**: a uint8_t that corresponds to the desired fan power. Permitted values
+> are between 0 - 255.
+
+> *Returns:* boolean (true if successfull).
+
+#### `bool set_laser_power( uint8_t value )`
+
+> **value**: a uint8_t that corresponds to the desired laser power. Permitted values
+> are between 0 - 255.
+
+> *Returns:* boolean (true if successfull).
+
+#### `bool toggle_fan( bool state )`
+
+> **state**: true to turn the fan on, and false to turn it off.
+
+> *Returns:* boolean (true if successfull).
+
+#### `bool toggle_laser( bool state )`
+
+> **state**: true to turn the laser on, and false to turn it off.
+
+> *Returns:* boolean (true if successfull).
+
+#### `String read_information_string()`
+
+> Returns a String containing the OPC firmware version and serial number.
+
+#### `String read_serial_number()`
+
+> **Only available for firmware versions >= 18**
+
+> *Returns:* a String containing the serial number.
+
+#### `Firmware read_firmware_version()`
+
+> *Returns*: a structure containing: `Firmware.major` and `Firmware.minor`.
+
+#### `Status read_status()`
+
+> **Only available for firmware versions >= 18**
+
+> *Returns*: structure containing: `Status.fanON`, `Status.laserON`,
+> `Status.fanDAC`, and `Status.laserDAC`.
+
+#### `ConfigVars read_configuration_variables()`
+
+> *Returns:* the ConfigVars structure which contains: `ConfigVars.bb0` -
+> `ConfigVars.bb14`, `ConfigVars.bpv0` - `ConfigVars.bpv15`, `ConfigVars.bpd0` -
+> `ConfigVars.bpd15`, `ConfigVars.bsvw0` - `ConfigVars.bsvw15`, `ConfigVars.gsc`,
+> `ConfigVars.sfr`, `ConfigVars.laser_dac`, `ConfigVars.fan_dac`, and `ConfigVars.tof_sfr`.
+
+#### `ConfigVars2 read_configuration_variables2()`
+
+> **Only available for firmware versions >= 18**
+
+> *Returns:* the ConfigVars2 structure which contains: `ConfigVars2.AMSamplingInterval`,
+> `ConfigVars2.AMIntervalCount`, `ConfigVars2.AMFanOnIdle`, `ConfigVars2.AMLaserOnIdle`,
+> `ConfigVars2.AMMaxDataArraysInFile`, and `ConfigVars2.AMOnlySavePMData`.
+
+#### `PMData read_pm_data()`
+
+> **Only available for firmware versions >= 18**
+
+> *Returns:* the PMData structure containing: `PMData.pm1`, `PMData.pm25`, and `PMData.pm10`.
+
+#### `HistogramData read_histogram( bool convert_to_conc )`
+
+> **convert_to_conc:** (boolean) If true, the raw histogram is converted to concentration
+> (#/cm3) by dividing the raw value by the product of the sampling period and the sample flow rate.
+
+> *Returns:* the HistogramData structure containing: `period`, `sfr`, `bin0` - `bin15`,
+> `bin1MToF`, `bin3MToF`, `bin5MToF`, `bin7MToF`, `temp_pressure`, `checksum`,
+> `pm1`, `pm25`, and `pm10`.
+
+[1]: https://github.com/dhhagan/py-opc

firmware/opcn2.cpp

@@ -556,7 +556,7 @@ struct PMData OPCN2::read_pm_data(){
   return data;
 }
 
-struct HistogramData OPCN2::read_histogram(){
+struct HistogramData OPCN2::read_histogram(bool convert_to_conc){
     HistogramData data;
     byte vals[62];
 
@@ -577,38 +577,47 @@ struct HistogramData OPCN2::read_histogram(){
 
     digitalWrite(this->_CS, HIGH);      // Pull the CS High
 
+    data.period = this->_calculate_float(vals[44], vals[45], vals[46], vals[47]);
+    data.sfr    = this->_calculate_float(vals[36], vals[37], vals[38], vals[39]);
+
+    // If convert_to_conc = True, convert from raw data to concentration
+    double conv;
+
+    if ( convert_to_conc != true ) {
+        conv = 1.0;
+    }
+    else {
+        conv = data.sfr * data.period;
+    }
+
     // Calculate all of the values!
-    data.bin0 = this->_16bit_int(vals[0], vals[1]);
-    data.bin1 = this->_16bit_int(vals[2], vals[3]);
-    data.bin2 = this->_16bit_int(vals[4], vals[5]);
-    data.bin3 = this->_16bit_int(vals[6], vals[7]);
-    data.bin4 = this->_16bit_int(vals[8], vals[9]);
-    data.bin5 = this->_16bit_int(vals[10], vals[11]);
-    data.bin6 = this->_16bit_int(vals[12], vals[13]);
-    data.bin7 = this->_16bit_int(vals[14], vals[15]);
-    data.bin8 = this->_16bit_int(vals[16], vals[17]);
-    data.bin9 = this->_16bit_int(vals[18], vals[19]);
-    data.bin10 = this->_16bit_int(vals[20], vals[21]);
-    data.bin11 = this->_16bit_int(vals[22], vals[23]);
-    data.bin12 = this->_16bit_int(vals[24], vals[25]);
-    data.bin13 = this->_16bit_int(vals[26], vals[27]);
-    data.bin14 = this->_16bit_int(vals[28], vals[29]);
-    data.bin15 = this->_16bit_int(vals[30], vals[31]);
+    data.bin0   = this->_16bit_int(vals[0], vals[1]) / conv;
+    data.bin1   = this->_16bit_int(vals[2], vals[3]) / conv;
+    data.bin2   = this->_16bit_int(vals[4], vals[5]) / conv;
+    data.bin3   = this->_16bit_int(vals[6], vals[7]) / conv;
+    data.bin4   = this->_16bit_int(vals[8], vals[9]) / conv;
+    data.bin5   = this->_16bit_int(vals[10], vals[11]) / conv;
+    data.bin6   = this->_16bit_int(vals[12], vals[13]) / conv;
+    data.bin7   = this->_16bit_int(vals[14], vals[15]) / conv;
+    data.bin8   = this->_16bit_int(vals[16], vals[17]) / conv;
+    data.bin9   = this->_16bit_int(vals[18], vals[19]) / conv;
+    data.bin10  = this->_16bit_int(vals[20], vals[21]) / conv;
+    data.bin11  = this->_16bit_int(vals[22], vals[23]) / conv;
+    data.bin12  = this->_16bit_int(vals[24], vals[25]) / conv;
+    data.bin13  = this->_16bit_int(vals[26], vals[27]) / conv;
+    data.bin14  = this->_16bit_int(vals[28], vals[29]) / conv;
+    data.bin15  = this->_16bit_int(vals[30], vals[31]) / conv;
 
     data.bin1MToF = int(vals[32]) / 3.0;
     data.bin3MToF = int(vals[33]) / 3.0;
     data.bin5MToF = int(vals[34]) / 3.0;
     data.bin7MToF = int(vals[35]) / 3.0;
 
-    data.sfr = this->_calculate_float(vals[36], vals[37], vals[38], vals[39]);
-
     // This holds either temperature or pressure
     // If temp, this is temp in C x 10
     // If pressure, this is pressure in Pa
     data.temp_pressure = this->_32bit_int(vals[40], vals[41], vals[42], vals[43]);
 
-    data.period = this->_calculate_float(vals[44], vals[45], vals[46], vals[47]);
-
     data.checksum = this->_16bit_int(vals[48], vals[49]);
 
     data.pm1 = this->_calculate_float(vals[50], vals[51], vals[52], vals[53]);

firmware/opcn2.h

@@ -204,7 +204,7 @@ class OPCN2
     ConfigVars read_configuration_variables();
     ConfigVars2 read_configuration_variables2();
     PMData read_pm_data();
-    HistogramData read_histogram();
+    HistogramData read_histogram(bool convert_to_conc);
 };
 
 #endif

spark.json

@@ -2,6 +2,6 @@
   "name": "opcn2",
   "author": "David H Hagan <[email protected]>",
   "license": "MIT",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "A simple library to operate the Alphasense OPC-N2 from a Particle Photon/Electron"
 }