The Essential Details of ESP32 Hardware Debugging

hello and welcome to another sunny day in thailand in early february sadly for me the sun is going through the sky higher and higher every day so i've i've lost my winter peak here and i'm starting to come back down in terms of my solar generation because the angle is too sharp but we're not here to talk about that today we're talking about how to debug esp32s so let's get to that [Music] so i haven't made a video in a while because i've been making slow but steady progress on my pm32 pollution sensor module it's going okay uh i'm at about 4 000 lines of code in this thing and i'm starting to push the boundary of the flash memory and the ram which is a little troubling uh also i'm getting tired of debugging by serial.printline statements it's just not efficient it's a big waste of time you can't it's not interactive i can't look at a variable just because i feel like it during execution of the code so the industry has provided a solution for this in the past in the form of hardware debugging and alert viewers remember my earlier project of the dc vccb for the battery pack in my electric motorbike which is a project that is stalled but i hope to get back to it but this is based on an atmel chip the atsam c c 18 something something i've forgotten but the one thing i like about the entire atmel universe is their hardware debugging is beautiful it it works it's fast it's complete it does everything that you could possibly want it to do it's wonderful uh now so i'm living in the world of esp32 now with uh this guy and some other projects that i've got lined up because i like the fact that um when i write some code it tends to work i'm not fighting the development tool like in the atmel world i just despise their development tool and the framework it's buggy it's not documented well forced me into this world now that's all great except i have not investigated hardware debugging in the esp32 world yet so i uh started working on a logging feature where i would log any issues that came up in the code and because i'm so memory constrained i didn't want to do it with strings and i'm writing into the spiffs file system in a logging file i didn't want to use strings because the string object is just destructive in memory so i wanted to use arrays of characters with a null at the end and manage them in a circular buffer it's almost impossible to try and debug that with print statements it's just not viable so i started looking at hardware debugging possibilities my searches had me end up with this board it's called the esp prog it's actually made by espressif the people that make the esp32 module so you've got to think they've done it right it's got a number of uh ports and cables that come in the kit and this the esp32 world is based on the jtag standard jtag as there's essentially every hardware vendor has their own debugging standard like like the uh the atmel guys here right but jtag is somewhat standardized uh but getting a piece of hardware that helps me implement uh real-time in-circuit debugging it's only half the story i need a piece of software running on my windows machine that talks with this board that lets me look at the code step through look at variables set watch points look at blocks of memory look at various other things that i need in the code and the arduino ide is not it i started off in arduino as do most people but it's a pretty terrible programming editor for one it has no hardware debugging capabilities so it's very easy to need to jump to the next level of functionality and my searches for that led me to platform io so let's talk about platform io so here's platform io it's basically implemented as a plugin to visual studio and gives us the ability to write internet of things applications across many many different chips and runtime environments and if we go over here to platforms and we click on embedded there's something like over 30 different chip families that this supports and they're all by plug-in there's my atmel sam that i gave up on and here's my espressif 32 which is the esp32 is esp8266 along with all the others if we go over here to frameworks these are all the runtime environments that the chip will be executing upon and we can directly build arduino-based solutions within platform io and it kind of looks and feels a lot like the arduino ide on steroids but it gives us the same programming framework to work in so you can bring your arduino code seamlessly over here or you can work directly with an underlying operating system like free rtos and if we click on boards you can see there are over 800 boards that are currently defined and then you can make your own if you want to and we just when you choose your project you just choose from this and move forward now i'm not going to go into how to install visual studio and then install platform io on top of this because there's too many great videos out there already andreas the men with the swiss accent has a fantastic one i'll provide a link to for that to you andreas also provides a link or a video about debugging with the esp prog board to one of his test boards and that's where i ran into my problems because in his video he just connects some things up that he doesn't show the wire for and then it just works and that did not happen for me and in the course of trying to solve my problem of getting the code uploaded and actually begin hardware debugging i learned a lot about how the underlying setup must be done uh both in the wiring and the setup of your development platform to get this all to work there are some things that you absolutely need to have exactly correct there are some optional things but i'm going to spend this video outlining those details to you because i found i never learn more than when something doesn't work right the first time that forces me to learn actually how it works so that i can solve the problem and move forward so let's start jumping into that okay so the esp prog board contains an ftdi chip with two serial ports in it and for it to work properly with platform io debugging we turn one of those serial ports and we install a different driver to make it look like a standard com port on interface zero on interface one we just leave it alone that's exactly what platform io needs to do debugging so you bring up your device manager and you see this now what you're going to see is after my configuration has been complete so you'll see i now have a usb serial port and i have this thing called a dual rs232-hs this is what you want it to look like at the end of the process to make this happen you go to this website zaddig.akeo.ie you download this little utility it's open source you can check the source code to your heart's content now you run zadig and it brings up this user interface the first thing you do is click options list all devices it will show all the usb devices that are connected to your board to your computer and we see the interface 0 and interface 1 of the dual rs232-hs these two interfaces are the two ports in the ftdi chip of the esp prog what we do is we take interface 0 and we install the win usb driver to it so since i've already completed that it is showing me currently my driver is win usb on a fresh install this would say ftdi something something something you would come over here and you would select win usb and click reinstall driver it actually takes a surprisingly long amount of time maybe about 30 seconds at this point you will see the device come up as a serial port make a note of this com port number because you will need that later you will still see interface 0 is remains with its original ftdi bus definition do not replace its driver so exit out of that and you should see one serial port with a com number and one remaining dual rs3232-hs board okay now that we have our windows driver set up we need to wire the debug board to our target board and that is done through this connector and most of the kits that come with this board provide these ribbon cables which plugs in here and this end is meant to plug into your target board but your target board probably does not have this so in this video demonstration i'm going to be using two different board types one is this board which is called a do it esp32 dev kit v1 which is basically an almost bare bones esp 32-room 32 module which is exactly the same module i'm using on my board and my board that i built tentatively called esp32 mango because mangoes are tropical and i like mangoes so what you need to do is wire the pins over from here to your board there are four important wires you must get them absolutely correct i o pins 12 13 14 and 15 you can also pick up 3.3 volts and ground which will let you power up your board right from here without any additional power supply so what i did is i made up this cable which is a strip of jumper wire and focus so i constructed this l shape with super glue and tape do not try to put shrink wrap around here because it'll melt the connector don't ask me how i know this this is 3.3 volts in ground and then those are the four gpio wires those break off here 3.3 volts and the the four i o pins and i've labeled them for my own use in the future because there's nothing like not being able to find a cable or not knowing where it goes or how it works or which one worked and which one didn't so i've taken to labeling wires that work for a particular scenario so i'm going to unplug this what you do is you plug the your homemade cable into the power ground and the top four signal pins there so you should have two pins at the bottom which are not connected on the the whole bottom row is not connected but they are connected at the top row focus anyway so now i can plug this in and i'm powering my board and i also have the ability to flash code and do hardware debugging through here i also made up yet a different cable for that it board which i bought off lazada but it was advertised as an a node mcu-32 which it's not it's actually this uh doit board and i made up its own cable for this it has the same l shape here plugs in the same way plug it in here and i'm now powering up this board i can push firmware to it and i can hardware debug through it now the cool thing with this setup is it's usb cable to esp prog to your target board that's it one thing that i found with the i watched about a dozen youtube videos nobody actually showed the wires of a working system what i discovered is some people have a serial usb cable plugged in here for hardware debugging and a serial a usb cable plugged in here for firmware update and i thought well that's a bit of overkill let's see if i can get it all done with one wire one connector and i have that capability now so we are now complete with step two we have our board wired into our debugging system okay so the third and final step of writing code uploading firmware and hardware debugging is working within platform io for your project i will very quickly walk you through the new project step and then show you the details of how everything works so we'll create a new project uh we'll call it debug test and then you get to select a board so the one i'm using now is called the do it and it actually is recognized the do it esp32 dev kit v1 you can choose to put it in your own directory if you want that's fine we come over here you can see we have our new project here on the left hand side the code is always under the src directory and i can open that up here you can see it looks just like an arduino and we've got your setup method your loop method and whenever you include arduino.h you are including all of the arduino runtime that we know and love now here's the tricky one platform.io i'm sorry platform io.ini is the configuration file that sets up all of the characteristics of the board the chipset the the serial port how to program it on on arduino a lot of these are done by menu selection but here you have to put it into this platform io file some key factors here platform is the the chipset basically so all esp32 projects are going to have espressif 32 as their platform your project will have one of the 900 board definitions listed here and all arduino-based applications are going to have the arduino as the framework i've read in some places that it defaults to arduino but if you forget to put it you'll get a bunch of compiler errors so i would always explicitly put in that framework now there are a lot of things that you can put in here a staggering number they're all documented so what i'm going to do is close down this sample and i'm going to open up the one that i've been working with so here's my main it just basically blinks the siri the the onboard led but here's my platform i o now you can see it's slightly more complicated we're going to look at each section the platform i started out with platform espressif 32 just like the other one did but i thought i found a bug so you can actually list the uh the github link to the latest and greatest version of the espressif framework or sorry platform support so you can put in a github link and it will understand that and it will self update to whatever is sitting here so that's good or you can explicitly list the platform and it'll use the one that's currently installed into the tool now for board the the do it board is this one my board is somewhat custom but the closest i could find to a completely bare bones uh module only board is called esp32dev and that seems to work for me and running cord on my board code on my board now i'm sticking with the arduino framework so that's good now a couple of things you can put here optionally this is the serial port speed that you will see the output of your serial port come on a lot of us use 115 200 as our serial port speed and you actually get to look at your serial port by clicking on this little power plug icon down here during run time your serial port output will come here and you choose which serial port you want to monitor now it will say com6 here when i plug the board in i do not have it plugged in right now the upload speed under arduino we're used to setting it to 92100 so that's fine now that here's where our com port comes into play depending on what you plug in windows will give you a different com port to talking with your board when i plug the do it board directly into my computer with a usb cable windows gives me com5 and using arduino i can flash the code and look at the serial port output using com5 when i plug my my esp32 mango board in windows gives it to me on com17 so that's what you've got to use arduino uses com17 for firmware and serial port but when i plug the esp32 prog board in i see it on com6 and we confirmed that before i'll come over here grab the debugging board and i'll plug it in and we can watch com 6 pop up there we are com 6. so it consistently gives us the same serial port but it can be different for different boards so you make sure that you uncomment the one of the serial port that your code will upload over so that's that now here's where i had a massive problem the code would just not upload uh when i asked it to even when i had the upload port correct you must say upload protocol equals esp-prog that tells platform io that you have an esp prog board plugged in and you want to use it to upload new firmware i believe and don't hold me to this if you leave this out it will try and upload over a serial port plugged into the native board not the esp32 esp prog board so that is critical and then some debugging things debug tool equals esp prog you've got to put this in or platform io will not understand how to do hardware debugging you want to create a build with all the debugging symbols included so you say build type equals debug this one here is optional debug init break equals t break space setup what this does is every time you say i want to debug my firmware it will stop at the first line of the setup method maybe that's not what you want maybe it is what you want but so this is an optional thing so with these magic incantations i was able to flash the code and perform hardware debugging on both the doit board and my esp32 mango if you have any problems you probably do not have the jtag connector wired correctly or you do not have one of these critically important tokens in your platform io dot any file so go back and review everything okay so now we have all of our configurations set up in hardware and software we're going to test firmware upload and you can see i'm in my platform.ini which is set up for my mango board so what i'm going to do is scroll this up so we can watch the upload process there's a little arrow right here that is the upload button and when i click it it will actually build and upload the code in one step for me so what i want to do is come over here and i've you can see we're blinking at one second intervals i've changed my code to blink at one tenth of a second intervals as soon as i click that so let's come over here and we can watch the progress now notice i'm not having to push the the reset and flash buttons over here as sometimes you have to do with a esp32 target board it all happens automatically over this cable so that's one less thing to worry about okay let's upload so it's compiling it in debug mode linking it all together into the target binary our upload protocol is esp prog and it's uploading it in four parts you've also seen this in arduino but you can see that four part programming started and finished verified okay shut down and look we are flashing in one tenth of a second or 100 millisecond intervals the it not only did this upload the new firmware for me i didn't even have to push the reset button it triggered a reset of the esp32 module over the wire so with one click right here i got new code uploaded to the board and it started execution and that is pretty awesome now you might remember from the code that the board is putting out some messages on the serial port lighting up blinky turning off blinky let's see if we can actually see that coming through we click here and it it's asking us what port do we want to use i can either type in the number two or column six i'm going to type in two and nothing so this is one of the first things i found that is not great about the system is that sometimes the debug output does not come through the serial port which was something that arduino seemed to be fine with okay so in an attempt to really get our serial port output i plugged a new usb cable directly into the native usb port of my mango board and i left everything else the same now if we come over here i click on serial port again and we need to find out what port number it is of what i plugged in and just became active and that's com17 right here so i come here i choose number three and there we are lighting up blinky turning off blinky so the secret is you get your serial.print line output of your native usb port through a separate cable it's not going to come through this cable good least we have that down we know the limitation we know how to work with okay we are at the final step this is the reason that we're here is we're trying to debug our code now everything we've done so far is absolutely mandatory to get working so let's figure out what the last step is the last step is here run start debugging is a simple click of the f5 key now what that's going to do is it will build the code it will flash the code it will initialize debugging and it's incredibly verbose you'll see some crazy stuff coming through here on the debug console until we finally get to the point where we are sitting to begin execution at the first line of setup actually right here which is set by this command right here debug init break t break setup this method will begin execution and the debugger will halt right before this serial.print line our serial.begin so let's see what happens i am clicking f5 right now and it's actually in two stages you'll see the debug you'll see the build you'll see the update then we have to click to another tab here to actually see the debugger begin its initialization so let's watch this so we're building again it succeeded now we come over here to debug console you can see all of this crazy stuff just let it go just let it go don't try and understand it it's going it's halting it's resetting it's going it's halting it's resetting it's flashing it's verifying and we are now sitting at the first line of setup we're in and as you might expect it has the standard debugging controls just play that means just start execution and don't stop this means step over essentially perform one line of execution this is step into which would actually follow the path of execution into the begin method this is step out this is restart the code from the beginning and this is halt halt execution now i want to show you a couple more things before we get going over here you can set up watch points for variables in your code i have previously set up watch points for loop count and flash delay there's no automatic way to do this you must click the plus button type in the variable name and hit enter and it will either say hey you've got an error or it'll give you the current value so let's just ignore that for now one thing is another thing is during execution you cannot change the value of this variable from the watch list this is read only to actually change a value you must go up here into the variable section now since my two uh variables are global to the code they are not inside a local a method meaning they're local to that method you will find them under this global section the global section has dozens of other variables which live in the runtime of the arduino framework and the underlying esp operating system they are not in alphabetical order you cannot search for it so you've simply got to go and find it and there's our loop count i could change this to one right now if i felt like it and that change is reflected here let's put that back if i look for my flash delay variable i found it a little farther down there it is right here i can change this to whatever value i want and it's reflected here and it will be picked up in the code this is very clunky and awkward both from a global standpoint separate my variables from the underlying operating system there's got to be a way to do that i want to use this as a read and write for the variables i've got in my code anyway let's take a look and step through let's step over serial.begin i click on this now in real time without being in uh in youtube fast forward 1.5 x speed watch how long it takes to execute this one line of code click okay and we're back let's do one more and we're back you saw how long that takes this is detrimental to a seamless and painless debugging operation that's another thing i liked about the atmel debugger man that thing was screaming fast it did not get in my way when i was debugging now let's go ahead and set a breakpoint you do that by clicking in this margin of the line you want after setup executes it's going to go into my loop so i'm going to click continue and and now we're in the first part of my loop and you can see it's showing your break point down here plus a lot of other garbage that's spit out by gdb i don't need this i want to filter this out can i filter this out i don't know we'll skip over we'll execute this line and let's uh let's open up our serial port and there we got our lighting up blinky line that was just executed now you're thinking if i click play it's going to execute one loop it's going to come back here and we've stopped again so i lit it up and i turned it off and my loop count is one if i turn off this break point and i click play my program is now in runaway mode and what if i want to halt it somehow if i click restart or halt i'm dead i found which i like a lot if i just click and add a new breakpoint it is captured in time my code stops at that line that is very very very useful i like it a lot now one thing i've noticed that hasn't happened to me yet here is sometimes this variable section just goes completely blank if i wanna to look at a value or set an updated value like if we come down here and change our my delay it's somewhere around here if we change the delay to 100 milliseconds there's loop count there's my flash delay it's actually showing it in green i don't know if that's because it's an integer or it's my local variable and if i click go i am now getting a one second uh delay which is great and here we are you see my variables has completely vanished oh and it's back this this is annoying um and i guess until the code is improved or the the interaction between platform io and the debug board is optimized something we're going to have to live with but we can now debug our code hence we have come to the end of our experience and i thank you for your time and your patience but this is the level that we have to go into in order to be able to successfully debug esp32 code if you have any other insight put it down in the doodly do below what do you do when the variable section vanishes for good all i've done is stopped and restarted is there have you found a way to optimize the the execution of the debugger when i want to go into step over mode is there a way to update my variables from the watch list or can i only really do it if it's inside a method which i would do from the local section here i've got no local variables so they're not showing up so thank you and give me all your experience down the doodley-doo uh i may end up doing another video based on the things i learn as i'm actively uh debugging real code that's it for now thanks hey if you found this video interesting please give it a thumbs up and if you like my other content i'd appreciate a subscribe take care and see you next time

Channel: Mike's Tropical Tech

Views: 8,547

Keywords: Atmel, Atmel Software Framework, ASF4, PLA, Arduino, ESP32, IoT, ESP-PROG, PlatformIO, Hardware Debugging

Id: eEzgwCbIbyM

Length: 37min 30sec (2250 seconds)

Published: Sun Feb 07 2021