Added/improved a couple of comments to better explain what is going o…

…n. (#107)

* Improved documentation, unified formatting, added explanations where necessary.

src/Bluejay.asm

@@ -468,7 +468,26 @@ ENDIF
     Initialize_Crossbar                 ; Initialize the crossbar and related functionality
     call switch_power_off               ; Switch power off again,after initializing ports
 
-    ; Clear RAM
+;**** **** **** **** **** **** **** **** **** **** **** **** ****
+;
+; Internal RAM
+;
+; EFM8 consists of 256 bytes of internal RAM of which the lower 128 bytes can be
+; directly adressed and the upper portion (starting at 0x80) can only be
+; indirectly accessed.
+;
+; NOTE: Upper portion of RAM and SFR use the same address space. RAM is accessed
+;       indirectly. If you are directly accessing the upper space, you are - in
+;       fact - addressing the SFR.
+;
+;**** **** **** **** **** **** **** **** **** **** **** **** ****
+;
+; Clear internal RAM
+;
+; First the accumlator is cleared, then address is overflowed to 255 and content
+; of addresses 255 - 0 is set to 0.
+;
+;**** **** **** **** **** **** **** **** **** **** **** **** ****
     clr  A                              ; Clear accumulator
     mov  Temp1, A                       ; Clear Temp1
 clear_ram:
@@ -496,14 +515,17 @@ init_no_signal:
     call switch_power_off
 
 IF MCU_TYPE == MCU_BB2 or MCU_TYPE == MCU_BB51
-    Set_MCU_Clk_24MHz                   ; Set clock frequency
+    ; While not armed, all MCUs run at 24MHz clock frequency. After arming those
+    ; MCUs that support it (BB2 & BB51) are switched to 48MHz clock frequency.
+    Set_MCU_Clk_24MHz
 ENDIF
 
-    mov  Temp1, #9                      ; Check if input signal is high for ~150ms
+    ; If input signal is high for about ~150ms, enter bootloader mode
+    mov  Temp1, #9
     mov  Temp2, #0
     mov  Temp3, #0
 input_high_check:
-    jnb  RTX_BIT, bootloader_done       ; Look for low
+    jnb  RTX_BIT, bootloader_done       ; If low is detected, skip bootloader check
     djnz Temp3, input_high_check
     djnz Temp2, input_high_check
     djnz Temp1, input_high_check
@@ -513,9 +535,14 @@ input_high_check:
     ljmp CSEG_BOOT_START                ; Jump to bootloader
 
 bootloader_done:
-    jnb  Flag_Had_Signal, setup_dshot   ; Check if DShot signal was lost
+    ; If we had a signal before, reset the flag, beep, wait a bit and contiune
+    ; with DSHOT setup. If we did not have a signal yet, continue with DSHOT
+    ; setup straight away.
+    jnb  Flag_Had_Signal, setup_dshot
     call beep_signal_lost
-    call wait250ms                      ; Wait for flight controller to get ready
+
+    ; Wait for flight controller to get ready
+    call wait250ms
     call wait250ms
     call wait250ms
     clr  Flag_Had_Signal
@@ -584,7 +611,7 @@ ENDIF
 
     Set_DShot_Tlm_Bitrate 375000        ; = 5/4 * 300000
 
-    ; Test whether signal is DShot300
+    ; Test whether signal is DShot300, if so begin arming
     mov  Rcp_Outside_Range_Cnt, #10     ; Set out of range counter
     call wait100ms                      ; Wait for new RC pulse
     mov  A, Rcp_Outside_Range_Cnt       ; Check if pulses were accepted
@@ -598,13 +625,14 @@ IF MCU_TYPE == MCU_BB2 or MCU_TYPE == MCU_BB51
 
     Set_DShot_Tlm_Bitrate 750000        ; = 5/4 * 600000
 
-    ; Test whether signal is DShot600
+    ; Test whether signal is DShot600, if so begin arming
     mov  Rcp_Outside_Range_Cnt, #10     ; Set out of range counter
     call wait100ms                      ; Wait for new RC pulse
     mov  A, Rcp_Outside_Range_Cnt       ; Check if pulses were accepted
     jz   arming_begin
 ENDIF
 
+    ; No valid signal detected, try again
     ljmp init_no_signal
 
 arming_begin:
@@ -617,20 +645,22 @@ arming_begin:
     mov  Startup_Stall_Cnt, #0          ; Reset stall count
 
     clr  IE_EA
-    call beep_f1_short                  ; Beep signal that RC pulse is ready
+    call beep_f1_short                  ; Confirm RC pulse detection by beeping
     setb IE_EA
 
+; Make sure RC pulse has been zero for ~300ms
 arming_wait:
     clr  C
     mov  A, Rcp_Stop_Cnt
     subb A, #10
-    jc   arming_wait                    ; Wait until rcp has been zero for ~300ms
+    jc   arming_wait
 
     clr  IE_EA
-    call beep_f2_short                  ; Beep signal that ESC is armed
+    call beep_f2_short                  ; Confirm arm state by beeping
     setb IE_EA
 
-wait_for_start:                         ; Armed and waiting for power on
+; Armed and waiting for power on (RC pulse > 0)
+wait_for_start:
     clr  A
     mov  Comm_Period4x_L, A             ; Reset commutation period for telemetry
     mov  Comm_Period4x_H, A
@@ -688,7 +718,8 @@ wait_for_start_no_beep:
     call scheduler_run
 
 wait_for_start_check_rcp:
-    jnb  Flag_Rcp_Stop, wait_for_start_nonzero ; Higher than stop,Yes - proceed
+    ; If RC pulse is higher than stop (>0) then proceed to start the motor
+    jnb  Flag_Rcp_Stop, wait_for_start_nonzero
 
     mov  A, Rcp_Timeout_Cntd            ; Load RC pulse timeout counter value
     ljz  init_no_signal                 ; If pulses are missing - go back to detect input signal
@@ -700,7 +731,7 @@ wait_for_start_check_rcp:
 wait_for_start_nonzero:
     call wait100ms                      ; Wait to see if start pulse was glitch
 
-    ; If Rcp returned to stop - start over
+    ; If RC pulse returned to stop (0) - start over
     jb   Flag_Rcp_Stop, wait_for_start_loop
 
     ; If no safety arm jump to motor start
@@ -747,7 +778,7 @@ motor_start:
 
 ; Begin startup sequence
 IF MCU_TYPE == MCU_BB2 or MCU_TYPE == MCU_BB51
-    Set_MCU_Clk_48MHz
+    Set_MCU_Clk_48MHz                   ; Enable 48MHz clock frequency
 
     ; Scale DShot criteria for 48MHz
     clr  C
@@ -990,7 +1021,8 @@ run6_bidir_continue:
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 ;
 ; Exit run mode and power off
-; on normal stop or comparator timeout
+;
+; Happens on normal stop (RC pulse == 0) or comparator timeout
 ;
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 exit_run_mode_on_timeout:

src/Modules/Common.asm

@@ -28,7 +28,11 @@
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
+;
 ; Device SiLabs EFM8BB1x/2x/51
+;
+; Include defines provided by SiLabs depending on target platform.
+;
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 IF MCU_TYPE == MCU_BB1
     $include (Silabs/SI_EFM8BB1_Defs.inc)
@@ -134,7 +138,8 @@ ELSEIF ESCNO == C_
 ENDIF
 ENDIF
 
-SIGNATURE_001 EQU 0E8h                  ; Device signature
+; Build device signature based on target platform: 0xE8, [0xB1 | 0xB2 | 0xB5]
+SIGNATURE_001 EQU 0E8h
 IF MCU_TYPE == MCU_BB1
     SIGNATURE_002 EQU 0B1h
 ELSEIF MCU_TYPE == MCU_BB2

src/Modules/Commutation.asm

@@ -25,14 +25,37 @@
 ;
 ; Commutation
 ;
-;**** **** **** **** **** **** **** **** **** **** **** **** ****
-
-;**** **** **** **** **** **** **** **** **** **** **** **** ****
+; Performs 6-step commutation switching.
+;
+; In 6-step commutation switching a full rotation is segregated in 6 sectors.
+; Every sectors is 60 degrees (6 * 60 = 360), thus 6 steps are needed to
+; complete one full rotation.
+;
+; Non reversed switching (PWM, non inverted shown here). The diagram shows two
+; full commutation runs:
+;
+;   123456123456
+; A __/‾‾\__/‾‾\
+;
+; B /‾‾\__/‾‾\__
+;
+; C ‾\__/‾‾\__/‾
 ;
-; Commutation routines
+; The followind table shows the states of the FETs for all phases including
+; complementary states:
 ;
-; Performs commutation switching
+; Step   AA' BB' CC'
+; 1 C->A 01  00  10
+; 2 B->A 01  10  00
+; 3 B->C 00  10  01
+; 4 A->C 10  00  01
+; 5 A->B 10  01  00
+; 6 C->B 00  01  10
 ;
+; NOTE: Every step has a "reverse" step which is used in bi-directional mode
+;       where the motor is allowed to spin in both directions. Depending on the
+;       current RC pulse the motor is commutated either in "normal" direction
+;       or in "reverse".
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 
 ; Comm phase 1 to comm phase 2

src/Modules/DShot.asm

@@ -29,9 +29,10 @@
 
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 ;
-; Detect DShot RCP level
+; Detect DShot RC pulse level
 ;
-; Determine if RCP signal level is normal or inverted DShot
+; Determine if RC pulse signal level is normal or inverted DShot. If inverted
+; DShot - we are using
 ;
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 detect_rcp_level:
@@ -56,7 +57,23 @@ detect_rcp_level_check_loop:
 ;
 ; Check DShot command
 ;
-; Determine received DShot command and perform action
+; Determine received DShot command and perform action if DShot command is not
+; zero:
+;
+; 1-5: Beacon beep
+;
+; All following commands need to be received 6 times in a row before action is
+; taken:
+;
+;  7: Set motor direction to normal
+;  8: Set motor direction to reverse
+;  9: Disable 3D mode
+; 10: Enable 3D mode
+; 12: Save settings
+; 13: Enable EDT (Extended DShot Telemetry)
+; 14: Disable EDT (Extended DShot Telemetry)
+; 20: Set motor direction to user programmed direction
+; 21: Set motor direction to reversed user programmed direction
 ;
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 dshot_cmd_check:
@@ -105,6 +122,7 @@ dshot_cmd_direction_bidir_off:
     ; Set motor control mode to normal (not bidirectional)
     cjne Temp1, #CMD_BIDIR_OFF, dshot_cmd_direction_bidir_on
 
+    ; 9: Set motor control mode to normal (not bidirectional)
     clr  Flag_Pgm_Bidir
 
     sjmp dshot_cmd_exit
@@ -191,8 +209,8 @@ dshot_cmd_save_settings:
     setb IE_EA
 
 dshot_cmd_exit:
-    mov  DShot_Cmd, #0                  ; Clear DShot command and exit
-    mov  DShot_Cmd_Cnt, #0
+    mov  DShot_Cmd, #0                  ; Clear DShot command
+    mov  DShot_Cmd_Cnt, #0              ; Clear Dshot command counter
 
 dshot_cmd_exit_no_clear:
     ret
@@ -244,11 +262,13 @@ dshot_tlm_create_packet:
     addc A, Temp2
     mov  Temp4, A                       ; Comm_Period3x_H
 
-    ; Timer2 ticks are ~489ns (not 500ns), so use approximation for better accuracy:
+    ; Timer2 ticks are ~489ns (not 500ns) - use approximation for better
+    ; accuracy:
+    ;
     ; E-period = Comm_Period3x - 4 * Comm_Period4x_H
 
-    ; Note: For better performance assume Comm_Period4x_H < 64 (6-bit, above ~5k erpm)
-    ; At lower speed result will be less precise
+    ; NOTE: For better performance assume Comm_Period4x_H < 64
+    ;       (6-bit, above ~5k erpm). At lower speed result will be less precise.
     mov  A, Tlm_Data_H                  ; Comm_Period4x_H
     rl   A                              ; Multiply by 4
     rl   A
@@ -334,7 +354,7 @@ dshot_tlm_12bit_encoded:
 ; Encodes 16-bit e-period as a 12-bit value of the form:
 ; <e e e m m m m m m m m m> where M SHL E ~ e-period [us]
 ;
-; Note: Not callable to improve performance
+; NOTE: Not callable to improve performance
 ;
 ;**** **** **** **** **** **** **** **** **** **** **** **** ****
 dshot_12bit_encode:
@@ -429,6 +449,7 @@ dshot_12bit_1:
 ; - Temp1: Data pointer for storing pulse timings
 ; - A: 4-bit value to GCR encode
 ; - B: Time that must be added to transition
+;
 ; Output
 ; - B: Time remaining to be added to next transition
 ;