From f3c6faa447f60c1709831d9f574ac95cd37064a4 Mon Sep 17 00:00:00 2001
From: pennam <m.pennasilico@arduino.cc>
Date: Thu, 6 Feb 2025 08:54:51 +0100
Subject: [PATCH 01/18] Add TimedAttempt

---
 examples/timedBlink/timedBlink.ino         |  25 +++
 extras/test/CMakeLists.txt                 |   9 +-
 extras/test/src/arduino/Arduino.cpp        |  21 +++
 extras/test/src/arduino/Arduino.h          |  18 +++
 extras/test/src/time/test_TimedAttempt.cpp | 173 +++++++++++++++++++++
 src/Arduino_TimedAttempt.h                 |  14 ++
 src/time/TimedAttempt.cpp                  |  77 +++++++++
 src/time/TimedAttempt.h                    |  39 +++++
 8 files changed, 375 insertions(+), 1 deletion(-)
 create mode 100644 examples/timedBlink/timedBlink.ino
 create mode 100644 extras/test/src/arduino/Arduino.cpp
 create mode 100644 extras/test/src/arduino/Arduino.h
 create mode 100644 extras/test/src/time/test_TimedAttempt.cpp
 create mode 100644 src/Arduino_TimedAttempt.h
 create mode 100644 src/time/TimedAttempt.cpp
 create mode 100644 src/time/TimedAttempt.h

diff --git a/examples/timedBlink/timedBlink.ino b/examples/timedBlink/timedBlink.ino
new file mode 100644
index 0000000..6bc59f7
--- /dev/null
+++ b/examples/timedBlink/timedBlink.ino
@@ -0,0 +1,25 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#include <Arduino_TimedAttempt.h>
+
+TimedAttempt blink(500, 1000);
+
+void setup() {
+    pinMode(LED_BUILTIN, OUTPUT);
+}
+
+void loop() { 
+  if(blink.isExpired()) {
+    blink.retry();
+    digitalWrite(LED_BUILTIN, blink.getRetryCount() % 2);
+  }
+
+}
diff --git a/extras/test/CMakeLists.txt b/extras/test/CMakeLists.txt
index 2fb0dd0..7877717 100644
--- a/extras/test/CMakeLists.txt
+++ b/extras/test/CMakeLists.txt
@@ -20,6 +20,7 @@ set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 
 include_directories(../../src)
+include_directories(src/arduino)
 
 set(TEST_SRCS
   src/lzss/test_decoder.cpp
@@ -27,6 +28,7 @@ set(TEST_SRCS
   src/crc16/test_crc16.cpp
   src/sha256/test_sha256.cpp
   src/hex/test_hex.cpp
+  src/time/test_TimedAttempt.cpp
 )
 
 set(TEST_DUT_SRCS
@@ -34,6 +36,11 @@ set(TEST_DUT_SRCS
   ../../src/crc/crc16.cpp
   ../../src/sha256/sha2.c
   ../../src/hex/chex.h
+  ../../src/time/TimedAttempt.cpp
+)
+
+set(TEST_STUB_SRCS
+  src/arduino/Arduino.cpp
 )
 
 ##########################################################################
@@ -45,7 +52,7 @@ add_compile_options(-Wno-cast-function-type)
 set(CMAKE_C_FLAGS   ${CMAKE_C_FLAGS}   "--coverage")
 set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} "--coverage -Wno-deprecated-copy")
 
-add_executable( ${TEST_TARGET} ${TEST_SRCS} ${TEST_DUT_SRCS} )
+add_executable( ${TEST_TARGET} ${TEST_SRCS} ${TEST_DUT_SRCS} ${TEST_STUB_SRCS})
 target_compile_definitions( ${TEST_TARGET} PUBLIC SOURCE_DIR="${CMAKE_SOURCE_DIR}" )
 
 target_link_libraries( ${TEST_TARGET} Catch2WithMain )
diff --git a/extras/test/src/arduino/Arduino.cpp b/extras/test/src/arduino/Arduino.cpp
new file mode 100644
index 0000000..cf277de
--- /dev/null
+++ b/extras/test/src/arduino/Arduino.cpp
@@ -0,0 +1,21 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#include <Arduino.h>
+
+static unsigned long current_millis = 0;
+
+void set_millis(unsigned long const millis) {
+  current_millis = millis;
+}
+
+unsigned long millis() {
+  return current_millis;
+}
diff --git a/extras/test/src/arduino/Arduino.h b/extras/test/src/arduino/Arduino.h
new file mode 100644
index 0000000..91ef626
--- /dev/null
+++ b/extras/test/src/arduino/Arduino.h
@@ -0,0 +1,18 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#pragma once
+
+#ifndef min
+  #define min(a,b) ((a)<(b)?(a):(b))
+#endif
+
+void          set_millis(unsigned long const millis);
+unsigned long millis();
diff --git a/extras/test/src/time/test_TimedAttempt.cpp b/extras/test/src/time/test_TimedAttempt.cpp
new file mode 100644
index 0000000..8009492
--- /dev/null
+++ b/extras/test/src/time/test_TimedAttempt.cpp
@@ -0,0 +1,173 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#include <catch2/catch_test_macros.hpp>
+
+#include <time/TimedAttempt.h>
+#include <Arduino.h>
+#include <limits.h>
+
+using namespace arduino::time;
+
+SCENARIO("Test broker connection retries") {
+  TimedAttempt _connection_attempt(0,0);
+
+  _connection_attempt.begin(1000UL, 32000UL);
+
+  /* 100000 retries are more or less 37 days without connection */
+  while(_connection_attempt.getRetryCount() < 100000) {
+    _connection_attempt.retry();
+
+   switch(_connection_attempt.getRetryCount()) {
+      case 1:
+      REQUIRE(_connection_attempt.getWaitTime() == 2000);
+      break;
+      case 2:
+      REQUIRE(_connection_attempt.getWaitTime() == 4000);
+      break;
+      case 3:
+      REQUIRE(_connection_attempt.getWaitTime() == 8000);
+      break;
+      case 4:
+      REQUIRE(_connection_attempt.getWaitTime() == 16000);
+      break;
+      default:
+      REQUIRE(_connection_attempt.getWaitTime() == 32000);
+      break;
+    }
+  }
+}
+
+SCENARIO("Test thing id request with no answer from the cloud") {
+  TimedAttempt _attachAttempt(0,0);
+
+  _attachAttempt.begin(2000UL, 32000UL);
+
+  /* 100000 retries are more or less 37 days of requests */
+  while(_attachAttempt.getRetryCount() < 100000) {
+    _attachAttempt.retry();
+
+  switch(_attachAttempt.getRetryCount()) {
+      case 1:
+      REQUIRE(_attachAttempt.getWaitTime() == 4000);
+      break;
+      case 2:
+      REQUIRE(_attachAttempt.getWaitTime() == 8000);
+      break;
+      case 3:
+      REQUIRE(_attachAttempt.getWaitTime() == 16000);
+      break;
+      default:
+      REQUIRE(_attachAttempt.getWaitTime() == 32000);
+      break;
+    }
+  }
+}
+
+SCENARIO("Test thing id request of a detached device") {
+  TimedAttempt _attachAttempt(0,0);
+
+  _attachAttempt.begin(2000UL, 32000UL);
+
+  while(_attachAttempt.getRetryCount() < 100000) {
+    _attachAttempt.retry();
+
+    switch(_attachAttempt.getRetryCount()) {
+      case 1:
+      REQUIRE(_attachAttempt.getWaitTime() == 4000);
+      _attachAttempt.reconfigure(2000UL * 10UL, 32000UL * 40UL);
+      break;
+      case 2:
+      REQUIRE(_attachAttempt.getWaitTime() == 80000);
+      break;
+      case 3:
+      REQUIRE(_attachAttempt.getWaitTime() == 160000);
+      break;
+      case 4:
+      REQUIRE(_attachAttempt.getWaitTime() == 320000);
+      break;
+      case 5:
+      REQUIRE(_attachAttempt.getWaitTime() == 640000);
+      break;
+      default:
+      REQUIRE(_attachAttempt.getWaitTime() == 1280000);
+      break;
+    }
+  }
+}
+
+SCENARIO("Test last value request") {
+  TimedAttempt _syncAttempt(0,0);
+
+  _syncAttempt.begin(30000UL);
+
+  /* 100000 retries are more or less 37 days of requests */
+  while(_syncAttempt.getRetryCount() < 100000) {
+    _syncAttempt.retry();
+
+    switch(_syncAttempt.getRetryCount()) {
+      default:
+      REQUIRE(_syncAttempt.getWaitTime() == 30000);
+      break;
+    }
+  }
+}
+
+SCENARIO("Test isExpired() and isRetry()") {
+  TimedAttempt attempt(0,0);
+
+  attempt.begin(1000UL, 32000UL);
+
+  /* Initial condition */
+  set_millis(0);
+  REQUIRE(attempt.isExpired() == false);
+  REQUIRE(attempt.isRetry() == false);
+
+  /* Normal retry 2000ms */
+  attempt.retry();
+  REQUIRE(attempt.isRetry() == true);
+  set_millis(1000);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(1999);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(2000);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(2001);
+  REQUIRE(attempt.isExpired() == true);
+
+  /* Retry with rollover 4000ms */
+  set_millis(ULONG_MAX - 1999);
+  attempt.retry();
+  REQUIRE(attempt.isRetry() == true);
+  set_millis(0);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(1999);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(2000);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(2001);
+  REQUIRE(attempt.isExpired() == true);
+
+  /* Normal retry 8000ms */
+  set_millis(4000);
+  attempt.retry();
+  REQUIRE(attempt.isRetry() == true);
+  set_millis(4000);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(11999);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(12000);
+  REQUIRE(attempt.isExpired() == false);
+  set_millis(12001);
+  REQUIRE(attempt.isExpired() == true);
+
+  attempt.reset();
+  REQUIRE(attempt.isRetry() == false);
+}
diff --git a/src/Arduino_TimedAttempt.h b/src/Arduino_TimedAttempt.h
new file mode 100644
index 0000000..6512dc1
--- /dev/null
+++ b/src/Arduino_TimedAttempt.h
@@ -0,0 +1,14 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+#include "./time/TimedAttempt.h"
+
+using namespace arduino::time;
diff --git a/src/time/TimedAttempt.cpp b/src/time/TimedAttempt.cpp
new file mode 100644
index 0000000..274eaa2
--- /dev/null
+++ b/src/time/TimedAttempt.cpp
@@ -0,0 +1,77 @@
+/*
+  This file is part of the Arduino_CloudUtils library.
+
+  Copyright (c) 2024 Arduino SA
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+
+#include <Arduino.h>
+#include "TimedAttempt.h"
+
+namespace arduino { namespace time {
+
+    TimedAttempt::TimedAttempt(unsigned long minDelay, unsigned long maxDelay)
+    : _minDelay(minDelay)
+    , _maxDelay(maxDelay) {
+    }
+
+    void TimedAttempt::begin(unsigned long delay) {
+        _retryCount = 0;
+        _retryDelay = 0;
+        _retryTick = 0;
+        _minDelay = delay;
+        _maxDelay = delay;
+    }
+
+    void TimedAttempt::begin(unsigned long minDelay, unsigned long maxDelay) {
+        _retryCount = 0;
+        _retryDelay = 0;
+        _retryTick = 0;
+        _minDelay = minDelay;
+        _maxDelay = maxDelay;
+    }
+
+    unsigned long TimedAttempt::reconfigure(unsigned long minDelay, unsigned long maxDelay) {
+        _minDelay = minDelay;
+        _maxDelay = maxDelay;
+        return reload();
+    }
+
+    unsigned long TimedAttempt::retry() {
+        _retryCount++;
+        return reload();
+    }
+
+    unsigned long TimedAttempt::reload() {
+        unsigned long shift = _retryCount > 31 ? 31 : _retryCount;
+        unsigned long delay = (1UL << shift) * _minDelay;
+        _retryDelay = min(delay, _maxDelay);
+        _retryTick = millis();
+        return _retryDelay;
+    }
+
+    void TimedAttempt::reset() {
+        _retryCount = 0;
+    }
+
+    bool TimedAttempt::isRetry() {
+        return _retryCount > 0;
+    }
+
+    bool TimedAttempt::isExpired() {
+        return millis() - _retryTick > _retryDelay;
+    }
+
+    unsigned int TimedAttempt::getRetryCount() {
+        return _retryCount;
+    }
+
+    unsigned int TimedAttempt::getWaitTime() {
+        return _retryDelay;
+    }
+
+}}  // arduino::time
diff --git a/src/time/TimedAttempt.h b/src/time/TimedAttempt.h
new file mode 100644
index 0000000..4b02e30
--- /dev/null
+++ b/src/time/TimedAttempt.h
@@ -0,0 +1,39 @@
+/*
+  This file is part of the Arduino_CloudUtils library.
+
+  Copyright (c) 2024 Arduino SA
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#pragma once
+
+namespace arduino { namespace time {
+
+    class TimedAttempt {
+
+    public:
+        TimedAttempt(unsigned long minDelay, unsigned long maxDelay);
+
+        void begin(unsigned long delay);
+        void begin(unsigned long minDelay, unsigned long maxDelay);
+        unsigned long reconfigure(unsigned long minDelay, unsigned long maxDelay);
+        unsigned long retry();
+        unsigned long reload();
+        void reset();
+        bool isRetry();
+        bool isExpired();
+        unsigned int getRetryCount();
+        unsigned int getWaitTime();
+
+    private:
+        unsigned long _minDelay;
+        unsigned long _maxDelay;
+        unsigned long _retryTick;
+        unsigned long _retryDelay;
+        unsigned int _retryCount;
+    };
+
+}}  // arduino::time

From f0f9a05aa5939a34cae905c0fadba23c9c1031de Mon Sep 17 00:00:00 2001
From: pennam <m.pennasilico@arduino.cc>
Date: Thu, 6 Feb 2025 15:56:52 +0100
Subject: [PATCH 02/18] TimedAttempt: fix overflow bug

---
 src/time/TimedAttempt.cpp | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/time/TimedAttempt.cpp b/src/time/TimedAttempt.cpp
index 274eaa2..4a0eee8 100644
--- a/src/time/TimedAttempt.cpp
+++ b/src/time/TimedAttempt.cpp
@@ -49,7 +49,8 @@ namespace arduino { namespace time {
     unsigned long TimedAttempt::reload() {
         unsigned long shift = _retryCount > 31 ? 31 : _retryCount;
         unsigned long delay = (1UL << shift) * _minDelay;
-        _retryDelay = min(delay, _maxDelay);
+        /* delay should always increase */
+        _retryDelay =  (delay > _retryDelay) ? min(delay, _maxDelay): _maxDelay;
         _retryTick = millis();
         return _retryDelay;
     }

From 2f902dfd5bd46ac5a682035c0877840d6b961594 Mon Sep 17 00:00:00 2001
From: pennam <m.pennasilico@arduino.cc>
Date: Thu, 6 Feb 2025 16:04:03 +0100
Subject: [PATCH 03/18] Compile examples: add timedBlink

---
 .github/workflows/compile-examples.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/compile-examples.yml b/.github/workflows/compile-examples.yml
index 6e4d438..1de2167 100644
--- a/.github/workflows/compile-examples.yml
+++ b/.github/workflows/compile-examples.yml
@@ -26,6 +26,7 @@ jobs:
         - examples/crc32
         - examples/crc16
         - examples/sha256
+        - examples/timedBlink
       SKETCHES_REPORTS_PATH: sketches-reports
 
     strategy:

From 0a3d995c394c7e5738a62802f20bf8f6602186e4 Mon Sep 17 00:00:00 2001
From: pennam <m.pennasilico@arduino.cc>
Date: Thu, 6 Feb 2025 16:52:32 +0100
Subject: [PATCH 04/18] Add LED_BUILTIN definition

---
 examples/timedBlink/timedBlink.ino | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/examples/timedBlink/timedBlink.ino b/examples/timedBlink/timedBlink.ino
index 6bc59f7..686e5ed 100644
--- a/examples/timedBlink/timedBlink.ino
+++ b/examples/timedBlink/timedBlink.ino
@@ -10,6 +10,10 @@
 
 #include <Arduino_TimedAttempt.h>
 
+#if !defined(LED_BUILTIN) && !defined(ARDUINO_NANO_ESP32)
+static int const LED_BUILTIN = 2;
+#endif
+
 TimedAttempt blink(500, 1000);
 
 void setup() {

From 61690fd8873fa9cce4ecc8376497e8e1176010f7 Mon Sep 17 00:00:00 2001
From: pennam <m.pennasilico@arduino.cc>
Date: Fri, 7 Feb 2025 10:26:58 +0100
Subject: [PATCH 05/18] Add functions description for TimedAttempt class

---
 src/time/TimedAttempt.h | 61 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/src/time/TimedAttempt.h b/src/time/TimedAttempt.h
index 4b02e30..523733d 100644
--- a/src/time/TimedAttempt.h
+++ b/src/time/TimedAttempt.h
@@ -12,20 +12,81 @@
 
 namespace arduino { namespace time {
 
+    /**
+     * The TimedAttempt class manages retry attempts with configurable delays.
+     * It allows setting minimum and maximum delays, and provides methods to
+     * begin, retry, reset, and check the status of attempts.
+     */
     class TimedAttempt {
 
     public:
+        /**
+        * Constructor to initialize TimedAttempt with minimum and maximum delay
+        * @param minDelay: minimum delay between attempts
+        * @param maxDelay: maximum delay between attempts
+        */
         TimedAttempt(unsigned long minDelay, unsigned long maxDelay);
 
+        /**
+        * Begin the attempt with a fixed delay
+        * @param delay: fixed delay between attempts
+        */
         void begin(unsigned long delay);
+
+        /**
+        * Begin the attempt with a range of delays
+        * @param minDelay: minimum delay between attempts
+        * @param maxDelay: maximum delay between attempts
+        */
         void begin(unsigned long minDelay, unsigned long maxDelay);
+
+        /**
+        * Reconfigure the attempt with new minimum and maximum delays and reload
+        * @param minDelay: new minimum delay between attempts
+        * @param maxDelay: new maximum delay between attempts
+        * @return the new delay after reconfiguration
+        */
         unsigned long reconfigure(unsigned long minDelay, unsigned long maxDelay);
+
+        /**
+        * Retry the attempt, incrementing the retry count and reloading the delay
+        * @return the new delay after retry
+        */
         unsigned long retry();
+
+        /**
+        * Reload the delay based on the retry count and return the new delay
+        * @return the new delay after reload
+        */
         unsigned long reload();
+
+        /**
+        * Reset the retry count to zero
+        */
         void reset();
+
+        /**
+        * Check if a retry has been attempted
+        * @return true if a retry has been attempted, false otherwise
+        */
         bool isRetry();
+
+        /**
+        * Check if the current attempt has expired based on the delay
+        * @return true if the current attempt has expired, false otherwise
+        */
         bool isExpired();
+
+        /**
+        * Get the current retry count
+        * @return the current retry count
+        */
         unsigned int getRetryCount();
+
+        /**
+        * Get the current wait time for the next retry
+        * @return the current wait time for the next retry
+        */
         unsigned int getWaitTime();
 
     private:

From 77c003df72f05220e980b797968220c3fef604f7 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Mon, 10 Feb 2025 15:07:38 +0100
Subject: [PATCH 06/18] renaming sha256 functions to avoid clashing with
 esp8266:esp8266:huzzah

---
 extras/test/src/sha256/test_sha256.cpp |  4 ++--
 src/sha256/SHA256.h                    | 16 ++++++++--------
 src/sha256/sha2.c                      | 18 +++++++++---------
 src/sha256/sha2.h                      | 19 ++++++++++++-------
 4 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/extras/test/src/sha256/test_sha256.cpp b/extras/test/src/sha256/test_sha256.cpp
index 216d732..b80dec5 100644
--- a/extras/test/src/sha256/test_sha256.cpp
+++ b/extras/test/src/sha256/test_sha256.cpp
@@ -19,7 +19,7 @@
 #ifdef TEST_VECTORS_LONG
 static void test_sha256_long_message(uint8_t *digest)
 {
-    sha256_ctx ctx;
+    acu_sha256_ctx ctx;
     uint8_t message[1000];
     int i;
 
@@ -36,7 +36,7 @@ static void test_sha256_long_message(uint8_t *digest)
 static void test_sha256_message4(uint8_t *digest)
 {
     /* Message of 929271 bytes */
-    sha256_ctx ctx;
+    acu_sha256_ctx ctx;
     uint8_t message[1000];
     int i;
 
diff --git a/src/sha256/SHA256.h b/src/sha256/SHA256.h
index 4498e9d..bf4b92b 100644
--- a/src/sha256/SHA256.h
+++ b/src/sha256/SHA256.h
@@ -14,17 +14,17 @@
 
 namespace arduino { namespace sha256 {
 
-    inline void begin(sha256_ctx * ctx) {
-        return sha256_init(ctx);
+    inline void begin(acu_sha256_ctx * ctx) {
+        return acu_sha256_init(ctx);
     }
-    inline void update(sha256_ctx *ctx, const uint8_t *input, uint32_t length) {
-        return sha256_update(ctx, input, length);
+    inline void update(acu_sha256_ctx *ctx, const uint8_t *input, uint32_t length) {
+        return acu_sha256_update(ctx, input, length);
     }
-    inline void finalize(sha256_ctx * ctx, uint8_t digest[SHA256_DIGEST_SIZE]) {
-        return sha256_final(ctx, digest);
+    inline void finalize(acu_sha256_ctx * ctx, uint8_t digest[SHA256_DIGEST_SIZE]) {
+        return acu_sha256_final(ctx, digest);
     }
     inline void sha256(const unsigned char *input, unsigned int ilen, unsigned char *output) {
-        ::sha256(input, ilen, output);
+        ::acu_sha256(input, ilen, output);
     }
 
     class SHA256 {
@@ -47,7 +47,7 @@ namespace arduino { namespace sha256 {
 
     private:
 
-        sha256_ctx _ctx;
+        acu_sha256_ctx _ctx;
     };
 
 }} // arduino::sha256
diff --git a/src/sha256/sha2.c b/src/sha256/sha2.c
index e0337d6..7e967b9 100644
--- a/src/sha256/sha2.c
+++ b/src/sha256/sha2.c
@@ -128,7 +128,7 @@ static const uint32_t sha256_k[64] =
 
 /* SHA-2 internal function */
 
-static void sha256_transf(sha256_ctx *ctx, const uint8_t *message,
+static void sha256_transf(acu_sha256_ctx *ctx, const uint8_t *message,
     uint64_t block_nb)
 {
     uint32_t w[64];
@@ -245,16 +245,16 @@ static void sha256_transf(sha256_ctx *ctx, const uint8_t *message,
 
 /* SHA-256 functions */
 
-void sha256(const uint8_t *message, uint64_t len, uint8_t *digest)
+void acu_sha256(const uint8_t *message, uint64_t len, uint8_t *digest)
 {
-    sha256_ctx ctx;
+    acu_sha256_ctx ctx;
 
-    sha256_init(&ctx);
-    sha256_update(&ctx, message, len);
-    sha256_final(&ctx, digest);
+    acu_sha256_init(&ctx);
+    acu_sha256_update(&ctx, message, len);
+    acu_sha256_final(&ctx, digest);
 }
 
-void sha256_init(sha256_ctx *ctx)
+void acu_sha256_init(acu_sha256_ctx *ctx)
 {
 #ifndef UNROLL_LOOPS
     int i;
@@ -272,7 +272,7 @@ void sha256_init(sha256_ctx *ctx)
     ctx->tot_len = 0;
 }
 
-void sha256_update(sha256_ctx *ctx, const uint8_t *message, uint64_t len)
+void acu_sha256_update(acu_sha256_ctx *ctx, const uint8_t *message, uint64_t len)
 {
     uint64_t block_nb;
     uint64_t new_len, rem_len, tmp_len;
@@ -304,7 +304,7 @@ void sha256_update(sha256_ctx *ctx, const uint8_t *message, uint64_t len)
     ctx->tot_len += (block_nb + 1) << 6;
 }
 
-void sha256_final(sha256_ctx *ctx, uint8_t *digest)
+void acu_sha256_final(acu_sha256_ctx *ctx, uint8_t *digest)
 {
     uint64_t block_nb;
     uint64_t pm_len;
diff --git a/src/sha256/sha2.h b/src/sha256/sha2.h
index d6de3a6..4e84df2 100644
--- a/src/sha256/sha2.h
+++ b/src/sha256/sha2.h
@@ -37,8 +37,13 @@
 #include <stddef.h>
 #include <string.h>
 
-#define SHA256_DIGEST_SIZE ( 256 / 8)
-#define SHA256_BLOCK_SIZE  ( 512 / 8)
+#ifndef SHA256_DIGEST_SIZE
+    #define SHA256_DIGEST_SIZE ( 256 / 8)
+#endif // SHA256_DIGEST_SIZE
+
+#ifndef SHA256_BLOCK_SIZE
+    #define SHA256_BLOCK_SIZE  ( 512 / 8)
+#endif // SHA256_BLOCK_SIZE
 
 #ifdef __cplusplus
 extern "C" {
@@ -49,12 +54,12 @@ typedef struct {
     uint64_t len;
     uint8_t block[2 * SHA256_BLOCK_SIZE];
     uint32_t h[8];
-} sha256_ctx;
+} acu_sha256_ctx;
 
-void sha256_init(sha256_ctx * ctx);
-void sha256_update(sha256_ctx *ctx, const uint8_t *message, uint64_t len);
-void sha256_final(sha256_ctx *ctx, uint8_t *digest);
-void sha256(const uint8_t *message, uint64_t len, uint8_t *digest);
+void acu_sha256_init(acu_sha256_ctx * ctx);
+void acu_sha256_update(acu_sha256_ctx *ctx, const uint8_t *message, uint64_t len);
+void acu_sha256_final(acu_sha256_ctx *ctx, uint8_t *digest);
+void acu_sha256(const uint8_t *message, uint64_t len, uint8_t *digest);
 
 #ifdef __cplusplus
 }

From c1231e9f0b8dc1a4230d8ea67dcfab227ed8bb9b Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Wed, 22 Jan 2025 14:24:26 +0100
Subject: [PATCH 07/18] restructuring cbor directory tree

---
 .codespellrc                                                    | 2 +-
 src/{ => cbor}/tinycbor/README.md                               | 0
 src/{ => cbor}/tinycbor/cbor-lib.h                              | 0
 src/{ => cbor}/tinycbor/patch/patch.diff                        | 0
 src/{ => cbor}/tinycbor/src/cbor.h                              | 0
 src/{ => cbor}/tinycbor/src/cborencoder.c                       | 0
 .../tinycbor/src/cborencoder_close_container_checked.c          | 0
 src/{ => cbor}/tinycbor/src/cborerrorstrings.c                  | 0
 src/{ => cbor}/tinycbor/src/cborinternal_p.h                    | 0
 src/{ => cbor}/tinycbor/src/cborjson.h                          | 0
 src/{ => cbor}/tinycbor/src/cborparser.c                        | 0
 src/{ => cbor}/tinycbor/src/cborparser_dup_string.c             | 0
 src/{ => cbor}/tinycbor/src/cborpretty.c                        | 0
 src/{ => cbor}/tinycbor/src/cborpretty_stdio.c                  | 0
 src/{ => cbor}/tinycbor/src/cbortojson.c                        | 0
 src/{ => cbor}/tinycbor/src/cborvalidation.c                    | 0
 src/{ => cbor}/tinycbor/src/compilersupport_p.h                 | 0
 src/{ => cbor}/tinycbor/src/open_memstream.c                    | 0
 src/{ => cbor}/tinycbor/src/tinycbor-version.h                  | 0
 src/{ => cbor}/tinycbor/src/utf8_p.h                            | 0
 20 files changed, 1 insertion(+), 1 deletion(-)
 rename src/{ => cbor}/tinycbor/README.md (100%)
 rename src/{ => cbor}/tinycbor/cbor-lib.h (100%)
 rename src/{ => cbor}/tinycbor/patch/patch.diff (100%)
 rename src/{ => cbor}/tinycbor/src/cbor.h (100%)
 rename src/{ => cbor}/tinycbor/src/cborencoder.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborencoder_close_container_checked.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborerrorstrings.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborinternal_p.h (100%)
 rename src/{ => cbor}/tinycbor/src/cborjson.h (100%)
 rename src/{ => cbor}/tinycbor/src/cborparser.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborparser_dup_string.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborpretty.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborpretty_stdio.c (100%)
 rename src/{ => cbor}/tinycbor/src/cbortojson.c (100%)
 rename src/{ => cbor}/tinycbor/src/cborvalidation.c (100%)
 rename src/{ => cbor}/tinycbor/src/compilersupport_p.h (100%)
 rename src/{ => cbor}/tinycbor/src/open_memstream.c (100%)
 rename src/{ => cbor}/tinycbor/src/tinycbor-version.h (100%)
 rename src/{ => cbor}/tinycbor/src/utf8_p.h (100%)

diff --git a/.codespellrc b/.codespellrc
index 4cdd0de..025901d 100644
--- a/.codespellrc
+++ b/.codespellrc
@@ -3,7 +3,7 @@
 [codespell]
 # In the event of a false positive, add the problematic word, in all lowercase, to a comma-separated list here:
 ignore-words-list = ,
-skip = ./.git,./.licenses,__pycache__,node_modules,./go.mod,./go.sum,./package-lock.json,./poetry.lock,./yarn.lock,./src/tinycbor
+skip = ./.git,./.licenses,__pycache__,node_modules,./go.mod,./go.sum,./package-lock.json,./poetry.lock,./yarn.lock,./src/cbor/tinycbor
 builtin = clear,informal,en-GB_to_en-US
 check-filenames =
 check-hidden =
diff --git a/src/tinycbor/README.md b/src/cbor/tinycbor/README.md
similarity index 100%
rename from src/tinycbor/README.md
rename to src/cbor/tinycbor/README.md
diff --git a/src/tinycbor/cbor-lib.h b/src/cbor/tinycbor/cbor-lib.h
similarity index 100%
rename from src/tinycbor/cbor-lib.h
rename to src/cbor/tinycbor/cbor-lib.h
diff --git a/src/tinycbor/patch/patch.diff b/src/cbor/tinycbor/patch/patch.diff
similarity index 100%
rename from src/tinycbor/patch/patch.diff
rename to src/cbor/tinycbor/patch/patch.diff
diff --git a/src/tinycbor/src/cbor.h b/src/cbor/tinycbor/src/cbor.h
similarity index 100%
rename from src/tinycbor/src/cbor.h
rename to src/cbor/tinycbor/src/cbor.h
diff --git a/src/tinycbor/src/cborencoder.c b/src/cbor/tinycbor/src/cborencoder.c
similarity index 100%
rename from src/tinycbor/src/cborencoder.c
rename to src/cbor/tinycbor/src/cborencoder.c
diff --git a/src/tinycbor/src/cborencoder_close_container_checked.c b/src/cbor/tinycbor/src/cborencoder_close_container_checked.c
similarity index 100%
rename from src/tinycbor/src/cborencoder_close_container_checked.c
rename to src/cbor/tinycbor/src/cborencoder_close_container_checked.c
diff --git a/src/tinycbor/src/cborerrorstrings.c b/src/cbor/tinycbor/src/cborerrorstrings.c
similarity index 100%
rename from src/tinycbor/src/cborerrorstrings.c
rename to src/cbor/tinycbor/src/cborerrorstrings.c
diff --git a/src/tinycbor/src/cborinternal_p.h b/src/cbor/tinycbor/src/cborinternal_p.h
similarity index 100%
rename from src/tinycbor/src/cborinternal_p.h
rename to src/cbor/tinycbor/src/cborinternal_p.h
diff --git a/src/tinycbor/src/cborjson.h b/src/cbor/tinycbor/src/cborjson.h
similarity index 100%
rename from src/tinycbor/src/cborjson.h
rename to src/cbor/tinycbor/src/cborjson.h
diff --git a/src/tinycbor/src/cborparser.c b/src/cbor/tinycbor/src/cborparser.c
similarity index 100%
rename from src/tinycbor/src/cborparser.c
rename to src/cbor/tinycbor/src/cborparser.c
diff --git a/src/tinycbor/src/cborparser_dup_string.c b/src/cbor/tinycbor/src/cborparser_dup_string.c
similarity index 100%
rename from src/tinycbor/src/cborparser_dup_string.c
rename to src/cbor/tinycbor/src/cborparser_dup_string.c
diff --git a/src/tinycbor/src/cborpretty.c b/src/cbor/tinycbor/src/cborpretty.c
similarity index 100%
rename from src/tinycbor/src/cborpretty.c
rename to src/cbor/tinycbor/src/cborpretty.c
diff --git a/src/tinycbor/src/cborpretty_stdio.c b/src/cbor/tinycbor/src/cborpretty_stdio.c
similarity index 100%
rename from src/tinycbor/src/cborpretty_stdio.c
rename to src/cbor/tinycbor/src/cborpretty_stdio.c
diff --git a/src/tinycbor/src/cbortojson.c b/src/cbor/tinycbor/src/cbortojson.c
similarity index 100%
rename from src/tinycbor/src/cbortojson.c
rename to src/cbor/tinycbor/src/cbortojson.c
diff --git a/src/tinycbor/src/cborvalidation.c b/src/cbor/tinycbor/src/cborvalidation.c
similarity index 100%
rename from src/tinycbor/src/cborvalidation.c
rename to src/cbor/tinycbor/src/cborvalidation.c
diff --git a/src/tinycbor/src/compilersupport_p.h b/src/cbor/tinycbor/src/compilersupport_p.h
similarity index 100%
rename from src/tinycbor/src/compilersupport_p.h
rename to src/cbor/tinycbor/src/compilersupport_p.h
diff --git a/src/tinycbor/src/open_memstream.c b/src/cbor/tinycbor/src/open_memstream.c
similarity index 100%
rename from src/tinycbor/src/open_memstream.c
rename to src/cbor/tinycbor/src/open_memstream.c
diff --git a/src/tinycbor/src/tinycbor-version.h b/src/cbor/tinycbor/src/tinycbor-version.h
similarity index 100%
rename from src/tinycbor/src/tinycbor-version.h
rename to src/cbor/tinycbor/src/tinycbor-version.h
diff --git a/src/tinycbor/src/utf8_p.h b/src/cbor/tinycbor/src/utf8_p.h
similarity index 100%
rename from src/tinycbor/src/utf8_p.h
rename to src/cbor/tinycbor/src/utf8_p.h

From d62f4c9c4b436fd70c7dd62e0cb25546a22e3b51 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 23 Jan 2025 15:23:04 +0100
Subject: [PATCH 08/18] importing encoder decoder interfaces

---
 src/interfaces/MessageDecoder.h | 41 ++++++++++++++++++++++++++++++++
 src/interfaces/MessageEncoder.h | 42 +++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 src/interfaces/MessageDecoder.h
 create mode 100644 src/interfaces/MessageEncoder.h

diff --git a/src/interfaces/MessageDecoder.h b/src/interfaces/MessageDecoder.h
new file mode 100644
index 0000000..f4d888e
--- /dev/null
+++ b/src/interfaces/MessageDecoder.h
@@ -0,0 +1,41 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+/******************************************************************************
+ * INCLUDES
+ ******************************************************************************/
+
+#include <stddef.h>
+#include <stdint.h>
+#include "message.h"
+
+/******************************************************************************
+ * CLASS DECLARATION
+ ******************************************************************************/
+
+class MessageDecoder {
+public:
+  enum Status: uint8_t {
+      Complete,
+      InProgress,
+      Error
+  };
+
+  /**
+   * Decode a buffer into a provided message structure
+   * @param msg: the message structure that is going to be filled with data provided in the buffer
+   * @param buf: the incoming buffer that needs to be decoded
+   * @param len: the length of the incoming buffer, value will be updated with the used len of the buffer
+   * @return SUCCESS: if the message is decoded correctly
+   *         ERROR:   if the message wasn't decoded correctly
+   */
+  virtual Status decode(Message* msg, const uint8_t* const buf, size_t &len) = 0;
+};
diff --git a/src/interfaces/MessageEncoder.h b/src/interfaces/MessageEncoder.h
new file mode 100644
index 0000000..d2fc453
--- /dev/null
+++ b/src/interfaces/MessageEncoder.h
@@ -0,0 +1,42 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#pragma once
+
+/******************************************************************************
+ * INCLUDES
+ ******************************************************************************/
+
+#include <stddef.h>
+#include <stdint.h>
+#include "message.h"
+
+/******************************************************************************
+ * CLASS DECLARATION
+ ******************************************************************************/
+
+class MessageEncoder {
+public:
+  enum Status: uint8_t {
+      Complete,
+      InProgress,
+      Error
+  };
+
+  /**
+   * Encode a message into a buffer in a single shot
+   * @param msg: the message that needs to be encoded
+   * @param buf: the buffer the message will be encoded into
+   * @param len: the length of the provided buffer, value will be updated with the consumed len of the buffer
+   * @return SUCCESS: if the message is encoded correctly
+   *         ERROR:   error during the encoding of the message
+   */
+  virtual Status encode(Message* msg, uint8_t* buf, size_t& len) = 0;
+};

From e8d32f2ac5361569e9c5b64a21bd073f421dc3ab Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 23 Jan 2025 15:23:39 +0100
Subject: [PATCH 09/18] implementing encoder interface

---
 src/cbor/MessageEncoder.cpp |  80 ++++++++++++++++++++++
 src/cbor/MessageEncoder.h   | 132 ++++++++++++++++++++++++++++++++++++
 2 files changed, 212 insertions(+)
 create mode 100644 src/cbor/MessageEncoder.cpp
 create mode 100644 src/cbor/MessageEncoder.h

diff --git a/src/cbor/MessageEncoder.cpp b/src/cbor/MessageEncoder.cpp
new file mode 100644
index 0000000..0dc0924
--- /dev/null
+++ b/src/cbor/MessageEncoder.cpp
@@ -0,0 +1,80 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#include "MessageEncoder.h"
+#include <algorithm>
+
+MessageEncoder::Status CBORMessageEncoderSingleton::encode(Message* message, uint8_t * data, size_t& len) {
+  // prepare cbor structure
+  CborEncoder encoder;
+
+  cbor_encoder_init(&encoder, data, len, 0);
+
+  auto encoder_it = encoders.begin();
+
+  for(; encoder_it != encoders.end(); encoder_it++) {
+    if(encoder_it->first == message->id) {
+      break;
+    }
+  }
+
+  // check if message.id exists on the encoders list or return error
+  if(encoder_it == encoders.end()) {
+    return MessageEncoder::Status::Error;
+  }
+
+  // encode the message
+  if(encoder_it->second->_encode(&encoder, message) == MessageEncoder::Status::Error) {
+    return MessageEncoder::Status::Error;
+  }
+
+  len = cbor_encoder_get_buffer_size(&encoder, data);
+
+  return MessageEncoder::Status::Complete;
+}
+
+CBORMessageEncoderSingleton& CBORMessageEncoderSingleton::getInstance() {
+  static CBORMessageEncoderSingleton singleton;
+
+  return singleton;
+}
+
+void CBORMessageEncoderSingleton::append(MessageId id, CBORMessageEncoderInterface* encoder) {
+  auto encoder_it = encoders.begin();
+
+  for(; encoder_it != encoders.end(); encoder_it++) {
+    if(encoder_it->first == id) {
+      return;
+    }
+  }
+
+  encoders.push_back(
+    std::make_pair(id, encoder)
+  );
+}
+
+CBORMessageEncoderInterface::CBORMessageEncoderInterface(const CBORTag tag, const MessageId id)
+: tag(tag), id(id) {
+  // call singleton/global variable and insert this encoder
+  CBORMessageEncoderSingleton::getInstance().append(id, this);
+}
+
+MessageEncoder::Status CBORMessageEncoderInterface::_encode(CborEncoder* encoder, Message *msg) {
+  // this must always be true, it could mean that there are issues in the map of encoders
+  assert(msg->id == id);
+
+  if (tag == cbor::tag::CBORUnknownCmdTag16b ||
+      tag == cbor::tag::CBORUnknownCmdTag32b ||
+      tag == cbor::tag::CBORUnknownCmdTag64b ||
+      cbor_encode_tag(encoder, tag) != CborNoError) {
+    return MessageEncoder::Status::Error;
+  }
+
+  return this->encode(encoder, msg);
+}
diff --git a/src/cbor/MessageEncoder.h b/src/cbor/MessageEncoder.h
new file mode 100644
index 0000000..2a8003b
--- /dev/null
+++ b/src/cbor/MessageEncoder.h
@@ -0,0 +1,132 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+#include <vector>
+#include "../interfaces/MessageEncoder.h"
+#include "CBOR.h"
+#include "../interfaces/message.h"
+#include "./tinycbor/cbor-lib.h"
+
+// forward declaration
+class CBORMessageEncoderSingleton;
+
+/*
+ * This library collects the interfaces used to encode Messages. Messages are C structs
+ * that are identified by a uint32 id after which they can contain anything.
+ * The objective of this library is to be modular and extensible in other libraries.
+ *
+ * In order to do so one have to extend the class `CBORMessageEncoderInterface`,
+ * provide the associated CBORTag and MessageId and provide a way to encode the message
+ * specific data. MessageId must be univocal across all EncoderInterfaces instantiated.
+ * The class implemented must be instantiated somewhere (using extern may be helpful)
+ * and that is enough to have it included in the encode process.
+ *
+ * In order to encode a message one can instantiate `CBORMessageEncoder` and
+ * call the encode function.
+ */
+
+/**
+ * CBORMessageEncoderInterface class is an abstract class one has to implement
+ * in order to provide the instructions needed to encode a buffer contasining
+ * a message specific data.
+ */
+class CBORMessageEncoderInterface {
+public:
+
+  /**
+   * Constructor that initializes the CBORMessageEncoderInterface by providing the associated
+   * CBORTag and MessageId. The constructor also appends the object into CBORMessageEncoderSingleton
+   * allowing it to be used in CBORMessageEncoderSingleton::encode
+   *
+   * @param tag the cbor tag the message is associated with
+   * @param id  the message id the message is associated with
+   */
+  CBORMessageEncoderInterface(const CBORTag tag, const MessageId id);
+  virtual ~CBORMessageEncoderInterface() {}
+
+protected:
+
+  /**
+   * Abstract encode function one must implement to encode a Message into a provided buffer
+   *
+   * @param encoder tinycbor encoder struct
+   * @param msg     The message from which data must be extracted
+   */
+  virtual MessageEncoder::Status encode(CborEncoder* encoder, Message *msg) = 0;
+
+private:
+  const CBORTag tag;
+  const MessageId id;
+
+  friend CBORMessageEncoderSingleton;
+
+  /**
+   * Encode wrapper function that encodes the cbor tag and then calls the encode virtual function
+   *
+   * @param encoder tinycbor encoder struct
+   * @param msg     The message from which data must be extracted
+   */
+  MessageEncoder::Status _encode(CborEncoder* encoder, Message *msg);
+};
+
+/**
+ * This class is a singleton. It collects CBORMessageEncoderInterfaces implementations to encode
+ * all possible CBOR encoded messages
+ */
+class CBORMessageEncoderSingleton: public MessageEncoder {
+public:
+  /**
+   * Get the singleton instance
+   */
+  static CBORMessageEncoderSingleton& getInstance();
+
+  /**
+   * Add a new encoder to the singleton instance associating it to the provided cbor tag
+   *
+   * @param tag     the tag to which we associate the encoder
+   * @param encoder the instance of encoder to append
+   */
+  void append(MessageId id, CBORMessageEncoderInterface* encoder);
+
+  /**
+   * Encode a message and put the contents into a byte buffer. The message should be big enough
+   * to accommodate the content of the buffer.
+   *
+   * @param[in] msg     A struct that embeds struct Message
+   * @param[in out] buf The output buffer onto which the message will be encoded
+   * @param[in out] len The length of the buffer
+   */
+  MessageEncoder::Status encode(Message* message, uint8_t * data, size_t& len);
+private:
+  CBORMessageEncoderSingleton() {}
+
+  std::vector<std::pair<MessageId, CBORMessageEncoderInterface*>> encoders;
+};
+
+/**
+ * In order to encode a message one can instantiate `CBORMessageEncoder` and
+ * call the encode function. In the future this class will contain encode session related
+ * information, in order to allow streaming decoding
+ */
+class CBORMessageEncoder: public MessageEncoder {
+public:
+  /**
+   * Encode a message and put the contents into a byte buffer. The message should be big enough
+   * to accommodate the content of the buffer.
+   *
+   * @param[in] msg     A struct that embeds struct Message
+   * @param[in out] buf The output buffer onto which the message will be encoded
+   * @param[in out] len The length of the buffer
+   */
+  inline MessageEncoder::Status encode(Message* msg, uint8_t* buf, size_t &len) {
+    return CBORMessageEncoderSingleton::getInstance().encode(msg, buf, len);
+  }
+};

From f137450a1c7d2adb55460973c058da114a3d169b Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 23 Jan 2025 15:23:51 +0100
Subject: [PATCH 10/18] implementing decoder interface

---
 src/cbor/MessageDecoder.cpp |  94 +++++++++++++++++++++++++
 src/cbor/MessageDecoder.h   | 133 ++++++++++++++++++++++++++++++++++++
 2 files changed, 227 insertions(+)
 create mode 100644 src/cbor/MessageDecoder.cpp
 create mode 100644 src/cbor/MessageDecoder.h

diff --git a/src/cbor/MessageDecoder.cpp b/src/cbor/MessageDecoder.cpp
new file mode 100644
index 0000000..ae630cd
--- /dev/null
+++ b/src/cbor/MessageDecoder.cpp
@@ -0,0 +1,94 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#include "MessageDecoder.h"
+
+MessageDecoder::Status CBORMessageDecoderSingleton::decode(Message* msg, const uint8_t* const buf, size_t &len) {
+  // prepare cbor structure
+  CborValue iter;
+  CborTag tag;
+  CborParser parser;
+
+  if (cbor_parser_init(buf, len, 0, &parser, &iter) != CborNoError) {
+    return MessageDecoder::Status::Error;
+  }
+
+  if (iter.type != CborTagType) {
+    return MessageDecoder::Status::Error;
+  }
+
+  if (cbor_value_get_tag(&iter, &tag) != CborNoError) {
+    return MessageDecoder::Status::Error;
+  }
+
+  if (cbor_value_advance(&iter) != CborNoError) {
+    return MessageDecoder::Status::Error;
+  }
+
+  auto decoder_it = decoders.begin();
+
+  for(; decoder_it != decoders.end(); decoder_it++) {
+    if(decoder_it->first == tag) {
+      break;
+    }
+  }
+
+  // check if message.id exists on the decoders list or return error
+  if(decoder_it == decoders.end()) {
+    return MessageDecoder::Status::Error;
+  }
+
+  // encode the message
+  if(decoder_it->second->_decode(&iter, msg) == MessageDecoder::Status::Error) {
+    return MessageDecoder::Status::Error;
+  }
+
+  return MessageDecoder::Status::Complete;
+}
+
+CBORMessageDecoderSingleton& CBORMessageDecoderSingleton::getInstance() {
+  static CBORMessageDecoderSingleton singleton;
+
+  return singleton;
+}
+
+void CBORMessageDecoderSingleton::append(CBORTag tag, CBORMessageDecoderInterface* decoder) {
+    auto decoder_it = decoders.begin();
+
+  for(; decoder_it != decoders.end(); decoder_it++) {
+    if(decoder_it->first == tag) {
+      return;
+    }
+  }
+
+  decoders.push_back(
+    std::make_pair(tag, decoder)
+  );
+}
+
+CBORMessageDecoderInterface::CBORMessageDecoderInterface(const CBORTag tag, const MessageId id)
+: tag(tag), id(id) {
+  // call singleton/global variable and insert this decoder
+  CBORMessageDecoderSingleton::getInstance().append(tag, this);
+}
+
+MessageDecoder::Status CBORMessageDecoderInterface::_decode(CborValue* iter, Message *msg) {
+  CborValue array_iter;
+  msg->id = this->id;
+
+  if (cbor_value_get_type(iter) != CborArrayType) {
+    return MessageDecoder::Status::Error;
+  }
+
+  if (cbor_value_enter_container(iter, &array_iter) != CborNoError) {
+    return MessageDecoder::Status::Error;
+  }
+
+  return decode(&array_iter, msg);
+}
diff --git a/src/cbor/MessageDecoder.h b/src/cbor/MessageDecoder.h
new file mode 100644
index 0000000..1a9bf58
--- /dev/null
+++ b/src/cbor/MessageDecoder.h
@@ -0,0 +1,133 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+#include <vector>
+#include "../interfaces/MessageDecoder.h"
+#include "CBOR.h"
+#include "../interfaces/message.h"
+#include "./tinycbor/cbor-lib.h"
+
+// forward declaration
+class CBORMessageDecoderSingleton;
+
+/*
+ * This library collects the interfaces used to decode Messages. Messages are C structs
+ * that are identified by a uint32 id after which they can contain anything.
+ * The objective of this library is to be modular and extensible in other libraries.
+ *
+ * In order to do so one have to extend the class `CBORMessageDecoderInterface`,
+ * provide the associated CBORTag and MessageId and provide a way to decode the message
+ * specific data. MessageId must be univocal across all DecoderInterfaces instantiated.
+ * The class implemented must be instantiated somewhere (using extern may be helpful)
+ * and that is enough to have it included in the decode process.
+ *
+ * In order to decode a message one can instantiate `CBORMessageDecoder` and
+ * call the decode function.
+ */
+
+/**
+ * CBORMessageDecoderInterface class is an abstract class one has to implement
+ * in order to provide the instructions needed to decode a buffer contasining
+ * a message specific data.
+ */
+class CBORMessageDecoderInterface {
+public:
+
+  /**
+   * Constructor that initializes the CBORMessageDecoderInterface by providing the associated
+   * CBORTag and MessageId. The constructor also appends the object into CBORMessageDecoderSingleton
+   * allowing it to be used in CBORMessageDecoderSingleton::decode
+   *
+   * @param tag the cbor tag the message is associated with
+   * @param id  the message id the message is associated with
+   */
+  CBORMessageDecoderInterface(const CBORTag tag, const MessageId id);
+  virtual ~CBORMessageDecoderInterface() {}
+
+protected:
+
+  /**
+   * Abstract decode function one must implement to decode the Message meaningful
+   * information present into the provided buffer
+   *
+   * @param iter tinycbor iterator to the buffer provided to CBORMessageDecoderSingleton::decode
+   * @param msg  The message to which data must be applied to. Casting may be needed
+   */
+  virtual MessageDecoder::Status decode(CborValue* iter, Message *msg) = 0;
+
+private:
+  const CBORTag tag;
+  const MessageId id;
+
+  friend CBORMessageDecoderSingleton;
+
+  /**
+   * Decode wrapper function that opens the cbor array and calls the abstract decode function
+   *
+   * @param iter tinycbor iterator to the buffer provided to CBORMessageDecoderSingleton::decode
+   * @param msg  The message to which data must be applied to. Casting may be needed
+   */
+  MessageDecoder::Status _decode(CborValue* iter, Message *msg);
+};
+
+/**
+ * This class is a singleton. It collects CBORMessageDecoderInterfaces implementations to decode
+ * all possible CBOR encoded messages
+ */
+class CBORMessageDecoderSingleton: public MessageDecoder {
+public:
+  /**
+   * Get the singleton instance
+   */
+  static CBORMessageDecoderSingleton& getInstance();
+
+  /**
+   * Add a new decoder to the singleton instance associating it to the provided cbor tag
+   *
+   * @param tag     the tag to which we associate the decoder
+   * @param decoder the instance of decoder to append
+   */
+  void append(CBORTag tag, CBORMessageDecoderInterface* decoder);
+
+  /**
+   * Decode a buffer and put the contents into a message. The message should be big enough
+   * to accommodate the content of the buffer.
+   *
+   * @param[out] msg    A struct that embeds struct Message onto which the content of buf is copied
+   * @param[in] buf     The input buffer containing a cbor encoded message
+   * @param[in out] len The length of the buffer
+   */
+  MessageDecoder::Status decode(Message* msg, const uint8_t* const buf, size_t &len);
+private:
+  CBORMessageDecoderSingleton() {}
+
+  std::vector<std::pair<CBORTag, CBORMessageDecoderInterface*>> decoders;
+};
+
+/**
+ * In order to decode a message one can instantiate `CBORMessageDecoder` and
+ * call the decode function. In the future this class will contain decode session related
+ * information, in order to allow streaming decoding
+ */
+class CBORMessageDecoder: public MessageDecoder {
+public:
+  /**
+   * Decode a buffer and put the contents into a message. The message should be big enough
+   * to accommodate the content of the buffer.
+   *
+   * @param[out] msg    A struct that embeds struct Message onto which the content of buf is copied
+   * @param[in] buf     The input buffer containing a cbor encoded message
+   * @param[in out] len The length of the buffer
+   */
+  inline MessageDecoder::Status decode(Message* msg, const uint8_t* const buf, size_t &len) {
+    return CBORMessageDecoderSingleton::getInstance().decode(msg, buf, len);
+  }
+};

From 6e29e448db7d3631dfb0c68d4fb45758e5f1dd42 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 23 Jan 2025 15:24:16 +0100
Subject: [PATCH 11/18] defining common structures for cbor

---
 src/cbor/CBOR.h | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 src/cbor/CBOR.h

diff --git a/src/cbor/CBOR.h b/src/cbor/CBOR.h
new file mode 100644
index 0000000..45e4033
--- /dev/null
+++ b/src/cbor/CBOR.h
@@ -0,0 +1,24 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+typedef uint64_t CBORTag;
+
+namespace cbor {
+  namespace tag {
+    enum : CBORTag {
+      // Unknown Command Tag https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
+      CBORUnknownCmdTag16b    = 0xffff,              // invalid tag
+      CBORUnknownCmdTag32b    = 0xffffffff,          // invalid tag
+      CBORUnknownCmdTag64b    = 0xffffffffffffffff,  // invalid tag
+      CBORUnknownCmdTag       = CBORUnknownCmdTag32b
+    };
+  }
+}

From 8fde6fbd1d0445090146e73b5cde30bd7820cf24 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 23 Jan 2025 15:25:25 +0100
Subject: [PATCH 12/18] improving entrypoint for cbor

---
 src/Arduino_TinyCBOR.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Arduino_TinyCBOR.h b/src/Arduino_TinyCBOR.h
index 0ac7ca1..c16e55d 100644
--- a/src/Arduino_TinyCBOR.h
+++ b/src/Arduino_TinyCBOR.h
@@ -9,4 +9,4 @@
 */
 #pragma once
 
-#include "./tinycbor/cbor-lib.h"
+#include "./cbor/tinycbor/cbor-lib.h"

From 8882b2767a4988eed1409201cb51dc44866cd2e3 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 23 Jan 2025 15:25:49 +0100
Subject: [PATCH 13/18] defining testing suite for cbor encoders/decoders

---
 extras/test/CMakeLists.txt                 | 15 ++++
 extras/test/src/cbor/test_cbor_decoder.cpp | 85 ++++++++++++++++++++++
 extras/test/src/cbor/test_cbor_encoder.cpp | 79 ++++++++++++++++++++
 3 files changed, 179 insertions(+)
 create mode 100644 extras/test/src/cbor/test_cbor_decoder.cpp
 create mode 100644 extras/test/src/cbor/test_cbor_encoder.cpp

diff --git a/extras/test/CMakeLists.txt b/extras/test/CMakeLists.txt
index 2fb0dd0..f504065 100644
--- a/extras/test/CMakeLists.txt
+++ b/extras/test/CMakeLists.txt
@@ -27,6 +27,8 @@ set(TEST_SRCS
   src/crc16/test_crc16.cpp
   src/sha256/test_sha256.cpp
   src/hex/test_hex.cpp
+  src/cbor/test_cbor_encoder.cpp
+  src/cbor/test_cbor_decoder.cpp
 )
 
 set(TEST_DUT_SRCS
@@ -34,6 +36,19 @@ set(TEST_DUT_SRCS
   ../../src/crc/crc16.cpp
   ../../src/sha256/sha2.c
   ../../src/hex/chex.h
+  ../../src/cbor/MessageDecoder.cpp
+  ../../src/cbor/MessageEncoder.cpp
+  ../../src/cbor/tinycbor
+  ../../src/cbor/tinycbor/src/cborencoder.c
+  ../../src/cbor/tinycbor/src/cborencoder_close_container_checked.c
+  ../../src/cbor/tinycbor/src/cborerrorstrings.c
+  ../../src/cbor/tinycbor/src/cborparser.c
+  ../../src/cbor/tinycbor/src/cborparser_dup_string.c
+  ../../src/cbor/tinycbor/src/cborpretty.c
+  ../../src/cbor/tinycbor/src/cborpretty_stdio.c
+  ../../src/cbor/tinycbor/src/cbortojson.c
+  ../../src/cbor/tinycbor/src/cborvalidation.c
+  ../../src/cbor/tinycbor/src/open_memstream.c
 )
 
 ##########################################################################
diff --git a/extras/test/src/cbor/test_cbor_decoder.cpp b/extras/test/src/cbor/test_cbor_decoder.cpp
new file mode 100644
index 0000000..09e24f4
--- /dev/null
+++ b/extras/test/src/cbor/test_cbor_decoder.cpp
@@ -0,0 +1,85 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/matchers/catch_matchers.hpp>
+#include <catch2/matchers/catch_matchers_string.hpp>
+#include <cbor/MessageDecoder.h>
+
+#include <stdio.h>
+
+enum : MessageId {
+    CBORTestMessageId = 0x0123,
+};
+
+enum : CBORTag {
+    CBORTestMessageTag = 0x0321,
+};
+
+struct CBORTestMessage {
+    Message m;
+    char parameter[20];
+};
+
+class CustomMessageDecoder: public CBORMessageDecoderInterface {
+public:
+    CustomMessageDecoder()
+    : CBORMessageDecoderInterface(CBORTestMessageTag, CBORTestMessageId) {}
+
+protected:
+    MessageDecoder::Status decode(CborValue* iter, Message *msg) override {
+        CBORTestMessage* test = (CBORTestMessage*) msg;
+        size_t dest_size = 20;
+
+        if(!cbor_value_is_text_string(iter)) {
+            return MessageDecoder::Status::Error;
+        }
+
+        // NOTE: keep in mind that _cbor_value_copy_string tries to put a \0 at the end of the string
+        if(_cbor_value_copy_string(iter, test->parameter, &dest_size, NULL) != CborNoError) {
+            return MessageDecoder::Status::Error;
+        }
+
+        return MessageDecoder::Status::Complete;
+    }
+} customMessageDecoder;
+
+SCENARIO( "A custom decoder is defined", "[cbor][decode]" ) {
+    CBORMessageDecoder decoder;
+    GIVEN( "A buffer containing a cbor encoded message" ) {
+        CBORTestMessage expected_result {
+            CBORTestMessageId,
+            "abcdef",
+        };
+
+        uint8_t buffer[] {
+            0xD9, 0x03, 0x21, 0x81, 0x66, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
+        };
+        size_t buffer_len = sizeof(buffer);
+
+        CBORTestMessage cmd_res;
+
+        MessageDecoder::Status res = decoder.decode((Message*)&cmd_res, buffer, buffer_len);
+
+        THEN( "Message decode result is Complete" ) {
+            REQUIRE(res == MessageDecoder::Status::Complete);
+        }
+
+        THEN( "the decode result matches the expectations" ) {
+            REQUIRE(buffer_len == sizeof(buffer));
+
+            REQUIRE(expected_result.m.id == cmd_res.m.id);
+
+            std::string parameter_expected(expected_result.parameter);
+            std::string parameter_result(cmd_res.parameter);
+
+            REQUIRE_THAT(parameter_result, Catch::Matchers::Equals(parameter_expected));
+        }
+    }
+}
diff --git a/extras/test/src/cbor/test_cbor_encoder.cpp b/extras/test/src/cbor/test_cbor_encoder.cpp
new file mode 100644
index 0000000..8c2d899
--- /dev/null
+++ b/extras/test/src/cbor/test_cbor_encoder.cpp
@@ -0,0 +1,79 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/matchers/catch_matchers.hpp>
+#include <catch2/matchers/catch_matchers_vector.hpp>
+#include <cbor/MessageEncoder.h>
+
+enum : MessageId {
+    CBORTestMessageId = 0x0123,
+};
+
+enum : CBORTag {
+    CBORTestMessageTag = 0x0321,
+};
+
+
+struct CBORTestMessage {
+    Message m;
+    char parameter[20];
+};
+
+class CustomMessageEncoder: public CBORMessageEncoderInterface {
+public:
+    CustomMessageEncoder()
+    : CBORMessageEncoderInterface(CBORTestMessageTag, CBORTestMessageId) {}
+
+protected:
+    MessageEncoder::Status encode(CborEncoder* encoder, Message *msg) override {
+        CBORTestMessage * testMessage = (CBORTestMessage *) msg;
+        CborEncoder array_encoder;
+
+        if(cbor_encoder_create_array(encoder, &array_encoder, 1) != CborNoError) {
+            return MessageEncoder::Status::Error;
+        }
+
+        if(cbor_encode_text_stringz(&array_encoder, testMessage->parameter) != CborNoError) {
+            return MessageEncoder::Status::Error;
+        }
+
+        if(cbor_encoder_close_container(encoder, &array_encoder) != CborNoError) {
+            return MessageEncoder::Status::Error;
+        }
+        return MessageEncoder::Status::Complete;
+    }
+} customMessageEncoder;
+
+SCENARIO( "A custom encoder is defined", "[cbor][encode]" ) {
+    CBORMessageEncoder encoder;
+    uint8_t buffer[100]; // shared buffer for encoding
+    const size_t buf_len = sizeof(buffer);
+
+    GIVEN( "A Message with an id that the global encoder is able to encode" ) {
+        CBORTestMessage cmd {
+            CBORTestMessageId,
+            "abcdef",
+        };
+        size_t res_len=buf_len;
+        MessageEncoder::Status res = encoder.encode((Message*)&cmd, buffer, res_len);
+
+        THEN( "Message encode result is Complete" ) {
+            REQUIRE(res == MessageEncoder::Status::Complete);
+        }
+
+        THEN( "the encode result matches the expectations" ) {
+            std::vector<uint8_t> res(buffer, buffer+res_len);
+
+            REQUIRE_THAT(res, Catch::Matchers::Equals(std::vector<uint8_t>{
+                0xD9, 0x03, 0x21, 0x81, 0x66, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
+            }));
+        }
+    }
+}

From 162d74d9dbdb2cff7671018d090cbf2f029e7557 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Mon, 27 Jan 2025 09:29:18 +0100
Subject: [PATCH 14/18] defining Message structure for encoding and decoding
 messages with an id specifier

---
 src/interfaces/message.h | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 src/interfaces/message.h

diff --git a/src/interfaces/message.h b/src/interfaces/message.h
new file mode 100644
index 0000000..ba09c87
--- /dev/null
+++ b/src/interfaces/message.h
@@ -0,0 +1,34 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#pragma once
+
+typedef uint32_t MessageId;
+
+/**
+ * The following struct can be used as a template to create ArduinoCloud compatible
+ * Messages that can be handled by encoders/decoders and other Cloud related message exchange
+ * These kind of messages are required to be identifiable by a starting uint32_t uinique identification number.
+ *
+ * In order to use this structure you need to embed this into another structure and
+ * add additional parameters
+ */
+struct Message {
+  MessageId id;
+};
+
+/**
+ * The following enum is defined to assign Arduino MessageIds starting values
+ * and boundaries and avoid value clashing
+ */
+enum : MessageId {
+  ArduinoIOTCloudStartMessageId     = 0x100,
+  ArduinoProvisioningStartMessageId = 0x200,
+};

From 90abb08af222734da5ef559ac2a507c204e9d194 Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 30 Jan 2025 12:43:40 +0100
Subject: [PATCH 15/18] adding entrypoint for CBOR wrapper library

---
 src/Arduino_CBOR.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 src/Arduino_CBOR.h

diff --git a/src/Arduino_CBOR.h b/src/Arduino_CBOR.h
new file mode 100644
index 0000000..d1584eb
--- /dev/null
+++ b/src/Arduino_CBOR.h
@@ -0,0 +1,13 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+#include "./cbor/MessageEncoder.h"
+#include "./cbor/MessageDecoder.h"

From 5fd19ba84d34ffbc3def4d1035d5a21fd9e2f06b Mon Sep 17 00:00:00 2001
From: Andrea Gilardoni <a.gilardoni@arduino.cc>
Date: Thu, 6 Feb 2025 15:01:13 +0100
Subject: [PATCH 16/18] Added example for CborEncoder and CborDecoder usage

---
 .github/workflows/compile-examples.yml        |  2 +
 .../customCborDecoder/customCborDecoder.ino   | 79 +++++++++++++++++++
 .../customCborEncoder/customCborEncoder.ino   | 77 ++++++++++++++++++
 3 files changed, 158 insertions(+)
 create mode 100644 examples/customCborDecoder/customCborDecoder.ino
 create mode 100644 examples/customCborEncoder/customCborEncoder.ino

diff --git a/.github/workflows/compile-examples.yml b/.github/workflows/compile-examples.yml
index 6e4d438..5c0df43 100644
--- a/.github/workflows/compile-examples.yml
+++ b/.github/workflows/compile-examples.yml
@@ -26,6 +26,8 @@ jobs:
         - examples/crc32
         - examples/crc16
         - examples/sha256
+        - examples/customCborDecoder
+        - examples/customCborEncoder
       SKETCHES_REPORTS_PATH: sketches-reports
 
     strategy:
diff --git a/examples/customCborDecoder/customCborDecoder.ino b/examples/customCborDecoder/customCborDecoder.ino
new file mode 100644
index 0000000..7d0931b
--- /dev/null
+++ b/examples/customCborDecoder/customCborDecoder.ino
@@ -0,0 +1,79 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#include <Arduino_CBOR.h>
+
+enum : MessageId {
+    CBORTestMessageId = 0x0123,
+};
+
+enum : CBORTag {
+    CBORTestMessageTag = 0x0321,
+};
+
+
+struct CBORTestMessage {
+    Message m;
+    char parameter[20];
+};
+
+class CustomMessageDecoder: public CBORMessageDecoderInterface {
+public:
+    CustomMessageDecoder()
+    : CBORMessageDecoderInterface(CBORTestMessageTag, CBORTestMessageId) {}
+
+protected:
+    MessageDecoder::Status decode(CborValue* iter, Message *msg) override {
+        CBORTestMessage* test = (CBORTestMessage*) msg;
+        size_t dest_size = 20;
+
+        if(!cbor_value_is_text_string(iter)) {
+            return MessageDecoder::Status::Error;
+        }
+
+        // NOTE: keep in mind that _cbor_value_copy_string tries to put a \0 at the end of the string
+        if(_cbor_value_copy_string(iter, test->parameter, &dest_size, NULL) != CborNoError) {
+            return MessageDecoder::Status::Error;
+        }
+
+        return MessageDecoder::Status::Complete;
+    }
+} customMessageDecoder;
+
+void setup() {
+    Serial.begin(9600);
+    while(!Serial);
+
+    CBORMessageDecoder decoder;
+
+    CBORTestMessage expected_result {
+        CBORTestMessageId,
+        "abcdef",
+    };
+
+    uint8_t buffer[] {
+        0xD9, 0x03, 0x21, 0x81, 0x66, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
+    };
+    size_t buffer_len = sizeof(buffer);
+
+    CBORTestMessage cmd_res;
+    MessageDecoder::Status res = decoder.decode((Message*)&cmd_res, buffer, buffer_len);
+
+    if(res == MessageDecoder::Status::Complete &&
+        cmd_res.m.id == expected_result.m.id &&
+        strcmp(cmd_res.parameter, expected_result.parameter) == 0) {
+
+        Serial.println("Decode operation completed with success");
+    } else {
+        Serial.println("Decode operation failed");
+    }
+}
+
+void loop() {}
diff --git a/examples/customCborEncoder/customCborEncoder.ino b/examples/customCborEncoder/customCborEncoder.ino
new file mode 100644
index 0000000..0ab9fc8
--- /dev/null
+++ b/examples/customCborEncoder/customCborEncoder.ino
@@ -0,0 +1,77 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+
+#include <Arduino_CBOR.h>
+
+enum : MessageId {
+    CBORTestMessageId = 0x0123,
+};
+
+enum : CBORTag {
+    CBORTestMessageTag = 0x0321,
+};
+
+
+struct CBORTestMessage {
+    Message m;
+    char parameter[20];
+};
+
+class CustomMessageEncoder: public CBORMessageEncoderInterface {
+public:
+    CustomMessageEncoder()
+    : CBORMessageEncoderInterface(CBORTestMessageTag, CBORTestMessageId) {}
+
+protected:
+    MessageEncoder::Status encode(CborEncoder* encoder, Message *msg) override {
+        CBORTestMessage * testMessage = (CBORTestMessage *) msg;
+        CborEncoder array_encoder;
+
+        if(cbor_encoder_create_array(encoder, &array_encoder, 1) != CborNoError) {
+            return MessageEncoder::Status::Error;
+        }
+
+        if(cbor_encode_text_stringz(&array_encoder, testMessage->parameter) != CborNoError) {
+            return MessageEncoder::Status::Error;
+        }
+
+        if(cbor_encoder_close_container(encoder, &array_encoder) != CborNoError) {
+            return MessageEncoder::Status::Error;
+        }
+        return MessageEncoder::Status::Complete;
+    }
+} customMessageEncoder;
+
+void setup() {
+    Serial.begin(9600);
+    while(!Serial);
+
+    CBORMessageEncoder encoder;
+    uint8_t buffer[100]; // shared buffer for encoding
+    uint8_t expected[] = {0xD9, 0x03, 0x21, 0x81, 0x66, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66};
+    const size_t buf_len = sizeof(buffer);
+
+    CBORTestMessage cmd {
+        CBORTestMessageId,
+        "abcdef",
+    };
+    size_t res_len=buf_len;
+    MessageEncoder::Status res = encoder.encode((Message*)&cmd, buffer, res_len);
+
+    if(res == MessageEncoder::Status::Complete &&
+        memcmp(buffer, expected, res_len) == 0) {
+
+        Serial.println("Encode operation completed with success");
+    } else {
+        Serial.println("Encode operation failed");
+    }
+}
+
+void loop() {}

From b48205af5adc152ec923418e4e8f1403439d088d Mon Sep 17 00:00:00 2001
From: Mattia Pennasilico <m.pennasilico@arduino.cc>
Date: Wed, 5 Mar 2025 12:32:53 +0100
Subject: [PATCH 17/18] readme: add CI badges and examples list

---
 README.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 80f3080..296ea8c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,14 @@
-# Arduino Cloud Utils
+# 🛠️ Arduino Cloud Utils
 
-This library contains a set of functionalities that may be shared among cloud related projects, in particular functionalities for ArduinoIoTCloud
\ No newline at end of file
+[![Arduino Lint](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/check-arduino.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/check-arduino.yml) [![Compile Examples](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/compile-examples.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/compile-examples.yml) [![Spell Check](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/spell-check.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/spell-check.yml) [![Sync Labels](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/sync-labels.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_CloudUtils/actions/workflows/sync-labels.yml) 
+
+This library contains a set of functionalities that may be shared among cloud related projects, in particular functionalities for ArduinoIoTCloud
+
+# 🔧 Utilities
+* ✉️ [CRC16](examples/crc16)
+* 📧 [CRC32](examples/crc32)
+* 🔒 [CBOR decoder](examples/customCborDecoder)
+* 🔓 [CBOR encoder](examples/customCborEncoder)
+* ⬆️ [LZSS decoder](examples/lzssDecoder)
+* 💨 [SHA256](examples/sha256)
+* ⏲️ [Timed action](examples/timedBlink)

From 55fb70a005075f6525c384a758225c7ad0d3abf2 Mon Sep 17 00:00:00 2001
From: Mattia Pennasilico <m.pennasilico@arduino.cc>
Date: Mon, 10 Mar 2025 10:45:19 +0100
Subject: [PATCH 18/18] Publish 1.0.0

---
 library.properties | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/library.properties b/library.properties
index e373679..3fc5233 100644
--- a/library.properties
+++ b/library.properties
@@ -1,5 +1,5 @@
 name=Arduino_CloudUtils
-version=0.0.1
+version=1.0.0
 author=Arduino
 maintainer=Arduino <info@arduino.cc>
 sentence=Utility module for features related to ArduinoCloud and Cloud in general