Skip to content

Project structure and GitLab workflow

Good project structure makes it easier to collaborate, debug, and hand in your work. This page suggests a simple layout and workflow for Arduino/ESP32 projects using GitLab.

1. Suggested repository layout

For a typical course project, use a structure like this:

your-project/
├─ embedded/
│  ├─ hello-world/
│  │  └─ hello-world.ino
│  ├─ test-sensor-x/
│  │  └─ test-sensor-x.ino
│  ├─ test-sensor-y/
│  │  └─ test-sensor-y.ino
│  ├─ project/
│  │  └─ project.ino
│  └─ libraries/        # optional: custom code shared between sketches
├─ docs/
│  ├─ ...
└─ ...

Guidelines:

  • Keep each sketch in its own folder inside embedded/.
    • To test a sensor or actuator, write and store a sketch in a dedicated folder. This is a good way to test the sensor or actuator before using it in the project.
  • Store wiring diagrams, photos, and documentation in docs/.

Tracking versions of your sketches

Instead of keeping many copies like code_v2_final_definitive.ino, let Git handle history:

  • Keep the current version as main.ino or project.ino in a folder.
  • Use informative commit messages to track changes.
  • Optionally tag important milestones (e.g. v1.0-demo).

This makes it easier for others (and your future self) to see how the project evolved.