Software/Arduino Core/Reference

Contributing

How problems are reported and changes submitted to the Neuro N6 Arduino core, and the house style the repository enforces.

intermediate2 min read

The core is developed in the ohmlab-ltd/stm32n6 repository. Its CONTRIBUTING.md sets out the reporting and review process summarised here.

Reporting a problem

An issue includes the board revision, the core version shown under Tools > Board, the Arduino IDE version, the output of arm-none-eabi-gcc --version, and the full build or serial output. A minimal sketch that reproduces the problem is preferred to a description.

Before a pull request

The same checks CI runs are run locally:

bash
python tools/check_ascii.py
python tools/build_all_examples.py --out after.json

A change to the core is compared against a build of main:

bash
python tools/build_all_examples.py --compare baseline.json after.json

A change described as cosmetic must produce byte-identical binaries. The build script compiles all examples serially, because the platform purges a shared core archive per build and parallel jobs drop model symbols. It fingerprints the unsigned .bin and the .elf, never the signed image, because the signing tool writes a fresh signature on every run.

House style

  • Source is ASCII. No em dashes, smart quotes or box drawing characters. tools/check_ascii.py rejects non-ASCII, byte order marks, CRLF line endings and NUL bytes outside the vendored trees.
  • Two-space indentation, LF line endings, K&R braces, per .editorconfig.
  • Comments state what the code does, in one line where possible. History belongs in commit messages; background belongs in this wiki.
  • Examples follow the Arduino writing style guide: a short title block, then inline comments written for a beginner.
  • Libraries follow the Arduino library specification: library.properties, src/, examples/, keywords.txt.

Third-party code

Vendored code is recorded in extras/THIRD-PARTY.md with its upstream, version, licence and any local modification. Local edits to vendored files are marked in the file. The vendored path list in tools/check_ascii.py is updated when a tree is added or moved.

Two libraries in the 1.0 library layout

tools/check_arduino_spec.py warns about two libraries whose sources sit at the library root. Both are deliberate. VL53L1CB holds ST's driver in subdirectories that the 1.0 format does not compile, so 79 one-line include shims at the root pull them in; restructuring would complicate the next update from ST. MMC5603NJ is GPL-3.0 code by a third party and is bundled unchanged.

Continuous integration

Two GitHub Actions workflows run on each change: one compiles every example, the other runs Arduino Lint.