Overview

As a team, with each new design cycle, we create new PCBs to add to the bike, each of which needs firmware to run. We organize this firmware by creating a repository corresponding to each PCB. For consistency, we want all the repositories to have a similar folder structure and compilation behavior. To accomplish this, we use a project template repository to start projects off and make changes that can be merged into all the projects. After the repository has been made, boards diverge in code pretty quickly, but there are a few steps of the organizational process that are shared across boards. While no part of this process is complicated, it is extremely important that these steps are followed closely because any failed communication at this stage can result in hours of work in the wrong direction.

Steps

Set Up Trello

The very first thing you should do when starting a new project is set up the Trello board to support it. Although it's not the most fun thing to work on, having clear communication, especially at the beginning of a project, can ensure everyone on the team knows what the new PCB, why we need it, and how we're progressing with it. The basic setup for the board should start with three cards:

1. Project Epic Card

   1. Stays in the Project list and is used to reference all the other cards for that project

   2. Briefly describe the PCB's use for the team

2. Repo Setup Feature Card 

   1. Card for tracking the setup of the new repository

   2. The steps for completing this step are described in the next section

3. State Machine Admin Card

   1. Card for tracking of the development of a state machine for the new PCB

   2. Most PCBs should have a state machine, although some behave simply enough that they don't really need one

Once these cards have been created, you should be able to continue on, but there are a few more things to remember. First, toward the beginning of a project, you will likely be getting a lot of new information about how the PCB should eventually work. Even if it's not immediately important, you should create a Trello card for every feature you think the board needs, so the team has a reference for the future. It may seem like a lot of documentation at the beginning, but it will save a lot of confusion in the long run. Also, be sure to put the link for every Trello card you make into the Project Epic. If any cards aren't added to the Epic, it's much more likely we will lose track of them and fail to develop a feature. 

Create the Repository

Once the Trello board is set up, you can actually get started on setting up the code. As described above, this repository should be made using the project template that the team has developed for this process. The README, which can be viewed on the GitHub page, provides a description of how to use it to create a new repository. Because it takes so much work to update all the repositories when the template changes, we will likely not update this repository very often, but be sure to check if there are any open Pull Requests or branches in the repository. If there are, check with the firmware lead before continuing to be sure you're not creating a new project right before the template changes, so you don't have to redo any work. If you do have to wait, you can always create a temporary branch off of EVT-core to do some basic testing despite not having a repo to work in.

Meet with the Electrical Team

The last step is your initial meeting with the electrical team working on your board. Although you will have to meet with the team many times to double-check things, clarify points, and give them information about what the firmware team needs, the first meeting you have with them is important because of how much information you need to collect. In general, you want to ask them every question you can come up with to ensure you have a clear understanding of the PCB, so you can explain the board to other people, but there are a few key things to ask about:

• At a high level, what does the board do for the bike?

• Does the board have JTAG/SWD and UART?

  • If it doesn't have one of these, be sure to let them know that they are practically required for development.

  • If they don't' have enough pins to support one or both of these, reach out to your firmware lead to see if there's any way to get around using them.

• What communication protocols does board use?

• What devices are on the board that will need drivers?

  • Ask for datasheets for each of the devices.

  • Also be sure to ask if they can get breakout boards or EVMs (EValuation Modules) that we can use for driver development.

• What other boards does the board communicate with?

• What CAN messages does it need to send and receive?

• Does the board have multiple states, or does it just operate in the same way the entire time?

  • If it has multiple states, you should work with them to develop a state machine.

The electrical team likely won't have all the answers you're looking for the first time you talk with them, but you should work closely with them over the following weeks to get all the answers you need. Clear communication between the electrical and firmware teams is crucial for our overall success.