...
You should be greeted with a bunch of installs- and this sets up the ESP32 specific tooling. In order for these changes to be recognized, you should deactivate and then reactivate the ner-venv. Also note, you may see some things “error”, but the install continues. This is generally okay, so feel free to ignore.
You'll need to then clone the launchpad repo - place it in the same NER folder described in the setup.
This repo has a “src” folder with a main file with an outline, and then some other miscellaneous files and folders. You shouldn’t need any files beyond this main.
| Note |
|---|
When testing with the magnet, do not let the 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
The repository contains some starter/outline code for you. There, the peripherals are initialized, and the thread/task outlines are provided. You may notice two tasks (or threads) have been created: one for Bluetooth, and one for polling the Hall sensor. In additional, you will see one interrupt handler for LED blinking. If none of that makes sense, no worries at all, just ask questions and we can explain what all of that means! When finished, you can also take a look at my completed example.
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.
...
| Note |
|---|
Depending on how many people participate, I may not be able to give everyone their own devboard. This means to test your code, you will have to stop by the bay during bay time or really whenever is convenient to test. |
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:
| Code Block |
|---|
lpbuild |
To upload the build code, run
| Code Block |
|---|
lprun |
To view the Bluetooth data, 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!
4. Tips/keep in mind
While it isnt conceptually important, ESP32 and freeRTOS specific syntax will be used in your code. I would piroritze understanding conceptually what you need to do - and then using online resources to figure out how to use their syntax to achieve that goal
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. You'll notice the starter code defines this as 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.
...
- inside of it are five files:
main.c - the application main code, with task/thread definitions and functional logic.
ble.h/.c - this is for some Bluetooth setup. I filled all of this in because its complicated and out of scope, you do not need to edit this at all. With that being said, feel free to look at it and try to make sense of it. Feel free to ask my if you have any questions.
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, ESP32, Bluetooth, and FreeRTOS 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 with some more function signatures that you have access to that I found necessary to complete the task.
| Note |
|---|
When testing with the magnet, do not let the 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
To complete this, find the comments labeled
| Code Block |
|---|
// TODO - |
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.
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 |
|---|
Depending on how many people participate, I may not be able to give everyone their own devboard. This means to test your code, you will have to stop by the bay during bay time or really whenever is convenient to test. |
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:
| Code Block |
|---|
lpbuild |
Your code may not compile due to user errors, but there is one error that you may encounter that wouldn’t be your code. Check the bottom of the Tips section below to see this
To upload the build code, run
| Code Block |
|---|
lprun |
To view the Bluetooth data, 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!
| Info |
|---|
While I’ve done my best to automate all of this to work on all platforms, some stuff eventually gets pretty messy. if any of the launchpad commands do not work - either ask someone for help or look into the aliases themselves and try to debug the error (they just alias to platformio commands) |
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. You'll notice the starter code defines this as 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.
Ex. for a ADC with 12 bit resolution:
The highest number that can be expressed with 16 bits is 2^16 = 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 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
(POSSIBLE BUILD ERROR THAT ISN’T YOUR FAULT)
When building, if you get this error:Code Block platformio run --target menuconfig
This should open up a menu. From there, navigate down to “component” and hit enter, and then navigate to “Bluetooth” and hit enter, and then hit enter on the Bluetooth option. Save and exit, and try building again.
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.