Documentation and software updates for V3.0 hardware

.gitattributes

@@ -0,0 +1 @@
+*.csv diff=localizablestrings

Board Versions/70mm by 50mm Ver2.4 ATmega328p/HOW-TO - Programming the Board.md

@@ -23,4 +23,8 @@ https://mcudude.github.io/MiniCore/package_MCUdude_MiniCore_index.json
 - Bootloader -> No bootloader
 3) Set the programmer of your choice, e.g. 'Arduino as ISP (MiniCore)', 'USB ASP', etc, and set the correct port.
 4) Burn bootloader to the Solder Reflow Board. This sets fuses and registers correctly so that the sketch needs not directly deal with them.
-5) Compile and upload to the Solder Reflow Board.
+5) Compile and upload to the Solder Reflow Board.
+
+### PWM Frequency
+
+By default, the PWM control of the heating element operates at the default PWM frequency used by Arduinos of around 490Hz. This can be increased to roughly 63kHz by uncommenting the definition of the FAST_PWM macro. Note that with current hardware designs, this will likely result in overheating of the input capacitor. The circuit requires redesign to correct this fault. If FAST_PWM is enabled, this will also modify the messages on the screen to remind the user that the input capacitor may get hot.

Board Versions/70mm by 50mm Ver2.4 ATmega328p/Software/SW1.0_HW2.4_70by50mm/SW1.0_HW2.4_70by50mm.ino

@@ -29,6 +29,27 @@
 #include <Adafruit_SSD1306.h>
 #include <EEPROM.h>
 
+/**
+ * Uncomment the following line to use Fast PWM - around 63kHz.
+ * Leave it commented out to use default PWM frequency - around 490Hz.
+ * Note that current designs induce high ripple current in the input capacitor.
+ * High frequency operation is desirable, but until the control circuitry is updated,
+ * high frequency operation may cause it to get very hot and possibly fail. Low frequency
+ * operation avoids this problem, but will cause audible sound from the hotplate and tax
+ * the power supply more than is desirable.
+ */
+//#define FAST_PWM
+
+/**
+ * Alter messages on screen to make it clear when FAST_PWM is enabled, which may cause
+ * a hot input capacitor.
+ */
+#ifdef FAST_PWM
+#define HEATING_MSG "Hot Input Cap"
+#else
+#define HEATING_MSG "Begin Heating"
+#endif
+
 //Version Definitions
 static const PROGMEM float hw = 2.4;
 static const PROGMEM float sw = 1.0;
@@ -145,8 +166,10 @@ void setup() {
   maxTempIndex = EEPROM.read(tempIndexAddr) % sizeof(maxTempArray);
 
   //Enable Fast PWM with no prescaler
+#ifdef FAST_PWM
   TCCR2A = _BV(COM2A1) | _BV(COM2B1) | _BV(WGM21) | _BV(WGM20);
   TCCR2B = _BV(CS20);
+#endif
 
   //Start-up Diplay
   display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS);
@@ -219,7 +242,7 @@ void main_menu() {
       display.print(F("HOLD  BUTTONS"));
       display.drawLine( 3, 12, 79, 12, SSD1306_WHITE ); 
       display.setCursor(3,18);
-      display.print(F("Begin Heating"));
+      display.print(F(HEATING_MSG));
     }
     x = ( x + 1 ) % y; //Display change increment and modulus
 

Board Versions/70mm by 50mm Ver3.0 ATmega4809/HOW-TO - Build the Stock Board.md

@@ -5,6 +5,10 @@ Building this solder reflow plate is a intermediate level task.
 While not overly complicated it still features many small surface mount components and a few polarity sensitive components.
 Future versions of the board are being developed to make home building easier to accomplish.
 
+## WARNING!!!
+
+This design lacks safety features to limit the amount of power it may draw or the temperature it may reach and there are other issues with the electrical design. With a suitable power supply and as long as the software doesn't have any major bugs, it can be operated without issue but there is a real risk that it could start a fire in the event of a software bug or other fault. Do not leave it unsupervised while connected to power.
+
 #### Preparations
 Firstly, download the Gerber files and Bill of Materials.
 While you are there, if you download the Pick and Place Doc you can have select board manufacturers populate the boards for you, normally at extra cost.
@@ -20,7 +24,7 @@ Order as many boards as you like ensuring you order the materials too.
 Delivery from China nrormally takes between 2 and 6 weeks.
 
 Some other bits to consider
-- You will need to buy a 0.91" OLED seperately. Ebay is normally good for this. Make sure to get the 4 pin I2C version.
+- You will need to buy a 0.91" OLED seperately. Ebay or Amazon are normally good for this. Make sure to get the 4 pin I2C version.
 - You will need a 12V power supply. Minimum of 5A (take a lot of power to heat to 180C). An enclosed power brick with a 2.5mm inner diameter barrel jack is a good option. Or you can rig one yourself from an open supply like [these](https://www.ebay.co.uk/itm/164636015985?_trkparms=ispr%3D1&hash=item2655123d71:g:0~EAAOSwWe9f-qaI&amdata=enc%3AAQAGAAACkPYe5NmHp%252B2JMhMi7yxGiTJkPrKr5t53CooMSQt2orsSLY2M1Gjmuwt9c03vWNfiRs%252FQ%252FM%252BYAJ6j8WnNhVqBTnBTru6OB86J8pc%252FYfL%252FNaBizpiin5VQ2FRoMM2xlSMmLikPq1Kfo827DnvZ98oP5KQz5lhOmHCrLavgEdachmpNk6IFLLp0VfjgkVc%252Fs%252B%252BX8KFBqiDdz4rX9wcFb7PwH1fO8ZEtIwpVbAxrW3%252FafmJJ18bdW%252BrzPZTBljdLcVAzgt7L33U2%252BnDSJ5JRD%252BA%252FmCWPD5Ah6XsDLI%252BsRJa7Xu6sBtNsFRM2CBmXp9DI6UX8qZYagrwBZa%252FjGHZTInWGRK3dJPABW%252Beq5G3GBKLwihaUJqCC5VI3fRwt%252B4pYKBpKseUG0vriRotickOTQR46RbQNNKgE4Wmf0QthOdwjOadBEksewf0Sqfs8FhBQd5ILciZSYxv%252F9MTtMLWLLqJaqGC7vd09YHPBfKJxCdZ3O0yACOYApZvqe1qnKExBBOneiSwT9%252BcrHj2LbBg53rFOsAVowVYD3uUypZ2x8WsQAM06zeZe6LoYHAKAfjmte4DfzaamhbOEAo%252FGx2hSSPkfUC8cGohhcl%252BUBomTqERhc9gly0pHWbekyhBpsr0flCOde9DuiSv3GefdP2yGA3%252FG6q34VpSfsxQUoaMNcuMXBKjUssQpRn3PitZj1Ipbor7HEPB8q3%252B8qAmTxWw5V1EUYUShj95m58kDRc9oVv3eEyryFRcMXJjavWD0leQ%252FEekao2hEheLD1U3thR%252B61JfoOMSXatZ0bMyf7NaTVmPFyDvA8AKqjWJ2jxogJ2asMWqSMCzpT92CwMjXS4NQ%252FLzdmxXwQ%252B77K20%252F9Tx%252BA2awmW1x%7Cclp%3A2334524%7Ctkp%3ABFBMmpvD9tdf), and a 2.5mm diameter barrel jack adapter. Just be careful as you will be dealing with mains (Live and Neutral) wiring so only do so if you are competent and confident.
 - If you picked up a stencil make sure to get some solder paste too.
 - Finally, some small hardware is good. The board has holes just bigger than M3 so standard motherboard stand-offs and similar should fit. The board will function without but lifting it off the desk is best.
@@ -34,7 +38,8 @@ Follow the following rough guidance to get you on your way.
 - Carefully remove the stencil and clean it.
 - Starting with the smaller components, gently place them onto the board following the circuit drawing.
 - If you have a working solder reflow board you can now reflow your working board (if any someone would develop one).
-- If not, use a fine pointed soldering iron to dab solder the smaller components.
+- If you have a decent lab power supply that can output 5A or better and a spare board, you could power one of your spare boards directly by attaching to the large pad of the MOSFET (the drain pad) and the lower pad of D2 (it's cathode pad). This is relatively easy if you solder some wires to those pads. Use current limiting to control heating. Slowly and cautiously increase the heat until you see the solder paste start to activate and melt. If you have a multimeter with a thermocouple or a thermal imager, some test runs to see the temperature at different current levels is advisable. Somewhere around 3-5A will probably be enough.
+- If that sounds too crazy/dangerous, use a fine pointed soldering iron to dab solder the smaller components.
 - More heat will be needed to solder the larger components, especially the large tab of the MOSFET.
 - Check for good solder joints and that there are no shorts, especially around the microcontroller.
 - Move onto the through-hole components. The switches need to be checked for polarity before fitting else they will confuse the software on first start-up. Fit them with the notch pointing towards the OLED.
@@ -44,4 +49,4 @@ Follow the following rough guidance to get you on your way.
 #### Finishing up
 Congratulations! You've soldered a thing that will definitely maybe work on the first try!
 Give the board a clean with some cleaning solvent or cleaning alcohol.
-You can now move onto the programming of the board so open up that document and get cracking.
+You can now move onto the programming of the board so open up that document and get cracking.

Board Versions/70mm by 50mm Ver3.0 ATmega4809/HOW-TO - Programming the Board.md

@@ -3,10 +3,42 @@
 ## How-To - Programming the Board
 This Solder Reflow Plate has been specifically designed to be Arduino based and easily programmed through the Arduino IDE or any other similar environment.
 For ease, here is a guide to programming the board via the Arduino IDE.
-The ATmega4809 is UPDI programmed. Once the boards arrive and I have experienced this myself I will write up a full guide. In the meantime there are a few good guides out there on UPDI programming from an Arduino.
+The ATmega4809 is UPDI programmed so you will need a UPDI programmer. If you are harvesting your ATMega4809 from an Arduino Nano Every or other Arduino board, you may be tempted to try to program it whilst still on the source board before transferring it. This is not recommended and will likely end up loading firmware that does not work. You shouldn't break anything. You'll just end up having to rebuild and program on the real board using UPDI.
 
 ### Preparation
-TBC
+1) Download and install the Arduino IDE from the [Arduino Website](https://www.arduino.cc/). The sketch was originally developed on version 1.8.19, though any recent and all future versions of the Arduino IDE should be fully supported.
+2) Install the [MegaCoreX](https://github.com/MCUdude/MegaCoreX) additional boards to allow programming of bare Atmega4809 and similar microcontrollers. Follow the instructions on the [MegaCoreX repository](https://github.com/MCUdude/MegaCoreX)
+3) Add the boards to the board manager by searching for and installing MegaCoreX in 'Tools->Board->Board Manager'.
+4) Search for and install the Bounce2, Adafruit_GFX and Adafruit_SSD1306 libraries in 'Tools->Manage Libraries'.
+5) Obtain a UPDI programmer. If you don't know what that is or you don't have one, your easiest option is probably to use an Arduino board with the [JTAG2UPDI](https://github.com/ElTangas/jtag2updi) sketch loaded onto it.
+
+### UPDI Programming with JTAG2UPDI
+If you already have a purpose built UPDI programmer and know how to use it, you can skip this section and just use your existing UPDI programmer. For the rest of us, if you have a spare Arduino board lying around, you can program it to play the role of a UPDI programmer. I used an Arduino Nano, but many other Arduino compatible boards should also work. Note that if you are using an Arduino board you need to disable the autoreset feature when using it as a programmer (ie. not during the initial programming with the JTAG2UPDI sketch, but after that). There are two main ways to do this, both of which aim to prevent the reset pin from being pulled high. Option 1, which is the option I used, is to place a large capacitance (around 10uF or bigger) between the ground and reset pins. Option 2 is to place a resistor less than 1k between reset and ground - something like 330 ohms might work although I haven't tried this option.
+1) Download the [JTAG2UPDI](https://github.com/ElTangas/jtag2updi) code from Github.
+2) Rename the source directory to jtag2updi to make the Arduino IDE happy.
+3) Load the jtag2updi/jtag2updi.ino sketch into your Arduino IDE.
+4) Connect your Arduino board via USB.
+5) Select the appropriate board type via the Tools->Board menu item.
+6) Select the appropriate port for you UPDI programmer Arduino board.
+7) If you're using a capacitor or resistor to disable the reset, *DO NOT* have this in place yet. You won't be able to load the JTAG2UPDI sketch with that in place.
+8) Compile and upload the sketch.
+9) Connect your capacitor between the reset and ground pins now.
+10) Connect a 4.7k resistor to the PD6 pin so it's ready to connect when you're ready to program.
+You should now have a UPDI programmer ready to go.
 
 ### Program
-TBC
+1) Connect your UPDI programmer to the UPDI pins on the Solder Reflow board - the 3 pin header on the right side of the board. You need to connect the top pin to ground and the centre pin to the UPDI pin on your programmer (PD6 is using JTAG2UPDI). If using JTAG2UPDI, make sure you have 4.7k of resistance between the PD6 and UPDI pins.
+2) You need to provide power to the Atmega4809 in order to program it. You have two options. You can connect 12V to the DC connector on the board and the 5V LDO will supply power to the MCU. Alternatively, you can connect the 5V pin on the 3-pin UPDI header to 5V on your UPDI programmer. This will also supply power to the MCU. Pick one. Don't do both.
+3) Select the following settings under the Tools menu:
+- Board->MegaCoreX->Atmega4809 
+- Clock->Internal 16MHz
+- BOD->BOD 2.6V
+- EEPROM->EEPROM retained
+- Pinout->48 pin Standard
+- Reset Pin->Reset
+- Bootloader->No bootloader
+4) Set the programmer of your choice. eg. JTAG2UPDI, Atmel ICE, etc
+5) Compile and upload.
+
+### PWM Frequency
+By default, the PWM control of the heating element operates at the default PWM frequency used by Arduinos of around 490Hz. This can be increased to roughly 63kHz by uncommenting the definition of the FAST_PWM macro. Note that with current hardware designs, this will likely result in overheating of the input capacitor. The circuit requires redesign to correct this fault. If FAST_PWM is enabled, this will also modify the messages on the screen to remind the user that the input capacitor may get hot.

Board Versions/70mm by 50mm Ver3.0 ATmega4809/Software/README.md

@@ -0,0 +1,46 @@
+# **Software Revisions**
+###### 70*50mm Solder Reflow plate
+
+## Note
+This software is barely functional. It was not written by me nor would I consider it actively maintained by anybody. The original developer appears to have abandoned the project.
+
+I am working on new designs to address many of the hardware and software design issues. In the meantime, this design can work with some limitations. Specifically:
+
+  - It's a little slow.
+  - It's not well suited for anything other than low temperature solder alloys (ie. SnBi alloys that melt around 140 celsius).
+  - The temperature measurements that it gives are wildly inaccurate.
+  - It won't follow a solder profile. It basically just heats up until it hits something it thinks is the requested maximum temperature and then shuts off power to the hotplate.
+
+## User Interface
+
+Use the buttons to adjust maximum temperature up and down in 10 degree increments.
+
+Press both buttons together to start the reflow cycle.
+
+## Operational Explanation
+
+The logic used to drive the heating algorithm is fundamentally flawed if the goal is to follow some kind of reflow profile.
+
+  - It doesn't consider time while the heating cycle is running, so how can it know what temperature is should be targeting at any given point in the reflow cycle.
+  - It does vary the PWM duty cycle during the heating cycle, but from the logic all it really does it:
+    - Quickly ramp up the PWM duty cycle to a "warm-up" value.
+    - Once the reported temperature reaches a warm-up value, quickly ramps up the PWM duty cycle to a maximum duty cycle value.
+    - Once the reported temperature reaches the maximum temperature requested, shuts off power to the heating element.
+    - The reported temperature continues to be monitored until the reported temperature falls below 45 celsius.
+
+## Potential Improvement Areas
+
+### Follow an actual reflow profile.
+
+There are designs out there that already do this, but I've not seen any firmware shared to do this. This would require a control method that understands how much time has passed from the beginning of the reflow cycle, can calculate the expected temperature at that time and produce a control signal to closely follow that expected temperature. PID control is probably the most appropriate method to do this, although there are other possible approaches.
+
+### PID Control with Autotuning
+
+PID control is relatively simple to implement, but how well it works is highly dependent on the proportional, integral and differential gains used. An auto-tuning cycle using some common auto-tuning algorithm like Ziegler-Nichols would be desirable so that users can relatively easily arrive at a reaonable working set of gains for their hotplate.
+
+### Reflow profile customization
+
+Once you have PID control and auto-tuning, you can follow a reflow profile provided that the device has sufficient power to keep up. The reflow profiles should be able to be customized. The simplest way would be to provide a relatively straightforward means of defining the reflow profile in the code and simply let users upload new firmware to set up a new profile. Whether it's possible to provide customization of reflow profiles via the two-button UI is dubious. While it could definitely be implemented, whether this can be done in a way that's usable enough to justify the effort is questionable.
+
+A more likely option may be to define several different hard-coded profiles in the firmware and provide a simple UI to select on of several reflow profiles instead of the current UI which allows selection of one of several maximum temperature settings.
+