fastChgTrig module

Status	Last Update	API Version
Active	2019-11-14	V1.00.00

Description

This page describes APIs accessing the fast-charge trigger service. Notice the Power Delivery protocol is not included in this module, it’s an independent module called pdSink

Typical procedure

A typical operating flow goes as the following:

1. Call fastChgTrig.open(), check the return value, if it is not fastChgTrig.OK, it means there is another process occupying the fast-charge trigger service, it could be the UI on the meter, PC software, lua script etc.

2. Call fastChgTrig.enterMode() to enter the mode you wanted. Here mode means the protocol.

3. Call fastChgTrig.setValue() to set the voltage & current limit you wanted, this might be called several times depends on your intention.

4. After use, call fastChgTrig.goIdle(), this will release the fast-charge protocol triggered, the charger should reset or go back to 5V after the that.

5. If you want to switch the protocol, call fastChgTrig.goIdle() and then fastChgTrig.enterMode().

6. When you don’t need it, call fastChgTrig.close().

7. Sample code is at the bottom of this page.

fastChgTrig.open()

Description

This occupy the fast-charge trigger service. One should check the result to dertermine if further operation could be performed.

Parameters

nil

Return value

number fastChgTrig.FAIL if failed. fastChgTrig.OK if done.

Example call

rtval = fastChgTrig.init()

fastChgTrig.enterMode()

Description

Enter the mode of a specific protocol.

Time Consumption

This function is time-consuming, all the modes requires 1 second or more.

Parameters

Name	Type	Range	Usage
<protocol>	number	*Note1	Specify the protocol
[completeCallback]	function		Specify the callback when operation completes. Optional parameter, if given, the function returns immediately, and call the specified callback when operation completes, the event is destroyed automatically after the call. If not given, the function waits for the operation to complete and return.

*Note1: The protocol includes the following so far: fastChgTrig.HW_SCP fastChgTrig.HW_SSCP fastChgTrig.SAM_AFC fastChgTrig.HW_FCP fastChgTrig.QC_2P0 fastChgTrig.QC_3P0 fastChgTrig.VOOC_STD fastChgTrig.VOOC_SUPER

Return value

nil

Example call

fastChgTrig.enterMode(fastChgTrig.QC_2P0)

or

function onEnterModeComplete()
  print("EnterMode completed.")
end

fastChgTrig.enterMode(fastChgTrig.QC_2P0,onEnterModeComplete)

fastChgTrig.setValue()

Description

Change/request new voltage and current limit.

Name	Type	Range	Usage
<voltage>	number		Specify the voltage *Note2
<current>	number		Specify the current *Note3

*Note2: All protocols except fastChgTrig.VOOC_SUPER supports voltage adjustment, for protocols don’t support voltage adjustment, this parameter is ignored. *Note3: Only certain protocols (fastChgTrig.HW_SCP fastChgTrig.HW_SSCP fastChgTrig.SAM_AFC fastChgTrig.HW_FCP) support current limit adjustment, for protocols don’t support current limit adjustment, this parameter is ignored.

Return value

nil

Example call

--Set voltage to 9V, current limit 3A
fastChgTrig.setValue(9.00,3.00)

fastChgTrig.goIdle()

Description

This exits the current running protocol, if any request has been made, it resets the charger to their default state.

Time Consumption

This function is time-consuming. Depends on the charger’s behaviour, this will typically return a few hundreds of miliseconds after call.

Parameters

Name	Type	Range	Usage
[completeCallback]	function		Specify the callback when operation completes. Optional parameter, if given, the function returns immediately, and call the specified callback when operation completes, the event is destroyed automatically after the call. If not given, the function waits for the operation to complete and return.

Return value

nil

Example call

rtval = fastChgTrig.goIdle()

or

function onGoIdleComplete()
  print("GoIdle completed.")
end

fastChgTrig.goIdle(onGoIdleComplete)

fastChgTrig.close()

Description

De-occupy the fast-charge trigger service, this can only be called when fastChgTrig is in idle.

Parameters

nil

Return value

nil

Example call

rtval = fastChgTrig.close()

Sample Code

Procedural programming

--[[This is a demo for fast-charge trigger APIs.
    When executed, should trigger QC2.0 and QC3.0 features of the charger connected. DON'T EXECUTE THIS WHEN ANY OTHER DEVICE IS CONNECTED.

    Detailed Documentation:
    Version: 191111
    Author:  yanke928
]]

enterDone = false

function showMeterFor (x)
    meter.setDataSource(meter.INSTANT)
    while(x > 0) do
    local voltage = meter.readVoltage()
    local current = meter.readCurrent()
    local power = meter.readPower()
    local dp = meter.readDP()
    local dm = meter.readDM()
   
    screen.showString(4,16,string.format("%06.3fV",voltage),font.f1424,color.yellow)
    screen.showString(4,41,string.format("%06.4fA",current),font.f1424,color.cyan)
    screen.showString(4,66,string.format("%06.4fW",power ),font.f1424,color.red)
    screen.showString(4,91,string.format("DP %.3fV",dp ),font.f1616,color.lightRed)
    screen.showString(4,107,string.format("DM %.3fV",dm ),font.f1616,color.lightGreen)
    delay.ms(50)
    x = x - 50
  end 
end

if(screen.open() ~= screen.OK) then 
  os.exit(-1)
end

if(fastChgTrig.open() ~= fastChgTrig.OK) then 
  screen.close()
  os.exit(-2)
end

screen.popHint("Start of demo",1000)

enterDone = false

fastChgTrig.enterMode(fastChgTrig.QC_2P0)

fastChgTrig.setValue(9)
showMeterFor(1000)
fastChgTrig.setValue(12)
showMeterFor(1000)
fastChgTrig.setValue(5)
showMeterFor(1000)

fastChgTrig.goIdle()
fastChgTrig.enterMode(fastChgTrig.QC_3P0)
v = 5
i = 7
while(i > 0) do
  fastChgTrig.setValue(v)
  showMeterFor(1000)
  v = v + 1
  i = i - 1
end

--[[You could do simmilar things for other protocols.]]

screen.popHint("End of demo",1000)

fastChgTrig.goIdle()
fastChgTrig.close()
screen.close()

Event-driven programming

--[[This is a demo for fast-charge trigger APIs using event-driven approach.
    When executed, should trigger QC3.0 feature of the charger connected. DON'T EXECUTE THIS WHEN ANY OTHER DEVICE IS CONNECTED.
    You should be able to observe the voltage increase from 5V to 12V with an increment of 1V.
    You can observe the result from both the terminal and the screen
    Also notice unlike the procedural version of the demo, the screen is always updated (Never frozen).

    Detailed Documentation:
    Version: 191111
    Author:  yanke928
]]

function refreshMeter()
    meter.setDataSource(meter.INSTANT)
    local voltage = meter.readVoltage()
    local current = meter.readCurrent()
    local power = meter.readPower()
    local dp = meter.readDP()
    local dm = meter.readDM()
    screen.showString(4,16,string.format("%06.3fV",voltage),font.f1424,color.yellow)
    screen.showString(4,41,string.format("%06.4fA",current),font.f1424,color.cyan)
    screen.showString(4,66,string.format("%06.4fW",power ),font.f1424,color.red)
    screen.showString(4,91,string.format("DP %.3fV",dp ),font.f1616,color.lightRed)
    screen.showString(4,107,string.format("DM %.3fV",dm ),font.f1616,color.lightGreen)
end

function demoEnd()
  print("----End of demo----")
  os.exit()
end

function onGoIdleComplete()
  print("GoIdle complete")
  fastChgTrig.close()
  demoEnd()
end

modeEntered = false
requestVoltage = 5

function requestTimerCallback()
  meter.setDataSource(meter.INSTANT)
  print(string.format("Voltage now: %.3fV", meter.readVoltage()))
  requestVoltage = requestVoltage + 1
  
  --Go idle and exit when reaches 12V
  if(requestVoltage > 12) then 
    print("Going idle")
    fastChgTrig.goIdle(onGoIdleComplete)
  else
    print(string.format("About to request %.3fV", requestVoltage))
    fastChgTrig.setValue(requestVoltage,1)
  end
end

function onEnterModeComplete()
  print("Mode entered")
  modeEntered = true 
  requestTimer = tmr.new()
  requestTimer: setup(500,500,tmr.AUTO_RELOAD,requestTimerCallback)
  requestTimer: start()
end

print("----Start of demo----")

if(screen.open() ~= screen.OK) then 
  demoEnd()
end

if(fastChgTrig.open() ~= fastChgTrig.OK) then 
  demoEnd()
end

fastChgTrig.enterMode(fastChgTrig.QC_3P0,onEnterModeComplete)
screen_refresh_tim = tmr.new()
screen_refresh_tim:setup(50,50,tmr.AUTO_RELOAD,refreshMeter)
screen_refresh_tim:start()