# HG changeset patch # User heinrichsweikamp # Date 1593440297 -7200 # Node ID 0e7c16dd774de6e108eb7c1bfa60dda6593c7112 # Parent 9eeab3fead8f02c3a79ab4ffe9e712484a4311c9 add wiki sub-directory diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Detailed CPU1-Discovery Project.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Detailed CPU1-Discovery Project.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,87 @@ +# How to Create From Scratch a Project for _CPU1-Discovery_ Code # + +The OpenSTM32 wiki have a [page](http://www.openstm32.org/Getting%2Bstarted%2Bwith%2BSystem%2BWorkbench%2Bfor%2BSTM32) to start a project from scratch. With the latest version of every support libraries and sources from ST. But here I prefer to have a project with the support files validated (and compatible) with the _OSTC4_ code. + +## Start with an Empty Project ## + +**Special Notes**: + +- _Linux_ users should read about this **well known _Eclipse_ bug** : http://www.openstm32.org/faq1#q22 +- We do have a _STM32F427IIT6_ chip as CPU1. But the support file provided by _ST_ lake for _LCD TFT Display Controller_ (aka LTDC), even in the latest available version 1.7.2 from 2017-11-06... So we use the STM32F429IITx support file instead, that seems to be similar enough. + +In the following description, I suppose you used _mercurial_ to clone the sources into a **D:\Dev\OSTC4** directory. Make the changes for your own settings... + +0. Start the IDE. On most machine it will be the `eclipse` in the _Ac6_ folder you installed. +1. Create an empty project: `File` > `New` > `C Project` +2. Choose `AC6 STM32 MCU Project` and `AC6 STM32 MCU GCC`. Click `Next` +Note: **make sure NOT TO CLICK FINISH... as it will skip all the rest of the configuration wizard !** +3. Keep `Debug` and `Release` configurations. Click `Next` +4. Create a new board, that you can name **OSTC4-CPU1-F429**, by choosing: +> Series: `STM32F4` +> Mcu: `STM32F429IITx` +> Debug: `JTAG` +Click `Next`. +5. Keep `No firmware` and select `Don't generate startup files`. Then click `Finish` + +## Configure Various Settings ## + +1. In the _C/C++ Projects_ explorer, select your project top-level folder +2. Right on it, select `Properties`, `Resource` and set `Text file encoding` to **UTF-8** +3. Right on it, select `Properties`, `Resource` then `Linked Resources` and click on `New...` to define a new variable **OSTC4** that points to your source folder **D:\Dev\OSTC4** (or whatever path you used on your system). +This should allow to change the project's origin with a single variable change. + +# Add Sources Folders # + +1. In the _C/C++ Projects_ explorer, select your project top-level folder +2. Right-click to add a `New` > `Folder`. In `Advanced settings >` click `Link to alternate location` and then the `Variables...` button. Click on the **OSTC4** variable, then click `Extend...` and select the **Common\\** sub-directory. Click `Finish` +3. Do the same to import the linked folder **OSTC4\Discovery** + +## Make _Eclipse_ aware you just added sources, not junk ## + +(_Note: this step is only useful on specific versions of Eclipse. And already done by default on others..._) + +1. In the _C/C++ Projects_ explorer, open your project top-level project. +2. Right click on the `Common` folder, select `Resource Configurations...`, and `Exclude from build`. Make sure to UNCHECK both `Debug` and `Release` check-boxes. +3. Do the same for the `Discovery` folder. + +## Make _Eclipse_ aware not to compile templates ## + +Some sources or directories in the _ST_ distribution contains source you shall not compile. So you should tell _OSE_. + +1. In the _Project Explorer_, open item `Common/Drivers/STM32F4xx_HAL_DRIVER_v120/Src`. Right click on `stm32f4xx_hal_msp_template.c`source file, select `Resource Configurations...`, and `Exclude from build`. Make sure both `Debug` and `Release` check-boxes are CHECKED. +2. Do the same on the `Common/Drivers/STM32F4xx_v220/Source/Templates` directory. + +# Compile # + +1. Select your top-level project, right-click to edit `properties`. In `C/C++ Build` choose `Settings`, then `MCU GCC Compiler` and `Optimization`. Choose `Optimization Level`: -Os (To reduce flash time) + +Ok, sources are there. You can read them. But you need a few more efforts to let the IDE find everything he requires to compile _CPU1 Discovery_ firmware. + +## Add include paths ## + +1. Select your top-level project, right-click to edit `properties`. In `C/C++ Build` choose `Settings`, then `MCU GCC Compiler` and `Includes`. **Make sure to select `Configuration: [All Configurations]` **. Click `Add...` choose `Workspace...` and select the `Common/Drivers/CMIS_v210` directory. +2. Do the same for `Common/Drivers/STM32F4xx_v220/Include` directory. +3. Do the same for `Common/Drivers/STM32F4xx_HAL_DRIVER_v120/Inc` directory. +4. Do the same for `Common/Inc` directory. +5. Do the same for `Discovery/Inc` directory. +6. Use the _Move Up_ icon to make sure `Discovery/Inc` is first. +7. Use the `Configuration:` pop-up to check you have all the includes in both `Debug` and `Release` configuration. + +Once done, If you go to the _C/C++ Projects explorer_, open your top-level project, and open the `Includes` item, you should see: + +- a few lines added by the system `.../Ac6/Workbench/plugins/.../compiler/...` with include paths required by the GCC compiler. +- then your 5 include directories (shown in alphabetic order, not priority order... too bad). Make sure to open each of them and to double-click on a .h file to check it opens correctly in the IDE. + +## Add Link Options ## + +1. Select your top-level project, right-click to edit `properties`. In `C/C++ Build` choose `Settings`, then `MCU G++ Linker` and `General`. +And select _linker Script_: `OSTC4/Common/CPU1-F429.ld` +2. In `C/C++ Build` choose `Settings`, then `MCU GCC Linker` and `Miscellaneous`. Add option -u _printf_float in Linker flags. This is necessary to prevent IDE warning "The float formatting support (-u _printf_float) is not enabled from linker flags". + +## Prepare generation of bin file ## +1. Select your top-level project, right-click to edit `properties`. In `C/C++ Build` choose `Settings`, then tab `Build Steps` and `Post build step command`. +2. Add option -R .upper\* to the command to removed the upper memory section, which is provided by the font library =>arm-none-eabi-objcopy -R .upper\* -O binary "${BuildArtifactFileBaseName}.elf" "${BuildArtifactFileBaseName}.bin"; arm-none-eabi-size "${BuildArtifactFileName}" + +## Build ELF firmware ## + +1. Click the `Build` button (hammer icon) on the top bar. diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Detailed CPU1-Upper Project.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Detailed CPU1-Upper Project.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,13 @@ +# How to Create From Scratch a Project for _CPU1-Upper_ Code # + +The main CPU (aka. _CPU1 Discovery_) firmware is splitted in two parts: +- The proper _CPU1 Discovery_ firmware, with the main code. +- The _protected upper memory_ firmware, which is programmed during _OSTC4_ production, and contains (amongst other things) code used to upload and install firmware upgrades. + +## Make a specific project ## + +Follow the same procedure than for [CPU1-Discovery](Detailed CPU1-Discovery Project.md), (same processor, same includes) but include the `CPU1-Upper` source directory. + +** +NOT FINISHED YET... BE PATIENT +** diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Detailed CPU2-RTE Project.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Detailed CPU2-RTE Project.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,12 @@ +# How to Create From Scratch a Project for _CPU2-RTE_ Code # + +Follow the same procedure than for [CPU1](Detailed CPU1-Discovery Project.md), with changes: + +- Create a new _board_ for processor: +> Series: `STM32F4` +> Mcu: `STM32F411xE` +> Debug: `JTAG` + +- Add `Small_CPU` linked source directory (instead of _Discovery_) + +- Use linker script `OSTC4/Small_CPU/CPU2-F411.ld` \ No newline at end of file diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Hardware Resources.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Hardware Resources.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,56 @@ +# OSTC4 Resources # + +## Hardware ## + +There are two processors in the OSTC4: + +* an [STM32F427IIT6](http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f4-series/stm32f427-437/stm32f427ii.html) as main processor. It is a Cortex-M4 processor with FPU, running at 180 MHz. +It crunches most of the decompression code, the graphic display operations and the user interface. + +* an [STM32F411RET6](http://www.st.com/en/microcontrollers/stm32f411re.html) as the RTE (Real-Time-Environment) processor. +This is another processor of the ARM Cortex M4 family, but with extremely low power modes and plenty of communication ports. +It runs real-time gas exchange simulation during dive, and interface to most peripherals. + +Various peripherals are connected to them: + +- A 800x480 pixels _LCD_ screen, with a live stream of color pixels send by an auto-refresh SDRAM. +- A pressure sensor. +- A magnetic compass. +- An ambient light sensor. +- Three buttons. +- A battery, and a battery gauge. + +_OSTC4_ programming is based on the _HAL_ (for _Hardware Abstraction Layer_) provided by _ST_. +This allows to have a more readable C code, and to evolve more easily to another processors of the same familly. + +## Drivers Used by the Main CPU - aka CPU1-Discovery ## + +The main _ARM-Cortex 4_ CPU uses the following resources provided by the +_HAL_ (_Hardware Abstraction Layer_) +provided by the processors makers _ST_ to ease code developement, security and portability: + +- **HAL_DMA** _Direct Memory Accelerator_: automated memory transfers, used to manage SPI reception and transmission channels. +- **HAL_DMA2D** : a _specialized DMA dedicated to images manipulation_, used by `gfx_engine`to clear screens. +- **HAL_FMC** _Flexible Memory Controller_ to drice the external SDRAM used for display. +- **HAL_GPIO** _General Purpose Input/Output_: this is the programmable pins of the chip, used to connect nearly evrything. +- **HAL_LTDC** _LCD TFT Display Controller_: to transfer images to the screen memory ? +- **HAL_NVIC** _Nested Vector Interrupt Controller_: CORTEX IRQs used in `base.c` to handle buttons interrupts, in `gfx_engine.c` to manage VSYNC (screen's vertical sync) and in `stm32f4xx_hal_msp_hw2.c` to manage all other interrupts (ticks, DMA, DMA2D, TIM and USART). +- **HAL_RCC** _Reset and Clock Control_: used in `base.c` to setup system, PLL and screen clocks. +- **HAL_SDRAM** RAM controller used in `stm32f4xx_hal_msp_hw2.c` and in `base.c` to interface the external memory used by the screen. +- **HAL_SPI** _Serial Peripheral Interface_: implement the [standard SPI protocol](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus). Used to do full duplex communication between the two CPU in `data_exchange_main.c` to exchange dive settings and state, and in `externCPU2bootloader.c` to send firmware to _CPU2-RTE_. +- **HAL_TIM** basic _Timers_ used in `base.c` and PWM (_Pulse Width Modulation_) used to control backlight intensity. +- **HAL_UART** _Universal Asynchronous Receiver Transmitter_: serial communications used in `bonnexConnect.c`, `ostc.c`, `stm32f4xx_hal_msp_hw2.c`, `tCCR.c`, `tCpmm.c` and `tDebug.c` + +## Drivers Used by the Secondary CPU - aka CPU2-RTE ## + +- **HAL_ADC** _Analog to Digital Converter_ channel 1 is used in `adc.c` for the ambient light sensor. +- **HAL_DMA** _Direct Memory Accelerator_: automated memory transfers, used to manage SPI reception and transmission channels when communicating to main CPU. +- **HAL_FLASH** allow erasing, programming, and managing read/write protection mechanisms of the internal FLASH memory. +- **HAL_GPIO** _General Purpose Input/Output_: this is the programmable pins of the chip, used to connect nearly evrything. +- **HAL_I2C** _Inter-Integrated Circuit_ [bus controller](https://en.wikipedia.org/wiki/I2C) is another standard bus, used to connect the pressure sensor in `pressure.c`, the magnetic compass in `compass.c` and the battery state in `batteryGauge.c`. Initialisations are in `baseCPU2.c` and `stm32f4xx_hal_msp_v3.c`. +- **HAL_NVIC** _Nested Vector Interrupt Controller_: CORTEX IRQs used in `baseCPU2.c` to handle clock ticks, buttons and wireless state. In `spi.c` to know end of SPI transmissions. And in `stm32f4xx_hal_msp_v3.c` to setup various _I2C_ interupts. +- **HAL_PWR** _Power Controller_: to manage sleep mode, low power and wakeup. And in `rtc.c` to manage FLASH power down. +- **HAL_RCC** _Reset and Clock Control_: used in `baseCPU2.c` to setup system, PLL clocks for ... +- **HAL_RTC** _Real Time Clock_ to handle date and time in `scheduler.c` +- **HAL_SPI** _Serial Peripheral Interface_: implement the [standard protocol](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus). Used to do full duplex communication between the two CPUs. In `spi.c`, SPI1 is used to communicate to the maon CPU, and SPI3 to commicate to buttons. +- **HAL_UART** _Universal Asynchronous Receiver Transmitter_: serial communications used in `uart.c` \ No newline at end of file diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Home.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Home.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,40 @@ +# Open Source Code for the OSTC4 Dive Computer # + + +## Documentation ## + +[Modules](Modules.md) page details the code organisation. +[Hardware Resources](Hardware Resources.md) page details the hardware parts, +the low-level, and the middle-ware drivers used to manage them. + +## How to Compile ? ## + +Most of the code is written in _C-99_. A small glue is in assembly. Everything is compatible with +the _GCC_ toolchain for ARM processors. + +* [Using OpenSTM32](Using OpenSTM32.md), the free integrated IDE from the OpenSTM32 community, based on GCC cross compiler within an _Eclipse_ environment. Project management and configuration. Compile & Link. Hardware debugger through a JTAG/SWD probe. + +## Other Tools ## + +* [STM32F429I-DISC1](http://www.st.com/en/evaluation-tools/32f429idiscovery.html) + It is a chip (~ 20€) evaluation board, that contains a _STM32F429ZIT6_ CPU, 2MB flash ROM, 256KB RAM, a 320x240 LCD touch screen a few LEDs and a pair of buttons. Very cheap (~ 25 Euro). + It should allows to run _OSTC4 Discovery code_, but just for basic testing as it lacks all specific sensors, LCD screen 800x640 resolution and the 3 interface buttons. + _An interesting project would be to add a special compilation option to get some reasonable support on this chip debugging platform, emulating the screen and buttons..._ + +* [STM32 ST-LINK Utility](http://www.st.com/en/development-tools/stsw-link004.html) (**Windows only**) allow to do many things to the _discovery kit_ through its JTAG/SWD interface: upload & verify application code, dump memory. Provides both a _Graphical_ and a _Command Line_ interface. + +* [STMStudio](http://www.st.com/en/development-tools/stm-studio-stm32.html) (**WINDOWS ONLY**) allows real-time inspection of an application running on the _discovery kit_. + It is connected through the JTAG/SWD interface. + It allows to read and write variables defined in the application's binary (ELF file). To display or to trace graphs (eg. to display gas loading during dive simulation ?) + +* [OpenOCD](http://openocd.org/) is another command utility to speak JTAG/SWD. Seems hard to use directly (very low level commands). But _OpenSTM32 IDE_ do use it for programming and debugging, and you can copy configuration files from a working project. Note version 0.10 (or above) seems mandatory to dump firmware contents. + +* _**OSTC4 with 2 SWD connectors**_, the ultimate debugging tool: a specially made OSTC4, with a pair of extra SWD connectors you can connect to any JTAG/SWD probe. Cannot dive (absolutely not water tight), but allows to debug code on the real hardware (ie. set break points, single step the code and read/write variables), using a standard JTAG/SWD debuggers (eg. a low cost [ST-Link/V2](http://www.st.com/stlinkv2) for ~ 25 euro). + _Note that heinrichs weikamp will freely provide SWD OSTC4 platform to programmer serious about involving in code development._ + +## Other Resources ## + +* The **Ultimate Reference** for everyone serious about the OSTC4 firmware details +and _HAL_ programming (1800 pages): [UM1725 HAL Users Manual] https://www.st.com/resource/en/user_manual/dm00105879.pdf +* Reserving memory from the linker script: https://mcuoneclipse.com/2012/11/01/defining-variables-at-absolute-addresses-with-gcc/ +* Placing a variable at an absolute address: https://sourceware.org/binutils/docs-2.24/ld/Source-Code-Reference.html#Source-Code-Reference \ No newline at end of file diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Make Firmware File.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Make Firmware File.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,17 @@ +# How to Make an Uploadable Firmware File for the OSTC4 # + +Generated BIN files from the SMT32 Workbench need modification in order to be installed via the OSTC Companion onto the OSTC4. + +## Build Command Line Tools ## + +These can be found in /ostc4pack (For Windows, CPP sources available) + +## Run the Tools Manually ## + +1. Copy generated BIN files (From the Release or debug directory) into /ostc4pack. Or: Modify .bat files to point to your Release or debug directory. +2. run step1_create_OSTC_RTE_upload.bat and/or step1_create_OSTC4_firmware_upload_bin.bat (Depending on which part you made changes) +3. run step2_create_OSTC4update_bin.bat to create final OSTC4update_xxxxxx.bin, with xxxxxx being the current date in YYMMDD format. This will add important checksums required for the OSTC4's bootloader to accept the file. + +## Upload this file with the OSTC Companion software to the OSTC4 ## + +See http://forum.heinrichsweikamp.com/read.php?7,19186 on how to get and use the "OSTC companion" \ No newline at end of file diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Modules.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Modules.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,38 @@ +# OSTC4 Code Modules # + +## Main CPU - aka CPU1-Discovery ## + +For historical reasons, the firmware of the main CPU was divided in three parts. +It helps development, allow smalled upgrades, and improve security as a bad manipulation won't kill the bootloader, responsible fot the next firmware upgrade. + +### Bootloader ## + +The code responsible to upload new firmwares for both CPU. + +### Font Pack ### + +This module does not contains any code. Just font data and images. + +### Firmware code ### + +The main OSTC4 firmware. The more important modules are: + +- Buehlmann decompression algorithm. +- VPM decompression algorithm. +- The simulator and dive planner. +- Logbook display (surface and dive mode). +- All user interface code, during dive or surface mode (`t*.c` files). +- Graphics (gfx) engine. +- Plus interface to the other CPU, the management of the _LCD_ screen, and the optional _Bonex_ scooter interface (No longer supported) + +## Small CPU - aka CPU2-RTE ## + +The _Real Time_ CPU handle everything that requires precise timming to function perperly. + +The most important modules are: + +- Real time computation of gas exchanges during dive (aka the _LifeData_ structure). +- Analog to digital conversion for the ... ambient light sensor. +- I2C bus interface to the pressure sensor, the magnetic compass and the battery gauge. +- SPI bus interface to the buttons and to the other CPU. +- Serial interface to the _RS232-over-Wireless_ connection. \ No newline at end of file diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Original HELP page.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Original HELP page.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,42 @@ +# Welcome + +Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it. + +## Wiki features + +This wiki uses the [Markdown](http://daringfireball.net/projects/markdown/) syntax. The [MarkDownDemo tutorial](https://bitbucket.org/tutorials/markdowndemo) shows how various elements are rendered. The [Bitbucket documentation](https://confluence.atlassian.com/x/FA4zDQ) has more information about using a wiki. + +The wiki itself is actually a mercurial repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately. + +Go ahead and try: + +``` +$ hg clone https://JeanDo@bitbucket.org/JeanDo/ostc4/wiki +``` + +Wiki pages are normal files, with the .md extension. You can edit them locally, as well as creating new ones. + +## Syntax highlighting + + +You can also highlight snippets of text (we use the excellent [Pygments][] library). + +[Pygments]: http://pygments.org/ + + +Here's an example of some Python code: + +``` +#!python + +def wiki_rocks(text): + formatter = lambda t: "funky"+t + return formatter(text) +``` + + +You can check out the source of this page to see how that's done, and make sure to bookmark [the vast library of Pygment lexers][lexers], we accept the 'short name' or the 'mimetype' of anything in there. +[lexers]: http://pygments.org/docs/lexers/ + + +Have fun! \ No newline at end of file diff -r 9eeab3fead8f -r 0e7c16dd774d wiki/Using OpenSTM32.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/wiki/Using OpenSTM32.md Mon Jun 29 16:18:17 2020 +0200 @@ -0,0 +1,15 @@ +# Using OpenSTM32 IDE to Compile OSTC4 Firmware # + +The free and Open [STM32 IDE](http://www.openstm32.org/System%2BWorkbench%2Bfor%2BSTM32) is an integrated development environment based on _Eclipse_ that will allows you to compile and link code for the OSTC4 dive computer. +You will then be able to generate `.bin` firmware files to upload to your computer using your favourite tools, eg. [OSTC Companion](https://ostc-planner.net/companion). + +1. Register on http://www.openstm32.org/ : that will allows you to download the IDE. +2. Once registered and logged in, you can go to _Documentation_ and _Installation Manual_. Follow the instructions to install the IDE (available for Windows 7, MacOS and Linux). +3. Use the ready made project ... in ... + +Or you can create a brand new project by following the _How To_'s: + +- [HowTo compile CPU1-Discovery main firmware](Detailed CPU1-Discovery Project.md) +- [HowTo compile CPU1-Discovery protected area firmware](Detailed CPU1-Upper Project.md) +- [HowTo compile CPU2-RTE real-time firmware](Detailed CPU2-RTE Project.md) +- [HowTo generate uploadable firmware file](Make Firmware File.md) \ No newline at end of file