# 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
```lua
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
```lua
fastChgTrig.enterMode(fastChgTrig.QC_2P0)
```
or
```lua
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
```lua
--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
```lua
rtval = fastChgTrig.goIdle()
```
or
```lua
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
```lua
rtval = fastChgTrig.close()
```
## Sample Code
### Procedural programming
```lua
--[[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
```lua
--[[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()
```