Merge pull request #77 from Thinkersbluff/extui

Uploads Release Candidate 61F_RC_290422_v1 to main extui

Author: Thinkersbluff

How-To_information.MD

@@ -0,0 +1,141 @@
+**CAUTION: THIS FILE IS OUT OF DATE.  IT IS HERE TO PRESERVE KEY USEFUL INFO UNTIL THE REPLACEMENT DOCUMENTATION (CURRENTLY IN WIP) IS READY TO POST.** - Thinkersbluff.
+
+### Translations / localization
+
+Internationalization support in DGUS DWIN is very cumbersome. The background images of each page has the text hardcoded. To translate and have it first-class, you would need to duplicate all the bmps, give it a separate ID, and maintain that mapping in firmware as well or make every label an icon, which is a lot of work. The development team has no capacity to maintain localizations.
+
+If you like to translate the user interface to your own language, you must fork this repository and maintain your own version of the touch screen firmware.
+
+The complete workflow would look like this:
+
+1. Fork this repository.
+2. Work on the extui branch (this is the branch for all work going forward)
+3. In your fork, follow [the steps in the images section of this file](#images--screen-images-sources) to change the current bitmaps and translate them. There are XCF files available as the source of these bitmaps, usable in Gimp, to make life easier but you can do what you want.
+4. When we change something, it is up to you to replicate those screen changes. Therefore I recommend only to update the screen backgrounds and don't use the DWIN editor for anything other than for the purpose of generating the ICL file.
+5. Translated touch screen builds are up to you to provide which would then need to be made from the same moment as we are releasing builds.
+
+Good luck, and if you maintain your own translated firmware, please let us know!
+
+## Documentation for development
+
+You need [the DGUS v8.2.1.14.x software](https://github.com/CR6Community/CR-6-touchscreen/releases/download/v2.0.8.1-cr6-community-release-6.1/DGUS_Tool_V8.2.1.14.7z) for editing the touch screen.
+
+You can open the .dgus project file in the [`src\DWIN`](src\DWIN) folder:
+
+![DGUS II interface](https://github.com/Thinkersbluff/CR-6-touchscreen_Thinkersbluff_Fork/blob/extui/doc/dgus2util.png)
+
+### Build firmware archive
+
+To build a firmware archive for distribution, use the `build.cmd` script. It will do a sanity check and then zip the files to the `build` folder.
+
+For development you can run the build script as follows: 
+
+```pwsh
+.\build -Deploy Q:
+```
+
+Where Q: is the path of your flash drive with the SD card.
+
+You need to have Powershell Core installed (pwsh).
+
+### Images / screen images sources
+
+You can find the source files where the screen bitmaps are generated from in the [`src\images_src`](src\images_src) folder.
+
+To update the BMP of a screen put the **generated BMP file you made with your image editor** in the [`src\DWIN\DWIN_SOURCE`](src\DWIN\DWIN_SOURCE) folder. 
+
+#### Updating the touch screen firmware files
+
+It will be picked up automatically by the build process of DWIN when saving or generating the project. However, the ICL file is what actually gets flashed. This is essentially a dictionary of concatenated compressed JFIF files.
+
+Next, re-generate the `23_Screen.icl` ICL file are follows:
+
+![Update ICL file](doc/update-screen-icl.gif)
+
+Things worthy of note:
+
+- Quality is set to 100%, followed by pressing the "Set all" button to apply it to each import file.
+- The `DWIN_SOURCE` is used as a source for generating the ICL.
+- The ICL is saved twice: once in the `DWIN_SOURCE` folder, once in the `DWIN_SET` folder.
+
+As you can note, you update it in both `DWIN_SET` and `DWIN_SOURCE`. The first is what goes to the touch screen, the latter is what the DWIN editor uses (apparently).
+
+For icon ICL generation the process is the same, except that you pick the icons from a subdirectory of `DWIN_SOURCE`.
+
+### Flash space
+
+DWIN uses a specific set-up of the flash space as described in the manual - as shown below.
+
+![DWIN flash space](doc/flash-space.png)
+
+Essentially what it boils down to:
+
+- The flash space is divided into 256KB sectors
+- The number prefix on the ICL/HZK/BIN file name is the sector number where the file is flashed
+- A sector can only contain a single file
+- A file can span over multiple sectors, and if a file needs 1½ sectors for instance, it will allocate 2 sectors.
+- There is no protection against sector overwriting: if you have files overlap sectors, DWIN will happily flash the next file over the previous file
+
+So with the above in mind one must take care to make sure files do not overlap. When you flash everything to the touch screen you must ensure you've deleted the old (renumbered) ICL files from your SD card, otherwise weird things will happen. Background may go missing, etc.
+
+During build a script will run to make sure no sectors have been overallocated. You can also run this script manually.
+
+![DWIN sector allocation check script](doc/sector-allocation-check.png)
+
+### How buttons are handled with code
+
+In the currently - cleaned up - source code of the touch screen handling in Marlin, the events of the touch screen are handled as described below. This may change in the future. This picture says it all:
+
+![DWIN button-code correlation](doc/button_type.png)
+
+For buttons:
+
+- Virtual Pointers for buttons are defined in `extui/lib/dgus_creality/DGUSDisplayDef.h`
+- In `extui/lib/dgus_creality/DGUSDisplayDef.cpp` in the `ListOfVP` the Virtual Pointer are connected to a callback handler
+- Because the Creality display used the same VP all over the place, sometimes in completely different functions or values (and this is quite some work to clean up!), these "legacy" VPs are delegated to `DGUSCrealityDisplay_HandleReturnKeyEvent`
+- For legacy VPs handlers are defined per page in `extui/lib/dgus_creality/PageHandlers.cpp`
+    - The "Key Data" is used to distinguish between the actual key pressed and passed to these functions as `buttonValue`
+
+For dynamic updatable values:
+
+- Dynamic updatable values are Virtual Pointers with a value that is pushed from the display when it is changed, and pushed to the display during the Marlin `idle` loop
+- The Virtual Pointers are defined in `extui/lib/dgus_creality/DGUSDisplayDef.h`
+- Per dynamically updated virtual pointer there is in `extui/lib/dgus_creality/DGUSDisplayDef.cpp`:
+    - A registration in `ListOfVP`, with:
+        - The VP ID
+        - A pointer to the memory location to read the value from in Marlin (can be `nullptr`)
+        - A callback that is triggered when the VP changed in the display and is pushed to firmware
+        - A callback that is triggered to format the VP for transfer to the display. This is because strings need to be sent differently than floats, or if your VP does not point to a direct value in memory.
+    - A mention in the specific `VPList` for the current page as referenced in `VPMap`. This is to optimize that we don't update VPs that are not displayed anyway.
+- Some values like the M117 text are transient and are pushed directly to the display, but are still present in the `ListOfVP`
+
+#### Previous version of the code
+
+If you like to see how the touch screen code is handled in the Creality firmware and the original Community Firmware release 3 and lower, please check the [cf3-legacy](https://github.com/CR6Community/CR-6-touchscreen/tree/cf-3-legacy) branch. This branch is no longer maintained and only exists for historical purposes.
+
+### Touch screen configuration
+
+The touch screen configuration file "T5LCFG_272480.CFG" has its specification describer in [T5L_DGUSII Application Development Guide20200902.pdf](./doc/vendor/T5L_DGUSII%20Application%20Development%20Guide20200902.pdf) chapter 4. You can use an editor like HxD to explore and edit it (with caution!). The DWIN editor also has a way to edit this file. Many parameters can also be set at runtime.
+
+### Fonts
+
+Font's are currently configured like below:
+
+![Font Settings](doc/font-settings.png)
+
+In the same folder where you have the DWIN tool unpacked a `0_DWIN_ASC.HZK` file is placed. You need to copy that to the DWIN_SET folder, and can flash it directly.
+The kerning of the current font is not ideal (especially using numbers that are small, like "1"), so perhaps we should look for a replacement.
+
+### Other documentation
+
+Vendor documentation is mirrored to the [doc/vendor](doc/vendor) folder.
+
+In addition, [this is a nice resource](https://github.com/rubienr/MarlinDgusResources/tree/creality-ender-5-plus/projects).
+
+## Credits
+
+[The core CR-6 Community firmware dev team](https://github.com/CR6Community/Marlin#credits)
+
+Icons from [Font Awesome](https://fontawesome.com/) and [Remix Icon](https://remixicon.com/).
+
+Font from [Google Fonts](https://fonts.google.com/specimen/B612) and customized with [FontForge](https://fontforge.org/).

README.md

@@ -32,7 +32,7 @@ If you wish to contribute to the project, please provide your inputs by raising
 
 ## Credits
 
-[InsanityAutomation](https://github.com/InsanityAutomation/Marlin/tree/CrealityDwin2.0_Bleeding) initiated and leads this project. It is upon his work that Thinkersbluff is building.
+[InsanityAutomation](https://github.com/InsanityAutomation/Marlin/tree/CrealityDwin2.0_Bleeding) initiated the refactoring project. It is upon his work that Thinkersbluff has built this Release.
 
 [The core CR-6 Community firmware dev team](https://github.com/CR6Community/Marlin#credits) did the heavy-lifting that resulted in the CF6.1 baseline.
 

doc/build/Release Candidate_29April_2022/61F_RC_290422_v1.zip

@@ -0,0 +1,34 @@
+# NOTE: These kernel files are not required, unless you are having problems resulting from having inadvertently overwritten the DGUS2 kernel for which your display was last calibrated.
+
+## STEP1 - BEFORE ACTING ON ANY OF THE FOLLOWING RECOMMENDATIONS:
+1. Create an EMPTY folder at the root directory of an EMPTY micro SD card.
+2. Ensure that your printer power is OFF
+3. Place that SD card in your display and cycle power ON
+4. The top line of the display will report which version of DGUS2 is currently flashed .  
+4. Make note of which DGUS version is currently flashed to your display hardware (see top line on display)
+5. Take care to follow the applicable instructions below.
+
+## IF your display is currently running v3.5 and it should be running v4.5:
+STEP 2: 
+1. Copy T5L_UI_DGUS2_V45_20220105.BIN to the DWIN_SET folder created at step 1 above, and flash that to your display.
+2. Verify that the top line on the blue flash screen is now overwritten in red confirming that DGUS2 v4.5 is flashed
+3. Optionally repeat step 1 with an empty DWIN_SET folder, to confirm v4.5 is now the DGUS2 OS
+
+# OR
+
+## IF your display is currently running v4.5 and it should be running v3.5:
+STEP 2: 
+1. Copy T5L_UI_DGUS2_V35_20200730.BIN to the DWIN_SET folder created at step 1 above, and flash that to your display.
+2. Verify that the top line on the blue flash screen is now overwritten in red confirming that DGUS2 v3.5 is flashed
+3. Optionally repeat step 1 with an empty DWIN_SET folder, to confirm v3.5 is now the DGUS2 OS
+
+
+# Here is how to interpret what you see:
+
+The top line of the blue boot screen always identifies the current DGUS2 OS in white text.
+
+If the DWIN_SET folder being flashed contains a DGUS kernel BIN file, the top line is overwritten in RED text, reporting the version that has been flashed.
+
+If the two lines are different, it may be difficult to read either line.
+
+If the two lines are identical, the current DWIN_SET folder has reflashed the same kernel to the display.

doc/build/Release Candidate_29April_2022/DGUS2 kernel upgrade files/README.md

@@ -0,0 +1,5 @@
+The following issues have been observed but not resolved, at this DRAFT release:
+
+1. The ABLprocess no longer uses the contents of 35_Autolevel.icl to animate the collection & display of the mesh data.  To enable old eyes to read the mesh, the normally white background of the initial screen has been changed to black.  As a result, when the process first initializes all of the values to 0.000 in white, those zeroes are now visible to the user, until replaced by the probing process. This will not look familiar to past users of 6.1, but should not be a problem for new users.
+
+IF you find any other issues, please message @Thinkersbluff with the key info.  TIA!

doc/build/Release Candidate_29April_2022/DGUS2 kernel upgrade files/T5L_UI_DGUS2_V35_20200730.BIN

@@ -0,0 +1,101 @@
+# Release#: 61F_RC_290422_v1
+
+## NOTE: As of this release, the release# is branded in orange on the load screen and on the Setup->INFO screen. If you do not see this release number on your system, you have not flashed this version of the touchscreen firmware. 
+
+# Introduction
+
+## If you are already running CF6.1-Final successfully on your printer
+
+There is no reason to flash this re-factored firmware. You can ignore this release.
+
+## Background
+
+The CF6.1 touch screen firmware was designed and distributed to run on the DGUS2 v3.5 operating system.
+
+Creality has now begun delivering the CR6 printers running a more recent version of DGUS2 (v4.5, at the time of this release.) 
+
+DGUS2 v4.5+ requires a different calibration of the display screen to run than did v3.5.
+
+Following the CF6.1 installation instructions to flash v3.5 with CF6.1 to these newer printers will cause the v4.5 screen calibration to be invalid. That results in the touchscreen becoming non-responsive to CF6.1. Reverting to Creality stock also then fails, until the DGUS2 v4.5 kernel is restored to the display.
+
+This re-factored version of the firmware will operate correctly on all CR6 printers flashed with DGUS2 OS version 2.0 or higher, as long as:
+1. The motherboard has also been flashed with the correct configuration of CF6.1-Final firmware
+
+2. The display hardware has already been calibrated to operate with the version of DGUS2 (2.0 or higher) that is installed on the display.
+
+
+
+# Recommendations for using this firmware
+## _PLEASE read all of these recommendations, before following any of them._
+
+**NOTE: As always, flashing this firmware to your system is done entirely at your own risk. The CR-6 Community firmware developers take no responsibility for any consequences of flashing this firmware to your system.**
+
+
+
+**STEP1 - BEFORE ACTING ON ANY OF THE FOLLOWING RECOMMENDATIONS:**
+1. Create an EMPTY folder at the root directory of an EMPTY micro SD card.
+2. Ensure that your printer power is OFF
+3. Place that SD card in your display and cycle power ON
+4. The top line of the display will report which version of DGUS2 is currently flashed .  
+4. Make note of which DGUS version is currently flashed to your display hardware (see top line on display)
+5. Take care to follow the applicable instructions below.
+
+
+### If you are currently running Creality stock firmware on your system, and your display is currently running DGUS2 v4.5+
+
+Flash this touchscreen firmware INSTEAD of the CF6.1-Final touchscreen firmware.  
+
+1. Ignore the Touchscreen firmware folder in the CF6.1-Final release zip file.
+
+2. INSTEAD, copy the DWIN_SET folder and contents from this release to the micro-SD card you use to flash the display 
+
+3. DO NOT copy ANY DGUS2 kernel upgrade files to the DWIN_SET folder before flashing it to your display.
+
+### If you are currently running Creality stock firmware on your system, and your display is currently running any version of DGUS2 between v2.0 and v4.0 (e.g. v3.5)
+
+EITHER: Go ahead and flash the CF6.1 TouchScreen Firmware to your system, following the CF6.1 Touchscreen Firmware README instructions precisely
+
+OR:
+
+Do exactly the same thing as recommended above for the v4.5 users:
+1. Ignore the Touchscreen firmware folder in the CF6.1-Final release zip file.
+
+2. INSTEAD, copy the DWIN_SET folder and contents from this release to the micro-SD card you use to flash the display 
+
+3. DO NOT copy ANY DGUS2 kernel upgrade files to the DWIN_SET folder before flashing it to your display.
+
+### If you already flashed the CF6.1-Final touchscreen firmware to your display hardware, your display is now running DGUS2 v3.5, and your display is non-responsive
+
+You can flash this re-factored version of the CF6.1 UI to your display and restore the display to running DGUS2 to v4.5, as follows:
+
+  1. Delete the DWIN_SET folder from the SD card with which you previously flashed your display. (Make sure you keep a copy, just in case!) OR prepare a new blank micro SD card.
+  2. Copy the new DWIN_SET folder distributed in this release to that SD card  
+  3. Copy T5L_UI_DGUS2_V45_20220105.BIN from the DGUS2 kernel upgrade files folder into the new DWIN_SET folder on that card
+  4. Re-flash your display with the updated card
+  5. Verify that the top line of the display shows the DGUS2 v4.5 OS was flashed as part of the process (it will be written in red text over the top of white text that said v3.5)
+  6. Power off the printer
+  7. Remove the SD card from the display and power it back up
+  8. The CF6.1 interface should now work correctly
+  9. Repeating the empty DWIN_SET folder trick described as STEP 1 above will allow you to confirm with confidence that DGUS2 v4.5 is now flashed to the display
+
+## Instructions for Reverting a Display to the Creality Stock Firmware
+
+### If you flashed the CF6.1 firmware and the DGUS v3.5 kernel upgrade files to a DWIN display that was previously configured to run on DGUS2 v4.5 and just want to revert to stock, rather than flashing this firmware release
+
+1. Copy the T5L_UI_DGUS2_V45_20220105.BIN kernel upgrade file into the Creality DWIN_SET folder. 
+2. Re-flash that DWIN_SET to your display. 
+3. Re-flash the stock Creality firmware to the motherboard
+
+The printer will now have been reverted to the Creality stock firmware.
+
+### If you successfully flashed CF6.1 or this release to a DWIN display without flashing any DGUS kernel upgrade files to that display, but now wish to revert to the Creality stock firmware
+
+Flash the stock Creality firmware back to the motherboard and the display, per Creality's instructions.
+
+## Instructions for reverting from this re-factored version BACK to the CF6.1-Final TouchScreen Firmware on a display running DGUS2 v3.5 
+
+Follow the flashing instructions in the CF6.1-Final Touchscreen firmware README file.
+
+
+
+