New datasheet and user guide, readme update, code comments edited

Arduino/Examples/IoT_cloud_logging/IoT_cloud_logging.ino

@@ -34,7 +34,7 @@ uint8_t cycle_period = CYCLE_PERIOD_100_S;
 uint8_t i2c_7bit_address = I2C_ADDR_7BIT_SB_OPEN;
 
 // Which particle sensor is attached (PPD42, SDS011, or OFF)
-ParticleSensor_t particleSensor = SDS011;
+ParticleSensor_t particleSensor = OFF;
 
 // The details of the WiFi network to connect to:
 char SSID[] = "PUT WIFI NETWORK NAME HERE IN QUOTES"; // network SSID (name)
@@ -95,7 +95,7 @@ void setup() {
 
   ////////////////////////////////////////////////////////////////////
 
-  // Apply chosen settings to the Metriful board
+  // Apply chosen settings to the MS430
   if (particleSensor != OFF) {
     transmit_buffer[0] = particleSensor;
     TransmitI2C(i2c_7bit_address, PARTICLE_SENSOR_SELECT_REG, transmit_buffer, 1);
@@ -117,7 +117,7 @@ void loop() {
   }
   ready_assertion_event = false;
 
-  /* Read data from Metriful into the data structs. 
+  /* Read data from the MS430 into the data structs. 
   For each category of data (air, sound, etc.) a pointer to the data struct is 
   passed to the ReceiveI2C() function. The received byte sequence fills the 
   struct in the correct order so that each field within the struct receives

Arduino/Examples/cycle_readout/cycle_readout.ino

@@ -26,7 +26,7 @@ uint8_t cycle_period = CYCLE_PERIOD_3_S;
 uint8_t i2c_7bit_address = I2C_ADDR_7BIT_SB_OPEN;
 
 // Which particle sensor is attached (PPD42, SDS011, or OFF)
-ParticleSensor_t particleSensor = PPD42;
+ParticleSensor_t particleSensor = OFF;
 
 // How to print the data over the serial port. If printDataAsColumns = true,
 // data are columns of numbers, useful to copy/paste to a spreadsheet
@@ -50,7 +50,7 @@ void setup() {
   // Initialize the host pins, set up the serial port and reset:
   SensorHardwareSetup(i2c_7bit_address); 
 
-  // Apply chosen settings to the Metriful board
+  // Apply chosen settings to the MS430
   if (particleSensor != OFF) {
     transmit_buffer[0] = particleSensor;
     TransmitI2C(i2c_7bit_address, PARTICLE_SENSOR_SELECT_REG, transmit_buffer, 1);
@@ -76,7 +76,7 @@ void loop() {
   }
   ready_assertion_event = false;
 
-  /* Read data from Metriful into the data structs. 
+  /* Read data from the MS430 into the data structs. 
   For each category of data (air, sound, etc.) a pointer to the data struct is 
   passed to the ReceiveI2C() function. The received byte sequence fills the data 
   struct in the correct order so that each field within the struct receives

Arduino/Examples/on_demand_readout/on_demand_readout.ino

@@ -29,7 +29,7 @@ uint32_t pause_ms = 3500;
 uint8_t i2c_7bit_address = I2C_ADDR_7BIT_SB_OPEN;
 
 // Which particle sensor is attached (PPD42, SDS011, or OFF)
-ParticleSensor_t particleSensor = SDS011;
+ParticleSensor_t particleSensor = OFF;
 
 // How to print the data over the serial port. If printDataAsColumns = true,
 // data are columns of numbers, useful to copy/paste to a spreadsheet
@@ -75,7 +75,7 @@ void loop() {
     yield();
   }
 
-  /* Read data from Metriful into the data structs. 
+  /* Read data from the MS430 into the data structs. 
   For each category of data (air, sound, etc.) a pointer to the data struct is 
   passed to the ReceiveI2C() function. The received byte sequence fills the data 
   struct in the correct order so that each field within the struct receives

Arduino/Examples/particle_sensor_toggle/particle_sensor_toggle.ino

@@ -43,12 +43,13 @@ bool printDataAsColumns = true;
 ParticleSensor_t particleSensor = SDS011;
 
 // Particle sensor power control options
-uint8_t off_cycles = 2;  // leave the sensor off for this many cycles between reads
+uint8_t off_cycles = 1;  // leave the sensor off for this many cycles between reads
 uint8_t particle_sensor_control_pin = 10; // host pin number which outputs the control signal
 bool particle_sensor_ON_state = true; 
 // particle_sensor_ON_state is the required polarity of the control 
-// signal; true means +V is output to turn the sensor on, while false
-// means 0V is output.
+// signal; true means +V is output to turn the sensor on (use this for 
+// 3.3 V hosts). false means 0V is output to turn the sensor on (use
+// this for 5 V hosts). The User Guide gives example switching circuits.
 
 // END OF USER-EDITABLE SETTINGS
 //////////////////////////////////////////////////////////
@@ -70,12 +71,12 @@ void setup() {
   // Initialize the host pins, set up the serial port and reset:
   SensorHardwareSetup(i2c_7bit_address); 
 
-  // Set up the particle sensor control, and turn it on
+  // Set up the particle sensor control, and turn it off initially
   pinMode(particle_sensor_control_pin, OUTPUT);
-  digitalWrite(particle_sensor_control_pin, particle_sensor_ON_state);
-  particleSensorIsOn = true;
+  digitalWrite(particle_sensor_control_pin, !particle_sensor_ON_state);
+  particleSensorIsOn = false;
 
-  // Apply chosen settings to the Metriful board
+  // Apply chosen settings to the MS430
   if (particleSensor != OFF) {
     transmit_buffer[0] = particleSensor;
     TransmitI2C(i2c_7bit_address, PARTICLE_SENSOR_SELECT_REG, transmit_buffer, 1);
@@ -101,7 +102,7 @@ void loop() {
   }
   ready_assertion_event = false;
 
-  /* Read data from the Metriful board into the data structs. 
+  /* Read data from the MS430 into the data structs. 
   For each category of data (air, sound, etc.) a pointer to the data struct is 
   passed to the ReceiveI2C() function. The received byte sequence fills the data 
   struct in the correct order so that each field within the struct receives

Arduino/Examples/web_server/web_server.ino

@@ -33,7 +33,7 @@ uint8_t cycle_period = CYCLE_PERIOD_3_S;
 uint8_t i2c_7bit_address = I2C_ADDR_7BIT_SB_OPEN;
 
 // Which particle sensor is attached (PPD42, SDS011, or OFF)
-ParticleSensor_t particleSensor = PPD42;
+ParticleSensor_t particleSensor = OFF;
 
 // Choose whether to create a new WiFi network (host as Access Point),
 // or connect to an existing WiFi network.
@@ -192,7 +192,7 @@ void loop() {
 
   // new data are now ready
 
-  /* Read data from Metriful into the data structs. 
+  /* Read data the MS430 into the data structs. 
   For each category of data (air, sound, etc.) a pointer to the data struct is 
   passed to the ReceiveI2C() function. The received byte sequence fills the data 
   struct in the correct order so that each field within the struct receives

Arduino/Metriful_Sensor/Metriful_sensor.cpp

@@ -354,7 +354,7 @@ void printParticleData(const ParticleData_t * particleData, bool printColumns,
 //
 // Returns true on success, false on failure.
 //
-// dev_addr_7bit = the 7-bit I2C address of the Metriful board.
+// dev_addr_7bit = the 7-bit I2C address of the MS430 board.
 // commandRegister = the settings register code or command code to be used.
 // data = array containing the data to be sent; its length must be at least "data_length" bytes.
 // data_length = the number of bytes from the "data" array to be sent. 
@@ -382,7 +382,7 @@ bool TransmitI2C(uint8_t dev_addr_7bit, uint8_t commandRegister, uint8_t data[],
 //
 // Returns true on success, false on failure.
 //
-// dev_addr_7bit = the 7-bit I2C address of the Metriful board.
+// dev_addr_7bit = the 7-bit I2C address of the MS430 board.
 // commandRegister = the settings register code or data location code to be used.
 // data = array to store the received data; its length must be at least "data_length" bytes.
 // data_length = the number of bytes to read. 

README.md

@@ -10,13 +10,14 @@ This repository provides instructions and software examples for running the MS43
 
 The code examples demonstrate various ways of using the module. This includes basic control/readout, saving data to files and IoT cloud storage. Detailed comments explain each part of the programs.
 
-The [**User Guide**](User_guide.pdf) covers hardware setup, gives an overview of the code examples and explains more about what the device measures. 
+The [**User Guide**](User_guide.pdf) covers hardware setup in more detail, gives an overview of the code examples and explains more about what the device measures. 
 
 The [**Datasheet**](Datasheet.pdf) is a detailed specification of the electrical and communications interfaces of the MS430. 
 
 You can also [visit the product homepage.](https://www.sensor.metriful.com)
 
 ### Contents
+**[Handling precautions](#handling-precautions)**<br>
 **[Use with Arduino](#use-with-arduino)**<br>
 **[Use with Raspberry Pi](#use-with-raspberry-pi)**<br>
 **[Use with NodeMCU](#use-with-nodemcu)**<br>
@@ -25,6 +26,16 @@ You can also [visit the product homepage.](https://www.sensor.metriful.com)
 **[Disclaimer](#disclaimer)**<br>
 
 
+## Handling precautions
+
+The MS430 can be damaged by static electricity discharges. Minimize this risk by observing the following precautions:
+
+- Handle the board by the edges
+- Avoid touching any metal part of the device or circuit it connects to
+- Store in the provided antistatic bag when not connected in a circuit
+- Keep away from metal objects which could cause shorted connections
+
+
 ## Use with Arduino
 
 All code examples in the Arduino folder run on the Arduino Nano 33 IoT and Arduino MKR WiFi 1010, while those not requiring a network connection also run on Arduino Uno and Nano. 
@@ -49,21 +60,21 @@ If using **Arduino Nano 33 IoT**, also do the following:
 
 ### Wiring for Arduino
 
-| MS430 pin       |       Uno            |      Nano            |     Nano 33 IoT     |     MKR WiFi 1010   |
+|    MS430 pin    |       Uno            |        Nano          |     Nano 33 IoT     |     MKR WiFi 1010   |
 |:---------------:|:--------------------:|:--------------------:|:-------------------:|:-------------------:|
 |        VIN      |       5V             |         5V           |        -            |         -           |
 |        VDD      |        -             |         -            |        3.3V         |        VCC          |
 |        GND      |       GND            |         GND          |        GND          |        GND          |
-|        VPU      |       5V             |         5V           |        3.3V         |        VCC          |
+|        VPU      |      IOREF           |         5V           |        3.3V         |        VCC          |
 |        SCL      |       SCL            |         A5           |        A3           |        SCL          |
 |        SDA      |       SDA            |         A4           |        A0           |        SDA          |
 |        LIT      |        D4            |         D4           |        A1           |        D4           |
 |        SIT      |        D7            |         D7           |        A2           |        D5           |
 |        RDY      |        D2            |         D2           |        D11          |        D0           |
 
-* Input VDD is not used with 5 V systems and VIN is not used with 3.3 V systems.
+* MS430 pin VDD is not used with 5 V systems and VIN is not used with 3.3 V systems.
 
-* If using the PPD42 particle sensor, connect:
+* If using the PPD42 particle sensor, note that its pin numbering runs from right to left, and connect:
 	* Arduino 5V pin to PPD42 pin 3
 	* Arduino GND pin to PPD42 pin 1
 	* PPD42 pin 4 to MS430 pin PRT
@@ -73,7 +84,9 @@ If using **Arduino Nano 33 IoT**, also do the following:
 	* Arduino GND pin to SDS011 pin "GND"
 	* SDS011 pin "25um" to MS430 pin PRT
 
-* Using particle sensors with **Nano 33 IoT**: the solder bridge labeled “VUSB” on the underside of the Arduino must be soldered closed (to provide 5V through the VUSB pin).
+* To obtain 5V output on the Nano 33 IoT: the solder bridge labeled "VUSB" on the underside of the Arduino must be soldered closed, then use the VUSB pin.
+* To obtain a third 5V output on the Uno: use pin number 2 on the 6-pin ICSP header
+* With all hosts, VPU can be supplied from any host digital output pin set to a high voltage state. This can be useful for hosts without enough power output pins.
 
 ### To run an example program on Arduino
 
@@ -109,10 +122,10 @@ This setup assumes that you are using Raspbian Buster, which comes with all requ
 
 ### Wiring for Raspberry Pi
 
-| MS430 pin         | Raspberry Pi pin number | Raspberry Pi pin name | 
+|      MS430 pin    | Raspberry Pi pin number | Raspberry Pi pin name | 
 |:-----------------:|:-----------------------:|:---------------------:|
 |         VIN       |           -             |           -           |
-|         VDD       |           1             |      3V3 power        |
+|         VDD       |          1              |       3V3 power       |
 |         GND       |          6              |        Ground         | 
 |         VPU       |          17             |      3V3 power        | 
 |         SCL       |          5              |      GPIO 3 (SCL)     |
@@ -121,9 +134,9 @@ This setup assumes that you are using Raspbian Buster, which comes with all requ
 |         SIT       |          8              |        GPIO 14        |
 |         RDY       |          11             |        GPIO 17        |
 
-* Input VIN is not used.
+* MS430 pin VIN is not used.
 
-* If using the PPD42 particle sensor, connect:
+* If using the PPD42 particle sensor, note that its pin numbering runs from right to left, and connect:
 	* Pi pin 2 (5V) to PPD42 pin 3
 	* Pi pin 9 (Ground) to PPD42 pin 1
 	* PPD42 pin 4 to MS430 pin PRT
@@ -162,21 +175,21 @@ Note that steps 1 and 2 are already complete if you have used Arduino before on
 
 ### Wiring for NodeMCU
 
-| MS430 pin       |       NodeMCU        | 
+|    MS430 pin    |       NodeMCU        | 
 |:---------------:|:--------------------:|
 |        VIN      |        -             |
-|        VDD      |       3V3             |
+|        VDD      |       3V3            |
 |        GND      |       GND            | 
-|        VPU      |       3V3             | 
+|        VPU      |       3V3            | 
 |        SCL      |    D2 (GPIO 4)       |
 |        SDA      |    D1 (GPIO 5)       |
 |        LIT      |    D3 (GPIO 0)       |
 |        SIT      |    D5 (GPIO 14)      |
 |        RDY      |    D6 (GPIO 12)      |
 
-* Input VIN is not used.
+* MS430 pin VIN is not used.
 
-* If using the PPD42 particle sensor, connect:
+* If using the PPD42 particle sensor, note that its pin numbering runs from right to left, and connect:
 	* NodeMCU Vin (5V) pin to PPD42 pin 3
 	* NodeMCU GND pin to PPD42 pin 1
 	* PPD42 pin 4 to MS430 pin PRT
@@ -205,10 +218,6 @@ IoT cloud hosting is available from many providers around the world. Some offer
 
 ### Tago cloud
 
-An example of MS430 data logging with the Tago cloud can be viewed publicly here:
-
-[https://admin.tago.io/public/dashboard/5e21a4f806fbee0026eb48c8/07c2e906-f806-4e30-adcd-0ca2919d9828](https://admin.tago.io/public/dashboard/5e21a4f806fbee0026eb48c8/07c2e906-f806-4e30-adcd-0ca2919d9828)
-
 The steps required to set up Tago for the IoT cloud logging code example are:
 
 1. Register for a free account at [Tago.io](https://tago.io)
@@ -230,16 +239,13 @@ The steps required to set up Tago for the IoT cloud logging code example are:
 	* **illuminance**
 	* **particulates** (air particle concentration)
 9. Create a Tago dashboard for viewing the data: click the **+** to add a new dashboard, choose its name and click **save**.
-10. Add widgets of various types to the dashboard (e.g. **Line** for a simple graph, **Card** to display text or numbers). The minimum configuration for each widget is to choose the **Variable** which it displays. It is also possible to edit graph and axis titles, coloring, calculate formulas, etc.
-11. To set graph time periods to 24 hours: on the **Data Range & Format** tab of the chart settings, input **864** as the **maximum number of points to be displayed**. This assumes that the data are logged every 100 seconds (there are 86,400 seconds in 24 hours).
-12. Generate a public link to your cloud data by choosing "share" in the dashboard menu.
+10. Add widgets of various types to the dashboard (e.g. **Line** for a simple graph, **Card** to display text or numbers). 
+11. Configure each widget: the minimum configuration is to choose the **Variable** which it displays. It is also possible to edit graph and axis titles, coloring, calculate formulas, etc.
+12. Set graph displayed time period, e.g. for 24 hours: on the **Data Range & Format** tab of the chart settings, input **864** as the **maximum number of points to be displayed**. This assumes that the data are logged every 100 seconds (there are 86,400 seconds in 24 hours).
+13. Create a public link for sharing your dashboard: click the three dots next to your dashboard name on the left-hand list. Choose “share” then copy the link displayed under the “share public” tab.
 
 ### Thingspeak cloud
 
-An example of MS430 data logging with the Thingspeak cloud can be viewed publicly here: 
-
-[https://thingspeak.com/channels/1014791](https://thingspeak.com/channels/1014791)
-
 The steps required to set up Thingspeak for the IoT cloud logging code example are:
 
 1. Register for a free account at [Thingspeak.com](https://thingspeak.com)
@@ -254,9 +260,9 @@ The steps required to set up Thingspeak for the IoT cloud logging code example a
 	* Field 5: **Breath VOC / ppm**
 	* Field 6: **Sound Level / dBA SPL**
 	* Field 7: **Illuminance / lx**
-	* Field 8: **Particle Concentration / ppL**
+	* Field 8: **Particle Concentration**
 6. Click **Save Channel**. The channel will show eight (initially empty) graphs.
-7. To set graph time periods to 24 hours: on each graph click the pencil icon, delete **60** from the **Results** box and put **1** in the **Days** box, then click **Save**. This changes the graph period from the last 60 values to the last 1 day. This must be done for both the private and public view if the channel is shared publicly.
+7. To set graph time periods to 24 hours: on each graph click the pencil icon, delete **60** from the **Results** box and put **1** in the **Days** box, then click **Save**. This changes the graph period from the last 60 values to the last 1 day. This must be done separately for both the private and public view if the channel is shared publicly.
 8. The channel can be made public, if desired, from the Thingspeak **Sharing** tab.
 9. Go to the **API Keys** tab and copy the Write API Key (a sequence of letters and numbers).
 10. Paste the API key into the Metriful IoT cloud logging example code as the variable **THINGSPEAK_API_KEY_STRING** and set the variable **useTagoCloud** as **false**.

Raspberry_Pi/IoT_cloud_logging.py

@@ -54,7 +54,7 @@
 # Set up the GPIO and I2C communications bus
 (GPIO, I2C_bus) = SensorHardwareSetup()
 
-# Apply the chosen settings to the Metriful board
+# Apply the chosen settings to the MS430
 if (particleSensor != PARTICLE_SENSOR_OFF):
   I2C_bus.write_i2c_block_data(i2c_7bit_address, PARTICLE_SENSOR_SELECT_REG, [particleSensor])
 I2C_bus.write_i2c_block_data(i2c_7bit_address, CYCLE_TIME_PERIOD_REG, [cycle_period])
@@ -82,7 +82,7 @@
   while (not GPIO.event_detected(READY_pin)):
     sleep(0.05)
 
-  # Now read all data from Metriful
+  # Now read all data from the MS430
 
   # Air data
   raw_data = I2C_bus.read_i2c_block_data(i2c_7bit_address, AIR_DATA_READ, AIR_DATA_BYTES)

Raspberry_Pi/log_data_to_file.py

@@ -28,7 +28,7 @@
 
 # Number of lines of data to log in each file before starting a new file
 # (required if log_to_file == True), and which directory to save them in.
-lines_per_file = 300
+lines_per_file = 3000
 data_file_directory = "/home/pi/Desktop"
 
 # How often to measure and read data (every 3, 100, 300 seconds):
@@ -43,7 +43,7 @@
 # Set up the GPIO and I2C communications bus
 (GPIO, I2C_bus) = SensorHardwareSetup()
 
-# Apply the chosen settings to the Metriful board
+# Apply the chosen settings to the MS430
 if (particleSensor != PARTICLE_SENSOR_OFF):
   I2C_bus.write_i2c_block_data(i2c_7bit_address, PARTICLE_SENSOR_SELECT_REG, [particleSensor])
 I2C_bus.write_i2c_block_data(i2c_7bit_address, CYCLE_TIME_PERIOD_REG, [cycle_period])