Skip to content

Creating an ato project

Project structure setup

To create a project, you can run the command

ato create

This command will start by asking for a name to your project. It will then clone the project template on github. Once created on GitHub, paste your repository URL into the command line. Your project should be up and running!

We also added a firmware and mech folder to store 3D designs or firmware associated with your project. Version controlling everything under the same project can be quite handy.


You can create your own project instead of using ato create. Perhaps you will want to setup the project and for it as you create your ato projects. Make sure to follow this project structure:

├── venv -> (active) virtual environment with python^3.11 and atopile installed
└── your-project
    ├── ato.yaml --> definition file for your atopile project
    ├── ato-lock.yaml --> file managed by atopile. Used to store automatically selected components + component position in the schematic
    ├── elec --> files related to your electrical design
    │    ├── src
    │    │   └── file.ato
    │    └── layout
    │        └── default
    │            ├── kicad-project.kicad_pro
    │            ├── kicad-project.kicad_pcb
    │            ├── kicad-project.kicad_sch
    │            └── fp-lib-table
    └── .github/workflows/ci_and_cd.yml file --> useful for running jobs automatically on your repo through github actions


Our template project contains example code for a github CI workflow to compile your ato files and access your manufacturing files from kicad. Find it here.

ato.yaml setup

The root of an ato project is marked by the presence of an ato.yaml file.

ato.yaml contains some project configuration information like the list of things you want to build. It's similar in concept to a package.json in js/node/npm land.

Here's an example:

# this line defines the version of compiler required to compile the project
ato-version: ^0.0.18
# those lines define the elements that will be built by the compiler
    entry: elec/src/your-project.ato:YourProject
# The compiler version follows semantic versioning. The required version to compile your project can be specified using npm's standard.

# Those lines define the package dependencies that your project might have. You can specify the exact package version you want using semantic versioning.
- generics^v1.0.0


The compiler version follows sementic versioning. The required version to compile your project can be specified using npm's standard. The same applies to your dependencies.

Building the project

To test that your project is building, run:

ato build


ato build will build the default module and kicad layout. You can specify a specific target with:

ato build --build [name_of_your_build]

The build name is defined in the ato.yaml file.

You should see a build directory appear in your project structure. This is where atopile places the output files generated from compilation.