Created update 1.2.0

Added prompt to retry the compatibility test if Vbus voltage is not present, instead of outright failing (2022-11-06).
Added CC deadband threshold tweaks to fix an issue where setting charge current overwrites the user's defaults (2022-11-06).
Fixed issue where double-tapping Select key in "Advanced... > Chg Reg Deadband" menu does not go up a level (2022-11-06).

Author: ginbot86

README.md

@@ -8,7 +8,7 @@ Lithium-ion batteries can be dangerous if mishandled or abused! The author accep
 Follow the prompts in the program when they appear, and try to do them promptly (but don't rush yourself). Some steps require user intervention to connect/disconnect the battery and/or adapter, as the tester has no innate switching capabilities; in other words, you are manually performing the work of a relay/switch. :)
 
 ## How does DingoCharge work?
-DingoCharge leverages the [USB PD PPS](https://www.belkin.com/us/support-article?articleNum=318878) protocol to control the amount of current that flows into a rechargeable battery (as of version 1.1.2, only lithium-ion chemistries are supported). By adjusting the difference between the battery's present voltage and the voltage being supplied from the adapter, the amount of current flowing into the battery can be controlled via closed-loop regulation; this provides software controlled constant-current and constant-voltage operation. The program also provides an easy-to-use interface to set up the required charging parameters (voltage, current, charge termination/cutoff, etc.), and also ensures that the requested settings are compatible with the adapter in use, as not all PD PPS adapters are equal.
+DingoCharge leverages the [USB PD PPS](https://www.belkin.com/us/support-article?articleNum=318878) protocol to control the amount of current that flows into a rechargeable battery (as of version 1.2.0, only lithium-ion chemistries are supported). By adjusting the difference between the battery's present voltage and the voltage being supplied from the adapter, the amount of current flowing into the battery can be controlled via closed-loop regulation; this provides software controlled constant-current and constant-voltage operation. The program also provides an easy-to-use interface to set up the required charging parameters (voltage, current, charge termination/cutoff, etc.), and also ensures that the requested settings are compatible with the adapter in use, as not all PD PPS adapters are equal.
 
 The program is built around the [Lua API](https://yk-lab.org:666/index.php/2020/01/09/lua-programming-overview/) feature that is present on the Shizuku platform. The API provides the necessary functions to interact with a USB PD PPS adapter, as well as providing basic routines for the user interface.
 
@@ -19,7 +19,7 @@ DingoCharge is meant for people with existing electronics/battery knowledge (hob
 DingoCharge takes advantage of existing features in hardware that you already purchased (the USB tester, USB-C to USB-C cable(s), and your USB-C PD adapter(s)). With a little bit of extra hardware (USB-C or USB-A plug to the various connections you may need to hook up the battery), you have a highly flexible battery charger for your projects.
 
 ## Extra hardware required
-The only extra hardware required is a USB power cable that connects the VBUS and ground pins to your battery, and a microUSB cable to an external 5 volt USB power source (as of version 1.1.2), and the battery you want to charge (as of version 1.1.2, lithium-ion/lithium iron phosphate batteries with a 1S to 5S (2S to 4S recommended) configuration are supported, with experimental support for 2S-8S lithium-titanate chemistries added but untested). Examples include USB-A to 5.5x2.1mm barrel jacks, XT30/XT60, Deans, SAE, Anderson Powerpole connectors, or alligator clips. If your PD adapter supports PPS with more than 3 amps of current, you will need a suitably rated 5 amp/100 watt USB-C to USB-C cable to connect the tester to the adapter.
+The only extra hardware required is a USB power cable that connects the VBUS and ground pins to your battery, and a microUSB cable to an external 5 volt USB power source (as of version 1.2.0), and the battery you want to charge (as of version 1.2.0, lithium-ion/lithium iron phosphate batteries with a 1S to 5S (2S to 4S recommended) configuration are supported, with experimental support for 2S-8S lithium-titanate chemistries added but untested). Examples include USB-A to 5.5x2.1mm barrel jacks, XT30/XT60, Deans, SAE, Anderson Powerpole connectors, or alligator clips. If your PD adapter supports PPS with more than 3 amps of current, you will need a suitably rated 5 amp/100 watt USB-C to USB-C cable to connect the tester to the adapter.
 
 DingoCharge will only work with the USB PD adapter connected to the tester's input, and the battery on the tester's output. It will not work if the connections are reversed.
 

main/lua/user/DC4S/LibMenu-DC4S.lc

@@ -9,7 +9,10 @@ Version history:
        Added an option to display system temperature in Fahrenheit (2022-10-12).
        Added 2.5V/cell and 8S cell configurations (2022-10-13).
 1.1.1: Fixed issue where some chargers' current-limiting conflicted with CV control loop (2022-10-15).
-1.1.2: Fixed issue where setting 8S configuration would result in a Config Error message (2022-10-20).]]
+1.1.2: Fixed issue where setting 8S configuration would result in a Config Error message (2022-10-20).
+1.2.0: Added prompt to retry the compatibility test if Vbus voltage is not present, instead of outright failing (2022-11-06).
+       Added CC deadband threshold tweaks to fix an issue where setting charge current overwrites the user's defaults (2022-11-06).
+       Fixed issue where double-tapping Select key in "Advanced... > Chg Reg Deadband" menu does not go up a level (2022-11-06).]]
 
 -- I guess this is easier than trying to build a configuration file parser...
 -- Note: as versions are updated, this file should be replaced with one from
@@ -66,67 +69,79 @@ function setDeadbandDefaults()
   --   For example, if cvDeadband is 50 mV, the algorithm will switch when the
   --   voltage is [voltsPerCell * numCells] - 50 mV. This causes a temporary
   --   overshoot in current but is limited in amount and duration (often less
-  --   than 10% for a couple minutes).
+  --   than 10% for a couple minutes), but if it is too high then charging will
+  --   fall back to constant-current mode; see setCcFallbackDefaults() below.
   --   This can be helpful when the adapter is unable to fully reach its
   --   maximum reported voltage (in testing, 3 of 3 "21V" capable adapters only
   --   produced 19.95V~20.5V, preventing use with 5S Li-ion packs unless 
   --   4V/cell is selected).
   pcDeadband = 0.01 -- Amps, precharge mode
-  ccDeadband = 0.025 -- Amps, constant-current mode
+  ccDeadbandNormal = 0.025 -- Amps, constant-current mode
+  ccDeadbandLow = 0.01 -- Amps, constant-current mode for lower currents
+  ccDeadbandThreshold = 0.5 -- Amps, use low deadband if current <= threshold
   cvDeadband = 0.01 -- Volts, constant-voltage mode
   tcDeadband = 0.01 -- Amps, end-of-charge mode
+  
+  -- CAUTION: Do not change the rest of the code in this section.
+  if (chargeCurrent <= ccDeadbandThreshold) then
+    ccDeadband = ccDeadbandLow
+  else
+    ccDeadband = ccDeadbandNormal
+  end
 end
 
 function setAggressiveGcDefaults()
   -- If enabled, Lua's collectgarbage() will be forced if free RAM is below
-  -- this threshold. This check occurs during every charge regulation loop
-  -- iteration. (Yes, this is a pretty blunt approach, but it works and it
-  -- keeps the system stable...)
+  --   this threshold. This check occurs during every charge regulation loop
+  --   iteration. (Yes, this is a pretty blunt approach, but it works and it
+  --   keeps the system stable...)
   -- Note: Although the option is provided to disable this behaviour, doing
-  -- so will severely impact stability (the system will likely hang, or crash
-  -- with an out-of-memory dialog within minutes or hours when running the main
-  -- charging/UI loop).
+  --   so will severely impact stability (the system will likely hang, or crash
+  --   with an out-of-memory dialog within minutes or hours when running the
+  --   main charging/UI loop).
   aggressiveGcThreshold = 16384 -- bytes
   isAggressiveGcEnabled = true -- should be true for proper program operation
 end
 
 function setSystemSoundDefaults()
   -- The Shizuku sound API is used to sound a beep on the splash screen, if a
-  -- PD request fails, and when charging is finished (transition from CV to
-  -- TC charge stage).
+  --   PD request fails, and when charging is finished (transition from CV to
+  --   TC charge stage).
   isSystemSoundsEnabled = true
 end
 
 function setCableResistanceDefaults()
   -- The algorithm can compensate for additional cable resistance between the
-  -- tester and the battery, which will raise the CC-to-CV threshold voltage
-  -- and CV voltage by (current * cableResistance). The algorithm inherently
-  -- compensates for resistance and offset from the adapter to the tester
-  -- without the need to define it manually.
+  --   tester and the battery, which will raise the CC-to-CV threshold voltage
+  --   and CV voltage by (current * cableResistance). The algorithm inherently
+  --   compensates for resistance and offset from the adapter to the tester
+  --   without the need to define it manually.
   -- Note: it is not recommended to overcompensate for downstream resistance
-  -- as it poses a risk of damaging the battery through overvoltage/overcharge.
+  --   as it poses a risk of damaging the battery through overvoltage. A safe
+  --   value is about half of the calculated downstream resistance:
+  --   cableResistance = (Vbus_meter - Vbat) / Icharge
   cableResistance = 0
 end
 
 function setCcFallbackDefaults()
   -- The algorithm can protect against excessive current draw when the charge
-  -- stage moves from constant-current (CC) to constant-voltage (CV) mode. If
-  -- the current flow exceeds (ccFallbackRate * chargeCurrent) then the stage
-  -- is sent back to CC mode from CV mode.
+  --   stage moves from constant-current (CC) to constant-voltage (CV) mode. If
+  --   the current flow exceeds (ccFallbackRate * chargeCurrent) then the stage
+  --   is sent back to CC mode from CV mode.
   ccFallbackRate = 1.1
 end
 
 function setTemperatureDisplayDefaults()
   -- During charging, DingoCharge displays the system temperature in the
-  -- MiscInfo section. The Lua API provides temperature in Celsius, but this
-  -- can be converted to Fahrenheit for locales that use it (e.g. USA).
+  --   MiscInfo section. The Lua API provides temperature in Celsius, but this
+  --   can be converted to Fahrenheit for locales that use it (e.g. USA).
   isTempDisplayF = false
 end
 
 function resetAllDefaults()
   -- This function is called upon program initialization. All of the referenced
-  -- functions above must be called here to ensure all settings are applied at
-  -- startup.
+  --   functions above must be called here to ensure all settings are applied
+  --   during startup.
   setDefaults()
   setPChgDefaults()
   setRefreshDefaults()

main/lua/user/DC4S/UserDefaults-DC4S.lua

@@ -9,7 +9,10 @@ Version history:
        Added an option to display system temperature in Fahrenheit (2022-10-12).
        Added 2.5V/cell and 8S cell configurations (2022-10-13).
 1.1.1: Fixed issue where some chargers' current-limiting conflicted with CV control loop (2022-10-15).
-1.1.2: Fixed issue where setting 8S configuration would result in a Config Error message (2022-10-20).]]
+1.1.2: Fixed issue where setting 8S configuration would result in a Config Error message (2022-10-20).
+1.2.0: Added prompt to retry the compatibility test if Vbus voltage is not present, instead of outright failing (2022-11-06).
+       Added CC deadband threshold tweaks to fix an issue where setting charge current overwrites the user's defaults (2022-11-06).
+       Fixed issue where double-tapping Select key in "Advanced... > Chg Reg Deadband" menu does not go up a level (2022-11-06).]]
 
 function checkConfigs()
   local returnStatus = false
@@ -116,10 +119,10 @@ function cfgCurr()
     tmpCurr = tmpCurr + (0.001 * screen.popMenu({string.format("%0.3fA",tmpCurr),string.format("%0.3fA",tmpCurr + 0.001),string.format("%0.3fA",tmpCurr + 0.002),string.format("%0.3fA",tmpCurr + 0.003),string.format("%0.3fA",tmpCurr + 0.004),string.format("%0.3fA",tmpCurr + 0.005),string.format("%0.3fA",tmpCurr + 0.006),string.format("%0.3fA",tmpCurr + 0.007),string.format("%0.3fA",tmpCurr + 0.008),string.format("%0.3fA",tmpCurr + 0.009)}))   
   end
   chargeCurrent = tmpCurr
-  if (chargeCurrent <= 0.5) then -- smaller deadband for low charge currents
-    ccDeadband = 0.01
+  if (chargeCurrent <= ccDeadbandThreshold) then -- smaller deadband for lower charge currents
+    ccDeadband = ccDeadbandLow
   else
-    ccDeadband = 0.025
+    ccDeadband = ccDeadbandNormal
   end
   screen.popHint(string.format("%0.3fA", chargeCurrent), 1000)
 end
@@ -233,24 +236,32 @@ function cfgDeadbandEntry(varSel)
   if (varSel == 1) then -- precharge
     varValue = pcDeadband
     varUnit = "A"
-    varType = "Precharge"
-  elseif (varSel == 2) then -- constant current
+    varType = "Precharge Dband"
+  elseif (varSel == 2) then -- constant current normal
+    varValue = ccDeadbandNormal
+    varUnit = "A"
+    varType = "CC Norm Dband"  
+  elseif (varSel == 3) then -- constant current low
     varValue = ccDeadband
     varUnit = "A"
-    varType = "CC Mode"  
-  elseif (varSel == 3) then -- constant voltage
+    varType = "CC Low Dband"
+  elseif (varSel == 4) then -- constant current normal/low decision threshold
+    varValue = ccDeadbandThreshold
+    varUnit = "A"
+    varType = "CC Low Thresh"
+  elseif (varSel == 5) then -- constant voltage
     varValue = cvDeadband
     varUnit = "V"
-    varType = "CV Mode"
-  elseif (varSel == 4) then -- terminate charge/current
+    varType = "CV Dband"
+  elseif (varSel == 6) then -- terminate charge/current
     varValue = tcDeadband
     varUnit = "A"
-    varType = "Chg Term"
+    varType = "Chg Term Dband"
   else
     return
   end
 
-  local dbndSel = screen.popMenu({string.format("Keep Current (%.3f%s)",varValue,varUnit),string.format("Set %s Dband...",varType)})
+  local dbndSel = screen.popMenu({string.format("Keep Current (%.3f%s)",varValue,varUnit),string.format("Set %s...",varType)})
   if dbndSel == 1 then
     -- Integer, always <1
     varValue = 0
@@ -266,29 +277,38 @@ function cfgDeadbandEntry(varSel)
   if (varSel == 1) then
     pcDeadband = varValue
   elseif (varSel == 2) then
-    ccDeadband = varValue
+    ccDeadbandNormal = varValue
   elseif (varSel == 3) then
-    cvDeadband = varValue
+    ccDeadbandLow = varValue
   elseif (varSel == 4) then
+    ccDeadbandThreshold = varValue
+  elseif (varSel == 5) then
+    cvDeadband = varValue
+  elseif (varSel == 6) then
     tcDeadband = varValue
   else
     return
   end
+  if (chargeCurrent <= ccDeadbandThreshold) then
+    ccDeadband = ccDeadbandLow
+  else
+    ccDeadband = ccDeadbandNormal
+  end
 end
 
 function cfgDeadband()
-  local hystCfgSel = 0
+  local dbandCfgSel = 0
   while true do
     screen.clear()
-    hystCfgSel = screen.popMenu({"<       Advanced...     ", string.format("Precharge Dband: %0.3fA",pcDeadband), string.format("CC Mode Dband: %0.3fA",ccDeadband), string.format("CV Mode Dband: %0.3fV",cvDeadband), string.format("Chg Term Dband: %0.3fA",tcDeadband), "Restore Defaults"})
+    dbandCfgSel = screen.popMenu({"<       Advanced...     ", string.format("Precharge Dband: %0.3fA",pcDeadband), string.format("CC Norm Dband: %0.3fA",ccDeadbandNormal), string.format("CC Low Dband: %0.3fA",ccDeadbandLow), string.format("CC Low Thresh: %.3fA",ccDeadbandThreshold), string.format("CV Dband: %0.3fV",cvDeadband), string.format("Chg Term Dband: %0.3fA",tcDeadband), "Restore Defaults"})
     screen.clear()
-    if (hystCfgSel == 5) then
+    if (dbandCfgSel == 7) then
       if (screen.popYesOrNo("Restore defaults?",color.yellow)) then
         setDeadbandDefaults()
         screen.popHint("Defaults Restored", 1000)
       end
-    elseif (hystCfgSel > 0) then
-      cfgDeadbandEntry(hystCfgSel)
+    elseif (dbandCfgSel > 0 and dbandCfgSel < 255) then
+      cfgDeadbandEntry(dbandCfgSel)
     else
       break
     end