diff --git a/sw/boitarire_sw/boitarire_sw.ino b/sw/boitarire_sw/boitarire_sw.ino
index 23b3389eac080e6c20d5f1f39eff54b573fbd9d4..06d4d0099a1248d4d3045e62d4b671c3173e7050 100644
--- a/sw/boitarire_sw/boitarire_sw.ino
+++ b/sw/boitarire_sw/boitarire_sw.ino
@@ -23,29 +23,39 @@
 #define SENSOR_ACCELEROMETER
 #define SENSOR_TOUCH_SENSOR1
 #define SENSOR_TOUCH_SENSOR2
-//#define MP3_RESET
-//#define DEBUG_UART_ACCELEROMETER // Warning : conflict with MP3 player
+
 
 // Other constants
+//Hardwaere constatnts : do not modify >_< !
 #define PIN_SENSOR_POSITION 9     // Position sensor input
 #define PIN_TOUCH_SENSOR1   8     // Touch sensor 1 input
 #define PIN_TOUCH_SENSOR2   5     // Touch sensor 2 input
 #define PIN_GROUND_SWITCH   7     // MP3 module ground switch command output
-#define PLAY_BLANK_DELAY    1000  // Blanking when playing a sound (ms)
-#define DELAY_MP3_RESET     100   // Time of ground cut of MP3 module for re-init (ms)
+
+//Calibration constants : do adjust :-)
+//#define MP3_RESET
+//#define DEBUG_UART_ACCELEROMETER // Warning : conflict with MP3 player
+#define PLAY_BLANK_DELAY    1000  // Blanking when playing a sound (ms): Must be longer than the played sample (recommended : sample duration + 100ms)
+#define DELAY_MP3_RESET     100   // Time of ground cut of MP3 module for re-init (ms) : Adjust only if hardware proiblems with new revisions of the mp3 module
 #define DEBOUNCE_DELAY      200   // Position sensor input debounce (ms)
-#define ACCEL_THRES_GYX     1000
-#define ACCEL_THRES_GYY     1000
-#define ACCEL_THRES_GYZ     1000
+#define ACCEL_THRES_GYX     1000  // Detection threshold for X axis acceleration
+#define ACCEL_THRES_GYY     1000  // Detection threshold for Y axis acceleration
+#define ACCEL_THRES_GYZ     1000  // Detection threshold for Z axis acceleration
 
 
 // Typedefs
+// Main state machine : start actions
 typedef enum 
 {
+  //Initialisation
   STM_INIT,
+  //Wainting for input (capteur)
   STM_IDLE,
+  //When input, play sample
   STM_PLAY,
+  //Waiting after playing sample
   STM_BLANK,
+  //Optional hardware reset of the MP3 module (See calibration constants for activation)
   STM_MP3_RESET,
 } tStateMachine;
 
@@ -87,21 +97,22 @@ void setup() {
   // Reserve 200 bytes for the inputString:
   inputString.reserve(200);
 
-  // Position sensor input pin - D9 - Input pull-up
+  // Position sensor input pin - See hardware constants for pin definition - Input pull-up
   pinMode(PIN_SENSOR_POSITION, INPUT_PULLUP);
 
-  // Touch sensor 1 input pin - D8 - Input no pull
+  // Touch sensor 1 input pin - See hardware constants for pin definition - Input no pull
   pinMode(PIN_TOUCH_SENSOR1, INPUT);
 
-  // Touch sensor 2 input pin - D5 - Input no pull
+  // Touch sensor 2 input pin - See hardware constants for pin definition - Input no pull
   pinMode(PIN_TOUCH_SENSOR2, INPUT);
 
   // LED output for visualisation
   pinMode(LED_BUILTIN, OUTPUT);
 
-  // MP3 module ground switch command - D7 - Output push-pull
+  // MP3 module ground switch command - See hardware constants for pin definition - Output push-pull
   pinMode(PIN_GROUND_SWITCH, OUTPUT);
 
+  //Intianlise variable, do not define constants value here
   play_blank_delay = 0;
   mp3_reset_delay = 0;
   stmState = STM_INIT;
@@ -139,7 +150,7 @@ void setup() {
 
 // Main loop
 void loop() {
-  // print the string when a newline arrives:
+  // print the string when a newline arrives: for debug purposes only
   if (stringComplete) {
     Serial.println(inputString);
 
@@ -226,7 +237,7 @@ void loop() {
         stmDebounceState = STM_DEBOUNCE_DEBOUNCE_0;
       }
       else if (millis_temp < debounce_delay)
-      { // Overflow protection
+      { // Overflow protection for uptime of several weeks or more.
         debounce_delay = 0;
       }
     break;
@@ -242,7 +253,7 @@ void loop() {
         stmDebounceState = STM_DEBOUNCE_DEBOUNCE_1;
       }
       else if (millis_temp < debounce_delay)
-      { // Overflow protection
+      { // Overflow protection for uptime of several weeks or more.
         debounce_delay = 0;
       }
     break;
@@ -277,6 +288,7 @@ void loop() {
   //-------------------
   switch (stmState)
   {
+  //Init is not used, here for future use and coding best practice
     case STM_INIT:
       stmState = STM_IDLE;
     break;
@@ -310,7 +322,7 @@ void loop() {
 #endif
       }
       else if (millis_temp < play_blank_delay)
-      { // Overflow protection
+      { // Overflow protection for uptime of several weeks or more.
         play_blank_delay = 0;
       }
     break;
@@ -323,7 +335,7 @@ void loop() {
         digitalWrite(PIN_GROUND_SWITCH, HIGH);
       }
       else if (millis_temp < mp3_reset_delay)
-      { // Overflow protection
+      { // Overflow protection for uptime of several weeks or more.
         mp3_reset_delay = 0;
       }
     break;