Skip to content

Commit

Permalink
Update README (remove unused make targets)
Browse files Browse the repository at this point in the history
  • Loading branch information
@danngreen
danngreen committed Sep 26, 2024
1 parent 242e6bf commit a335a61
Show file tree
Hide file tree
Showing 3 changed files with 43 additions and 133 deletions.
141 changes: 10 additions & 131 deletions docs/firmware-building.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,57 +21,23 @@ 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))

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

Expand All @@ -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
Expand All @@ -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.


31 changes: 31 additions & 0 deletions docs/firmware-debugging.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions firmware/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

0 comments on commit a335a61

Please sign in to comment.