diff --git a/README.md b/README.md index c3aa42f..906807f 100644 --- a/README.md +++ b/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 diff --git a/firmware/opcn2.cpp b/firmware/opcn2.cpp index 3e4a9b2..ab9b58e 100644 --- a/firmware/opcn2.cpp +++ b/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]); diff --git a/firmware/opcn2.h b/firmware/opcn2.h index 5370cbf..b3b6873 100644 --- a/firmware/opcn2.h +++ b/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 diff --git a/spark.json b/spark.json index 4057bc7..9d38c8e 100644 --- a/spark.json +++ b/spark.json @@ -2,6 +2,6 @@ "name": "opcn2", "author": "David H Hagan ", "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" }