Merge pull request #1255 from River-b/master

Added new Documentation file & edited existing documentation for clarity
This commit is contained in:
Ben V. Brown
2022-03-13 10:54:51 +11:00
committed by GitHub
5 changed files with 133 additions and 65 deletions

View File

@@ -1,12 +1,12 @@
# Debugging Menu
In this firmware there is extra debugging information hidden under an extra menu.
This is accessed by holding the rear (B) button on the iron while it is on the home screen.
This is accessed by holding the rear (-/B) button on the iron while it is on the home screen.
This menu is meant to be simple, so it has no fancy GUI animations.
To move through the menu use the front (A) button.
To exit, use the rear (B) button again.
To move through the menu use the front (+/A) button.
To exit, use the rear (-/B) button again.
## Menu items
@@ -45,7 +45,7 @@ This can be used with RTip for assessing temperature processing performance.
### CHan
This is the handle temperature in C. This is used for cold junction compensation of the tip temp.
This is the handle temperature in C. This is used for cold junction compensation of the tip temperature.
This is shown in degrees C x10, so 200 == 20.0C
### Vin
@@ -73,14 +73,16 @@ This may change during power up as the sources are negotiated in turn.
- **QC** input (We used QC2/3 negotiation for current supply)
- **PD W. VBus** input (We used the PD subsystem to negotiate for the current supply); and VBus is connected to your input power source
- **PD No VBus** input (We used the PD subsystem to negotiate for the current supply); and VBus is **NOT** connected to your input power source
- If you successfully modified the Pinecil to support 24V by cutting the trace line to Vbus, then 'PD No VBus' displays on screen.
- Connect to any PD USB power to check Vbus status. It will not show any PD message when Pinecil is powered by DC port, QC, or USB 5V (non PD).
### Max
This indicates the max temp in C that the system estimates it can measure the tip reliably to.
This indicates the max temperature in C that the system estimates it can measure the tip reliably to.
This is dependant on a few factors including the handle temperature so it can move around during use.
### Hall
This will appear if your device is capable of having a magnetic hall effect sensor fitted.
This will show the current field strength reading from the sensor, this can be used to check the sensor is operational and measure how strong the magnetic field is for diagnostics.
This appears if your device is capable of having a magnetic hall effect sensor installed (Pinecil).
This shows the current field strength reading from the sensor. It can be used to check if the sensor is operational, and measure how strong the magnetic field is for diagnostics and optimal placement of magnets on a stand.

View File

@@ -12,7 +12,7 @@ These are built on every change and can be found on the Actions tab (see below).
Main releases are made to the [releases page](https://github.com/Ralim/IronOS/releases).
Download the zip file that matches your model of soldering iron, and extract it.
You then need to use the appropriate file type for your unit, in general Miniware devices need `.hex` and Pinecil need `.bin`.
Select the appropriate file type for your unit, in general Miniware devices need `.hex` and Pinecil needs `.dfu`.
Flash according to details below
### Bleeding edge / latest
@@ -24,7 +24,7 @@ In general you probably want `master`.
Once you click on a run, scroll down to the "Artifacts" section and then click on your model to download a zip file.
Then this works the same as a production release (use the correct file).
## Miniware devices (TS100, TS80, TS80P & MHP30)
# Miniware devices (TS100, TS80, TS80P & MHP30)
This is completely safe, but if it goes wrong just put the `.hex` file from the official website ([TS100](https://www.minidso.com/forum.php?mod=viewthread&tid=868&extra=page%3D1), [TS80](https://www.minidso.com/forum.php?mod=viewthread&tid=3202&extra=page%3D1), [TS80P](https://www.minidso.com/forum.php?mod=viewthread&tid=4070&extra=page%3D1) & [MHP30](https://www.minidso.com/forum.php?mod=viewthread&tid=4385&extra=page%3D1)) onto the unit and you're back to the old firmware. Downloads for the `.hex` files to flash are available on the [releases page.](https://github.com/Ralim/IronOS/releases) The file you want is called _(MODEL)\_EN.hex_ unless you want the translations, they are (MODEL)\__language short name_.hex. Where (MODEL) is either TS100 or TS80.
@@ -47,13 +47,13 @@ There is a complete device flash backup included in this repository. (Note this
For the TS80 the SWD pins are used for the QC negotiation, so you can actually connect to the SWD power via the USB connector.
# Mac
## Mac
sgr1ff1n (Shane) commented in [issue 11](https://github.com/Ralim/ts100/issues/11) that upgrading worked on their Mac as per normal:
> I just wanted to say that I was able to update the firmware on my ts100 from the stock version to 1.08 found in this repository using my Mac. I simply followed the same steps however through Finder. I have a MacBook Pro (13-inch, Mid 2012) running Sierra 10.12.4 (16E195).
# Linux
## Linux
While in the past there were reports of unreliable upgrades, the consensus in [issue 11](https://github.com/Ralim/ts100/issues/11) is that things work mostly as expected in Linux.
@@ -86,68 +86,111 @@ rmdir /tmp/mntdfu
Device will reboot and automount will rerun if not disabled.
Check the extension of your firmware, it should be `.RDY` now.
## Pinecil (Pine64)
The MCU used in the Pinecil supports usb-dfu.
# Pinecil (Pine64)
There is the nice gui [Pinecil Firmware Updater](https://github.com/pine64/pinecil-firmware-updater/releases). In the event that this tool is unavailable or otherwise does not meet your needs, the below process may be used to update the firmware.
- The MCU used in the Pinecil supports usb-dfu. Reference [Pinecil Wiki](https://wiki.pine64.org/wiki/Pinecil).
- Recommended: the [Pine64 Updater](https://github.com/pine64/pinecil-firmware-updater/releases), is an easy to use GUI app. It is fast, and works in several types of OS, i.e. Windows/Mac, and will automatically fetch the newest stable version of IronOS from Github.
- If you have issues using the Pine64 Updater or your install fails, please look at some of the troubleshooting tips below. If that does not work, then join the Pine64 Pinecil channel. There are volunteer community helpers in Discord/Telegram/Matrix. Discord has a bridge bot connection to Telegram and Matrix so that all pine volunteers/members can see the issues and advice for Pinecil and related items or get tips on which Power supply to purchase.
- One advantage of Pinecil is that you can not permanently damage it doing a firmware update (because DFU is in ROM); an update could render Pinecil temporarily inoperable if you flash an invalid firmware. Never fear, simply re-flashing with a working firmware copy will fix everything.
- If your OS is not currently supported by the [Updater](https://github.com/pine64/pinecil-firmware-updater/releases) or it does not meet your needs, the below manual method may be used. It requires connectting your Pinecil to a computer using a USB cable. Generally all usb controllers work, but some hubs have issues so it is preferred to avoid USB hubs for updates.
To enter DFU mode, hold the button at the back of the iron while connecting to usb over usb-c.
Generally all usb controllers work, but some hubs have issues so avoiding hubs may be best.
## Linux and Mac
Once the device is connected while holding the button, the screen will stay **off**.
### Steps
This is normal, and then you can use the appropriate tool to load the `.hex` or `.bin` file as per your OS.
⛔ Do not use the DC power jack while updating firmware or you may destroy your PC. ⛔
You can also refer to the Pine64 [Wiki](https://wiki.pine64.org/wiki/Pinecil).
### Linux and Mac
Using `dfu-util` you can flash the firmware using a command line as such:
1. Download and extract the firmware package from Github [IronOS Releases](https://github.com/Ralim/IronOS/releases).
2. Highly recommend updating `dfu-util` to the newest version.
3. Enter DFU mode: press and hold (-) button at the back of the iron (do not release).
4. Connect USB to PC, and USB-C to back of Pinecil, keep holding (-) button down.
5. The screen will stay **black/off** to indicate the Pinecil is in DFU mode. This is normal.
6. Once USB cable is connected at two ends, wait 10 seconds more, then release the (-) button.
7. Using `dfu-util` you can flash the firmware using a command line like this:
```
dfu-util -D Pinecil_EN.dfu
```
If you get a message stating that `More than one DFU capable USB device found!` when running the above command you probably have an old version of `dfu-util` installed. Might be worth updating. You can still install on the old version, but you will have to specify which DFU interface to flash to. Running the command `dfu-util -l` will show you if there are several DFU devices detected. Example:
Choose the file name from the folder with the appropriate 2-letter country code for your chosen language (i.e, EN = English).
#### Troubleshooting:
- If you get a message stating that `More than one DFU capable USB device found!` when running the above command you probably have an old version of `dfu-util` installed. Might be worth updating. You can still install on the old version, but you will have to specify which DFU interface to flash to. Running the command `dfu-util -l` will show you if there are several DFU devices detected. Example:
```
Found DFU: [28e9:0189] ver=0100, devnum=48, cfg=1, intf=0, path="1-1", alt=1, name="@Option Bytes /0x1FFFF800/01*016Be", serial="??"
Found DFU: [28e9:0189] ver=0100, devnum=48, cfg=1, intf=0, path="1-1", alt=0, name="@Internal Flash /0x08000000/128*001Kg", serial="??"
```
In this example we see that more than one part of the Pinecil is detected as a DFU interface and we need to specify which one we want to flash to. We want to the `Internal Flash` so in this case we can use `alt=0` to identify which interface to target. The command would then look like this:
In this example we see that more than one part of the Pinecil is detected as a DFU interface and we need to specify which one we want to flash to. We want the `Internal Flash` so in this case we can use `alt=0` to identify which interface to target. The command would then look like this:
```
dfu-util -D Pinecil_EN.dfu -a 0
```
Note that if you are using an older release of `dfu-util` and you do not see `alt=0, name="@Internal Flash /0x08000000/128*001Kg"` when running `dfu-util -l` you likely will not be able to update without updating `dfu-util`.
- Note: if you are using an older release of `dfu-util` and you do not see `alt=0, name="@Internal Flash /0x08000000/128*001Kg"` when running `dfu-util -l` you likely will not be able to update without first updating `dfu-util`.
- If your update is crashing using USB2 or USB3 ports, make sure you are connected directly and not using a USB hub and use shorter cables.
- Switch to a different PC/Laptop and use different ports. If your PC supports it, USB-C ports are recommended.
- Also try to hold down the (-) button for the entire firmware update, do not release until near the end.
### Windows
For Windows there are two options, you can use dfu-util via command line as shown above.
## Windows
If you are uncomfortable with the command line, the easiest tool to use is the vendors gui tool from [here](http://www.gd32mcu.com/en/download?kw=GD32+MCU+Dfu+Tool&lan=en).
Two Options for Windows
Should the link break, its called "GD32 MCU Dfu Tool" and can be grabbed from http://www.gd32mcu.com/en/download/.
### Option 1: use command line
You will also need the matching drivers from [here](http://www.gd32mcu.com/en/download?kw=GD32+Dfu+Drivers&lan=en) installed if you have not used gigadevice parts before.
### Steps
These are called "GD32 Dfu Drivers" if the link breaks.
⛔ Do not use the DC power jack while updating firmware or you may destroy your PC. ⛔
#### Steps:
1. Using command line `dfu-util` is similar to above for Linux / Mac.
2. Highly recommend updating `dfu-util` to the newest version.
3. Download and extract the firmware package from Github [IronOS Releases](https://github.com/Ralim/IronOS/releases).
4. Enter DFU mode: press and hold (-) button at the back of the iron (do not release).
5. Connect USB to PC, and USB-C to the back of Pinecil, keep holding (-) button down.
6. Screen will stay **black/off** to indicate the Pinecil is in DFU mode. This is normal.
7. After the USB cable is connected at both ends, wait ~10 seconds more, then release the (-) button.
8. Open PowerShell or Command window.
9. Change to the directory of the unzipped firmware files
10. Using `dfu-util,` flash the firmware using a command like this:
1. Download both the `GD32 MCU DFU TOOL` and the `Drivers`.
2. Install the drivers and open the DFU tool.
3. Ignore the prompt to update the tool.
4. Connect the Pinecil to a Windows PC via USB cable while holding down the minus button, **screen will stay blank** but you will hear the noise from Windows connecting to it.
5. At the top of the DFU tool, you should see `GD DFU DEVICE 1` appear.
6. Change the mode to `Download to device`.
7. Select the `open` button in that area of the window and load the `Pinecil_XX.hex` file from the downloaded release.
8. Tick the `verify after download` check box.
9. Click the OK button at the bottom of the window to run the process.
10. After it is complete either click `Leave DFU` or unplug the iron and power cycle it while _not_ holding down the buttons.
```
dfu-util -D Pinecil_EN.dfu
```
- If you have errors, see Troubleshooting [above](https://github.com/Ralim/IronOS/blob/7cb83850a8177eba5e7edbce4717b7aefd5938a0/Documentation/Flashing.md#troubleshooting).
You can also use dfu-util if you wish to set it up, but that is better documented by others when it comes to Windows.
### FAQ
### Option 2: use the gui tool from chip vendor
### Steps
⛔ Do not use the DC power jack while updating firmware or you may destroy your PC. ⛔
1. If you are uncomfortable with the command line, then this chip vendor supplied gui tool/drivers is an option.
2. Download and extract the firmware package from Github [IronOS Releases](https://github.com/Ralim/IronOS/releases).
3. Download both the `GD32 MCU DFU TOOL` and the `GD32 Dfu Drivers`.
- GD32 DFU Tool [here](http://www.gd32mcu.com/en/download?kw=GD32+MCU+Dfu+Tool&lan=en). If the link breaks, search for "GD32 MCU Dfu Tool" at this [link](http://www.gd32mcu.com/en/download/).
- GD32 DFU Drivers [here](http://www.gd32mcu.com/en/download?kw=GD32+Dfu+Drivers&lan=en). If the link breaks, search for "GD32 Dfu Drivers" at this [link](http://www.gd32mcu.com/en/download/).
- Check properties of both downloads, tick Unblock if needed, then Unzip
4. Install the drivers and the GD32 DFU tool (ignore prompts to update the tool).
5. Enter DFU mode: press and hold (-) button at the back of Pinecil (do not release).
6. Connect Pinecil to a PC via USB cable (do not release the (-) yet).
7. Screen will stay **black/off** to indicate the Pinecil is in DFU mode. This is normal.
8. You may hear a beep from Windows as it connects to Pinecil in DFU mode.
9. If you see windows notification that it `does not recognize Usb device`, then you didn't connect, repeat step 3-8.
10. Open the GD32 DFU Tool (ignore prompts to update tool).
11. At the top of the DFU tool, you should see `GD DFU DEVICE 1` appear if you successfully connected Pinecil.
12. If DFU Device box at top is blank, then Pinecil is not connected in DFU mode, repeat steps 3-11.
13. If it has been more than 10 seconds since you connected the USB cable, Release the (-) button. (don't use Upload from Device section)
14. Select `Download to device` > Open > Browse to folder dyou unziped in step 2.
15. Select the `hex` file for language. English is Pinecil_EN.hex , tick `Verify after download`.
16. Click `OK` at bottom. After a few minutes you will see 0-100%, Download successfully! Click `Leave DFU` at the top.
17. Disconnect pinecil cable from PC, plug it into a power supply.
18. Do not need to press any buttons, a new screen should appear.
19. To confirm upgrade, hold the minus (-) button down for a few seconds, it then shows new firmware version v2.xx.x....date
Note: pc/laptop can not power pinecil, it generally only gets 5V (non-PD) there to communicate for firmware updates and Pinecil will report `DC Low` if you try.
## FAQ
#### [Miniware] The file is showing up with the extension `.ERR`
@@ -173,7 +216,7 @@ If you are on Windows, it's often best to try another computer (friends, work, p
2. Try other USB ports. Often different USB controllers will interact with the units differently due to design quirks in the miniware design.
## [Miniware] Alternative bootloader
### [Miniware] Alternative bootloader
If you are an advanced user, and you have used `usb-dfu` tools before, or you would like to learn; there is an alternative bootloader for these irons.
This will **NOT** show up as a USB storage drive, but instead show up using a standard DFU protocol device. You can then use dfu tools or GUI's to upgrade the iron using the `.bin` files that are posted to the releases page.

View File

@@ -1,7 +1,7 @@
# Getting Started
Getting started with Iron OS on your Pinecil/TS80/TS80P/TS100.
If your device did not come with Iron OS already installed, or if you need to update to the latest version; please see the [Flashing Guide](/Documentation/Flashing.md).
Getting started with IronOS on your Pinecil/TS80/TS80P/TS100.
If your device did not come with IronOS already installed, or if you need to update to the latest version; please see the [Flashing Guide](/Documentation/Flashing.md). It is recommended to update to the newest stable release.
Once your Iron has been flashed, on first power on it _may_ warn you about the system settings being reset.
_Do not panic_; this is 100% completely normal. This is here to note to you that they have been reset to handle the internal structure changing.
@@ -18,7 +18,7 @@ By default this will show a screen similar to the one below:
Note that this may be drawn mirrored depending on the orientation of your screen.
The soldering iron symbol on the screen will appear near the tip. This is here to indicate that pressing the button closest to the front of the soldering iron will enter soldering mode.
The soldering iron symbol on the screen will appear near the tip. This is here to indicate that pressing the button closest to the front of the iron will enter soldering mode.
And naturally, the spanner like icon represents that pressing the button near the rear of the soldering iron will enter the settings menu.
@@ -40,40 +40,43 @@ If you press and hold the button near the rear of the iron it will take you into
## Soldering Mode
When you press the button to enter into the soldering mode, the iron will instantly start to heat up the tip.
When you press the button to enter the soldering mode, the iron will instantly start to heat up the tip.
The firmware defaults to 320C as the set point for the soldering mode, however on this screen you can enter into the adjustment screen by pressing either button.
Pressing and holding the button near the tip will enter **boost** mode. This allows temporarily overriding the set temperature to a higher (or lower) value. This can be useful as a way to force the tip to a higher temperature to drive more wattage into a large joint when the thermal connection is not ideal.
Pressing and holding the button near the tip will enter **Boost** mode. This allows a temporary override of the set temperature to a higher (or lower) value. This can be useful as a way to force the tip to a higher temperature to drive more wattage into a large joint when the thermal connection is not ideal.
Pressing and holding the rear button will exit soldering mode and land you back at the home screen. You can also do this by pressing both buttons at once and this will also work, this is a bit harder to do but is kept for compatibility with the Miniware firmware.
Pressing and holding **both** buttons at once will enter locked mode, which will prevent the buttons from doing anything. You can in the settings allow boost mode in locked mode optionally. This can be useful if you find yourself hitting the buttons and entering into the temperature adjustment screen by accident.
### Idle sleep
### Idle Sleep
If the iron detects a period of time without any significant movement, it will enter into a sleep mode. This is indicated with a graphic on the screen similar to ZZzz (or text in detailed mode).
If the iron detects a period of time without any significant movement, it will enter sleep mode. This is indicated with a screen graphic similar to ZZzz (or text in detailed mode).
In this mode, the temperature of the iron will automatically reduce down to a temperature just below the melting point of the solder. This helps reduce the rate of oxidation and damage to the iron tip.
In Sleep mode, the temperature of the iron automatically lowers to 150C (default), which is just below the melting point of the solder. This helps reduce rate of oxidation and damage to the iron tip. In general, when not using the iron, unplug it or let it sleep to increase the longevity of replaceable tips. The default sleep temperature can be customized.
Simply picking up or moving the iron will wake it back up into soldering mode. You can also press any button and this will also wake the iron up.
The Pinecil has a footprint (unpopulated) on the PCB for a hall effect sensor (Si7210). If you fit this then iron will additionally force sleep when it detects a strong magnetic field near the tip of the plastic body. This allows attaching a strong magnet near your iron holder to ensure it always enters sleep.
Optional Hall Effect Feature (Pinecil only):
Pinecil has an unpopulated footprint (U14) for a hall effect sensor (Si7210). Adding the sensor and placing a strong magnet on the holder stand will trigger Pinecil to sleep after it enters the stand, and ZZzz will appear on the screen. The magnet is positioned on the stand in proximity to the sensor which then activates one of 10 user defined settings (0=off, 1= lowest sensitivity, 9= highest sensitivity). Read the Hall Sensor document for details on [installation](/Documentation/HallSensor.md).
### Idle shutdown
If, after entering sleep mode the iron still does not see movement for a much longer time; it will shut down and return to the home screen.
### Idle Shutdown
If, after entering sleep mode, the iron still does not see movement for a much longer time (default = 10 min.); it will shut down and return to the home screen.
## Settings Menu
The settings menu is the most often evolving aspect of the firmware, so each option is not documented here. However, do not panic, as every menu option has a description so that you don't _need_ to come back here to figure them all out.
The settings menu is the most often evolving aspect of the firmware, so each option is not documented here. However, do not panic, as every menu option has an on-screen description so you don't _need_ to come back here to figure them all out.
To navigate the menu, the two buttons act separately.
The button that you pressed to enter the menu (rear) cycles down the options, and the other button (front) will change the current option.
The button that you pressed to enter the menu (rear) scrolls down the options, and the other button (front) will enter and change the current option.
To see a description of an option, just pause and wait and after a little bit, it will scroll across the screen.
To see a description of an option, just wait and after a little time, it will scroll across the screen.
The menu is comprised of a "main menu" of categories and then sub-items that allows you to adjust parameters.
The menu is comprised of a 'main menu' of categories and then sub-items that allows you to adjust parameters.
You can long hold buttons to change through options faster, and there is some acceleration when holding the buttons.
@@ -81,4 +84,4 @@ There is a small scrollbar that will be shown along the edge of the screen to in
Additionally, this scrollbar will blink rapidly when you are on the last item in a menu choice.
I highly recommend taking a few minutes to go through all of the options in the menu to get a feel for what you can change, almost every aspect of the internal system is adjustable to suit you.
I highly recommend taking a few minutes to go through all of the options in the menu to get a feel for what you can change, almost every aspect of the internal system is adjustable to suit your needs.

View File

@@ -0,0 +1,20 @@
# Hall Effect Sensor
## Sleep Mode Menu
In Sleep mode, the temperature of the iron automatically lowers to 150C (default), which is just below the melting point of the solder. This helps reduce rate of oxidation and damage to the iron tip. In general, when not using the iron, unplug it or let it sleep to increase the longevity of replaceable tips. The default sleep temperature can be customized.
Simply moving the iron will wake it back up into soldering mode. You can also press any button and this will also wake-up the iron.
### Optional Hall Effect Feature (Pinecil only):
Inside the Sleep Menu is an additional type of sleep setting. Pinecil has an unpopulated footprint (U14) for a hall effect sensor (Si7210). It is possible with the hall sensor to trigger Pinecil to go to sleep after it enters the stand, and ZZzz will appear on the screen. After installing the hall sensor, a magnet is positioned on the stand close enough to the sensor to activate one of ten user selectable settings.
- 0 = off, 1 = 1000, 2 = 750, 3 = 500, 4 = 250, 5 = 150, 6 = 100, 7 = 75, 8 = 50, 9 = 25 (9 has the highest sensitivity to magnets)
- Setting of 1 might be used if you solder on PCBs with magnets and do not wish Pinecil to auto-sleep constantly. And a very strong/large magnet would be required on the stand to activate the sensor sleep mode.
- Setting of 9 would be useful if you only had a small magnet and are not concerned about Pinecil falsely triggering sleep mode near magnetized items/tools.
- Neodymium magnets are recommended. If using small magnets, 2-3 may be required, but too many can also be detrimental.
- Actively watch the hall number change (in [debug menu](/Documentation/DebugMenu.md)) while you slowly move the magnet around to seek the best locations & whether you have too many or too few magnets. Positioning the magnet where you have the highest hall number will ensure consistent sleep mode when you place the iron in the stand. This requires some experimenting.
- Sensor is physically located near the copper contacts for the tip at the front of the handle. Reference [Schematics U14](https://files.pine64.org/doc/Pinecil/Pinecil_schematic_v1.0a_20201120.pdf).
- Positioning/type/quantity of magnets is important for best results. Sometimes [too many magnets](https://www.youtube.com/shorts/afkqKwCX00I) breaks the effect by distorting the magnetic field.
- Orientation of North and South faces of magnets is important to increase reaction of the hall sensor [SI7210-B-00-IV](https://www.silabs.com/documents/public/application-notes/an1018-si72xx-sensors.pdf).

View File

@@ -28,10 +28,10 @@ You perform this the same way as if you were flashing a new firmware, and all of
### Pinecil
For the Pinecil, we require to flash the logo using dfu-util instead.
To flash the logo, use the following steps:
For Pinecil, we require using dfu-util instead to flash the logo art (Pinecil does not use hex).
To flash the logo, use the following steps to convert the PNG image into a .dfu file and then install the .dfu file.
- `python3 img2ts100.py input.png logo.dfu`
- `dfu-util -D logo.dfu`
The converter will create a DFU instead of a HEX file if the .dfu extension is used.
The converter will create a DFU instead of a HEX file if the .dfu extension is used.