From e78838f750035b6ed943db80e8552a501adabab4 Mon Sep 17 00:00:00 2001 From: Nathan Schulte <8540239+nmschulte@users.noreply.github.com> Date: Tue, 4 Jul 2023 08:07:44 -0500 Subject: [PATCH] edits to intro/flashing page; add hardware/flashing-software-notes page (#112) * edit firmware update intro page * add flashing software notes page to hardware section --------- Co-authored-by: Piotr Rogowski --- docs/Hardware/Flashing-Software-Notes.md | 61 +++++++++++++++ .../HT-Flashing-The-Firmware.md | 41 ---------- .../HT-Updating-The-Firmware.md | 74 ++++++++++++++++++ .../{Flashing-FW => Updating-FW}/ecudef.png | Bin .../fomeconsole.png | Bin .../fwsuccess.png | Bin .../{Flashing-FW => Updating-FW}/mandfu.png | Bin .../popularvehicles.png | Bin docs/intro.md | 4 +- 9 files changed, 138 insertions(+), 42 deletions(-) create mode 100644 docs/Hardware/Flashing-Software-Notes.md delete mode 100644 docs/Intro-Start-Here/HT-Flashing-The-Firmware.md create mode 100644 docs/Intro-Start-Here/HT-Updating-The-Firmware.md rename docs/Intro-Start-Here/{Flashing-FW => Updating-FW}/ecudef.png (100%) rename docs/Intro-Start-Here/{Flashing-FW => Updating-FW}/fomeconsole.png (100%) rename docs/Intro-Start-Here/{Flashing-FW => Updating-FW}/fwsuccess.png (100%) rename docs/Intro-Start-Here/{Flashing-FW => Updating-FW}/mandfu.png (100%) rename docs/Intro-Start-Here/{Flashing-FW => Updating-FW}/popularvehicles.png (100%) diff --git a/docs/Hardware/Flashing-Software-Notes.md b/docs/Hardware/Flashing-Software-Notes.md new file mode 100644 index 0000000..2b91e9e --- /dev/null +++ b/docs/Hardware/Flashing-Software-Notes.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 3 +--- + +# Flashing Software Notes + +:::note + +Some boards, notably those with processors utilizing certain dual bank memory layout, like the STM32F7, suffer from an +issue such that flashing does not succeed correctly, due to an error with the erasure mechanism. For these situations, +manually erase the flash memory before flashing; i.e. perform a full/mass erase procedure first. + +::: + +While the FOME console is the recommended and officially supported way to update FOME firmware on supported boards, +other mechanisms exist to flash firmware to board supporting FOME. These tools are also useful in odd situations, like +the event of a firmware update/flash failure, or some other firmware corruption issue, such that FOME console nor +TunerStudio recognize the ECU when connected. + +For the ECU, you will need to access buttons or pins on the main board to force the processor into bootloader/DFU mode. +Some boards use a momentary button, likely near to the reset button, to force this mode during power-up. Others might +use a set of pins or pads that need shorted to force this mode during power-up. Press the button or short the pins with +the ECU disconnected from the computer, then simultaneously connect the ECU into the computer. Once connected, the +button can be released or the short removed. + +## STM32CubeProgrammer + +STM32CubeProgrammer is an officially STMicroelectronics supported tool to flash STM32 processors. Information about +and how to download and install the tool can be found on [the STM +wiki](https://wiki.st.com/stm32mpu/wiki/STM32CubeProgrammer). + +In STM32CubeProgrammer, select the *USB* tab on the right and refresh the port in the right side menu until a DFU is +detected. Click *Connect* to connect the ECU to the programmer. Click the *Read* button to read the device memory and to +validate that the ECU is connected. + +Once validated, choose the *Open File* button and load the file marked *fome.bin* within the firmware bundle downloaded +earlier. This is a binary file containing the ECU firmware. Now choose the *Download* button to write this firmware to +the ECU. Give it up to several minutes to download and once the status console confirms successful download, disconnect +from the programmer then unplug the ECU and plug it back in. The ECU should now connect to the computer and TS normally +again. + +## dfu-util + +dfu-util is a free software tool to flash Device Firmware Upgrade (DFU) compatible devices, including STM32 processors. +It supports most popular operating systems, including MacOS and Linux. Information about dfu-util can be found on [the +dfu-util website](https://dfu-util.sourceforge.net/). + +Updating with dfu-util is as straight-forward as invoking it like so: + +```sh +dfu-util -v -d 0483:df11 -a 0 -D fome.dfu -s :leave +``` + +Note that the `:leave` option does not always work, which would otherwise automatically instruct the processor to leave +DFU mode and load the firmware; the board must be manually reset to load the flashed firmware. + +To erase a device, use the following invocation: + +```sh +dfu-util -v -d 0483:df11 -a 0 -s :mass-erase:force +``` diff --git a/docs/Intro-Start-Here/HT-Flashing-The-Firmware.md b/docs/Intro-Start-Here/HT-Flashing-The-Firmware.md deleted file mode 100644 index 239e250..0000000 --- a/docs/Intro-Start-Here/HT-Flashing-The-Firmware.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Flashing the firmware - -Flashing the firmware is easy to do however it is important to do it correctly to prevent errors or board misconfiguration. If you haven't already, read the guide on downloading the firmware and setting up TunerStudio [here](/Intro-Start-Here/Where-To-Get-Firmware/). - -## Load the firmware onto the ECU - -Once you have downloaded the [latest firmware bundle](https://github.com/FOME-Tech/fome-fw/releases), extract it then navigate through the *console* folder to *fome_console.exe* and launch it. Ensuring that TS is **not** running, plug your ECU into the computer. The console should detect the board and show a similar screen to below: - -![image](Flashing-FW/fomeconsole.png) - -Click *Update Firmware* and leave the board plugged in until the prompt screen goes green and indicates that the update was successful. Only once the update has given this message, unplug and re-plug the ECU into the computer to reboot it. - -![image](Flashing-FW/fwsuccess.png) - -If this does not complete successfully, the firmware may need to be loaded by putting the board into bootloader or DFU mode. - -## Loading firmware in manual bootloader mode - -In the event that your firmware update fails and the computer fails to recognize the ECU when plugged into it, the firmware needs to be loaded by manually putting the board into boot mode. When the computer fails to recognize the ECU, the firmware has not loaded correctly so the console is unable to automatically put it into bootloader (or DFU) mode to update it. This process manually puts the ECU into bootloader mode then uploads the firmware file to it. - -On the ECU, you will then need to access the main board to find the boot/DFU pins/button. With the ECU un-powered, short the two boot pins (or push and hold the button) while plugging the ECU into the computer. Once plugged into the computer, the pins can be separated or the boot button released. If this has been done correctly, the console should come up with the manual DFU update selection. - -![image](Flashing-FW/mandfu.png) - -Click *Update Firmware* and keep the board connected until the prompt screen goes green and indicates a successful update. - -## Setting up TunerStudio - -Open TS with the ECU plugged in, it should recognise that the ECU definition is out of date and come up with a prompt to update the ECU definition. Press *Update ECU definition* and if it cannot find it online, load the *.ini* file from the firmware bundle downloaded earlier - -![image](Flashing-FW/ecudef.png) - -Next, under the *Controller* tab, open the *Popular Vehicles* menu and click the button to load the preset for your vehicle (not the button to reset the firmware settings). - -![image](Flashing-FW/popularvehicles.png) - -Once the preset has been loaded, you can either start tuning or load your tune from the older firmware versions under *File > Load Tune (msq)*. After that, the update is complete! \ No newline at end of file diff --git a/docs/Intro-Start-Here/HT-Updating-The-Firmware.md b/docs/Intro-Start-Here/HT-Updating-The-Firmware.md new file mode 100644 index 0000000..208cba5 --- /dev/null +++ b/docs/Intro-Start-Here/HT-Updating-The-Firmware.md @@ -0,0 +1,74 @@ +--- +sidebar_position: 4 +--- + +# Updating the firmware + +Updating the firmware is easy to do, however it is important to do it correctly to prevent errors or board +misconfiguration. A guide to downloading FOME firmware and setting up TunerStudio can be found +[here](/Intro-Start-Here/Where-To-Get-Firmware/). + +Updating firmware involves a process sometimes called "flashing" or even "programming" the ECU. Generally, these all +refer to the same thing: taking the compiled FOME firmware and loading it into the non-volatile flash memory on the ECU. + +## Updating the firmware with FOME console + +After confirming the firmware to flash to the ECU, software to do so must be used. FOME provides a utility, the **FOME +console**, which is capable of flashing firmware to supported ECUs and is the recommended way to update FOME firmware. +The FOME console is included with each firmware release, and bundles can be downloaded from [the release +page](https://github.com/FOME-Tech/fome-fw/releases). + +After extracting the bundle contents, navigate to the `console/` directory and run the FOME console program (e.g. +`fome_console.exe` if using Windows). After first confirming **TunerStudio is not running**, connect the ECU to the +computer. FOME console will automatically detect the board and present similar to the display below. + +![image](Updating-FW/fomeconsole.png) + +Next, choose the *Update Firmware* button and leave the board connected until the console notifies that the update was +successful with a green display. Only once the console has presented this success message, disconnected and re-connect +the ECU to the computer to reboot it with the new firmware. + +![image](Updating-FW/fwsuccess.png) + +If the update completes successfully, congratulations; proceed to [the Setting up TunerStudio +section](#setting-up-tunerstudio). If the update does not complete successfully, the firmware may need to be loaded by +first forcing the board into bootloader or Device Firmware Update (DFU) mode, documented in the next section. + +## Updating firmware via manual bootloader/DFU mode + +In the event of a firmware update/flash failure, or some other firmware corruption issue, such that FOME console nor +TunerStudio recognize the ECU when connected, the board needs to be first forced into bootloader mode before updating. +In these situations, the FOME console cannot communicate with the firmware and so is unable to configure it into +bootloader mode for updating. + +To enter bootloader mode, on the ECU you will need to access buttons or pins on the main board to force the processor +into this mode. Some boards use a momentary button, likely near to the reset button, to force this mode during +power-up. Others might use a set of pins or pads that need shorted to force this mode during power-up. Press the +button or short the pins with the ECU disconnected from the computer, then simultaneously connect the ECU into the +computer. Once connected, the button can be released or the short removed. + +When a board has been successfully booted into bootloader/DFU mode, the FOME console will recognize this and display the +manual DFU update selection. + +![image](Updating-FW/mandfu.png) + +Next, choose the *Update Firmware* button and leave the board connected until the console notifies that the update was +successful with a green display. Only once the console has presented this success message, disconnected and re-connect +the ECU to the computer to reboot it with the new firmware. + +## Setting up TunerStudio + +With the ECU connected, open TunerStudio with the associated project. TunerStudio will recognize that the project's ECU +definition is out of date and display a prompt to update it. Choose the *Update ECU Definition* button, which will +attempt to automatically update the definition from official sources. If an official definition cannot be found, +manually load the `.ini` definition file associated with the firmware (i.e. from the downloaded bundle). + +![image](Updating-FW/ecudef.png) + +Next, under the *Controller* tab, open the *Popular vehicles* menu and choose the top button (e.g. *Hellen NB1 36 wheel* +as shown here) to load the preset for your vehicle (**not the button to *Reset firmware settings***). + +![image](Updating-FW/popularvehicles.png) + +Once the preset has been loaded, you can either start tuning or load your tune from the older firmware versions under +*File > Load Tune (msq)*. After that, the update is complete! diff --git a/docs/Intro-Start-Here/Flashing-FW/ecudef.png b/docs/Intro-Start-Here/Updating-FW/ecudef.png similarity index 100% rename from docs/Intro-Start-Here/Flashing-FW/ecudef.png rename to docs/Intro-Start-Here/Updating-FW/ecudef.png diff --git a/docs/Intro-Start-Here/Flashing-FW/fomeconsole.png b/docs/Intro-Start-Here/Updating-FW/fomeconsole.png similarity index 100% rename from docs/Intro-Start-Here/Flashing-FW/fomeconsole.png rename to docs/Intro-Start-Here/Updating-FW/fomeconsole.png diff --git a/docs/Intro-Start-Here/Flashing-FW/fwsuccess.png b/docs/Intro-Start-Here/Updating-FW/fwsuccess.png similarity index 100% rename from docs/Intro-Start-Here/Flashing-FW/fwsuccess.png rename to docs/Intro-Start-Here/Updating-FW/fwsuccess.png diff --git a/docs/Intro-Start-Here/Flashing-FW/mandfu.png b/docs/Intro-Start-Here/Updating-FW/mandfu.png similarity index 100% rename from docs/Intro-Start-Here/Flashing-FW/mandfu.png rename to docs/Intro-Start-Here/Updating-FW/mandfu.png diff --git a/docs/Intro-Start-Here/Flashing-FW/popularvehicles.png b/docs/Intro-Start-Here/Updating-FW/popularvehicles.png similarity index 100% rename from docs/Intro-Start-Here/Flashing-FW/popularvehicles.png rename to docs/Intro-Start-Here/Updating-FW/popularvehicles.png diff --git a/docs/intro.md b/docs/intro.md index fae9ec8..b883d07 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -17,7 +17,7 @@ The first page to view should probably be [the FOME Overview page](Intro-Start-H - [FOME Overview](Intro-Start-Here/Overview) - [Which FOME hardware to choose](Intro-Start-Here/Which-Hardware-For-Me) - [Where to get firmware](Intro-Start-Here/Where-To-Get-Firmware) -- [Flashing the firmware](Intro-Start-Here/HT-Flashing-The-Firmware) +- [Updating the firmware](Intro-Start-Here/HT-Updating-The-Firmware) - [Performing a safe first start](Intro-Start-Here/HT-First-Start-Safely) - [How to setup a board for first use](Intro-Start-Here/HT-Set-Up) - [How to test inputs and outputs](Intro-Start-Here/HT-Test-IO) @@ -207,6 +207,8 @@ The first page to view should probably be [the FOME Overview page](Intro-Start-H ### Hardware +- [Flashing Software Notes](Hardware/Flashing-Software-Notes) + #### Hardware Circuits - [High/Low circuits](Hardware/Hardware-Circuits/High-Low)