Development¶

Contributing guidelines¶

This is a learning project.
People have different usage scenarios, UI preferences, etc. It is not possible to fit everything into a single firmware.
All feature requests, ideas, observations, questions and answers should go into the Discussions section.
Issues should be used only for bugs and planned tasks.
Pull Requests are not guaranteed to be accepted, unless the maintainer(s) consider them suitable for the majority of users. Documentation, bugfixes and code quality improvements are usually welcome! If in doubt, please propose your contribution as a Discussion first.
You are encouraged to make your own custom firmware forks! Feel free to share a link to your firmware version in the Discussions. Interesting features or color themes might be included into the ATS Mini firmware.

Video tutorial¶

A short video tutorial on how to build a custom firmware version:

Compiling the source code¶

Install Arduino CLI.
Go to the repository root folder
Compile and flash the firmware

arduino-cli compile --clean -e -p COM_PORT -u ats-mini

Compile-time options¶

The available options are:

DISABLE_REMOTE - disable remote control over the USB-serial port
ENABLE_HOLDOFF - enable delayed screen update while tuning
HALF_STEP - enable encoder half-steps (useful for EC11E encoder)

To set an option, add the --build-property command line argument like this:

arduino-cli compile --build-property "compiler.cpp.extra_flags=-DENABLE_HOLDOFF" --clean -e -p COM_PORT -u ats-mini

Enabling the pre-commit hooks¶

Install uv https://docs.astral.sh/uv/getting-started/installation/
Run uv sync
run uv run pre-commit install --install-hooks

Using the make command¶

You can do all of the above using the make command as well:

ENABLE_HOLDOFF=1 PORT=/dev/tty.usbmodem14401 make upload

Adding a changelog entry¶

Install uv https://docs.astral.sh/uv/getting-started/installation/
Run uv sync
Create an entry:
```
uv run towncrier create --edit ID.CATEGORY.md
```
ID is an issue or a PR number, or +STRING if there is no issue/PR. CATEGORY is one of added, changed, fixed, etc. see the tool.towncrier.type sections in the pyproject.toml for the full list.

Improving the documentation¶

Install uv https://docs.astral.sh/uv/getting-started/installation/
Run uv sync
Run a local webserver uv run sphinx-autobuild docs/source docs/build and open the http://127.0.0.1:8000 in a browser
Edit the Markdown files in docs/source folder and immediately see your changes reflected in the browser

Theme editor¶

A terminal command T toggles a special mode that helps you pick the right colors faster without recompiling and flashing the firmware each time. When the theme editor is enabled, some screen elements are always visible (and the battery indicator switches its state every 10 seconds):

Press @ to print the current color theme to the serial console:

Color theme Default: x0000xFFFFxD69AxF800xD69Ax07E0xF800xF800xFFFFxFFFFx07E0xF800x001FxFFE0xD69AxD69AxD69Ax0000xD69AxD69AxF800xBEDFx0000xF800xFFFFxBEDFx105BxBEDFxBEDFxFFFFxD69AxF800xFFE0xD69AxFFFFxF800xC638

Then copy the theme to your favorite text editor, change the colors as you see (here is a handy 565 color picker).

To preview the theme, paste it to the serial console with the ! character appended:

!x0000xFFFFxD69AxF800xD69Ax07E0xF800xF800xFFFFxFFFFx07E0xF800x001FxFFE0xD69AxD69AxD69Ax0000xD69AxD69AxF800xBEDFx0000xF800xFFFFxBEDFx105BxBEDFxBEDFxFFFFxD69AxF800xFFE0xD69AxFFFFxF800xC638

Once you are happy, add the resulting colors to Theme.cpp.

Release process¶

Bump the APP_VERSION constant in the Common.h file
If the new version has a different EEPROM layout, bump the EEPROM_VERSION as well (it will force the EEPROM reset)
Generate the CHANGELOG.md by running uv run towncrier build --version X.XX
Add and commit the changes with a message like “Release X.XX”, then push them to the repository
Once the build is complete, download, flash and test it!
Tag the release and push the tag git tag -a vX.XX -m 'Version X.XX' && git push --follow-tags (the tag should start with v!)