--- /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.

--- /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
+**

--- /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

--- /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

--- /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

--- /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

--- /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

--- /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

--- /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