Skip to main content

Project Setup

Setup Your Project Directory Structure​

This tutorial will show you how to generate and run a Qroma project to define your app commands and messages, integrate them with your device firmware, and then use serial communication )over USB) to interact with a Python PC app and a web browser. It assumes you have Visual Studio Code installed, though any text editor will do.

Setup​

We're going to generate a new Qroma project using the Qroma CLI. We have a convention for using a : prefix for our project identifier so that qroma can find our projects in a special $HOME/qroma-projects directory. If you don't use the :, your commands will happen relative to the directory your CLI is in (if you are in a project subdirectory, the qroma command will look in parent directories until it finds a qroma.toml file, which identifies that directory as a qroma project root).

We're going to create a project structure with the name my-qroma-project. Run the command qroma new :my-qroma-project. This will download a template project directory, put your project name in place, and (on Windows) open your project root directory.

From the command line, navigate to your new project directory, e.g. cd my-qroma-project or

cd $HOME
cd qroma-projects
cd my-qroma-project

Single command setup​

For the purposes of a tutorial, it's best to not run the command below now. Since it does all the setup steps at once, we won't be able to break them down piecemeal to get an understanding of what's going on. However, once you're comfortable with what qroma does for you, it's handy to know that this exists.

To simplify testing our project workflows, we have added a lot of command line options when creating a project. The command below will let us set up a project and have the equivalent of Hello, world running in a few minutes.

qroma new --replace-existing --full-build --do-git-prepare --run-site :$PROJECT-ID

And some flag explanations:

  • --replace-existing - delete the current project directory and put the new project in its place
  • --full-build - BUILD EVERYTHING! This means build the protocol buffer outputs, the firmware binaries, and the website contents
  • --do-git-prepare - Add a git commit message after initial project template creation, then another after the site build step and files are auto-generated.
  • --run-site - Run the project website which lets you install the firmware to your board. After that's done, you can send and receive protocol messages with your board.

Directory structure​

Looking at the project root directory, you can see there is a lot going on. Here is a quick overview of what's in there.

  • qroma.toml file - config file for your project
  • protobufs directory - where the Protocol Buffer definitions that connect your applicatons are stored
  • firmware directory - default location for your project's embedded device applications
  • apps directory - default location for your project's PC apps (smartphone apps yet to come)
  • sites directory - default location for your project websites
  • manufacturing directory - default location for physical aspects of the project (e.g. PCB, 3D printer, parts lists, etc.)