Launchpad is our effort to help new members get acclimated with some of the skills they may use on our team. It is absolutely not going to teach everything, but its meant to be a small project to pick up as your first ticket on the team that will incorporate the general kind of coding that you may become familiar with.
Full disclosure: the boards + environment used here are ESP32s - we do not actually use them in NER (instead, currently all of our boards are STM32s). The tooling here is quite simple, but don't be surprised if its a bit different than what you use after completing this. Similarly, ESPs are known for their Bluetooth capabilities - and while our car doesn't use Bluetooth, I thought it would be really cool to take advantage of it here. Again, this is just supposed to be a fun intro into embedded development that is a little bit more advanced than what you may see in a class like cornerstone- nothing more. Have fun and please ask questions as they come up! We will have dedicated time in the first several meetings of the semester to talk about this, but please slack us anytime throughout the week as needed!
1. Setting Up
...
Introduction
Welcome to the Northeastern Electric Racing Embedded Software Launchpad! Launchpad was designed to teach new members the skills they need to excel on the embedded team in a scalable, paced, and fun way. This semester, you will be designing a virtual car with wireless telemetry on an embedded system using the methods and tools that we use on this team. By the end of Launchpad, you will be able to actively contribute to the code that will be running on the car, and you will have learned key skills for working in industry.
Launchpad is broken up into multiple steps to keep learning happening at a steady pace and provide students with a direction from week to week. It is expected that each step is completed by the week specified in the schedule, however it is ok to fall behind and/or complete Launchpad late. What matters is that you complete Launchpad and understand the concepts of embedded programming that are essential to contributing to this team. To keep up with Launchpad, it is expected that you will attend team meetings and bay times while you are still learning to learn more about the team, touch base with leads on progress, and ask any questions you may have. Launchpad will be conducted through GitHub Classroom, a service provided by GitHub that allows for students to upload their code to be reviewed by leads at every step of Launchpad. Since you will be programming an embedded system, you will need to venture to the bay, which is in the basement of Richards Hall (054), to test your code on the club’s ESP32 microcontrollers. Note that hardware access will be limited, especially during bay time, so students should plan to test their code at times other than bay time, and they may reserve time with hardware in the team’ Slack channel (#fw_launchpad).
Environment Setup
Before any coding can happen, you first must set up your development environment. A development environment is a virtual workshop where all the tools needed to write code for this team are located. Follow the instructions on this page to set up your dev environment, and make sure you do the part where it says to set up a shell alias.
1. Setting Up
To do the final preperations, in your terminal (with the venv active), simply run
...
2. Clone the github classroom repo.
TODO: INSERT 2025 Linkhttps://classroom.github.com/a/T9csPaFk
main.c - the application main code, with task/thread definitions and functional logic.
...
api.h/.c - These are the function calls you may need to use. While you should be able to complete the task using just this and other simple calls, you do not necessarily need to if you do not want. The purpose of this was to hide some of the messy syntax from you, and instead provide more clear APIs. Again, you do not need to edit this, but I encourage you to see what these do, since you' have to make calls to these functions. On top of the APIs defined there, I’ve included a comment in api.h with some more function signatures that you have access to that I found helpful to complete the task. Note: I did not create APis to hide FreeRTOS stuff, since you should become familiar with them !
| Note |
|---|
When testing with the magnet, do not let the metal magnet touch the board. It is a big piece of metal, and can short components together. It doesn't need to be too close to work! |
That’s all for now !
2. Create the app
Your goal is to create a simple application that utilizes a few of the tools embedded into the ESP chip:
Bluetooth
Hall Effect Sensor (magnetic field strength)
This application, running freeRTOS, should:
continuously read magnetic field data
blink an LED based on the strength of that field (stronger field == faster blinking)
Utilize an interrupt (ISR) to trigger the LED blink
Broadcast the raw data over Bluetooth
Broadcast this data over serial monitor
To complete this, find the comments labeled
...
This indicates some functionality that you must implement - and usually follows up with an explanation of what needs to be done. This should be doable with only the API functions in api.h/.c, the other function signatures shown in a comment within api.h, and some simple C logical code. You do not need to edit anything that isn't given a “TODO” comment
That's all! You are not expected to necessarily know anything about freeRTOS, interrupts, or any of these skills; Just because I haven’t in detail explained these things in this doc does not mean you are expected to understand it. I literally am keeping these instructions somewhat vague intentionally to ensure I don't sway you towards doing this a certain way, because there are multiple ways to do it. Ask questions, do some individual investigation, or use whatever tools you want to help. freeRTOS and interrupts are used extensively in our vehicle apps, so getting some experience with them here will help out.
3. Testing
| Note |
|---|
I may not be able to give everyone a board. Whether you get a board or need to come to the Richards makerspace to test, you'll need to connect to an external LED, which will be setup in the makerspace, to view that component of the output. If a breadboard with an LED is not setup when you go down, feel free to skip this part in testing (I will still check code for the functionality), or challenge yourself by building your own breadboard setup. It only takes 3 components: a breadboard, an LED, and a resistor! |
You’ll need a micro-USB cable to connect your laptop to the device. If you don’t have one around, stop by the Richards Makerspace and test it with one of ours down there.
Once your code is ready to build, and assuming you’ve run “launchpad install” in the venv, you can do so with the following command:
...
To upload the built code to the board, connect over MicroUSB, and run
| Code Block |
|---|
ner lp flash |
...
To view the Bluetooth data (optional until later on), download the NRF connect app on your phone. In the scanner, you should see an ESP device. Connect to that and you should be able to see the message!
Similarly youInfo
4. Tips/keep in mind
The value returned from the sensor is a raw ADC value. This means it is a unitless value, understood as a strength “percentage”. To understand this value, the resolution of the ADC needs to be known. For this device, the default resolution is 12 bits. This value is simply the number of bits used to depict this percentage - the more bits, the higher the precision you are able to achieve.
...
The highest number that can be expressed with 12 bits is 2^12 = 4096. A raw ADC value of 2048, for instance, means 50% “strength”. Really, its just looking at this value as a percentage of the resolution.
The hall sensor normally would need to be calibrated to account for the ambient magnetic field in your environment. Doing so is out of scope of this task, so don’t worry about it too much, just try to set it up so that the light does not blink much at the reading level it gets without the magnet nearby. Depending on your environment, this might be at different reading values. All apps have the same ADC resolution, but you may read stronger or weaker fields, which is okay. Regardless, the strength should increase as the magnet gets closer. To test this, you may want to simply guess and check - you should incorporate some sort of “offset” ADC value, where the LED doesnt/barely blinks if the reading is as low as you record when no magnet is nearby. Also, it doesn't need to be extremely precise. Maybe you only have 2 or 3 blink speeds for strength ranges - this doesn't need to be a continuous and fine grained speed increase for every tiny change in field strength
When Using multiple threads like in an RTOS application, data atomicity is important. If a piece of data is accessed from multiple threads, it is important to use a locking mechanism, like a mutex or semaphore, to make sure that sharing this data is done safely
Explore your tools: We use the dependency command
platformio. The abovener lpcommands are simply shortcuts. Feel free to try otherplatformiocommands to further test, debug, or learn more about what you are building.
Ok you know all of the basics, check out Part 1 to get started!
| Child pages (Children Display) | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Again, please ask questions! Bay times and meetings will dedicate time for launchpad discussions, if you are new to embedded, this stuff may seem really confusing and we are here to help make it less daunting.
...
If you have questions out of a meeting, ask on #fw_launchpad