Debugging SimpleFOClibrary sketches
So you hooked everything up, downloaded your sketch, applied power, and… nothing. Or another common scenario: motor jerks around and makes terrible sounds.
Don’t worry! Trust us, we’ve been there. Everyone has this experience, nobody has a working setup on the first try. BLDC motor control isn’t always easy, and there are lots of mistakes to be made.
There are different techniques to help you find problems on the software side, but one extremely useful one is to produce some debug output, and having a way to see debug output in a
Serial terminal will be invaluable when hunting for problems.
SimpleFOClibrary provides debug output using the
Serial port which is enabled by adding the following line to your
Place this function call early in the
setup function to see the debug output of the motor intialization, which can be important to help you find problems with your setup.
or specify the
Serial port instance to use:
Note: you can also use other serial ports, e.g. Serial1, Serial2, as supported by your MCU.
Debugging the motor init
motor will produce debug output about its status during the initialization
motor.init() and the alignment procedure
motor.initFOC(). Enabling this functionality will not directly influence the real-time performance because there is no debug output in real time-loop in the functions
This is an example of the
motor initialization monitoring output gone well:
MOT: Monitor enabled! MOT: Init MOT: Enable driver. MOT: Align sensor. MOT: sensor direction==CW MOT: PP check: OK! MOT: Zero elec. angle: 4.28 MOT: Align current sense. MOT: Success: 2 MOT: Ready.
Failed motor initialization due to the position sensor:
MOT: Monitor enabled! MOT: Init MOT: Enable driver. MOT: Align sensor. MOT: Failed to notice movement MOT: Init FOC failed.
And failed motor initialization due to the current sense:
MOT: Monitor enabled! MOT: Init MOT: Enable driver. MOT: Align sensor. MOT: sensor direction==CW MOT: PP check: OK! MOT: Zero elec. angle: 4.28 MOT: Align current sense. MOT: Fail! MOT: Init FOC failed.
Writing your own debug statements
You can use the SimpleFOClibrary easily for your own purposes:
SIMPLEFOC_DEBUG("Hello world!"); SIMPLEFOC_DEBUG("Float value: ", fval); SIMPLEFOC_DEBUG("Int value: ", ival);
Using this macro has several advantages, see FlashStringHelper, global disable and rationale, below.
See the SimpleFOCDebug class header for all available methods.
The SimpleFOCDebug macro automatically uses FlashStringHelper, and you should not use the F() macro on strings supplied to the
Debug - global disable
Using the build flag
SIMPLEFOC_DISABLE_DEBUG you can globally disable all debug output, potentially also saving a few bytes of program space if you are short on memory.
Why have our own
SimpleFOCDebug? Wny not just use
When supporting many hardware platforms (as SimpleFOClibrary does), we can’t make assumptions about the availability of the
Serial object. While it is a pretty standard feature of Arduino framework, a given board may not support it, or may for whatever reasons have a different name for it. We also can’t make assumptions about which
Serial object you would want to use. Some MCUs support 6 or more Serial ports.
We also like the abstraction it provides, making it easier to port SimpleFOClibrary to other platforms/frameworks. In future we may abstract the debug output functionality one level further, allowing debug output via SPI, MQTT or other protocols. For this reason it is also good to have a seperation between debug and
Other debugging methods
Plain old Serial.println
Can I just use
Serial output as per normal in my SimpleFOClibrary sketch?
Yes and no… There is no problem with calling Serial.println() in your sketches, you are not forced to use our debug facility as described above.
But you have to care not to use too much time for
Serial output. The
loopFOC functions need to called very often in your main
loop and you can’t output to the
Serial port all time. You will have to write the code in such a way to minimize the bytes you output, and include some timing code to make sure you only output once or twice a second.
A great way to debug simple things is to use
digitalWrite and an usused pin:
digitalWrite(5, HIGH); // 5 is an unused pin // ... digitalWrite(5, LOW);
Using this technique will not impact the execution time, and using your oscilloscope or logic analyser you can check the output pin and see things like how long calls are taking to execute, whether the code is taking certain branches, etc…
Using a real debugger with SimpleFOClibrary can be a challenge. The code is very real-time dependent, and can’t easily be paused or run more slowly. In the author’s experience using the debugger slows execution to the point that BLDC motor control is quite impossible.
But it would depend on the problem you’re trying to catch, the MCU and debugging hardware used and other factors, so keeping the real-time considerations in mind, give it a shot in the debugging tool of your choice and see how it goes.
We can’t stress enough how much help the SimpleFOClibrary communities can be if you’re having problems!
We have a Discourse Forum and a Discord Server you can join any time and ask questions. Our members are both knowledgable and helpful, so rather than sweat it out by yourself, drop by and ask some like-minded souls for advice.
If you isolate your problem, and find it to be our problem, please don’t hesitate to file a bug report on GitHub!