Addon library to RemoteDebug: An Simple Software Debugger, based on SerialDebug
RemoteDebuggger is an addon to RemoteDebug library, with and simple software debugger, to see/change global variables, to add watch for these variables, or call a function, in runtime, using commands by telnet.
- About
- How it looks
- News
- Beta version
- Github
- Benefits
- Commands
- Install
- Usage
- Khow issues
- Releases
- Links
- Thanks
This library is a addon, and need that the RemoteDebug library installed too.
The Arduino official IDE, not have debugger. Only way, until now, is using a another IDE, that can be paid, and a hardware debugger, as JTAG.
SerialDebug is an library to Improved serial debugging and simple software debugger to Arduino. It is made for serial debugging over USB conexion. And it have a simple sofware debugger, simple but functional, and not need a extra hardware to do it.
Yes, now we can use this debugger,
RemoteDebuggger (this library), is a addon to RemoteDebug, to implement the simple software debugger, based in SerialDebug.
Notes:
- This not good as a real hardware debugger, as GBD with JTAG USB hardware. And hardware debuggers require skills to configure and use. Few Arduino developers use it (e.g. Arduino IDE not have this feature). But RemoteDebugger is simple and funcional and works wireless, by WiFi (telnet connection).
- This not is a C++ class, like RemoteDebug, due keep code compatibility with SerialDebug. With it, all your debugger codes, by serial or telnet, is same.
It is an addon, due not overhead projects with RemoteDebug, that not needs an debugger.
RemoteDebuggger in telnet client:
Image:
- The new version of RemoteDebug, the 2.0.0, implements an support to RemoteDebuggger, few code added, just some callbacks. Please update this, if you have olders versions of RemoteDebug.
This is a beta version. Not yet fully tested, optimized, and documented.
This is a previous documentation. It will be better documented before first RC version.
Contribute to this library development by creating an account on GitHub.
Please give a star, if you find this library usefull, this help a another people, discover it too.
Please add a issue for problems or suggestion.
I suggest you use a Github Desktop New app to clone, it help to keep updated.
This debugger is optimized for features that it have:
The initial status of debugger is inactive, where no CPU waste time for process debugger elements. Well, there may not be anyone seeing it.
After the telnet client connection, the debugger will become active. If it is desconnected, the debugger is disable too.
For simple software debugger, have memory optimizations:
-
No fixed arrays, is used C++ Vector to dynamic arrays
-
Is used void* pointer to store values, when it is need. s more complicate, but it dramatically reduces use of memory, compared to store 17 variables for support 17 kinds of this.
Note: due a extra overhead in processing simple software debugger, it starts disabled. You can enable when you need (dbg command)
In future versions, the debugger will more otimized, for CPU and memory
RemoteDebug process commands by telnet connection. RemoteDebuggger receive it by callbacks and process predefined commands as:
f -> call the function
f ? -> to show more help
dbg [on|off] -> enable/disable the simple software debugger
Only if debugger is enabled:
g -> see/change global variables
g ? -> to show more help
wa -> see/change watches for global variables
wa ? -> to show more help
Not yet implemented:
gpio -> see/control gpio
For simple software debugger:
- For functions:
- To show help: f ?
- To show: f [name|num]
- To search with start of name (case insensitive): f name
- To call it, just command: f [name|number] [arg]
- Enable/disable the debugger:
- To enable: dbg on
- To disable: dbg off
Note: the debugger starts disabled, to avoid extra overhead to processing it
You can enable it when need
- For global variables:
- To show help: g ?
- To show: g [name|num]
- To search by start of name: g name
- To change global variable, g [name|number] = value [y]
note: y is to confirm it (without confirm message)
- For watches:
- To show help: wa ?
- To show: wa [num]
- To add: wa a {global [name|number]} [==|!=|<|>|<=|>=|change] [value] [as]
notes: change not need a value, and as -> set watch to stop always
- To add cross (2 globals): wa ac {global [name|number]} [=|!=|<|>|<=|>=] {global [name|number]} [as]
- To change: wa u {global [name|number]} [==|!=|<|>|<=|>=|change] [value] [as]
- To change cross (not yet implemented)
- To disable: wa d [num|all]
- To enable: wa e [num|all]
- To nonstop on watches: wa ns
- To stop on watches: wa s
Just download or clone this repository.
Or for Arduino IDE, you can use the library manager to install and update the library.
For install help, click on this:
Note: insure that both libraries are installed
Please open the example project, to see it working.
To add RemoteDebuggger to your Arduino project (that uses RemoteDebug):
Place it, after include of RemoteDebug:
// RemoteDebug addon library: RemoteDebugger, an Simple software debugger - based on SerialDebug Library
#include "RemoteDebugger.h" //https://github.com/JoaoLopesF/RemoteDebuggerConverter:
RemoteDebugger has a converter to help add this debugger to your Arduino codes, that uses RemoteDebug library.
To do it manually:
Place it, after the RemoteDebug commands (Debug.begin, Debug.set...)
// Init the simple software debugger, based on SerialDebug library
Debug.initDebugger(debugGetDebuggerEnabled, debugHandleDebugger, debugGetHelpDebugger, debugProcessCmdDebugger); // Set the callbacks
debugInitDebugger(&Debug); // Init the debuggerTo add elements to debugger, put this codes, after the debugInitDebugger:
For example, for functions:
// Add functions that can called from RemoteDebuggger
if (debugAddFunctionVoid("benchInt", &benchInt) >= 0) {
debugSetLastFunctionDescription("To run a benchmark of integers");
}
if (debugAddFunctionVoid("benchFloat", &benchFloat) >= 0) {
debugSetLastFunctionDescription("To run a benchmark of float");
}
if (debugAddFunctionVoid("benchGpio", &benchGpio) >= 0) {
debugSetLastFunctionDescription("To run a benchmark of Gpio operations");
}
if (debugAddFunctionVoid("benchAll", &benchAll) >= 0) {
debugSetLastFunctionDescription("To run all benchmarks");
}
if (debugAddFunctionVoid("benchSerial", &benchSerial) >= 0) {
debugSetLastFunctionDescription("To benchmarks standard Serial debug");
}
if (debugAddFunctionVoid("benchSerialDebug", &benchSerialDebug) >= 0) {
debugSetLastFunctionDescription("To benchmarks SerialDebug");
}
if (debugAddFunctionStr("funcArgStr", &funcArgStr) >= 0) {
debugSetLastFunctionDescription("To run with String arg");
}
if (debugAddFunctionChar("funcArgChar", &funcArgChar) >= 0) {
debugSetLastFunctionDescription("To run with Character arg");
}
if (debugAddFunctionInt("funcArgInt", &funcArgInt) >= 0) {
debugSetLastFunctionDescription("To run with Integer arg");
}Or short use, if you not want descriptions:
// Add functions that can called from SerialDebug
debugAddFunctionVoid("benchInt", &benchInt);
debugAddFunctionVoid("benchFloat", &benchFloat);
debugAddFunctionVoid("benchGpio", &benchGpio);
debugAddFunctionVoid("benchAll", &benchAll);
debugAddFunctionVoid("benchSerial", &benchSerial);
debugAddFunctionVoid("benchSerialDebug", &benchSerialDebug);
debugAddFunctionStr("funcArgStr", &funcArgStr);
debugAddFunctionChar("funcArgChar", &funcArgChar);
debugAddFunctionInt("funcArgInt", &funcArgInt);
debugSetLastFunctionDescription("To run with Integer arg");Note: If it is for old boards, as UNO, Leornardo, etc. You must use F() to save memory:
// Add functions that can called from SerialDebug
debugAddFunctionVoid(F("benchInt"), &benchInt);Notes: It is too for all examples showed below
For global variables (note: only global ones):
// Add global variables that can showed/changed from SerialDebug
// Note: Only globlal, if pass local for SerialDebug, can be dangerous
if (debugAddGlobalUInt8_t("mRunSeconds", &mRunSeconds) >= 0) {
debugSetLastGlobalDescription("Seconds of run time");
}
if (debugAddGlobalUInt8_t("mRunMinutes", &mRunMinutes) >= 0) {
debugSetLastGlobalDescription("Minutes of run time");
}
if (debugAddGlobalUInt8_t("mRunHours", &mRunHours) >= 0) {
debugSetLastGlobalDescription("Hours of run time");
}
// Note: easy way, no descriptions ....
debugAddGlobalBoolean("mBoolean", &mBoolean);
debugAddGlobalChar("mChar", &mChar);
debugAddGlobalByte("mByte", &mByte);
debugAddGlobalInt("mInt", &mInt);
debugAddGlobalUInt("mUInt", &mUInt);
debugAddGlobalLong("mLong", &mLong);
debugAddGlobalULong("mULong", &mULong);
debugAddGlobalFloat("mFloat", &mFloat);
debugAddGlobalDouble("mDouble", &mDouble);
debugAddGlobalString("mString", &mString);
// Note: For char arrays, not use the '&'
debugAddGlobalCharArray("mCharArray", mCharArray);
// Note, here inform to show only 20 characteres of this string or char array
debugAddGlobalString("mStringLarge", &mStringLarge, 20);
debugAddGlobalCharArray("mCharArrayLarge",
mCharArrayLarge, 20);
// For arrays, need add for each item (not use loop for it, due the name can not by a variable)
// Notes: Is good added arrays in last order, to help see another variables
// In next versions, we can have a helper to do it in one command
debugAddGlobalInt("mIntArray[0]", &mIntArray[0]);
debugAddGlobalInt("mIntArray[1]", &mIntArray[1]);
debugAddGlobalInt("mIntArray[2]", &mIntArray[2]);
debugAddGlobalInt("mIntArray[3]", &mIntArray[3]);
debugAddGlobalInt("mIntArray[4]", &mIntArray[4]);
The debugger allow add watches, it is usefull to warning when the content of global variable, is changed or reaches a certain condition.
How this works, without a real hardware debugger? :
-
If have any watch (enabled),
-
Is verified this content is changed,
-
And is verified the watch, And trigger it, if value is changed, or the operation is true
This is done before each debug show messages or in debugHandleDebuuger function.
And for watches:
// Add watches for some global variables
// Note: watches can be added/changed in serial monitor too
// Watch -> mBoolean when changed (put 0 on value)
debugAddWatchBoolean("mBoolean", DEBUG_WATCH_CHANGED, 0);
// Watch -> mRunSeconds == 10
debugAddWatchUInt8_t("mRunSeconds", DEBUG_WATCH_EQUAL, 10);
// Watch -> mRunMinutes > 3
debugAddWatchUInt8_t("mRunMinutes", DEBUG_WATCH_GREAT, 3);
// Watch -> mRunMinutes == mRunSeconds (just for test)
debugAddWatchCross("mRunMinutes", DEBUG_WATCH_EQUAL, "mRunSeconds");RemoteDebuggger not need any extra code, as handle. This is do by callbacks in RemoteDebug
- Nothing yet repported
- Support to RemoteDebug with connection by web socket
- debugBreak for RemoteDebug now is redirect to a debugSilence of RemoteDebug
- Adjustments in example
- Adjustment: the debugger still disable until dbg command, equal to SerialDebug
- Changed to one debugHandleDebugger routine
- Add debugSetDebuggerEnabled routine
- Changed handle debugger logic
- First beta
This library is made on Slober - the Eclipse for Arduino See it in -> Eclipse for Arduino I recommend, is very good IDE, with refactoring and anothers good features of Eclipse IDE.
Special thanks to:
- Arduino, for bring open hardware to us.
- Espressif, to bring good IoT boards to us.
- Good people, that work hard, to bring to us excellent open source,
as libraries, examples, etc..
That inspire me to make new libraries, as SerialDebug, RemoteDebug, RemoteDebugger, etc.
- Makers people, that works together as a big family.
Hit counter on this file, starting at 2019-03-03:
