Merge pull request #12 from mooinglemur/20231010-textupd

Suggested changes to instructions/readme text

README.md

@@ -3,15 +3,15 @@
 # Commander X16 Flashing Utility
 
 Contains the source code of the commander x16 update utility.
-This utility allows you to upgrade (or downgrade) your CX16 on-board SMC firmware and main ROM, and/or, to flash external ROMs etched on an ISA cardridge board.
+This utility allows you to upgrade (or downgrade) your CX16 on-board SMC firmware and main ROM, and/or, to flash external ROMs installed on a cartridge board.
 
-Please find below a short user manual.
+Please see below for a short user manual.
 
 ## Notice of caution
 
 Updating your on-board firmware requires you to carefully follow the instructions. There is a small risk that your on-board firmware may get damaged during the update process and may generate your CX16 unusable, resulting in a bricked CX16!
 
-Further steps to mitigate and recover from such situations are pending to be documented. However, please direct youself in such situations to the commander X16 [Discord]() or [Forum](https://www.commanderx16.com/forum)!
+Further steps to mitigate and recover from such situations are pending to be documented. However, please direct youself in such situations to the Commander X16 [Discord](https://discord.gg/nS2PqEC) or [Forum](https://www.commanderx16.com/forum)!
 
 # User Manual
 
@@ -20,11 +20,11 @@ Please consider this draft user manual as a first guide how to use the update to
 ## 0. What you need
 
 Depending on your configuration and the new release artefacts available from the CX16 community site,  
-specific hardware on your CX16 board will be upgraded. But in essence, the upgrade should be fairly straightforward and user friendly!
+specific hardware on your CX16 board will be updated. But in essence, the update should be fairly straightforward and user friendly!
 
 - Ensure you have a valid and working SDCARD that has sufficient free space and is formatted in FAT32.
 - You need a Commander X16 computer (the real thing).
-- You optionally can have an add-on ISA cardridge board, that is plugged in any of the 4 ISA slots. This ISA RA/ROM board can contain an extra 3.5 MB of RAM/ROM!
+- You optionally can have an add-on cartridge board, that is plugged in any of the 4 expansion slots. This RAM/ROM board can contain an extra 3.5 MB of RAM/ROM!
 
 On the Commander X16 main board, you have 3 important compontents that this utility can update:
 
@@ -39,7 +39,7 @@ The latest version of the program can be found on the [release page](https://git
 ## 2. Download the Commander X16 community firmware release files from the web site.
 
 Download the latest SMC.BIN and ROM.BIN file from the Commander X16 community web site.
-Any additional ROMs on the ISA expansion card to be flashed, require ROMn.BIN files to be added,  according your rom flashing strategy.  
+Any additional ROMs on the expansion card to be flashed, require ROMn.BIN files to be added,  according your rom flashing strategy.
 
 ### 2.1. Update your SMC and main ROM firmware on your CX16 board
 
@@ -54,33 +54,33 @@ Once you have the J1 jumper pins properly closed, the ROM on the main board of t
 
 Ensure that the J5 jumper pins on the Commander X16 main board are closed, to ensure that no issue occurs reading the contents of the SMC chipset. The update utility can flash the SMC with the J5 jumper pins open, but to ensure that no issue occurs, it is safer to have them also closed.
 
-### 2.2. Flash multiple ROMs on the external RAM/ROM ISA cardidge.
+### 2.2. Flash multiple ROMs on the external RAM/ROM board or cartridge.
 
-First for all clarity, find below a picture of such a ISA ROM expansion cardridge:
+First for all clarity, find below a picture of such a ROM expansion cartridge:
 
-![ROM-cardridge](https://user-images.githubusercontent.com/13690775/225110167-546596e6-998a-464f-b6a9-53fb598c19b4.jpg)
+![ROM-cartridge](https://user-images.githubusercontent.com/13690775/225110167-546596e6-998a-464f-b6a9-53fb598c19b4.jpg)
 
-On the ROM cardridge, 7 extra RAM/ROM chips can be placed for usage, and flashing. The cardridge is placed in one of the 4 CX16 extension slots, and provides an extra 3.5 MB of banked RAM/ROM to your CX16 between addresses $C000 and $FFFF, with zeropage $01 as the bank register. Each bank has $4000 bytes!
+On the ROM cartridge, 7 extra RAM/ROM chips can be placed for usage, and flashing. The cartridge is placed in one of the 4 CX16 extension slots, and provides an extra 3.5 MB of banked RAM/ROM to your CX16 between addresses $C000 and $FFFF, with zeropage $01 as the bank register. Each bank has $4000 bytes!
 
-Each ROM is addressing wise 512K separated from each other, and can be flashed with its own ROM[N].BIN file(s), where N must be a number between 1 and 7! For example, ROM1.BIN will flash ROM#1 on the cardridge. ROM5.BIN will flash ROM#5. ROM devices are to be placed and counted, from left to right!
+Each ROM is addressing wise 512K separated from each other, and can be flashed with its own ROM[N].BIN file(s), where N must be a number between 1 and 7! For example, ROM1.BIN will flash ROM#1 on the cartridge. ROM5.BIN will flash ROM#5. ROM devices are to be placed and counted, from left to right!
 
-To ensure that no harmful program can damage your ROMs, jumper pins J1 and J2 on the cardridge are to be remained open. However, in order to flash the ROMs, close the relevant jumper pins.
+To ensure that no harmful program can damage your ROMs, jumper pins J1 and J2 on the cartridge are to be remained open. However, in order to flash the ROMs, close the relevant jumper pins.
 
-Close the J1 jumper pins (at the left side of the ISA cardridge board) to remove the write-protection for ROM#1 till ROM#6. 
+Close the J1 jumper pins (at the left side of the cartridge board) to remove the write-protection for ROM#1 till ROM#6.
 
 ![ROM-DIP-J1](https://user-images.githubusercontent.com/13690775/225111120-56eeaca5-69a6-4812-a854-5cfc1246045a.jpg)
 
-Close the J2 jumper pins (at the right side of the ISA cardridge board) to remove the write-protection for ROM#7. 
+Close the J2 jumper pins (at the right side of the cartridge board) to remove the write-protection for ROM#7.
 
 ![ROM-DIP-J2](https://user-images.githubusercontent.com/13690775/225111150-c441812c-5331-46b1-805f-f769064507f7.jpg)
 
-Once you have the J1 and/or J2 jumper pins properly closed on the ISA cardridge board, the ROMs will be detected by the flashing program. If the jumper pins are open, the ROMs won't be recognized by the flashing program and your ROM[n].BIN file(s) will not be flashed!
+Once you have the J1 and/or J2 jumper pins properly closed on the cartridge board, the ROMs will be detected by the flashing program. If the jumper pins are open, the ROMs won't be recognized by the flashing program and your ROM[n].BIN file(s) will not be flashed!
 
 ## 3. Proceed with updating your Commander X16 firmware or ROMs.
 
 Once you've copied the CX16-UPDATE.PRG and the relevant SMC.BIN and ROM[N].BIN files onto the SDcard, you are ready to update your Commander X16!
 
-Place the SDcard in the foreseen VERA card slot, and again, verify that all indicated J1 and J5 jumper pins are closed properly on the Commander X16 main board and optionally on the ISA cardridge board.
+Place the SDcard in the VERA card slot, and again, verify that all indicated J1 and J5 jumper pins are closed properly on the Commander X16 main board and optionally on the cartridge board.
 
 Boot/Start your Commander X16 computer.
 
@@ -108,16 +108,16 @@ Below are all the possible components shown that this update utility supports. A
 
 ![into-1](https://github.com/FlightControl-User/x16-flash/blob/main/images/intro-1.jpg)
 
-Please read carefully the text at the bottom panel of the screen, and press SPACE to continue ...
+Please carefully read the text at the bottom panel of the screen, and press SPACE to continue ...
 
-A second screen appears, which indicates the color schema used to indicate the update status of each component on your Commander X16 main board and/or your ISA expansion cardridge board. Press SPACE to continue.
+A second screen appears, which indicates the color schema used to indicate the update status of each component on your Commander X16 main board and/or your expansion cartridge board. Press SPACE to continue.
 
 ![intro-2](https://github.com/FlightControl-User/x16-flash/blob/main/images/intro-2.jpg)
 
 
 ### 3.2. Component detection
 
-Next, the update utility detects which components are upgradable. The Commander X16 main board SMC, VERA and main ROM chip are detected, together with the remaining 7 ROM chips (the most right chip is ROM#7), which would be the right most chip on the ISA expansion cardridge.
+Next, the update utility detects which components are upgradable. The Commander X16 main board SMC, VERA and main ROM chip are detected, together with the remaining 7 ROM chips (the most right chip is ROM#7), which would be the right most chip on the expansion cartridge.
 
 Each component detected will be highlighted with a Detected status and a WHITE led. The capacity of each detected ROM is shown in KBytes. Other components that are not detected are highlighed with a None staus and a BLACK led. These ROMs won't be considered for flashing.
 
@@ -201,6 +201,6 @@ The identified ROMs for flashing will be flashed from the highest ROM# number to
 
 The reason why this sequence was chosen, is to ensure that the program has the ROM routines available for allowing the user to view the flashing results and press the keyboard to continue the process.
 
-Once the onboard ROM has been flashed, the program will automatically reset.
+Once the onboard ROM has been flashed, the program will automatically reset the computer.
 
 Please find in more details this sequence explained visually, with an explanation of the screens and the meaning of the symbols/colors.

src/cx16-display-text.h

@@ -9,27 +9,28 @@
  * 
  */
 
-const char display_intro_briefing_count = 14;
-const char* display_into_briefing_text[14] = {
-    "Welcome to the CX16 update tool! This program will update the",
-    "chipsets on your CX16 board and on your ROM expansion cardridge.",
-    "",
-    "Depending on the type of files placed on your SDCard,",
-    "different chipsets will be updated of the CX16:",
-    "- The mandatory SMC.BIN file updates the SMC firmware.",
-    "- The mandatory ROM.BIN file updates the main ROM.",
-    "- An optional VERA.BIN file updates your VERA firmware.",
-    "- Any optional ROMn.BIN file found on your SDCard ",
-    "  updates the relevant ROMs on your ROM expansion cardridge.",
-    "  Ensure your J1 jumpers are properly enabled on the CX16!",
-    "",
-    "Please read carefully the step by step instructions at ",
+const char display_intro_briefing_count = 15;
+const char* display_into_briefing_text[15] = {
+    "Welcome to the CX16 update tool! This program updates the",
+    "chipsets on your CX16 and ROM expansion boards.",
+    "",
+    "Depending on the files found on the SDCard, various",
+    "components will be updated:",
+    "- Mandatory: SMC.BIN for the SMC firmware.",
+    "- Mandatory: ROM.BIN for the main ROM.",
+    "- Optional: VERA.BIN for the VERA firmware.",
+    "- Optional: ROMn.BIN for a ROM expansion board or cartridge.",
+    "",
+    "  Important: Ensure J1 write-enable jumper is closed",
+    "  on both the main board and any ROM expansion board.",
+    "",
+    "Please carefully read the step-by-step instructions at ",
     "https://flightcontrol-user.github.io/x16-flash"
 };
 
 const char display_intro_colors_count = 16;
 const char* display_into_colors_text[16] = {
-    "The panels above indicate the update progress of your chipsets,",
+    "The panels above indicate the update progress,",
     "using status indicators and colors as specified below:",
     "",
     " -   None       Not detected, no action.",
@@ -44,7 +45,7 @@ const char* display_into_colors_text[16] = {
     " -   Issue      Problem identified during update.",
     " -   Error      Error found during update.",
     "",
-    "Errors indicate your J1 jumpers are not properly set!"
+    "Errors can indicate J1 jumpers are not closed!"
 };
 
 const char display_no_valid_smc_bootloader_count = 9;
@@ -54,10 +55,10 @@ const char* display_no_valid_smc_bootloader_text[9] = {
     "A valid bootloader is needed to update the SMC chip.",
     "Unfortunately, your SMC chip cannot be updated using this tool!",
     "",
-    "You will either need to install or downgrade the bootloader",
-    "onto the SMC chip on your CX16 using an arduino device,",
-    "or alternatively to order a new SMC chip from TexElec or",
-    "a CX16 community friend containing a valid bootloader!"
+    "A bootloader can be installed onto the SMC chip using an",
+    "an Arduino or an AVR ISP device.",
+    "Alternatively a new SMC chip with a valid bootloader can be",
+    "ordered from TexElec."
 };
 
 const char display_smc_rom_issue_count = 8;
@@ -77,10 +78,10 @@ const char* display_smc_unsupported_rom_text[7] = {
     "There is an issue with the CX16 SMC or ROM flash versions.",
     "",
     "Both the SMC and the main ROM must be updated together,",
-    "to avoid possible conflicts of firmware, bricking your CX16.",
+    "to avoid possible conflicts, risking bricking your CX16.",
     "",
-    "The SMC.BIN does not support the current ROM.BIN file",
-    "placed on your SDcard. Upgrade the CX16 upon your own risk!"
+    "The SMC.BIN and ROM.BIN found on your SDCard may not be",
+    "mutually compatible. Update the CX16 at your own risk!"
 };
 
 

src/cx16-smc.c

@@ -221,7 +221,7 @@ unsigned int smc_flash(unsigned int smc_bytes_total) {
     unsigned int smc_row_bytes = 0;
     unsigned long flash_bytes = 0;
 
-    display_action_progress("To start the SMC update, do the below action ...");
+    display_action_progress("To start the SMC update, do the following ...");
 
     unsigned char smc_bootloader_start = cx16_k_i2c_write_byte(FLASH_I2C_SMC_DEVICE, FLASH_I2C_SMC_BOOTLOADER_RESET, 0x31);
     if(smc_bootloader_start) {

src/cx16-update.c

@@ -301,9 +301,9 @@ void main() {
 
     // VA2 | SMC.BIN does not support ROM.BIN release | Display warning that SMC.BIN does not support the ROM.BIN release. Ask for user confirmation to continue flashing Y/N. If the users selects not to flash, set both the SMC and the ROM as an Issue and don't flash. | Issue
     if(check_status_smc(STATUS_FLASH) && check_status_cx16_rom(STATUS_FLASH) && !smc_supported_rom(rom_release[0])) {
-        display_action_progress("The ROM.BIN isn't compatible with SMC.BIN, no flash allowed!");
+        display_action_progress("Compatibility between ROM.BIN and SMC.BIN can't be assured!");
         display_progress_text(display_smc_unsupported_rom_text, display_smc_unsupported_rom_count);
-        unsigned char ch = util_wait_key("You still want to continue with flashing? [YN]", "YN");
+        unsigned char ch = util_wait_key("Continue with flashing anyway? [Y/N]", "YN");
         if(ch == 'N') {
             // Cancel flash
             display_info_smc(STATUS_ISSUE, NULL);
@@ -438,7 +438,7 @@ void main() {
                         }
                     }
                 } else {
-                    display_info_rom(rom_chip, STATUS_ISSUE, "Update SMC failed!");
+                    display_info_rom(rom_chip, STATUS_ISSUE, "SMC Update failed!");
                 }
             }
         }
@@ -460,8 +460,8 @@ void main() {
         if(check_status_smc(STATUS_ERROR) || check_status_vera(STATUS_ERROR) || check_status_roms(STATUS_ERROR)) {
             // DE2 | There is an error with one of the components
             vera_display_set_border_color(RED);
-            display_action_progress("Update Failure! Your CX16 may be bricked!");
-            display_action_text("Take a foto of this screen, shut down power and retry!");
+            display_action_progress("Update Failure! Your CX16 may no longer boot!");
+            display_action_text("Take a photo of this screen, shut down power and retry!");
             while(1);
         } else {
             if(check_status_smc(STATUS_ISSUE) || check_status_vera(STATUS_ISSUE) || check_status_roms(STATUS_ISSUE)) {