Merge pull request #18 from untzag/programming

programming instructions

5 files changed, 72 insertions, 41 deletions

diff --git a/digital-controller/arduino-uno-controller/firmware/firmware.ino b/digital-controller/arduino-uno-controller/firmware/firmware.ino
index 3735c4a..f90ae05 100644
--- a/digital-controller/arduino-uno-controller/firmware/firmware.ino
+++ b/digital-controller/arduino-uno-controller/firmware/firmware.ino
@@ -1,3 +1,24 @@
+/* EXAMPLE FIRMWARE
+ * CONTROLLING WPP DRIVERS FROM ARDUINO UNO
+ * 
+ * SERIAL INTERFACE
+ * 9600 baud
+ * newline terminated (no carriage return)
+ * space separated commands:
+ * <ADDRESS> <LED INTENSITY> <FAN INTENSITY>
+ * 
+ * example: full brightness full speed:
+ * 38 255 255
+ * example: LED off fan full speed:
+ * 38 0 255
+ * example: LED medium fan off
+ * 38 100 0
+ * 
+ * if <ADDRESS> 0, commands sent to all devices
+ * 
+ * if <ADDRESS> -1, list of addresses seen returned
+ */
+
 #include <Wire.h>
 
 #define INPUT_SIZE 100  // TODO: make this a reasonable value
diff --git a/fabrication-and-operation-instructions/arduino-interface.jpg b/fabrication-and-operation-instructions/arduino-interface.jpg
new file mode 100644
index 0000000..046275d
--- /dev/null
+++ b/fabrication-and-operation-instructions/arduino-interface.jpg
diff --git a/fabrication-and-operation-instructions/tiny-programmer.jpg b/fabrication-and-operation-instructions/tiny-programmer.jpg
new file mode 100644
index 0000000..9d97971
--- /dev/null
+++ b/fabrication-and-operation-instructions/tiny-programmer.jpg
diff --git a/fabrication-and-operation-instructions/wpp-fabrication-operation.pdf b/fabrication-and-operation-instructions/wpp-fabrication-operation.pdf
index aeb26b2..56beb08 100644
--- a/fabrication-and-operation-instructions/wpp-fabrication-operation.pdf
+++ b/fabrication-and-operation-instructions/wpp-fabrication-operation.pdf
diff --git a/fabrication-and-operation-instructions/wpp-fabrication-operation.tex b/fabrication-and-operation-instructions/wpp-fabrication-operation.tex
index 77862f3..888b70e 100644
--- a/fabrication-and-operation-instructions/wpp-fabrication-operation.tex
+++ b/fabrication-and-operation-instructions/wpp-fabrication-operation.tex
@@ -70,9 +70,9 @@
 
 \section{Introduction}
 
-Below are instructions for fabrication, operation and documentation of Wisconsin Photoreactor Platform (WPP) devices. 
+Below are instructions for fabrication, operation and documentation of Wisconsin Photoreactor Platform (WPP) devices.
 
-For access to all project source files, documentation and resources, visit the Wisconsin Photoreactor Platform project repository on GitHub at \href{https://github.com/uw-madison-chem-shops/wisconsin-photoreactor}{https://github.com/uw-madison-chem-shops/wisconsin-photoreactor}. 
+For access to all project source files, documentation and resources, visit the Wisconsin Photoreactor Platform project repository on GitHub at \href{https://github.com/uw-madison-chem-shops/wisconsin-photoreactor}{https://github.com/uw-madison-chem-shops/wisconsin-photoreactor}.
 
 \begin{figure}[H]
 	\includegraphics[width=\textwidth]{"./fig1.png"}
@@ -93,7 +93,7 @@ If you would like to contribute to the WPP project or notice an issue, please co
 \section{Fabrication}
 
 WPP devices are simple to fabricate.
-To fabricate a WPP device, you'll need a soldering iron, electronics tweezers, thin nose pliers and a screwdriver. 
+To fabricate a WPP device, you'll need a soldering iron, electronics tweezers, thin nose pliers and a screwdriver.
 The fabrication process is divided into three parts:
 
 \begin{itemize}
@@ -117,15 +117,15 @@ The project repository provides README files containing a bill of materials for
 \end{figure}
 
 The WPP architecture uses industry standard 20 mm ``LED star'' circuit boards mounted with 3 high-intensity LEDs to deliver photons to photoreactions (Figure 2A).
-LED stars are commercially available or can be easily fabricated. 
+LED stars are commercially available or can be easily fabricated.
 The range of wavelengths provided by a LED star depends upon the emission profile of the mounted LEDs.
 \textbf{\textit{Through variation of the LED star integrated into a WPP base (Figure 2B), the user can control the wavelengths of light delivered by the photon source to a reaction vessel.}}
-An aluminim heatsink and cooling fan are integrated to keep the LED star from overheating. 
+An aluminim heatsink and cooling fan are integrated to keep the LED star from overheating.
 
-A list of LED stars tested with the WPP platform is available in the 'photon-source-leds' subdirectory of the project repository. 
+A list of LED stars tested with the WPP platform is available in the 'photon-source-leds' subdirectory of the project repository.
 It is easiest to use LED stars with pre-mounted LEDs.
 Otherwise, you can order discrete LEDs and bare LED star circuit boards to fabricate your own.
-Custom LED star production requires a reflow oven. 
+Custom LED star production requires a reflow oven.
 All LED stars must be mounted with LEDs with a maximum forward current of 1000 mA.
 
 \begin{figure}[H]
@@ -140,7 +140,7 @@ This is often sold as "standard hookup wire"
 Soldering may be challenging, as the LED star itself will resist efforts to heat it.
 Using lead-based solder with a low melting point may help.
 
-Solder a connector to the end of the LED star. 
+Solder a connector to the end of the LED star.
 Ensure the connection between the connector and wire is strong and has plenty of sodler ()Figure 3C).
 Using heat-shrink tubing, seal the connector and wire junction (Figure 3D).
 
@@ -156,7 +156,7 @@ When interacting with the design files in our repository you will see several fi
 We have designed the WPP enclosure using Fusion 360, and included f3d design source files for those that wish to extend or modify our designs.
 Interacting with f3d files requires use of Fusion 360 license.
 You will also find stl files in the repository.
-These are common 3D-model exchange files which can be viewed with 3D modeling programs or printed with 3D-printers. 
+These are common 3D-model exchange files which can be viewed with 3D modeling programs or printed with 3D-printers.
 
 We recommend white PLA as the printing material. We have also used white ABS.
 If you are printing yourself, follow the instructions provided by your 3D-printer's manufacturer.
@@ -187,7 +187,7 @@ The heatsink can be tapped by hand.
 You only need to tap two of the innermost holes.
 
 Install the LED star and heatsink into the WPP base using 1/4'' screws.
-Ensure the LED wires face towards the hole in the side of the printed base.  
+Ensure the LED wires face towards the hole in the side of the printed base.
 
 \begin{figure}[H]
 	\includegraphics[width=\textwidth]{"./fig6.png"}
@@ -199,7 +199,7 @@ Pay special attention to the orientation of the fan, including the location of t
 Use 3/4'' screws here.
 Then, install the cable anchor using a 1/4'' screw.
 Use a zip tie to capture the fan cord (Figure 6B).
-Finally, screw in the threaded standoffs (Figure 6C). 
+Finally, screw in the threaded standoffs (Figure 6C).
 Your WPP base is now ready for use.
 
 \begin{figure}[H]
@@ -237,7 +237,7 @@ Second, the multiple reaction configuration, where multiple vessels are placed i
 This configuration exposes each vessel to less light relative to the single reaction configuration but provides equivalent exposure to each vessel.
 \textbf{\textit{Through variation of the reaction module, the user can configure the reaction vessel type, size and placement within a WPP apparatus.}}
 
-To fabricate a reaction module, simply 3D-print a reaction chamber and vial holder models. You can use those supplied in the 'photoreaction-modules' subdirectory or design your own using the templates designs in the same subdirectory. 
+To fabricate a reaction module, simply 3D-print a reaction chamber and vial holder models. You can use those supplied in the 'photoreaction-modules' subdirectory or design your own using the templates designs in the same subdirectory.
 
 \begin{figure}[H]
 	\centering
@@ -249,7 +249,7 @@ Once you have both parts printed, cut reflective material to line the inside of
 Remove the backing and stick the material to the chamber walls (Figure 9A---B).
 It is fine to leave overlap around the interior.
 The 3D printed vial holder requires no modification.
-Your reaction module is now ready for use. 
+Your reaction module is now ready for use.
 
 \clearpage
 
@@ -275,13 +275,13 @@ The analog driver board is designed exceedingly simple to fabricate and use.
 The circuit accepts DC 12 V through a barrel jack.
 A small knob is used to adjust light intensity.
 Fan speed is not adjustable.
-\textbf{We recommend chemists interested in adopting the WPP architecture first build and test the analog driver board.} 
+\textbf{We recommend chemists interested in adopting the WPP architecture first build and test the analog driver board.}
 Refer to \autoref{SEC:analog-driver} for analog driver board assembly instructions and further explanation.
 
 
 The digital driver board is made to be incorporated into an I$^2$C-based digital control system.
 In addition to power, these boards have 4-pin connectors to carry the I$^2$C serial data.
-\textbf{We recommend experienced chemists interested in automation of WPP devices and integration of peripherals to expand device functionality use the digital driver board.} 
+\textbf{We recommend experienced chemists interested in automation of WPP devices and integration of peripherals to expand device functionality use the digital driver board.}
 Refer to \autoref{SEC:digital-driver} for digital driver board assembly instructions and further explanation.
 
 The simple driver circuit allows for use of any commerical 1000 mA LED driver with the WPP architecture.
@@ -330,13 +330,13 @@ These values are derived from Mean Well's datasheet for the analog board’s LDD
 		1.00                        & 40\%                                          \\
 		0.75                        & 30\%                                          \\
 		0.5                         & 20\%                                          \\
-		0.45                        & 0\%                                          
+		0.45                        & 0\%
 	\end{tabular}
 	\caption{Test point voltage to approximate relative LED intensity conversion. TODO: FIX TABLE FORMATTING.}
 	\label{tab:analog-board-conversion}
 \end{table}
 
-To fabricate an analog driver board, start by ordering analog board PCBs from a PCB manufacturer. Your PCB manufacturer will send you bare boards of the type seen in Figure 12A. 
+To fabricate an analog driver board, start by ordering analog board PCBs from a PCB manufacturer. Your PCB manufacturer will send you bare boards of the type seen in Figure 12A.
 
 \begin{figure}[H]
 	\centering
@@ -344,12 +344,12 @@ To fabricate an analog driver board, start by ordering analog board PCBs from a
 	\caption{(A) Blank analog driver board. (B) Analog driver board with labeled surface mount components.}
 \end{figure}
 
-Begin by adding the surface mount components. 
+Begin by adding the surface mount components.
 Refer to the analog driver schematic for part identities.
 We recommend using thin solder, e.g. 0.015''.
 The surface mount resistors and capacitors have no polarity.
 However, the power indicator LED does have a polarity---ensure that the small green line points towards ground (left).
-Once done your analog board should look that depicted in Figure 12B. 
+Once done your analog board should look that depicted in Figure 12B.
 
 \begin{figure}[H]
 	\centering
@@ -359,7 +359,7 @@ Once done your analog board should look that depicted in Figure 12B.
 
 Next, solder on the connectors and the potentiometer knob (Figure 13A).
 From now on we recommend standard gage solder, e.g. 0.031''.
-You can then add the barrel jacks and test points. 
+You can then add the barrel jacks and test points.
 With these added you may plug in your board into power for the first time.
 Either barrel jack can be plugged in.
 You should see your power indicator LED illuminate (Figure 13B)
@@ -371,7 +371,7 @@ You should see your power indicator LED illuminate (Figure 13B)
 \end{figure}
 
 Finally, solder on the Mean Well LDD-100L LED driver (Figure 14).
-This component goes on the back of the analog driver board. 
+This component goes on the back of the analog driver board.
 The analog driver board is now ready for use.
 
 \includepdf[landscape=true]{"../analog-driver-board/driver.pdf"}
@@ -379,43 +379,54 @@ The analog driver board is now ready for use.
 \subsubsection{Digital Driver Board} \label{SEC:digital-driver}
 
 \begin{figure}[H]
-	\centering
-	\includegraphics[width=\textwidth]{"./fig15.png"}
-	\caption{(A) WPP devices fitted with digital driver boards connected in series. (B) Powered WPP devices connected in series.}
+  \centering
+  \includegraphics[width=\textwidth]{"./fig15.png"}
+  \caption{(A) WPP devices fitted with digital driver boards connected in series. (B) Powered WPP devices connected in series.}
+  \label{FIG:digital-driver-network}
 \end{figure}
 
 The digital driver circuit can be controlled from a computer or some other digital device.
-We built our driver to work over I2C, consistent with an emerging standard for many ``maker'' products.
+We built our driver to work over I$^2$C, consistent with an emerging standard for many ``maker'' products.
 While the physical connectors may be different, our digital circuit is compatible with the following systems.
 
 \begin{itemize}
   \item \href{https://learn.adafruit.com/introducing-adafruit-stemma-qt}{Adafruit STEMMA}
   \item \href{https://www.sparkfun.com/qwiic}{Sparkfun Qwiic}
   \item \href{https://www.seeedstudio.com/category/Grove-c-1003.html}{Seeed Grove}
+  \item \href{https://store.ncd.io/?fwp_product_type=i2c-mini-modules}{NCD I2C Mini Modules}
 \end{itemize}
 
+Multiple digital driver boards may be ``networked'' together onto one I$^2$C bus by simply daisy-chaining the boards together, as shown in \autoref{FIG:digital-driver-network}.
+I$^2$C peripherals in these families can be connected to digital driver boards to expand functionality, but software must be produced to interface with them.
 Through use of the digital driver board, one can control WPP device light intensity and fan speed.
 This control is achieved by connecting a control unit, like an Arduino Uno, to the digital driver board using custom software.
-Multiple WPP devices with digital driver boards can be connected to a single control unit and power supply (Figure 5).
-Open-source software for interfacing digital driver boards and Arduino Uno control units is provided in the project repository.
-Instructions for implementing this software and controlling WPP devices using it are in the fabrication guide.
-Other I2C peripherals can be connected to digital driver boards to expand functionality, but software must be produced to interface with them.
+A schematic of the digital driver board appears at the end of this section.
+
+\clearpage
 
 \begin{center}
-  \includegraphics[width=\textwidth/2]{"./digital-wired.jpg"}
+  \includegraphics[width=\textwidth/2]{"./tiny-programmer.jpg"}
 \end{center}
 
-Each digital driver is based around an ATtiny85 microcontroller acting as an I2C peripheral.
-Multiple digital driver boards may be ``networked'' together onto one I2C bus by simply daisy-chaining the boards together, as shown above.
-In such a use-case you must choose a unique I2C address for each ATtiny85 peripheral.
+Each digital driver board requires a programmed ATtiny85 microcontroller which acts as the ``brains'' of the circuit.
+The microcontroller's primary purpose is to serve as a peripheral in the I$^2$C network.
+The firmware is provided within the /digital-driver-board/firmware directory of the online repository.
+We used the Arduino IDE and a commercially available programmer (pictured above).
+Follow the detailed instructions provided with the programmer that you purchase.
+Note that each peripheral has an address, defined at the top of the firmware file.
+This address must be totally unique within the network of connected I$^2$C devices.
+You may wish to write the address used onto the microcontroller chips as you program them.
 
 \begin{center}
-  \includegraphics[width=\textwidth/2]{"./redboard.jpg"}
+  \includegraphics[width=\textwidth/2]{"./arduino-interface.jpg"}
 \end{center}
 
-There are many ways to interface with the I2C bus.
-We have used a SparkFun RedBoard, pictured above.
-You may find an example within the online repository that dynamically controls both the LED intensity and fan speed.
+There are many strategies you might employ for interfacing with your digital driver boards.
+We have provided firmware appropriate for using an Arduino Uno to control the reactors over a USB cable from any computer.
+Find the firmware within the /digital-controller/arduino-uno-controller/firmware directory.
+Once you have flashed this firmware onto your Arduino, connect at least the SCL, SDA, and GND pins as pictured above.
+This example firmware allows you to control multiple reactors by sending serial-over-USB commands from your computer.
+Read the description at the top of the firmware file for details.
 
 \includepdf[landscape=true]{"../digital-driver-board/driver.pdf"}
 
@@ -437,12 +448,11 @@ However, no circuit board fabrication is required, and any commercial 1000 mA LE
 Once a WPP apparatus is configured with the desired photon source, reaction module and reactor driver, it is ready to drive photoreactions.
 
 \begin{figure}[H]
-	\centering
-	\includegraphics[width=\textwidth]{"./fign8.png"}
-	\caption{A WPP apparatus with a 450 nm photon source, 4 mL reactor module and digital driver board on a standard laboratory stir plate conducting 6 simultaneous photoreactions in the multiple reaction configuration.}
+  \centering
+  \includegraphics[width=\textwidth]{"./fign8.png"}
+  \caption{A WPP apparatus with a 450 nm photon source, 4 mL reactor module and digital driver board on a standard laboratory stir plate conducting 6 simultaneous photoreactions in the multiple reaction configuration.}
 \end{figure}
 
-
 To conduct a photoreaction using a WPP device, an assembled apparatus should be placed on a lab stir plate, to provide reaction mixture stirring, and reaction vessels should be inserted into the apparatus in the desired layout (Figure 8).
 The 130 by 130 mm footprint of the WPP architecture is compatible with typical stir plates.
 A standard 12 V power supply can then be plugged into the reactor driver to turn on the device and start reaction.