Feature request: uClock nano - low memory mode

[awonak]

I have been thinking about ways to help reduce memory usage with this library that might be useful to other folks. In my current use case, I only want to use uClock for the internal / external clock sync, and use setOnOutputPPQN to drive all of my app's logic. I experimented by commenting out all of the onSyncXXCallback and all associated counters, as well as the shuffle code that I don't need for my app. This freed up 1830 bytes of program memory and 130 of dynamic memory. For smaller microcontrollers like the Arduino Nano, this is a huge savings and frees me up to keep adding more features.

Can we make a low memory mode feature like this available to users? Is this an idea you would be interested in pursuing? Could we possibly wrap some of these allocation and implementation blocks in a flag like #ifndef UCLOCK_NANO to allow us to use the library in a very simple, low memory mode? Do you have any other ideas that would help us reduce memory allocation of features our firmware doesn't use?

[awonak]

It looks like my assumption was incorrect that using the #ifndef UCLOCK_NANO would reduce program memory usage. It helps reduce dynamic memory, but the program memory is relatively unchanged.

[midilab]

Yes, this is a common issue for some libraries used on microcontrollers that have limited RAM. To address the memory footprint in another project (uCtrl), I’ve used macro definitions to selectively include or exclude features at compile time.

A similar approach could be applied here by modularizing the library using configurable macros—just like in uCtrl. For example:

#define UCLOCK_NO_SHUFFLE
#define UCLOCK_NO_SYNC_CALLBACKS
// ... and so on

This would allow users to reduce memory usage by disabling unused features.

I'll mark this as a feature request and plan to expand on it as soon as possible.

[midilab]

It looks like my assumption was incorrect that using the #ifndef UCLOCK_NANO would reduce program memory usage. It helps reduce dynamic memory, but the program memory is relatively unchanged.

One of the reasons I haven’t implemented macro-based feature selection in uClock yet is that most features don’t consume much code memory. However, they can impact runtime memory usage, which is more critical on constrained systems.

That said, I do believe it's worthwhile to optimize the library for selective features at compile time. Even saving a few bytes can make a significant difference in resource-limited environments—sometimes those few bytes can save lives!

[awonak]

I think my assumptions of how the compiler works here might be incorrect. I attempted implementing the feature restriction define flags here: awonak@f72c725

When I build my library against main/develop here is my compiled memory usage:

Sketch uses 27958 bytes (91%) of program storage space. Maximum is 30720 bytes.
Global variables use 1755 bytes (85%) of dynamic memory, leaving 293 bytes for local variables. Maximum is 2048 bytes.

When I enable the flags implemented above (and I confirm the additional sync callbacks are no longer available), here is my compiled memory usage:

Sketch uses 27958 bytes (91%) of program storage space. Maximum is 30720 bytes.
Global variables use 1755 bytes (85%) of dynamic memory, leaving 293 bytes for local variables. Maximum is 2048 bytes.

Given I do not see any change, I wonder if the compiler is already taking care of the task of removing the unused code?

However, I tested another branch where I just remove all of the unused code, and I do see memory usage reduction. awonak@6ed1218

Sketch uses 26544 bytes (86%) of program storage space. Maximum is 30720 bytes.
Global variables use 1663 bytes (81%) of dynamic memory, leaving 385 bytes for local variables. Maximum is 2048 bytes.

Perhaps the first implementation using DEFINE blocks to omit unused code will still help in the area of dynamic memory used in the stack (vs global or program), but I'm not sure how to test that.

[midilab]

Arduino build system does not propagate #define macros from .ino files to external libraries. During compilation, all .ino files are combined into a single translation unit, which is then compiled separately from the libraries. As a result, any macro defined in the .ino file—or even in a header located within the src/ directory of the sketch—won’t affect the library code directly.

To make a macro available to the library, it needs to be defined in a header file that’s part of the library itself, or passed as a compiler flag via build_flags (when using platforms like PlatformIO).

This limitation makes modularizing libraries using macros quite inconvenient for the end user on Arduino platform. Since they can’t simply define macros in their .ino file or sketch-level headers, they’re often forced to modify the library source directly or use more advanced build systems like PlatformIO.

[tuulikauri]

I (independently) implemented
#define USE_SHUFFLE
and
#define USE_MANY_SYNCS and came by to see if anyone wanted a copy :)
It free'd about 75 bytes of SRAM which isn't nothing on my Nano. The biggest saver is the 4 bytes per array element in the input sync tempo averager though, volatile uint32_t ext_interval_buffer[EXT_INTERVAL_BUFFER_SIZE];

Happy to contribute this, would you like a PR? Cheers!

[midilab]

Hi @tuulikauri,

Thank you for your implementation! I've made some optimizations on the develop branch to reduce the size of unused structures. I'm still exploring alternatives to a macro-based solution, as the Arduino IDE can be challenging for beginners to navigate with macros. If we can't find a suitable alternative, we can proceed with the macro-based approach.
Significant changes have been made in the develop branch, which I'm preparing to merge into main for the next release. I'm currently finalizing the basic documentation for this.

@awonak , Could you please test the develop branch to evaluate how much SRAM is saved? The implementation now only allocates sync signatures defined during setup(), and the EXT_INTERVAL_BUFFER_SIZE defaults to 1 unless a higher value is specified in setup(). Let me know your feedback!

[tuulikauri]

the Arduino IDE can be challenging for beginners to navigate with macros

Yeah completely agree... I also looked for other ways to edit the settings with #define, without diving into the library's files; but research I did found that the *.ino files are compiled separately; so #define and other compiler pre-directives dont carry through to library files in the Arduino IDE unless you edit the library files and include them there. If we find an alternate way that would be great.

In lieu of that I'd suggest a clearly defined section for editing user preferences; and documenting this in the Wiki for the library. A configuration section clearly delineated and obvious like this would be ideal for beginners to search for and edit confidently.

[awonak]

Excellent work! I'll try it out this weekend and report back.

[midilab]

@awonak , @tuulikauri , could you guys please check the status of v2.3.0 for memory footprint? i have made some changes without macros to reduce ram and code size. depending on the results we can go for macro based features select on next release.

[tuulikauri]

2.2.1 was the base for my custom library, tuulClock.h where I added TIMER2 functionality (for use with AltSoftSerial, which needs TIMER1) and compiler directives for USE_SHUFFLE and USE_ALL_SYNCS.

Results on a nano compile (note, I'm not actually uploading this code. Just compiling in the IDE, with the board selected as Nano - the used memory is reported on compile, not on upload).

Is there something specific you want done with the hardware tests? I don't have a reproducible crash rig, but it was happening around 85% memory usage, which is when I started looking into freeing 100 bytes :)

Bottom line is the library consumes SRAM as:

• 164 bytes with EXT_INTERVAL_BUFFER_SIZE to 1 and no compiler directives
• 89 bytes by using compiler directives to remove shuffle and many of the syncs, and set EXT_INTERVAL_BUFFER_SIZE to 1, on baseline 2.2.1.
• 99 bytes by using 2.3.0. Nice!

This is the space consumed by shuffle and many syncs; so I'm interested to poke into it at some point and see if there's still room to save more space with directives, on top of the changes in 2.3.0
//With: #define USE_SHUFFLE //costs 21 bytes of dynamic memory (SRAM) on a Nano
//With: #define USE_ALL_SYNCS //costs 54 bytes of dynamic memory (SRAM) on a Nano

Here's my test notes with various configurations of settings in uClock.h.

//No includes: Sketch uses 444 bytes (1%) of program storage space. Maximum is 30720 bytes.                 Global variables use 9 bytes (0%) of dynamic memory, leaving 2039 bytes for local variables. Maximum is 2048 bytes.

//#include <LiquidCrystal.h> //Sketch uses 444 bytes (1%) of program storage space. Maximum is 30720 bytes.   Global variables use 9 bytes (0%) of dynamic memory, leaving 2039 bytes for local variables. Maximum is 2048 bytes.
//#include <MIDI.h> //Sketch uses 444 bytes (1%) of program storage space. Maximum is 30720 bytes.            Global variables use 9 bytes (0%) of dynamic memory, leaving 2039 bytes for local variables. Maximum is 2048 bytes.
//#include "Adafruit_seesaw.h"//Sketch uses 1658 bytes (5%) of program storage space. Maximum is 30720 bytes. Global variables use 122 bytes (5%) of dynamic memory, leaving 1926 bytes for local variables. Maximum is 2048 bytes.
//#include <AltSoftSerial.h> //Sketch uses 1084 bytes (3%) of program storage space. Maximum is 30720 bytes.  Global variables use 169 bytes (8%) of dynamic memory, leaving 1879 bytes for local variables. Maximum is 2048 bytes.

//#include <tuulClock.h> //Sketch uses 4680 bytes (15%) of program storage space. Maximum is 30720 bytes.     Global variables use 675 bytes (32%) of dynamic memory, leaving 1373 bytes for local variables. Maximum is 2048 bytes.
//Baseline:
//Sketch uses 4680 bytes (15%) of program storage space. Maximum is 30720 bytes.                            Global variables use 675 bytes (32%) of dynamic memory, leaving 1373 bytes for local variables. Maximum is 2048 bytes.
//without #define USE_SHUFFLE
//Sketch uses 4360 bytes (14%) of program storage space. Maximum is 30720 bytes.                            Global variables use 654 bytes (31%) of dynamic memory, leaving 1394 bytes for local variables. Maximum is 2048 bytes.
//Without #define USE_ALL_SYNCS
//Sketch uses 3472 bytes (11%) of program storage space. Maximum is 30720 bytes.                            Global variables use 600 bytes (29%) of dynamic memory, leaving 1448 bytes for local variables. Maximum is 2048 bytes.
//With EXT_INTERVAL_BUFFER_SIZE 1 //128 volatile uint32_t array size.... 4 bytes each. Saves the clock message time diffs in handleExternalClock(), called atomically by clockMe
//Sketch uses 3338 bytes (10%) of program storage space. Maximum is 30720 bytes.                            Global variables use 92 bytes (4%) of dynamic memory, leaving 1956 bytes for local variables. Maximum is 2048 bytes.

//With: #define USE_UCLOCK_SOFTWARE_TIMER //dont use any hardware timers
//x#define USE_TIMER2 //uses arduino nano TIMER2. Probably works on other 328p avr boards but untested. 
//x#define USE_SHUFFLE //costs 21 bytes of dynamic memory (SRAM) on a Nano 
//x#define USE_ALL_SYNCS //costs 54 bytes of dynamic memory (SRAM) on a Nano
//With: #define EXT_INTERVAL_BUFFER_SIZE 1 //128
//Sketch uses 676 bytes (2%) of program storage space. Maximum is 30720 bytes.                              Global variables use 89 bytes (4%) of dynamic memory, leaving 1959 bytes for local variables. Maximum is 2048 bytes.

//With: #define USE_UCLOCK_SOFTWARE_TIMER //dont use any hardware timers
//x#define USE_TIMER2 //uses arduino nano TIMER2. Probably works on other 328p avr boards but untested. 
//With: #define USE_SHUFFLE //costs 21 bytes of dynamic memory (SRAM) on a Nano 
//With: #define USE_ALL_SYNCS //costs 54 bytes of dynamic memory (SRAM) on a Nano
//With: #define EXT_INTERVAL_BUFFER_SIZE 1 //128
//Sketch uses 948 bytes (3%) of program storage space. Maximum is 30720 bytes.                              Global variables use 164 bytes (8%) of dynamic memory, leaving 1884 bytes for local variables. Maximum is 2048 bytes.


//All: Sketch uses 6532 bytes (21%) of program storage space. Maximum is 30720 bytes.                       Global variables use 948 bytes (46%) of dynamic memory, leaving 1100 bytes for local variables. Maximum is 2048 bytes.
//All, after tuulClock cleanup: Sketch uses 5190 bytes (16%) of program storage space. Maximum is 30720 bytes. Global variables use 365 bytes (17%) of dynamic memory, leaving 1683 bytes for local variables. Maximum is 2048 bytes.


//#include <uClock.h> //2.2.1
//With: #define USE_UCLOCK_SOFTWARE_TIMER //dont use any hardware timers
//With: #define EXT_INTERVAL_BUFFER_SIZE 128
//Sketch uses 1086 bytes (3%) of program storage space. Maximum is 30720 bytes.                             Global variables use 672 bytes (32%) of dynamic memory, leaving 1376 bytes for local variables. Maximum is 2048 bytes.
//With: #define EXT_INTERVAL_BUFFER_SIZE 1
//Sketch uses 948 bytes (3%) of program storage space. Maximum is 30720 bytes.                              Global variables use 164 bytes (8%) of dynamic memory, leaving 1884 bytes for local variables. Maximum is 2048 bytes.

#include <uClock.h> //2.3.0
//With: #define USE_UCLOCK_SOFTWARE_TIMER //dont use any hardware timers
//It seems there isnt #define EXT_INTERVAL_BUFFER_SIZE anymore, instead its a variable
//Sketch uses 1654 bytes (5%) of program storage space. Maximum is 30720 bytes.                             Global variables use 99 bytes (4%) of dynamic memory, leaving 1949 bytes for local variables. Maximum is 2048 bytes.


void setup() {
  // put your setup code here, to run once:
}

void loop() {
  // put your main code here, to run repeatedly:
}

[tuulikauri]

Further update; I opened a separate issue for the 2.3.0 update; but just focussing on some further SRAM results here:

Ported my TIMER2 feature into 2.3.0 so that I could compile my project code on baseline 2.3.0 library.

2.3.0 mod with TIMER2:
Sketch uses 20812 bytes (67%) of program storage space. Maximum is 30720 bytes.
Global variables use 1182 bytes (57%) of dynamic memory, leaving 866 bytes for local variables. Maximum is 2048 bytes.

2.2.1 with #defines to remove extra sync and shuffle and TIMER2:
Sketch uses 20328 bytes (66%) of program storage space. Maximum is 30720 bytes.
Global variables use 1253 bytes (61%) of dynamic memory, leaving 795 bytes for local variables. Maximum is 2048 bytes.

Compiling the AcidStepSequencer.ino example.
2.3.0:
Sketch uses 6556 bytes (21%) of program storage space. Maximum is 30720 bytes.
Global variables use 387 bytes (18%) of dynamic memory, leaving 1661 bytes for local variables. Maximum is 2048 bytes.

2.2.1:
Sketch uses 5624 bytes (18%) of program storage space. Maximum is 30720 bytes.
Global variables use 452 bytes (22%) of dynamic memory, leaving 1596 bytes for local variables. Maximum is 2048 bytes.

[midilab]

hi @tuulikauri ,

TIMER2 is a 8bits timer, its not a option for the uClock archtecture that demands at minumun of a 16bits timer. AVR only have one 16 bits timer wich is the one used for uClock as default.

If you can't free up TIMER1 on your project, you can try to use software implementation. Or make the other library use TIMER2.

You can use uClock with TIMER2 but its not recommended, all the clock algorithm is expected to work with a 16bits presicion timer.

[midilab]

@tuulikauri ,

Thanks for the tests so far.

Is there something specific you want done with the hardware tests? I don't have a reproducible crash rig, but it was happening around 85% memory usage, which is when I started looking into freeing 100 bytes :)

I just want to have an idea on how both v.2.2.1 vs v2.3.0 were reducing sram and code size for different projects.

Now i think there is no need anymore for a macro to remove onSync, everything was encapsulated on a simple small code and data structure to hold X onSync, removing repetitive code for each setOnSyncXX.

The shuffle i think still worth crete a macro for it, since it take a large part of code size.

Everything sram related im using now a alloc once and forever policy on the heap to control shuffle and onsync data, if the user dont setup any of those explicity, no memory will be used, same for EXT_INTERVAL_BUFFER_SIZE wich now is a dinamyc allocation if the user requests a larger buffer, other wise no memory wasted.