Merge pull request #21 from bkp23/master

Thanks for the helpful code comments!

grbl-lpc/delay.cpp

@@ -22,11 +22,11 @@
 
 void delay_init()
 {
-    LPC_TIM3->CTCR = 0;   // timer mode
+    LPC_TIM3->CTCR = 0;   // Count Control (0=TimerMode, 1-3=EdgeCounterMode)
-    LPC_TIM3->PR = 0;     // no prescale
+    LPC_TIM3->PR = 0;     // no Prescale (TC increments ever PR+1 clocks)
-    LPC_TIM3->MCR = 0;    // no MR actions
+    LPC_TIM3->MCR = 0;    // no Match Control actions
-    LPC_TIM3->CCR = 0;    // no capture
+    LPC_TIM3->CCR = 0;    // no Capture Control actions
-    LPC_TIM3->EMR = 0;    // no external match
+    LPC_TIM3->EMR = 0;    // no External Match (controls external match pins)
-    LPC_TIM3->TCR = 0b10; // reset
+    LPC_TIM3->TCR = 0b10; // reset Timer Control (0b10=Reset, 0b01=Enable)
-    LPC_TIM3->TCR = 0b01; // enable
+    LPC_TIM3->TCR = 0b01; // enable Timer Control (0b10=Reset, 0b01=Enable)
 }

grbl-lpc/flash.cpp

@@ -25,37 +25,38 @@ static constexpr unsigned flash_addr = 0xF000;                    // Last 4k sec
 static constexpr unsigned flash_size = 1024;                      // Only using 1k of a 4k sector
 static char *flash_memory = (char *)flash_addr;                   // Flash memory
 static char flash_buffer[flash_size] __attribute__((aligned(4))); // Copy of flash memory
-using Iap = void(unsigned[], unsigned[]);                         // IAP entry point
+using Iap = void(unsigned[], unsigned[]);                         // IAP entry point function
-static const Iap *iap = (Iap *)0x1FFF1FF1;                        // IAP entry point
+static const Iap *iap = (Iap *)0x1FFF1FF1;                        // IAP entry point address
 
 void eeprom_init()
 {
-    memcpy(flash_buffer, flash_memory, flash_size);
+    memcpy(flash_buffer, flash_memory, flash_size);  // Copy flash memory into local flash buffer
 }
 
 void eeprom_commit()
 {
     if (!memcmp(flash_buffer, flash_memory, flash_size))
-        return;
+        return; // No changes to commit
     unsigned prepCommand[5] = {
-        50,
+        50,                     // Prepare sector(s) for write operation
-        flash_sector,
+        flash_sector,           // Start sector
-        flash_sector,
+        flash_sector,           // End sector
     };
     unsigned eraseCommand[5] = {
-        52,
+        52,                     // Erase sector(s)
-        flash_sector,
+        flash_sector,           // Start sector
-        flash_sector,
+        flash_sector,           // End sector
-        SystemCoreClock / 1000,
+        SystemCoreClock / 1000, // CPU clock frequency in kHz
     };
     unsigned writeCommand[5] = {
-        51,
+        51,                     // Copy RAM to Flash
-        flash_addr,
+        flash_addr,             // Destination flash address (256-byte boundary)
-        (unsigned)flash_buffer,
+        (unsigned)flash_buffer, // Source RAM address (word boundary)
-        flash_size,
+        flash_size,             // Number of bytes to write (must be: 256, 512, 1024, 4096)
-        SystemCoreClock / 1000,
+        SystemCoreClock / 1000, // CPU clock frequency in kHz
     };
     unsigned output[5];
+    // Run In-Application Programming (IAP) routines
     iap(prepCommand, output);
     iap(eraseCommand, output);
     iap(prepCommand, output);

grbl/config.h

@@ -125,7 +125,7 @@
 // #define HOMING_CYCLE_1 (1<<Y_AXIS)  // COREXY COMPATIBLE: Then home Y
 
 // Number of homing cycles performed after when the machine initially jogs to limit switches.
-// This help in preventing overshoot and should improve repeatability. This value should be one or
+// This helps in preventing overshoot and should improve repeatability. This value should be one or
 // greater.
 #define N_HOMING_LOCATE_CYCLE 1 // Integer (1-128)
 

grbl/cpu_map.h

@@ -147,7 +147,7 @@
   #define SPINDLE_PWM_PORT    PORTB
   #define SPINDLE_PWM_BIT     3    // Uno Digital Pin 11
 
-#endif
+#endif // end of CPU_MAP_ATMEGA328P
 
 
 #ifdef CPU_MAP_SMOOTHIEBOARD // (Smoothieboards)
@@ -256,7 +256,7 @@
   #define SPINDLE_TCCRB_REGISTER    TCCR2B
   #define SPINDLE_OCR_REGISTER      OCR2A
   #define SPINDLE_COMB_BIT          COM2A1
-#endif
+#endif // end of CPU_MAP_SMOOTHIEBOARD
 
 
 #ifdef CPU_MAP_C3D_REMIX // (Cohesion3D Remix Boards)
@@ -359,7 +359,7 @@
   #define SPINDLE_TCCRB_REGISTER    TCCR2B
   #define SPINDLE_OCR_REGISTER      OCR2A
   #define SPINDLE_COMB_BIT          COM2A1
-#endif
+#endif // end of CPU_MAP_C3D_REMIX
 
 
 #ifdef CPU_MAP_C3D_MINI // (Cohesion3D Mini Boards)
@@ -462,7 +462,7 @@
   #define SPINDLE_TCCRB_REGISTER    TCCR2B
   #define SPINDLE_OCR_REGISTER      OCR2A
   #define SPINDLE_COMB_BIT          COM2A1
-#endif
+#endif // end of CPU_MAP_C3D_MINI
 
 
 #ifdef CPU_MAP_MKS_SBASE // (MKS SBASE Boards)
@@ -577,7 +577,7 @@
   #define SPINDLE_TCCRB_REGISTER    TCCR2B
   #define SPINDLE_OCR_REGISTER      OCR2A
   #define SPINDLE_COMB_BIT          COM2A1
-#endif
+#endif // end of CPU_MAP_MKS_SBASE
 
 
 #ifdef CPU_MAP_AZTEEG_X5 // (Azteeg X5 Boards)  not tested yet!
@@ -682,7 +682,7 @@
   #define SPINDLE_TCCRB_REGISTER    TCCR2B
   #define SPINDLE_OCR_REGISTER      OCR2A
   #define SPINDLE_COMB_BIT          COM2A1
-#endif
+#endif // end of CPU_MAP_AZTEEG_X5
 
 
 /*

grbl/defaults.h

@@ -77,7 +77,7 @@
   #define DEFAULT_SPINDLE_PWM_OFF_VALUE 0    // $34 % (% of PWM when spindle is off)
   #define DEFAULT_SPINDLE_PWM_MIN_VALUE 1    // $35 % (% of PWM when spindle is at lowest setting)
   #define DEFAULT_SPINDLE_PWM_MAX_VALUE 100  // $36 % (% of PWM when spindle is at highest setting)
-  // Up to 3 HOMING_CYCLE_x can be defined, specifying which axes are homed and in which order
+  // Up to 4 HOMING_CYCLE_x can be defined (0-3), specifying which axes are homed and in which order
   #define HOMING_CYCLE_0 ((1<<X_AXIS)|(1<<Y_AXIS))
 #endif // end of DEFAULTS_GENERIC
 

grbl/limits.c

@@ -158,9 +158,9 @@ void limits_go_home(uint8_t cycle_mask)
 
   // Initialize variables used for homing computations.
   uint8_t n_cycle = (2*N_HOMING_LOCATE_CYCLE+1);
-  uint32_t step_pin[N_AXIS];
+  uint32_t step_pin[N_AXIS]; // Tracks which pins correspond to which axes (reduces calls to get_step_pin_mask())
   float target[N_AXIS];
-  float max_travel = 0.0;
+  float max_travel = 0.0; // Maximum travel distance to move searching for limits
   uint8_t idx;
   for (idx=0; idx<N_AXIS; idx++) {
     // Initialize step pin masks
@@ -183,11 +183,12 @@ void limits_go_home(uint8_t cycle_mask)
   uint32_t limit_state, axislock, n_active_axis;
   do {
 
+    // convert current sys_position (steps) to target (mm) so unused axes remain in place
     system_convert_array_steps_to_mpos(target,sys_position);
 
     // Initialize and declare variables needed for homing routine.
-    axislock = 0;
+    axislock = 0; // Track which pins still need to find limits. Lock these axes by clearing these bits.
-    n_active_axis = 0;
+    n_active_axis = 0; // Track number of axes being homed
     for (idx=0; idx<N_AXIS; idx++) {
       // Set target location for active axes and setup computation for homing rate.
       if (bit_istrue(cycle_mask,bit(idx))) {
@@ -215,7 +216,7 @@ void limits_go_home(uint8_t cycle_mask)
           if (approach) { target[idx] = max_travel; }
           else { target[idx] = -max_travel; }
         }
-        // Apply axislock to the step port pins active in this cycle.
+        // Apply axislock to the step port pins active in this cycle, allowing motion
         axislock |= step_pin[idx];
       }
 
@@ -237,6 +238,7 @@ void limits_go_home(uint8_t cycle_mask)
         for (idx=0; idx<N_AXIS; idx++) {
           if (axislock & step_pin[idx]) {
             if (limit_state & (1 << idx)) {
+                // Clear the axislock bits to prevent axis from moving after limit is hit
                 #ifdef COREXY
                   if (idx==Z_AXIS) { axislock &= ~(step_pin[Z_AXIS]); }
                   else { axislock &= ~(step_pin[A_MOTOR]|step_pin[B_MOTOR]); }
@@ -297,7 +299,7 @@ void limits_go_home(uint8_t cycle_mask)
   // can be on either side of an axes, check and set axes machine zero appropriately. Also,
   // set up pull-off maneuver from axes limit switches that have been homed. This provides
   // some initial clearance off the switches and should also help prevent them from falsely
-  // triggering when hard limits are enabled or when more than one axes shares a limit pin.
+  // triggering when hard limits are enabled or when more than one axis shares a limit pin.
   int32_t set_axis_position;
   // Set machine positions for homed limit switches. Don't update non-homed axes.
   for (idx=0; idx<N_AXIS; idx++) {

grbl/main.c

@@ -42,13 +42,13 @@ int main(void)
 {
   // Initialize system upon power-up.
   debug_init();    // Initialize debug leds
-  isr_init();      // Set ISR priorities
+  isr_init();      // Set ISR priorities (stepper ISR uses Timer1)
-  delay_init();    // Setup delay timer
+  delay_init();    // Setup delay timer (uses Timer3)
   serial_init();   // Setup serial baud rate and interrupts
-  eeprom_init();   // Init EEPROM or FLASH
+  eeprom_init();   // Init EEPROM or Flash
   settings_init(); // Load Grbl settings from EEPROM
   current_init();  // Configure stepper driver current
-  stepper_init();  // Configure stepper pins and interrupt timers
+  stepper_init();  // Configure stepper pins and interrupt timers (uses Timer1)
   system_init();   // Configure pinout pins and pin-change interrupt
 
   memset(sys_position,0,sizeof(sys_position)); // Clear machine position.
@@ -85,8 +85,8 @@ int main(void)
     sys.r_override = DEFAULT_RAPID_OVERRIDE; // Set to 100%
     sys.spindle_speed_ovr = DEFAULT_SPINDLE_SPEED_OVERRIDE; // Set to 100%
     memset(sys_probe_position,0,sizeof(sys_probe_position)); // Clear probe position.
-    sys_probe_state = 0;
+    sys_probe_state = 0;   // PROBE_OFF
-    sys_rt_exec_state = 0;
+    sys_rt_exec_state = 0; // EXEC_STATUS_REPORT
     sys_rt_exec_alarm = 0;
     sys_rt_exec_motion_override = 0;
     sys_rt_exec_accessory_override = 0;
@@ -94,16 +94,16 @@ int main(void)
     // Reset Grbl primary systems.
     serial_reset_read_buffer(); // Clear serial read buffer
     gc_init();      // Set g-code parser to default state
-    spindle_init();
+    spindle_init(); // Configure spindle pins and PWM values
-    coolant_init();
+    coolant_init(); // Configure coolant pins
-    limits_init();
+    limits_init();  // Configure limit input pins and interrupts
-    probe_init();
+    probe_init();   // Configure probe input pin
     plan_reset();   // Clear block buffer and planner variables
     st_reset();     // Clear stepper subsystem variables.
 
     // Sync cleared gcode and planner positions to current system position.
-    plan_sync_position();
+    plan_sync_position(); // Synchronize plan position with (actual) system position
-    gc_sync_position();
+    gc_sync_position();   // Synchronize g-code position with (actual) system position
 
     // Print welcome message. Indicates an initialization has occured at power-up or with a reset.
     report_init_message();

grbl/settings.c

@@ -177,7 +177,7 @@ uint8_t settings_read_startup_line(uint8_t n, char *line)
   if (!(memcpy_from_eeprom_with_checksum((char*)line, addr, LINE_BUFFER_SIZE))) {
     // Reset line with default value
     line[0] = 0; // Empty line
-    settings_store_startup_line(n, line);
+    settings_store_startup_line(n, line); // Clear this startup line because it's corrupted
     return(false);
   }
   return(true);
@@ -190,7 +190,7 @@ uint8_t settings_read_build_info(char *line)
   if (!(memcpy_from_eeprom_with_checksum((char*)line, EEPROM_ADDR_BUILD_INFO, LINE_BUFFER_SIZE))) {
     // Reset line with default value
     line[0] = 0; // Empty line
-    settings_store_build_info(line);
+    settings_store_build_info(line); // Clear out build info string because it's corrupted
     return(false);
   }
   return(true);

grbl/settings.h

@@ -26,7 +26,7 @@
 
 
 // Version of the EEPROM data. Will be used to migrate existing data from older versions of Grbl
-// when firmware is upgraded. Always stored in byte 0 of eeprom
+// when firmware is upgraded. Always stored in byte 0 of EEPROM.
 #define SETTINGS_VERSION 11  // NOTE: Check settings_reset() when moving to next version.
 
 // Define bit flag masks for the boolean settings in settings.flag.
@@ -56,6 +56,7 @@
 // NOTE: The Atmega328p has 1KB EEPROM. The upper half is reserved for parameters and
 // the startup script. The lower half contains the global settings and space for future
 // developments.
+// Note: Address 0 of EEPROM is reserved for SETTINGS_VERSION.
 #define EEPROM_ADDR_GLOBAL         1U
 #define EEPROM_ADDR_PARAMETERS     512U
 #define EEPROM_ADDR_STARTUP_BLOCK  768U
@@ -80,7 +81,7 @@ typedef struct {
   float steps_per_mm[N_AXIS];
   float max_rate[N_AXIS];
   float acceleration[N_AXIS];
-  float max_travel[N_AXIS];
+  float max_travel[N_AXIS];  // NOTE: Stored as a negative value
   float current[N_AXIS];
 
   // Remaining Grbl settings

grbl/stepper.c

@@ -235,9 +235,9 @@ void st_wake_up()
   #endif
 
   // Enable Stepper Driver Interrupt Timer
-  LPC_TIM1->TCR = 0b10;   // reset
+  LPC_TIM1->TCR = 0b10;   // reset Timer Control (0b10=Reset, 0b01=Enable)
-  LPC_TIM1->MR0 = 4000;   // Generate first interrupt soon
+  LPC_TIM1->MR0 = 4000;   // Generate first interrupt soon (Match Register for TC)
-  LPC_TIM1->TCR = 0b01;   // enable
+  LPC_TIM1->TCR = 0b01;   // enable Timer Control (0b10=Reset, 0b01=Enable)
 }
 
 
@@ -245,11 +245,11 @@ void st_wake_up()
 void st_go_idle()
 {
   // Disable Stepper Driver Interrupt. Allow Stepper Port Reset Interrupt to finish, if active.
-  LPC_TIM1->TCR = 0;          // Disable Timer1
+  LPC_TIM1->TCR = 0;          // Disable Timer1 Control (0b10=Reset, 0b01=Enable)
   busy = false;
 
   // Set stepper driver idle state, disabled or enabled, depending on settings and circumstances.
-  bool pin_state = false; // Keep enabled.
+  bool pin_state = false; // Stepper is disabled when pin_state is true. Keep enabled by default.
   if (((settings.stepper_idle_lock_time != 0xff) || sys_rt_exec_alarm || sys.state == STATE_SLEEP) && sys.state != STATE_HOMING) {
     // Force stepper dwell to lock axes for a defined amount of time to ensure the axes come to a complete
     // stop and not drift from residual inertial forces at the end of the last movement.
@@ -355,7 +355,7 @@ extern "C" void TIMER1_IRQHandler()
       #endif
 
       // Initialize step segment timing per step and load number of steps to execute.
-      LPC_TIM1->MR0 = st.exec_segment->cycles_per_tick;
+      LPC_TIM1->MR0 = st.exec_segment->cycles_per_tick;  // Set Match Register to wait one tick
       st.step_count = st.exec_segment->n_step; // NOTE: Can sometimes be zero when moving slow.
       // If the new segment starts a new planner block, initialize stepper variables and counters.
       // NOTE: When the segment data index changes, this indicates a new planner block.
@@ -570,17 +570,17 @@ void st_reset()
 void stepper_init()
 {
   // Configure step and direction interface pins
-  STEP_DDR |= STEP_MASK;
+  STEP_DDR |= STEP_MASK;                         // Set selected stepper step pins as outputs
-  STEPPERS_DISABLE_DDR |= STEPPERS_DISABLE_MASK;
+  STEPPERS_DISABLE_DDR |= STEPPERS_DISABLE_MASK; // Set selected stepper disable pins as outputs
-  DIRECTION_DDR |= DIRECTION_MASK;
+  DIRECTION_DDR |= DIRECTION_MASK;               // Set selected stepper direction pins as outputs
 
   // Configure Timer 1: Stepper Driver Interrupt
-  LPC_TIM1->TCR = 0;            // disable
+  LPC_TIM1->TCR = 0;            // disable Timer Control (0b10=Reset, 0b01=Enable)
-  LPC_TIM1->CTCR = 0;           // timer mode
+  LPC_TIM1->CTCR = 0;           // Count Control (0=TimerMode, 1-3=EdgeCounterMode)
-  LPC_TIM1->PR = 0;             // no prescale
+  LPC_TIM1->PR = 0;             // no Prescale (TC increments every PR+1 clocks)
-  LPC_TIM1->MCR = 0b011;        // MR0: !stop, reset, interrupt
+  LPC_TIM1->MCR = 0b011;        // Match Control (0b001=InterruptEnbl, 0b010=Reset_Enbl, 0b100=Stop_Enbl)
-  LPC_TIM1->CCR = 0;            // no capture
+  LPC_TIM1->CCR = 0;            // no Capture Control actions
-  LPC_TIM1->EMR = 0;            // no external match
+  LPC_TIM1->EMR = 0;            // no External Match (controls external match pins)
   NVIC_EnableIRQ(TIMER1_IRQn);  // Enable Stepper Driver Interrupt
 }
 

grbl/system.c

@@ -23,6 +23,7 @@
 
 void system_init()
 {
+  // Configure user control pins (for cycle start, reset, feed hold, etc.)
   CONTROL_DDR &= ~(CONTROL_MASK); // Configure as input pins
   #ifdef DISABLE_CONTROL_PIN_PULL_UP
     CONTROL_PORT &= ~(CONTROL_MASK); // Normal low operation. Requires external pull-down.
@@ -195,7 +196,7 @@ uint8_t system_execute_line(char *line)
           if (!sys.abort) {  // Execute startup scripts after successful homing.
             sys.state = STATE_IDLE; // Set to IDLE when complete.
             st_go_idle(); // Set steppers to the settings idle state before returning.
-            if (line[2] == 0) { system_execute_startup(line); }
+            if (line[2] == 0) { system_execute_startup(line); } // Execute startup script again.
           }
           break;
         case 'S' : // Puts Grbl to sleep [IDLE/ALARM]