# fastChgTrig模块

| 状态 |最后更新 | API版本 |
| ------ | ------ | ------ |
| Active | 2019-11-14 | V1.00.00 |

## 描述
通过模块访问快速充电触发服务。
*请注意PD协议不在本模块支持的范围内，对它的访问又另一模块`pdSink`提供。*

## 典型操作流程
对本模块典型的操作流程如下:
1.调用`fastChgTrig.open()`并检查其返回值，如果返回值不是`fastChgTrig.OK`，说明快速充电触发服务被其他进程占用，可能是表头本身的UI，上位机等。
2.调用`fastChgTrig.enterMode()`来进入您想要的协议模式。
3.调用`fastChgTrig.setValue()`来设置电压和限流值，这个函数可以在使用过程中调用数次。
4.使用后，调用`fastChgTrig.goIdle()`，这会释放已经触发的快充协议，调用后，充电头应回到初始状态或返回5V电压。
5.如果您想要切换协议，您需要调用`fastChgTrig.goIdle()`后再重新调用`fastChgTrig.enterMode()`。
6.当您不再想使用快充触发服务时，调用 `fastChgTrig.close()`。
7.文末有示例代码。

## fastChgTrig.open()
### 描述
这将占用快速充电触发服务。
您应检查其返回值来决定是否要继续操作。
### 参数
nil
### 返回值
number
`fastChgTrig.FAIL` 如果失败.
`fastChgTrig.OK` 如果完成.
### 调用例
```lua
rtval = fastChgTrig.init()
```

## fastChgTrig.enterMode()
### 描述
进入指定协议的模式。

### 时间消耗
这个函数非常耗时，所有模式返回时间都在一秒钟以上。

### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------ | ------ | ------ |  ------ |
| <protocol> | number| **Note1* |指定协议|
| [completeCallback] | function|  |可选参数。如果有此参数，调用时函数立刻返回，并在操作完成时调用指定的回调函数，调用后事件被自动销毁。如果缺省，则函数等待操作完成后返回。|

*Note1: 以下是支持的协议：
`fastChgTrig.HW_SCP` `fastChgTrig.HW_SSCP` `fastChgTrig.SAM_AFC`  `fastChgTrig.HW_FCP` `fastChgTrig.QC_2P0` `fastChgTrig.QC_3P0` `fastChgTrig.VOOC_STD` `fastChgTrig.VOOC_SUPER`

### 返回值
nil
### 调用例
```lua
fastChgTrig.enterMode(fastChgTrig.QC_2P0)
```
或
```lua
function onEnterModeComplete()
  print("EnterMode completed.")
end

fastChgTrig.enterMode(fastChgTrig.QC_2P0,onEnterModeComplete)
```

## fastChgTrig.setValue()
### 描述
请求新的电压和限流值
### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------ | ------ | ------ |  ------ |
| <voltage> | number|  |指定电压 **Note2*|
| <current> | number|  |指定电流 **Note3*|

*Note2: 除`fastChgTrig.VOOC_SUPER` 外,所有协议均支持电压调节。对于不支持电压调节的协议，这个参数将被忽略。
*Note3: 仅特定的协议(`fastChgTrig.HW_SCP` `fastChgTrig.HW_SSCP` `fastChgTrig.SAM_AFC`  `fastChgTrig.HW_FCP`)支持限流编程，对于不支持限流编程的协议，这个参数将被忽略。
### 返回值
nil
### 调用例
```lua
--Set voltage to 9V, current limit 3A
fastChgTrig.setValue(9.00,3.00)
```
## fastChgTrig.goIdle()
### 描述
这将退出已经进入的快充触发模式，并将充电头复位至初始状态。
### 时间消耗
这个函数非常耗时，根据充电器的行为，通常消耗几百毫秒。
### 参数

| 名称 | 类型 | 范围 | 用途 |
| ------ | ------ | ------ |  ------ |
| [completeCallback] | function|  |可选参数。如果有此参数，调用时函数立刻返回，并在操作完成时调用指定的回调函数，调用后事件被自动销毁。如果缺省，则函数等待操作完成后返回。|

### 返回值
nil
### 调用例
```lua
rtval = fastChgTrig.goIdle()
```
或
```lua
function onGoIdleComplete()
  print("GoIdle completed.")
end

fastChgTrig.goIdle(onGoIdleComplete)
```

## fastChgTrig.close()
### 描述
解除对快充触发服务的占用，这只能在`fastChgTrig`模块处于待机（即，没有进入任何协议模式）时调用。
### 参数
nil
### 返回值
nil
### 调用例
```lua
rtval = fastChgTrig.close()
```
## 示例代码
## 过程实现
```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()

```
## 事件实现
```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()
```