diff --git a/docs/firmware-building.md b/docs/firmware-building.md index f1fdb9c0e..5e0a0958c 100644 --- a/docs/firmware-building.md +++ b/docs/firmware-building.md @@ -21,10 +21,10 @@ The `make configure` command is a shortcut for running: ``` # MacOS, Linux: -cmake --fresh --preset base -GNinja +cmake --fresh --preset full -GNinja -DLOG_LEVEL=DEBUG # MinGW: -cmake --fresh --preset base -G"Unix Makefiles" +cmake --fresh --preset full -G"Unix Makefiles" -DLOG_LEVEL=DEBUG ``` (The work-around for MinGW is documented with [issue #78](https://github.com/4ms/metamodule/issues/78)) @@ -32,46 +32,12 @@ cmake --fresh --preset base -G"Unix Makefiles" The `make all` command is a shortcut for running: ``` -cmake --build --preset base -``` - -### Limiting the modules built - -You also can limit the modules built to substantially reduce the compilation -and link times, as well as binary size. Create a text file with the modules -you want built, one per line. Each line should contain an -entry in the form `Brand:Module`. For example: - -``` -echo "4ms:EnOsc" >> quickbuild.txt -echo "Befaco:EvenVCO" >> quickbuild.txt -echo "hetrickcv:PhasorGen" >> quickbuild.txt - -make limit quickbuild.txt -``` - -This would tell CMake to re-configure the project and just build those three modules. -You can still open patches containing other modules, but their artwork won't be shown -and you can't play them. - -### Build with wifi bridge - -To simpilfy development workflow, the wifi bridge functionality is not included in the build by default. -To enable it, configure with the `full` preset - -``` -make configure PRESET=full -``` - -Note that currently this generates a binary that's too large to fit onto NOR Flash, -so it's only suitable for loading firmware via JTAG. -To build a smaller binary that includes the wifi functionality (but cannot be used to update -a wifi module), configure like this; - -``` -cmake --fresh --preset full -G Ninja -DENABLE_WIFI_BRIDGE_UPDATE=OFF +cmake --build --preset full ``` +You can set a different LOG_LEVEL, if you want, to control +how much gets sent to the console via UART. See [Firmware +Debugging](firmware-debugging.md). ### Using an SD Card @@ -80,7 +46,7 @@ path the SD Card device to save time. If you don't do this, then the system will prompt you whenever you run one of the SD Card flashing scripts. The device path should be to the entire SD Card device (not just one partition). ``` -cmake --preset base -DSD_DISK_DEV=/dev/disk4 +cmake --preset full -DSD_DISK_DEV=/dev/disk4 # Alternatively, set an environment variable: export SD_DISK_DEV=/dev/disk4 @@ -95,101 +61,14 @@ images for the M4 and A7 cores. For debugging, the symbols are in ### Specifying the toolchain *Optional*: if you have multiple versions of the gcc arm toolchain installed and don't want to -change your PATH for this project, you can set the METAMODULE_ARM_NONE_EABI_PATH var like this: +change your PATH for this project, you can set the TOOLCHAIN_BASE_DIR var like this: ``` # Put in your bashrc/zshrc for convenience: # Note the trailing slash (required) -export METAMODULE_ARM_NONE_EABI_PATH=/path/to/arm-gnu-toolchain-12.x-relX/bin/ -``` - - -### Automatically generated materials - -Several files are automatically generated using python scripts, e.g. faceplate -LVGL code. These generated files are already committed for a few reasons: 1) -the conversion process uses some specific external programs (inkscape CLI, and -a particular version of node); 2) generating all the assets takes a long time; -3) the assets don't change very often (if ever) and are completely orthogonal -to the code. Also conversion from SVG to PNG can generate a file that is -visually the same but has a different binary representation, causing lots of -noise in the git diffs. However if you wish to (re)-generate these files, the -following commands can be run: - +export TOOLCHAIN_BASE_DIR=/path/to/arm-gnu-toolchain-12.x-relX/bin/ ``` -# Generating LVGL image files for components -make comp-images - -# Generating LVGL image files for faceplates -make faceplate-images - -# Updating/creating 4ms VCV artwork SVGs files from *_info.svg files -make vcv-images - -# Updating/creating CoreModule *_info.hh files from *_info.svg -make module-infos - -# All of the above -make regenerate-all -``` - -If you just want to re-generate one image (that is, convert one SVG to a PNG and LVGL format), then you can invoke the python script directly. -Here are some examples. These commands can be run from anywhere, but for these examples we'll show it from the firmware dir: - -``` -cd firmware/ -``` - - -Make sure the output directories exist first: - -``` -mkdir -p src/gui/images/BRANDNAME/components/ -mkdir -p src/gui/images/BRANDNAME/modules/ -``` - -Convert a component SVG: -The first argument is `convertSvgToLvgl` which is the command to execute. -The second argument is the SVG file you want to convert. -The third argument is the path where you want the generated files to be saved. - -In the following example, two files will be generated in -`src/gui/images/BRANDNAME/components`: newcomponent.c and newcomponent.png. -Also, the component image struct will be named `newcomponent`, which is how the -code accesses the image. So, make sure the base name of the svg file is a valid C token -(doesn't start with a number, no special characters, etc). Look inside the generated .c -file if you want to see under the hood. - - -``` -../shared/svgextract/svgextract.py convertSvgToLvgl \ - path/to/newcomponent.svg \ - src/gui/images/BRANDNAME/components -``` - -Convert a faceplate SVG: -This is the same as converting a component SVG, except for Alpha blending is disabled, and the height is fixed at 240px. - -``` -../shared/svgextract/svgextract.py createLvglFaceplate \ - path/to/newfaceplate.svg \ - src/gui/images/BRANDNAME/modules/newfaceplate.c -``` - -Optionally, you can only export one layer from a faceplate SVG file by specifying the layer name as a 3rd argument: - -``` -../shared/svgextract/svgextract.py createLvglFaceplate \ - path/to/newfaceplate.svg \ - src/gui/images/BRANDNAME/modules/newfaceplate.c \ - artworklayer -``` - -The svgextract script can do more, to see its help and view available commands: - -``` -../shared/svgextract/svgextract.py -``` +Remember that arm-none-eabi-gcc v12.2 or v12.3 is required. diff --git a/docs/firmware-debugging.md b/docs/firmware-debugging.md index bb4f3e201..bee9e18b3 100644 --- a/docs/firmware-debugging.md +++ b/docs/firmware-debugging.md @@ -156,6 +156,37 @@ pin). The bottom four pins are all GND. Settings are 115200, 8N1. See image abov Use `pr_dbg()`, `pr_warn()`, `pr_err()`, and `pr_trace()` for debug output. These require the `pr_dbg.hh` header. +Make sure to set the console log level equal or lower to what you want to see. The levels are: + +- NONE (no console output) +- ERROR (pr_err only) +- WARN (pr_warn and above) +- INFO (pr_info and above) +- DEBUG (pr_dbg and above) +- TRACE (pr_trace and above) +- DUMP (pr_dump and above) + +To set the log level, configure with cmake like this: + +``` +cmake --fresh --preset full -G Ninja -DLOG_LEVEL=TRACE +``` + +The convention for each level is as follows: + +- Error: unexpected conditions that may lead to program failure +- Warnings: conditions that deserve attention but do not lead to program failure +- Info: Important or useful information that is neither a warning or error +- Debug: temporary messages used for debugging +- Trace: detailed log of execution +- Dump: large amounts of verbose data + +Debug (pr_dbg) is particularly useful to use ONLY when debugging. Then, when the +feature is ready to merge, it's easy to search for pr_dbg and remove all +instances (or selectively replace with a more suitable level). +This technique reduces clutter in the console as we continually add features. + + ## Notes diff --git a/firmware/Makefile b/firmware/Makefile index f94f5ce26..99c7d0091 100644 --- a/firmware/Makefile +++ b/firmware/Makefile @@ -14,11 +14,11 @@ configure: cmake --fresh --preset ${PRESET} -G ${GEN} -DLOG_LEVEL=DEBUG # Auto-complete these targets: -bootloader tests dep_tests simulate gen_minblep module-infos vcv-images comp-images faceplate-images flash-bootloader-sd flash-app-sd flash-dfu jprog debug start-jlinkgdb start-openocd flash_loader flash_loader_dfu new-api-sym-list: +bootloader tests dep_tests simulate gen_minblep flash-bootloader-sd flash-app-sd flash-dfu jprog debug start-jlinkgdb start-openocd flash_loader flash_loader_dfu new-api-sym-list: cmake --build --preset ${PRESET} -- $(MAKECMDGOALS) # Forward any other arguments %: cmake --build --preset ${PRESET} -- $(MAKECMDGOALS) -.PHONY: configure all bootloader tests dep_tests simulate gen_minblep module-infos vcv-images comp-images faceplate-images flash-bootloader-sd flash-app-sd flash-dfu jprog debug start-jlinkgdb start-openocd flash_loader flash_loader_dfu new-api-sym-list +.PHONY: configure all bootloader tests dep_tests simulate gen_minblep flash-bootloader-sd flash-app-sd flash-dfu jprog debug start-jlinkgdb start-openocd flash_loader flash_loader_dfu new-api-sym-list