From 813ec2cf98eaaf47e001620a111dd69170ecc928 Mon Sep 17 00:00:00 2001
From: heck <heck@pep.foundation>
Date: Fri, 20 Sep 2024 21:01:27 +0200
Subject: [PATCH] DOC: add README.md

---
 README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 151 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9eb7912
--- /dev/null
+++ b/README.md
@@ -0,0 +1,151 @@
+# Heck Daisy Template
+
+Daisy project template featuring:
+* toolchain setup
+* dependencies setup
+*
+* build scripts
+* upload (DFU and JTAG)
+* debug
+* clang-format
+* clang-tidy
+
+
+## git started
+
+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.
+
+
+
+## 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
+```
+
+``` 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!
+
+
+
+## Various
+
+Stahl and Marcs fire synthesizer. Now with sausage mode: https://wiki.sgmk-ssam.ch/wiki/F%C3%BC%C3%BCr_Synthie_mit_Daisy_Seed   
+
+
+
+
+