Merge pull request #1653 from Ralim/dev

Release 2.21

.github/workflows/docs.yml

@@ -28,8 +28,13 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-python@v4
 
-      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files
+
+      - run: |
+          pip install --upgrade pip &&
+          pip install mkdocs mkdocs-gen-files pymdown-extensions \
+              mkdocs-git-revision-date-plugin mkdocs-autolinks-plugin \
+              mkdocs-awesome-pages-plugin 
       - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
 
       - name: Publish docs
-        run: mkdocs gh-deploy
+        run: mkdocs gh-deploy

.github/workflows/push.yml

@@ -140,14 +140,14 @@ jobs:
 
     steps:
       - name: deps
-        run: apk add --no-cache python3 py3-pip make git
+        run: apk add --no-cache python3 py3-pip make git black
 
       - uses: actions/checkout@v3
         with:
           submodules: true
 
       - name: install black
-        run: python3 -m pip install bdflib black flake8
+        run: python3 -m pip install bdflib flake8
 
       - name: Check formatting with clang-format
         run: cd source && make clean && make check-style

Dockerfile

@@ -8,12 +8,20 @@ WORKDIR /build
 # Misc -> findutils make git
 # musl-dev is required for the multi lang firmwares
 # clang is required for clang-format (for dev)
+ARG APK_COMPS="gcc-riscv-none-elf gcc-arm-none-eabi newlib-riscv-none-elf \
+               newlib-arm-none-eabi"
+ARG APK_PYTHON="python3 py3-pip black"
+ARG APK_MISC="findutils make git"
+ARG APK_DEV="musl-dev clang bash clang-extra-tools"
 
-RUN apk add --no-cache gcc-riscv-none-elf gcc-arm-none-eabi newlib-riscv-none-elf newlib-arm-none-eabi findutils python3 py3-pip make git musl-dev clang bash clang-extra-tools
+# PIP packages
+ARG PIP_PKGS='bdflib'
+
+RUN apk add --no-cache ${APK_COMPS} ${APK_PYTHON} ${APK_MISC} ${APK_DEV}
 
 # Install Python3 packages
 
-RUN python3 -m pip install bdflib black
+RUN python3 -m pip install ${PIP_PKGS}
 # Git trust
 RUN git config --global --add safe.directory /build/source
 

Documentation/Development.md

@@ -104,3 +104,40 @@ If you _need_ an IDE I have used [Nuclei's IDE](https://nucleisys.com/download.p
 Follow the same idea as the STM Cube IDE notes above.
 
 ## Building Pinecil V2
+
+To build the Pinecil V2 firmware, you can use a Docker container that provides a consistent development environment across different operating systems, including Windows with WSL2. Here's how to do it:
+
+### Prerequisites
+
+Docker Desktop: Install the latest version of Docker Desktop for your operating system from the official website.
+
+On Windows follow the instructions on the official documentation to install 'Windows Subsystem for Linux' (WSL2).
+
+### Building Steps
+
+1. Clone the repository, initialize and update submodules:
+
+    ```sh
+    git clone --recurse-submodules https://github.com/Ralim/IronOS.git
+    ```
+
+2. Start the Docker container with the development environment:
+
+    ```sh
+    cd IronOS
+    ./start_dev.sh
+    ```
+
+    This script will build a Docker image and run a container with the necessary tools to build the firmware.
+
+3. Build the firmware for Pinecil V2:
+
+    ```sh
+    cd source/source
+    ./build.sh -l EN -m Pinecilv2
+    ```
+
+    This command will compile the firmware with English language support for Pinecil V2 board.
+
+4. Find the firmware artifacts:
+    After the build completes successfully, you can find the firmware artifacts in the `source/Hexfile` directory.

Documentation/Flashing/Pinecil V1.md

@@ -12,8 +12,8 @@ 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.
-Select the appropriate file type for your unit, in general Miniware devices need `.hex` and Pinecil needs `.dfu`.
-Flash according to details below
+Select the appropriate file type for your unit, in general Miniware devices need `.hex`, Pinecil V1 needs `.dfu`, and Pinecil V2 needs `.bin`.
+Flash according to details below.
 
 ### Bleeding edge / latest
 
@@ -26,13 +26,16 @@ Then this works the same as a production release (use the correct file).
 
 # Pinecil V1
 
-- The MCU used in Pinecil supports usb-dfu. Reference [Pinecil Wiki](https://wiki.pine64.org/wiki/Pinecil).
-- Recommended Updater: 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. It will automatically fetch the newest stable version of IronOS from GitHub.
+- The MCU used in Pinecil supports usb-dfu. Reference [Pinecil Wiki](https://wiki.pine64.org/wiki/Pinecil) for hardware and firmware instructions.
+- Recommended Updater for Windows/MacOS: [Pine64 Updater](https://github.com/pine64/pine64_updater) is an easy-to-use GUI app. It is fast and automatically fetches the newest stable version of IronOS from GitHub. It can also be used to load custom boot logo art.
+- Recommended Updater for Linux/MacOS: [PineFlash](https://github.com/Spagett1/PineFlash) is an easy-to-use GUI app. It is fast and automatically fetches the newest stable version of IronOS from Github. It can also be used to load custom boot logo art.
+
 - Troubleshooting: if you have issues using the Pine64 Updater or your install fails, please go to troubleshooting tips below.
-- Community chat: if troubleshooting doesn't work, then join the Pine64 > Pinecil channel. There are knowledgeable members in Discord/Telegram/Matrix. Discord has a bridge bot connection to Telegram and Matrix so that all pine volunteers/members can see advice for Pinecil and related items or just get tips on which Power supply to purchase.
+- The [Pinecil Wiki](https://wiki.pine64.org/wiki/Pinecil) is a great resource for all things Pinecil.
+- Community chat: if troubleshooting doesn't work, then join the Pine64 > Pinecil channel [here](https://wiki.pine64.org/wiki/Pinecil#Live_Community_Chat). There are knowledgeable members in Discord/Telegram/Matrix. Discord has a bridge bot connection to Telegram and Matrix so that all pine64 volunteers/members can see advice for Pinecil and related items or just get tips on which power supply to purchase.
 - One advantage of Pinecil is that you cannot 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. But no worries, simply re-flashing with a working firmware copy will fix everything.
 - USB-C cable is required to do an update. Generally, all USB controllers work, but some hubs have issues, so it is preferred to avoid USB hubs for updates.
-- Alternate Update Methods: 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, i.e., you want to install a beta version, the below manual methods may be used.
+- Alternate Update Methods: if your OS is not currently supported by the [Pine64 Updater](https://github.com/pine64/pine64_updater) or it does not meet your needs, i.e., you want to install a beta version, the below manual methods may be used.
 
 ## Linux and Mac
 

Documentation/Flashing/Pinecil V2.md

@@ -12,21 +12,25 @@ 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.
-Select the appropriate file type for your unit, in general Miniware devices need `.hex` and Pinecil needs `.dfu`.
-Flash according to details below
+Select the appropriate file type for your unit, in general Miniware devices need `.hex`, Pinecil V1 needs `.dfu`, and Pinecil V2 needs `.bin`.
+Flash according to details below.
 
 ### Bleeding edge / latest
 
-For the _latest_ code, you will need to download the zip file from the artifacts page on the build for what you want.
-Head to the [Actions](https://github.com/Ralim/IronOS/actions) page and then select the run for the appropriate branch you would like.
+For the _latest_ code, you need to download the zip file from the artifacts page for the build that you want.
+Head to the [Actions](https://github.com/Ralim/IronOS/actions) page and then select the run for the appropriate branch and beta you would like.
 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.
+Once you click on a run, scroll down to the "Artifacts" section and then click on your device model name to download a zip file.
 Then this works the same as a production release (use the correct file).
 
 # Pinecil V2
 
-- The MCU in V2 is Bouffalo BL706 and does _not_ use usb-dfu for flashing as the previous MCU did.
-- The current firmware (2.18) is very fresh and no upgrade is available/needed.
-- When an update is released for V2, then IronOS will also include an update method to follow.
+- The MCU in Pinecil V2 is Bouffalo BL706 and does _not_ use usb-dfu for flashing as the previous Pinecil V1 MCU did.
+- See the Pinecil Wiki page [here](https://wiki.pine64.org/wiki/Pinecil#Firmware_&_Updates) for instructions.
+- The V2 uses the [BLISP flasher](https://github.com/pine64/blisp) to upload the firmware to the MCU.
+- The [Pinecil Wiki](https://wiki.pine64.org/wiki/Pinecil) is a great resource for all things Pinecil.
+- Community chat: if there are issues updating, then join the Pine64 > Pinecil channel [here](https://wiki.pine64.org/wiki/Pinecil#Live_Community_Chat). There are knowledgeable members in Discord/Telegram/Matrix. Discord has a bridge bot connection to Telegram and Matrix so that all pine64 volunteers/members can see advice for Pinecil and related items or just get tips on which power supply to purchase.
+- One advantage of Pinecil is that you cannot permanently damage it doing a firmware update (because BIN is in ROM); an update could render Pinecil temporarily inoperable if you flash an invalid firmware. But no worries, simply re-flashing with a working firmware copy will fix everything.
+- USB-C cable is required to do an update. Generally, all USB controllers work, but some hubs have issues, so it is preferred to avoid USB hubs for updates.
 - Background on the [BL706 chipset](https://lupyuen.github.io/articles/bl706)

Documentation/GettingStarted.md

@@ -28,7 +28,7 @@ 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 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.
+And naturally, the slider controls icon (or spanner icon in older versions) represents that pressing the button near the rear of the soldering iron will enter the settings menu.
 
 In the settings, you can turn on a detailed idle screen instead. The buttons still function the same, however, the image will be swapped for a text telling you the current status of the iron with extra details.
 

Documentation/Menu.md

@@ -39,11 +39,13 @@ To calibrate your iron:
 7. Press both buttons at the same time to Save and Exit to the menu
 
 ### Calibrate Tip CJC
-This performs a Tip Cold Junction Calibration (CJC) ([see Temperature for details](https://ralim.github.io/IronOS/Temperature/)). This is normally not needed unless you have an issue with tip temperature or your tips are wearing out prematurely. Changing tip lengths does not necessarily mean a calibration is needed. Check first that your tips are not defective, and measured resistance is close to specifications (Pinecil/TS100 short tips 6.2 Ω, long tips 8 Ω, TS80(P) ~4.5 Ω).
+This calibrates the [Cold Junction Compensation](https://ralim.github.io/IronOS/Temperature/) *(CJC)* for the tip. This is normally not needed unless you have an issue with tip temperature or your tips are wearing out prematurely. Changing tip lengths does not necessarily mean a calibration is needed. Check first that your tips are not defective and measured resistance is close to specifications *[Pinecil / TS100 short tips **6.2 Ω**, long tips **8 Ω**, TS80/P ~**4.5 Ω**]*.
 
-What this is for: some tips have an offset on their readings which causes issues, i.e., the actual temperature of the tip is much higher than displayed. To calibrate this out, perform the following steps. 
+What this is for:<br>
+Some tips have an offset on their readings which causes issues, i.e. The actual temperature of the tip is much higher than displayed. Follow the steps below to calibrate this.
 
-Caution: if the method below is not followed, the iron could be worse than before calibration. If you need to repeat the method, first unplug and let the handle/PCB cool down to room temperature.
+Caution:<br>
+If the method below is not followed, the iron could be worse than before calibration. If you need to repeat the method, first unplug and let the handle/PCB cool down to room temperature.
 
 1. Connect power to your device.
 2. Go to **`Advanced Settings`** using (`-/B`) and press (`+/A`) to select it. Use (`-/B`) to scroll to **`Calibrate CJC at next boot`** and confirm with (`+/A`).
@@ -52,11 +54,11 @@ Caution: if the method below is not followed, the iron could be worse than befor
 4. Unplug you device.
 5. **Critical: Make sure a tip is attached & wait until the tip & handle are at room temperature.** (Wait a reasonable amount of time after having used the device.)
 6. Power the device and ideally keep it out of your hands (You know it might get warm.).
-7. The display shows **`....`** for a short time while the device measures and compares the tip and handle voltages.
-8. As a result the new *Offset value* is displayed. This value can later be viewed in the **`Debug menu`**.
+7. The display shows **`calibrating ....`** for a short time while the device measures and compares the tip and handle voltages.
+8. **`Calibration done!`** is displayed for 3 seconds. The new offset value can later be viewed in the **`Debug menu`**.
 9. Calibration is done and the device proceeds booting.
 
-Note: offsets are dependant on your tip, temperature sensor, and the MCU. It's the culmination of tolerances at rest. Typical values are 700-1000 range. This is only designed to be used at boot while cold (ambient room temperature), as temperatures drift apart as soon as power is connected. Doing this reading repeatedly could result in wide varience of the offset number and/or incorrect calibration.
+Note: offsets are dependant on your tip, temperature sensor, and the MCU. It's the culmination of tolerances at rest. Typical values are 700-1000 range. This is only designed to be used at boot while cold (ambient / room temperature), as temperatures drift apart as soon as power is connected. Doing this reading repeatedly could result in wide varience of the offset number and/or incorrect calibration.
 
 ### Boost mode
 

Documentation/Translation.md

@@ -1,6 +1,12 @@
 # Translation
-If you would like to contribute a translation, use the [Translation Editor](http://htmlpreview.github.io/?https://github.com/Ralim/ts100/blob/master/Translations/TranslationEditor.html).
 
-[Open a reference language file and optionally a target language file](https://github.com/Ralim/ts100/tree/master/Translations).
+At the present time the main way of performing translations is to open a PR to this repository.
+All translations are stored as `json` files in the repository. Currently there is ongoing work to look into a more user friendly method of editing translations than these but for now these are reliable.
 
 You can create a pull request with the new / updated json configuration file, and this will include this language into the new builds for the firmware.
+
+For testing you can build locally and test of course; but if you dont want to figure out the build environment; you can just open a PR and github will build the firmware for you using the _actions_ feature.
+
+This means that once you have a github account you can perform all of your edits inside Github should this be desired.
+
+Translations are _NOT_ accepted via issues/discussions or email.