From 0015e9457c905bb83794654e109052d215de5ead Mon Sep 17 00:00:00 2001
From: heck <heck@pep.foundation>
Date: Tue, 10 Sep 2024 01:46:53 +0200
Subject: [PATCH] DOC: add README.md

---
 README.md | 160 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 135 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index 6619b4e..9eb7912 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,151 @@
-# DaisyBlinkProject
+# Heck Daisy Template
 
-Basic Blink Project with all required libraries, etc.
+Daisy project template featuring:
+* toolchain setup
+* dependencies setup
+*
+* build scripts
+* upload (DFU and JTAG)
+* debug
+* clang-format
+* clang-tidy
 
-## Get Started
 
-If cloning this repo from Github, you will want to do so with the submodules with:
+## git started
 
-```console
-git clone https://github.com/electro-smith/DaisyBlinkProject --recurse-submodules
-```
+to use git, either die or use hecks git-ui.   
+heck-git-ui: https://gitea.heck.live/heck/HeckBashSetup/src/branch/master/bash_profile.d/git.sh
+
+Alternatively, you can avoid using git... TODO
+
+
+## Toolchain Setup
+
+### Compiler
+
+compiler used is gcc for arm:  
+Options:
+* install version specified by electro-smith: https://developer.arm.com/downloads/-/gnu-rm
+* install the latest version: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain
+
+**IMPORTANT:** Do NOT use any OTHER gcc-arm toolchain than these ones!!!
+There is a pitfall that is quite hard to debug. I used the gcc-arm from macports.
+There is NO libc-nano shipped with it, because its not GPL.
+BUT the daisy build scripts specify the use of libc-nano.
+
+
+### Programmer / Debugger
+
+on macos:
+`port install dfu-util openocd`
+
+
+`dfu-util` is the program that is invoked by the Makefiles to program the thing via DFU.
+`openocd` is the program that is invoked by the Makefiles to program the thing via JTAG.
+`openocd` also is the debugger we use.
 
-if you've already cloned the repo without this you can fill the submodules by running the following:
 
-```console
-git submodule update --init
+
+## Flashing
+
+Can be flashed via:
+* DFU: all you need is a micro-usb-cable
+* JTAG: any JTAG programmer will work, but the STLink v3 is the fastest.
+
+### DFU
+No magic, you just need a program called `dfu-util`.   
+TODO...
+
+### JTAG
+no magic, you just need a programm called `openocd`
+
+TODO:
+The JTAG method is heavily recommended since JTAG is faster than DFU, and if you use the (product ad ahead warning, sorry)   
+STLink v3 its even faster. Its the fastest method i know of.
+
+### Benchmark DFU vs. JTAG
+
+**DFU: 15.725s**   
+**JTAG: 1.850s**
+
+JTAG is at least **8.5 times** faster (since there is constant time overhead)
+
+``` shell
+[heck@YOOROOX::~/src/DaisyExamples/seed/Blink] (master ?M) $ time m program-dfu;
+dfu-util -a 0 -s 0x08000000:leave -D build/Blink.bin -d ,0483:df11
+blabla...
+...
+real	0m15.725s
 ```
 
-Alternatively, you can avoid using git, and building libraries if you download the latest zip compiled zip file in the releases.
+``` shell
+[heck@YOOROOX::~/src/DaisyExamples/seed/Blink] (master ?M) $ time m program;
+openocd -s /opt/local/bin/openocd/ -f interface/stlink.cfg -f target/stm32h7x.cfg -c "program ./build/Blink.elf verify reset exit"
+blabla...
+...
+real	0m1.850s
+```
+
+
+## Debugging
+TODO:
+
+
+
+
+
+
+
+## Daisy Coding
+* C++ bare metal like any STM32 - needlessly brutal
+* C++ and libDaisy - libDaisy is the electro-smith hardware abstraction
+* Pure-Data patch compiler
+* JUCE
+* FAUST for DSP algo
+* Max-msp gen~ (proprietary $hit)
+
+
+### C++ Bare Metal
+Just code like for any STM32 - needlessly brutal   
+TODO: add hecks STM32 project
+
+### C++ and libDaisy
+libDaisy is the electro-smith hardware abstraction and is basically what makes the daisy be the daisy.
+TODO:
+
+
+### Pure-Data Patch Compiler
+this here: https://github.com/electro-smith/pd2dsy   
+TODO: Marc? anyone?
+
+
+### JUCE
+TODO: anyone?   
+e.g. https://github.com/electro-smith/Daisy-Juce-Example
+
+### FAUST
+This here: https://faust.grame.fr/
+stahl has workflow/project
+
+### Max-Msp gen~
+max is the proprietary version of pure-data, but dont want to exclude them just for that.
+gen~ alone will cost you extra $$$ after even you paid for max. just so you know, hu?
+
+
+
+
+
+## Daisy-Hardware
+
+TODO: PLEASE everyone share their hardware HERE!
+
 
-## Contents
 
-Includes:
+## Various
 
-* libDaisy - hardware library for Daisy
-* DaisySP - DSP library
-* Blink - Basic example demonstrating a blink
+Stahl and Marcs fire synthesizer. Now with sausage mode: https://wiki.sgmk-ssam.ch/wiki/F%C3%BC%C3%BCr_Synthie_mit_Daisy_Seed   
 
-This also contains the following VS code tasks:
 
-* Build Libraries: builds libDaisy, and DaisySP from scratch. This is only necessary when manually updating, or cloning for the first time.
-* Build: build the blink example
-* Clean: removes compiled Blink code
-* Program DFU: programs the Blink.bin file via USB
-* Build and Program DFU: Rebuilds the program and downloads it via USB DFU
 
-In addition, the following debug configurations are available:
 
-* Debug Blink: debugs the Blink application
 
-**Note**: debugging an application from VS Code requires an ST-Link or similar probe, as well as the Cortex Debug extension for VS Code.