Forgetfulino 2.0.1 – never lose your sketch again

Forgetfulino is an Arduino library + Arduino IDE 2.x extension that turns every upload into a self‑contained backup of your sketch.

This repository contains the Arduino library (this is what goes into your Arduino/libraries folder or is picked by the Arduino Library Manager).
The IDE extension development project lives in a separate repository:
https://github.com/IamTheVector/Forgetfulino-Extension.

Your source code is:

• stored in flash (PROGMEM) alongside the firmware,
• compressed (deflate + Base64) to save flash space,
• recoverable at any time via Serial, even if the .ino files are gone.

Install it once, forget about it – and still be able to recover your code months later.

---

1. What Forgetfulino does

1.1 High-level description

• Embed your full sketch (all .ino and .cpp files) into PROGMEM.
• Dump the embedded source:
  • as human‑readable text, or
  • as a compact compressed Base64 line.
• Decode & restore the sketch directly inside Arduino IDE 2.x using the Forgetfulino extension.
• Annotate library versions automatically in the recovered code (#include <EEPROM.h> // version 1.0.0).
• On-demand dump mode with password – trigger only when you send a specific word on the Serial Monitor.

1.2 Videos

• Watch the short workflow example on YouTube
• Watch the full explaination of all the functions here

---

2. API – Functions, description, usage, scenarios

Global object:

#include <Forgetfulino.h>

extern ForgetfulinoClass Forgetfulino;

2.1 Setup and basic dump

Function	Description	How to use	Case scenario
begin()	Initializes the library.	Call once in setup(), after Serial.begin(...).	Required for dumpSource() / dumpCompressed() (not for OnDemand).
dumpSource()	Dumps the embedded source as plain text over Serial.	Call in setup() or loop(). Requires headers generated by the extension.	You want to read the sketch directly in the Serial Monitor.
dumpCompressed()	Dumps a deflate‑compressed Base64 line with a short header.	Call once in setup() (or when needed). Copy the Base64 line and decode it with the IDE extension.	You want a compact, copy‑paste‑friendly dump that you can fully reconstruct in the IDE.

2.2 On‑demand dump with trigger word / password

void dumpSource_OnDemand(const char* trigger = "forgetfulino");
void dumpCompressed_OnDemand(const char* trigger = "forgetfulino");

Function	Description	How to use	Case scenario
dumpSource_OnDemand()	Non‑blocking: listens on Serial, and when the trigger word is received, dumps the plain source once.	Call in loop(). By default, trigger is "forgetfulino" (case‑insensitive, spaces around are ignored).	You want to be able to request the full readable source only when you type the magic word.
dumpCompressed_OnDemand()	Same as above, but dumps the compressed Base64 string.	Call in loop(). Default trigger = "forgetfulino" (case‑insensitive).	Ideal for production sketches: no dump spam, but you can always recover the compressed dump on request.

Trigger & password behavior (2.0.1):

• No password mode – these are all equivalent and never activate cooldown or lockout:

  • Forgetfulino.dumpCompressed_OnDemand();
  • Forgetfulino.dumpCompressed_OnDemand("");
  • Forgetfulino.dumpCompressed_OnDemand("forgetfulino");
  • Forgetfulino.dumpCompressed_OnDemand("Forgetfulino");
  • Forgetfulino.dumpCompressed_OnDemand("fOrgetfulinO");

  In all these cases the active trigger is "forgetfulino":

  • case‑insensitive (FORGETFULINO, Forgetfulino, etc.),
  • leading/trailing spaces/tabs/CR/LF are ignored,
  • works with or without newline (Serial Monitor “No line ending”).

• Password mode – any other non‑empty string:

  Forgetfulino.dumpCompressed_OnDemand("MySecret123");

  • matching becomes case‑sensitive, exact string only (ignored leading/trailing spaces),
  • on wrong password:
    • the dump is not triggered,
    • a non‑blocking cooldown of 5 seconds is applied (subsequent wrong attempts during this window are ignored),
  • after 3 wrong attempts:
    • Forgetfulino prints Too many wrong attempts. Wait 5 minutes.,
    • further attempts are ignored for 5 minutes (still non‑blocking for your sketch).

---

3. Typical usage patterns

3.1 One‑shot dump at boot

Best when you want the compressed dump immediately after upload.

#include <Forgetfulino.h>

void setup() {
  Serial.begin(115200);
  delay(2000);

  Forgetfulino.begin();

  // One-shot compressed dump on boot.
  Forgetfulino.dumpCompressed();
}

void loop() {
  // Your application code here.
}

3.2 On‑demand, default trigger (forgetfulino)

Best when you do not want any Serial output until you explicitly ask for it.

#include <Forgetfulino.h>

void setup() {
  Serial.begin(115200);
  Forgetfulino.begin();
}

void loop() {
  // Only dump when you type "forgetfulino" in the Serial Monitor
  // (any case, spaces around are ignored).
  Forgetfulino.dumpCompressed_OnDemand();
  // Forgetfulino.dumpSource_OnDemand();

  // Your application code here...
}

3.3 On‑demand with password

Best when you want a “password” style trigger.

void loop() {
  
  Forgetfulino.dumpCompressed_OnDemand("Forgetfulino"); // Retrieve the code only when the password is issued
  // Forgetfulino.dumpSource_OnDemand("Forgetfulino");  // Retrieve the code only when the password is issued
  // No password = type "forgetfulino" (case-insensitive)
}

Change "Forgetfulino" to any secret string – now matching is case‑sensitive and only that exact sequence will trigger the dump.

---

4. Installation and folder layout

Installed under Arduino/libraries/Forgetfulino (or Forgetfulino-main) you will find:

• library.properties – Arduino metadata (version 2.0.0, MIT license).
• src/
  • Forgetfulino.h, Forgetfulino.cpp – core library.
  • forgetfulino_source_data.h – plain merged source (generated by the IDE extension).
  • forgetfulino_compressed.h – deflate‑compressed source (generated by the IDE extension).
• examples/ – example sketches.
• extensions/
  • forgetfulino-arduino-ide-extension-0.0.1.vsix – packaged IDE extension.
  • README-Extensions.txt – step‑by‑step VSIX installation.

The heavy extension development project (TypeScript, node_modules, etc.) lives in the repository root under extension build/ and is not shipped to users.

4.1 Install the library

• Via Library Manager (once published):

  1. Open Arduino IDE.
  2. Sketch → Include Library → Manage Libraries…
  3. Search Forgetfulino.
  4. Click Install.

• Manual:

  1. Download or clone the repository.
  2. Copy Forgetfulino-main into your Arduino/libraries/ folder (rename to Forgetfulino if you like).
  3. Restart Arduino IDE.

Typical locations:

• Windows: Documents/Arduino/libraries/
• macOS: ~/Documents/Arduino/libraries/
• Linux: ~/Arduino/libraries/

4.2 Install the IDE extension (Arduino IDE 2.x)

1. Close Arduino IDE 2.x.
2. Locate your .arduinoIDE folder:
   • Windows: C:\Users\<you>\.arduinoIDE\
   • macOS: /Users/<you>/.arduinoIDE/
   • Linux: /home/<you>/.arduinoIDE/
3. Ensure .arduinoIDE/extensions/ exists.
4. Copy:
   • from: Arduino/libraries/Forgetfulino/extensions/forgetfulino-arduino-ide-extension-0.0.1.vsix
   • to: .arduinoIDE/extensions/forgetfulino-arduino-ide-extension-0.0.1.vsix
5. Start Arduino IDE 2.x and check .arduinoIDE/deployedPlugins/ for a folder containing forgetfulino-arduino-ide-extension.

---

5. Arduino IDE extension – what you get

Once installed, the Forgetfulino (Arduino IDE) extension adds context‑menu entries and commands that glue everything together.

5.1 Inject templates (right‑click on a .ino)

• Inject → Inject in setup (show dump every reboot)

  • Adds #include <Forgetfulino.h> (if missing).
  • Ensures Serial.begin(115200); and Forgetfulino.begin(); in setup().
  • Inserts Forgetfulino.dumpCompressed(); in setup() so every reset prints the compressed dump.

• Inject → Inject in loop (show dump when you write forgetfulino in serial)

  • Adds #include <Forgetfulino.h> and initialization in setup().
  • Inserts the on‑demand block at the start of loop():

    Forgetfulino.dumpCompressed_OnDemand("Forgetfulino"); // Retrieve the code only when the password is issued
    // Forgetfulino.dumpSource_OnDemand("Forgetfulino");  // Retrieve the code only when the password is issued
    // No password = type "forgetfulino" (case-insensitive)

5.2 Auto‑inject for new sketches

For brand‑new .ino files (empty or default Arduino skeleton), the extension can auto‑inject a Forgetfulino template on first save:

• Auto Inject → Inject in setup (show dump every reboot)

  • Enables forgetfulino.autoInjectTemplate = true.
  • Sets forgetfulino.autoInjectMode = "setup".

• Auto Inject → Inject in loop (show dump when you write forgetfulino in serial)

  • Enables forgetfulino.autoInjectTemplate = true.
  • Sets forgetfulino.autoInjectMode = "loop".

• Auto Inject → Deactivate

  • Stops auto‑injection.

5.3 Generate headers & auto‑generate on save

• Forgetfulino: Generate headers

  • Scans the sketch folder, merges all .ino/.cpp, sanitizes, compresses and writes:
    • src/forgetfulino_source_data.h
    • src/forgetfulino_compressed.h

• Auto‑generate on save

  • Forgetfulino: Activate auto-generate on save / Deactivate…
  • Controlled by forgetfulino.autoGenerateOnSave.
  • When enabled, saving any .ino, .cpp or .c regenerates the headers.

5.4 Comments in dump

• Forgetfulino: Click to activate comment in dump
• Forgetfulino: Click to deactivate comment in dump

Controlled by forgetfulino.includeCommentsInDump:

• On → store the sketch with comments (easier to read).
• Off → store a comment‑stripped version (smaller, more compact).

---

6. Decoding a compressed dump in the IDE

1. On the board, call:
   • Forgetfulino.dumpCompressed(); or
   • Forgetfulino.dumpCompressed_OnDemand(...); and trigger it via Serial.
2. In the Serial Monitor:
   • Select the Base64 line (or copy it),
   • Or paste it into an editor tab.
3. Right‑click the selected text → Forgetfulino: Decode compressed dump.

The extension will:

• Strip Serial timestamps like HH:MM:SS.mmm ->.
• Remove spaces and line breaks from the selected dump.
• Decode Base64 and inflate back to the original UTF‑8 source.
• Add // version ... comments to each #include when the library version is known.
• Open the recovered code in a new C++ tab.
• Delete the original Base64 line/selection from the source where you pasted it, keeping your file clean.

If anything goes wrong, you get an error message and the original text is left untouched.

---

7. Why you might actually want this

• You upload from a laptop, then months later only the board is left – Forgetfulino lets you pull the code back.
• You inherit a project where “the source is somewhere” – you can at least retrieve what is currently running.
• You want to archive firmware together with its exact source and library versions without managing external backups.

Forgetfulino does not replace git or good habits… but it saves you the day when those fail.

---

8. Acknowledgements

• lunastrod (Reddit) – for highlighting the importance of precise library versioning. Forgetfulino annotates each #include in the recovered source with the corresponding library version (when available), so you can reliably recreate the original build environment.
• kahveciderin (Reddit) – for pushing toward a more memory‑oriented design and pointing out how easily a missing #include or forgotten library could prevent the source from ever being shown. This led to automatic template injection and a more robust workflow.
• J‑M‑L (Arduino community) – for motivating proper multi‑file sketch support. Forgetfulino now collects all .ino and .cpp files in the sketch folder, preserving their order and boundaries.
• robtillaart (Arduino Forum) – for suggesting the use of compression. The 2.0.0 release adopts true deflate compression plus Base64 transport, significantly reducing flash usage compared to text‑only approaches.
• ptillisch (Arduino Team, Arduino Forum) – for pointing out the possibility of implementing an IDE extension, which completely changed the usability of Forgetfulino by automating header generation and decoding.

---

9. License

Forgetfulino is released under the MIT License.
See library.properties and the root LICENSE file for details.