Contributing

Whether you’re fixing bugs, adding new functionality, improving documentation, or creating your own projects, your contribution is highly valued and appreciated!

Getting Started
Styling Guidelines
How to Contribute
Roadmap

Getting Started

Before diving in, familiarize yourself with SensEdu:

Read through this wiki
Run basic examples and finished projects
Explore existing issues
Review styling guidelines

If you are still not sure what to do, feel free to open a discussion, and we’ll find a task for you!

Styling Guidelines

Please familiarize yourself with the following conventions to ensure styling consistency. It keeps the project manageable, easy to navigate for other developers, and make releases easier to create.

Code Style

The code style is documented per area, because the library, the sketches and the host scripts each have their own conventions:

Library Contributions: C sources, file and section layout, naming, namespaces, error handling, reference headers, register access, interrupts
Project Contributions: Arduino sketches, sketch skeleton, settings blocks, error handling, MATLAB and Python host scripts
Documentation Contributions: page headers, alerts, math, tables and page templates

4-space indentation is used everywhere, including .ino sketches, where the Arduino default is 2

Branch Naming

Follow the format:

<type>/<issue-number>/<short-name>

Try to avoid creating a branch without a linked issue. If you must, follow the format:

<type>/<descriptive-name>

Types

pcb: Hardware design
lib: STM32 library
proj: SensEdu projects
docs: Website or README documentation
deploy: Website deployment

Good Examples

proj/7/record-audio
lib/13/dma-integration
pcb/34/tweak-rx-schematics
docs/10/web-emg-page

Commit Messages

Follow the format:

<type>: <subject>

<optional body>

Subject line: maximum 50 characters, use imperative (“Add” not “Added”)
No period at the end of subject line
During PR review, reference the PR number in subject line

Types

feat: New features/additions
fix: Bug fixes and other broken behaviour
refactor: Code or project restructuring
docs: Website or README documentation

Commit types describe the kind of change. Branch types such as pcb, proj, lib and deploy are reserved for branch names and do not appear in commit subjects (docs is the only type valid in both).

Good Examples

# New lib feature:
feat: Add ADC3 support

# PCB design:
feat: Draw power supply schematic

# Docs editing:
docs: Finish EMG implementation section

Document hardware setup
Explain RC values for amplifier circuit
Add data acquisition code snippet

# Bug fix:
fix: Rewrite ADC polling

Fix improper ADC initialization in CFGR1 register

# PR review:
refactor: Rename lib example (#90)

Rename `adc_Record` to `ADC_Record`

Pull Requests

Keep PRs small, focusing on one feature or fix per PR. The PR title follows the same <type>: <Descriptive Name> format as a commit subject. Before requesting a review, make sure that:

The code follows the style guidelines above
The code compiles and new additions are tested on hardware
Library changes do not break any of the existing examples in libraries/SensEdu/examples/
New functionality is documented on this website, see Documentation Contributions

How to Contribute

Report Bugs

Found a bug or unexpected behaviour? Help us fix it:

Search for existing issues to avoid duplicates
Create a new issue with bug label, providing:
1. Steps to reproduce
2. Expected vs actual behaviour
3. Screenshots, logs, oscilloscope waveforms or any additional data

Suggest Features

Have an idea for a new sensor driver, project or optimization?

Create an issue with the enhancement label:
1. Describe your idea in detail
2. Provide some usage examples

Improve Documentation

Clear documentation is essential for our educational purposes, help us:

Fix typos or grammatical errors
Clarify ambiguous explanations to ensure everything is easy to understand
Fill in missing explanations

Check Documentation Contributions for detailed instructions.

For educational purposes, the documentation is aimed not only at developers but at beginner students as well. Try to avoid logical skips, use simple language, and add diagrams, images or code examples!

Improve Code

If you are an experienced embedded systems developer, feel free to optimize library code for better performance.

Review the library wiki section and Library Contributions
Assign yourself an issue to ensure collaboration with others who are working on the same feature and to avoid duplicates
Create a fork and develop your feature
Submit a Pull Request (PR) and ask for a review

Check the Pull Requests checklist before asking for a review.