# task.py 函数文档

任务调度系统的核心实现，提供协作式多任务调度、定时器管理和看门狗功能。

## 常量定义

### 任务模式
- **TASK_MODE_ONCE**: 单次执行任务 (0)
- **TASK_MODE_PERIOD**: 周期执行任务 (1)

### 定时器模式
- **TIMER_MODE_TIMER**: 普通定时器 (0)
- **TIMER_MODE_ONCEROUTINE**: 单次回调定时器 (1)
- **TIMER_MODE_CYCROUTINE**: 循环回调定时器 (2)

### 系统参数
- **MAX_TIMER**: 最大定时器数量 (5)
- **TICK_PER_S**: 每秒时钟滴答数 (1000)

## 工具函数

### seconds_to_hms(total_seconds)
```python
def seconds_to_hms(total_seconds)
```
- **功能**: 将秒数转换为时:分:秒格式
- **参数**: 
  - total_seconds: 总秒数
- **返回值**: 格式化的时间字符串 (HH:MM:SS)

## 核心类

### task_Timer 类
```python
class task_Timer
```
- **功能**: 基础定时器实现
- **方法**:
  - set(interval): 设置定时器间隔
  - expired(): 检查定时器是否过期

### TaskData 类
```python
class TaskData
```
- **功能**: 任务数据结构
- **属性**:
  - active: 任务是否激活
  - mode: 任务模式
  - task_id: 任务ID
  - name: 任务名称
  - last_time: 上次执行时间
  - period: 执行周期
  - task_proc: 任务处理函数

### TimerData 类
```python
class TimerData
```
- **功能**: 定时器数据结构
- **属性**:
  - in_use: 是否在使用
  - timer_id: 定时器ID
  - timer_ex_id: 外部定时器ID
  - mode: 定时器模式
  - period: 周期
  - last_time: 剩余时间
  - routine: 回调函数
  - param: 回调参数

### TaskScheduler 类
```python
class TaskScheduler
```
- **功能**: 任务调度器实现
- **主要方法**:

#### 任务管理
```python
def add_task(self, task_id, mode, name, period, task_proc)
```
- **功能**: 添加新任务
- **参数**:
  - task_id: 任务ID
  - mode: 任务模式
  - name: 任务名称
  - period: 执行周期
  - task_proc: 任务处理函数

```python
def active_task(self, task_id, period)
```
- **功能**: 激活任务
- **参数**:
  - task_id: 任务ID
  - period: 执行周期

```python
def suspend_task(self, task_id)
```
- **功能**: 挂起任务
- **参数**:
  - task_id: 任务ID

#### 定时器管理
```python
def start_timer(self, mode, period, routine, param=None)
```
- **功能**: 启动定时器
- **参数**:
  - mode: 定时器模式
  - period: 周期
  - routine: 回调函数
  - param: 回调参数
- **返回值**: 定时器ID

```python
def stop_timer(self, timer_id)
```
- **功能**: 停止定时器
- **参数**:
  - timer_id: 定时器ID

#### 系统功能
```python
def task_proc(self)
```
- **功能**: 主任务处理函数
- **实现**: 
  - 处理中断计数
  - 更新任务时间
  - 执行到期任务

## 全局对象

### scheduler
```python
scheduler = TaskScheduler()
```
- **功能**: 全局任务调度器实例

### wdt
```python
wdt = WDT(timeout=40000)
```
- **功能**: 看门狗定时器
- **超时**: 40秒（考虑网络连接时间）

## 系统初始化函数

### init_timer()
```python
def init_timer()
```
- **功能**: 初始化1ms系统定时器

### init_task()
```python
def init_task()
```
- **功能**: 初始化系统任务
- **初始化任务**:
  1. 看门狗任务 (1s周期)
  2. LED闪烁任务 (100ms周期)
  3. 蜂鸣器任务
  4. 时钟同步任务 (59分钟周期)

## 主循环函数

### task_run()
```python
def task_run()
```
- **功能**: 系统主循环
- **实现**: 持续执行任务处理函数

## 使用示例

```python
from task import scheduler, init_task, task_run

# 初始化任务系统
init_task()

# 添加自定义任务
def custom_task():
    print("Custom task running")

scheduler.add_task(TASK_ID_CUSTOM, TASK_MODE_PERIOD, "CustomTask", 1000, custom_task)
scheduler.active_task(TASK_ID_CUSTOM, 1000)

# 启动任务系统
task_run()
```

## 注意事项

1. 看门狗超时时间为40秒，需确保关键任务在此时间内完成
2. 任务调度是协作式的，每个任务应该尽快完成
3. 定时器数量限制为5个，使用时需要合理规划
4. 时钟同步任务每59分钟执行一次
5. 系统使用1ms定时器中断作为基本时钟源