Contributing

Contributing to the project

Thank you for your interest in contributing. The project is open source and contributions of every kind are welcome, from fixing a typo in the documentation to implementing new diagnostic modes.

Ways to contribute

• 🐛 Bug report - open an Issue with the bug label.
• 💡 Feature proposal - open an Issue with the enhancement label, but check the wish list below first.
• 🔧 Code - a pull request following the instructions below.
• 📖 Documentation - improvements to the wiki, to the assembly instructions, translations.
• 🔬 Testing - compatibility reports for diagnostic tools we have not tested are very valuable (state the tool model, the simulator firmware version and a traffic capture if possible).

Bug report - what to include

1. Hardware configuration: the build (breadboard with the module on an adapter, or the dedicated board), and the board revision.
2. Firmware version (git commit or release tag).
3. Steps to reproduce and expected versus actual behaviour.
4. For protocol problems: a CAN traffic capture (candump or an analyser) or at least a hexadecimal dump of the request and the response, plus the diagnostic tool model.

Pull request procedure

1. Fork the repository and create a branch from master, which is the default branch:

   git checkout -b feature/mode-06-support

2. Follow the code conventions (below).
3. Run the unit tests, all of them have to pass:

   pio test -e native

   Changes in the can and obd modules have to add tests for the new behaviour (range edge cases, negative responses).
4. Check that the firmware compiles for the hardware environment custom-board and that the native environment still runs the tests.
5. In the PR description state what changed, why, and how it was tested (including testing on real hardware where applicable).
6. One PR = one logical change. Smaller PRs are easier to review and get merged faster.

Conventions

• Language: all code, identifiers, comments and commit messages are written in English. The project documentation (wiki, guides) is available in Croatian and English.
• Standard: C++17, no exceptions and no RTTI, no dynamic allocation in the hot path of CAN traffic handling.
• Architecture: respect the split into modules (can, obd, sim, ui, storage, hal) and the communication between FreeRTOS tasks exclusively through message queues. Access to the SPI bus only through the HAL mutex.
• Protocol: all constants and formulas of the SAE J1979 / ISO 15031-5 standards live in the obd module. Do not copy the text of the standards into the repository, they are copyrighted.
• Commit messages: imperative, English, for example Add mode 0x06 monitor test results handler.

Hardware contributions

• Schematics and PCB are edited in KiCad, and an updated Gerber/PDF export goes together with the change.
• Regenerate the derived files and commit them with the change. After anything that touches the board or its routing, run hardware/kicad/scripts/regen_outputs.ps1. That single command refreshes the Gerbers, the fabrication package, the dimensioned drawing, the interactive board view and both 3D renders, hardware/kicad/render-top.png and render-bottom.png. The renders are embedded in hardware/README.md, so a pull request that changes the board without them shows a picture of a board that no longer exists. A re-route changes both sides, an edit to the silkscreen alone changes only the top one.
• With every schematic change, check the rules written down in /hardware/README.md and in /hardware/kicad/PRE-FABRICATION-CHECKLIST.md. Two of them were learned the hard way:
  • peripheral interrupt pins (for example CAN INT) must not be shared with other signals (in earlier revisions that fault was caused by the interrupt of the touch controller, removed in v0.4),
  • analogue inputs (the axes of switch SW6) have to stay on the ADC1 converter channels (GPIO1-GPIO10), encoder ENC1 is digital and uses GPIO1, GPIO38 and GPIO39, the strapping pins (3, 45, 46) and the flash/PSRAM range (GPIO26-37) are avoided, and GPIO0 carries only the BOOT service button (SW4) in its standard role.
• Mark new board revisions incrementally (v0.7 → v0.8) and document the changes in the revision changelog.

Wish list (roadmap)

Directions for further development you can join:

1. The UDS protocol (ISO 14229) - advanced diagnostics beyond the emission-mandated set of services.
2. Multiple ECUs at once (0x7E8-0x7EF): engine, transmission, ABS, each with an independent fault bank.
3. Remote scenario control over Wi-Fi (a web interface or a REST API), useful for automated testing.
4. Modes 0x06 and 0x0A for full SAE J1979 coverage, and CAN FD support.
5. Recording and replaying traffic from a real vehicle (logging and replay).

Before starting work on a larger item, open an Issue so we can align on the approach. It would be a shame for two people to do the same thing in parallel.

Contribution licence

The project is licensed under the MIT licence (the LICENSE file in the repository root). By sending a pull request you accept that your contribution is published under the same licence. MIT allows use, modification and distribution (commercial as well) as long as the attribution notice is kept. It was deliberately chosen as the simplest widespread licence, to keep the barrier to picking the project up and extending it as low as possible.

Community conduct

Be polite and constructive. Code reviews comment on the code, not on the person. Beginner questions are welcome, everyone started somewhere.