#ifndef __SYSTEM_H__
#define __SYSTEM_H__

#include "config.h"

/* ====== GPIO 与外设初始化接口 ====== */

/**
 * @brief 系统 GPIO 端口模式初始化配置
 * @details 将按键引脚 (KEY_UP, KEY_DOWN, KEY_CONFIRM, KEY_SOS) 配置为高阻输入模式，
 *          并将输出控制引脚 (MOTOR, RGB_DIN, SGM_CTRL, SHUT, 以及 LCD 屏幕 SPI 管脚) 
 *          配置为推挽输出模式，建立系统初始电气环境。
 */
void GPIO_Init(void);

/**
 * @brief 初始化 UART1 (串口 1)
 * @details 设定波特率为 115200 bps (使用定时器 2 做波特率发生器，1T 模式，系统时钟为 24.0 MHz)，
 *          主要用于输出系统调试日志、监控按键与射频接收状态。
 */
void Uart1_Init(void);


/* ====== 阻塞式精确延时工具函数 ====== */

/**
 * @brief 阻塞毫秒级延时函数
 * @param ms 延时时长 (单位: 毫秒)
 */
void Delay_ms(u16 ms);

/**
 * @brief 阻塞 10 微秒延时函数 (汇编级精确延时)
 */
void Delay10us(void);

/**
 * @brief 阻塞微秒级延时函数
 * @param us 延时时长 (单位: 微秒)
 */
void Delay_us(u16 us);

/**
 * @brief 获取安全的 Timer0 计数器值 (暂未使用)
 */
u16 GetTimer0_Safe(void);


/* ====== 串口数据打印与日志辅助函数 ====== */

/**
 * @brief 串口 1 发送 1 个字节数据
 * @param dat 待发送的字节数据
 */
void Uart_SendByte(u8 dat);

/**
 * @brief 串口 1 发送以 '\0' 结尾的字符串
 * @param s 目标字符串指针
 */
void Uart_SendString(char *s);

/**
 * @brief 串口 1 非阻塞接收字符
 * @return char 接收到的字符。若接收缓冲区为空，则立即返回 '\0'。
 */
char Uart_RxChar(void);

/**
 * @brief 串口 1 打印输出 4 位十六进制数 (半字节，0x0~0xF)
 */
void Uart_SendHex4(u8 val);

/**
 * @brief 串口 1 打印输出 8 位十六进制数 (单字节，0x00~0xFF)
 */
void Uart_SendHex8(u8 val);

/**
 * @brief 串口 1 打印输出 16 位十六进制数 (双字节，0x0000~0xFFFF)
 */
void Uart_SendHex16(u16 val);

/**
 * @brief 串口 1 打印输出 20 位十六进制数 (主要用于射频解码输出，5位十六进制格式)
 */
void Uart_SendHex20(u32 val);

/**
 * @brief 串口 1 打印输出 32 位十六进制数 (双字，8位十六进制格式)
 */
void Uart_SendHex32(u32 val);

/**
 * @brief 格式化 32 位数为 8 位十六进制字符串
 * @param val 要格式化的 32 位数值
 * @param buf 输出目标字符数组指针 (至少保留 9 字节空间)
 */
void FormatHex(u32 val, char *buf);


/* ====== 电源管理与休眠/唤醒流程接口 ====== */

/**
 * @brief 系统切入低功耗深度休眠 (Power-Down Sleep)
 * @details 负责关闭马达与灯光，保存当前运行的 App 现场，关闭屏幕的供电与复位，
 *          并将 GPIO 端口的按键外部中断唤醒源以及射频中断唤醒源进行配置，
 *          最终拉低 SHUT，置位单片机的 PCON 寄存器切入停机低功耗状态。
 */
void Enter_Low_Power_Sleep(void);

/**
 * @brief 从低功耗休眠被中断唤醒后的系统恢复流程
 * @details 当检测到外部中断触发硬件唤醒后，首先将供电芯片使能拉高（SHUT=1），
 *          阻塞延时 50ms 避开冲击电流浪涌，随后重新初始化屏幕 RM69310 的全部控制寄存器，
 *          并重置闲置休眠计数器，启动时钟应用恢复主界面的正常显示与事件分发。
 */
void Wakeup_Restore(void);

/**
 * @brief 系统开机上电硬件自检函数
 * @details 检测 PWR_HOLD 锁存状态、ADC 采样基准与串口通讯，输出完整自检 report
 */
void Self_Test(void);

/**
 * @brief 执行关机断电流程
 * @details 关断外设、震动提示并拉低 PWR_HOLD 引脚切断总电源
 */
void Power_Off(void);

#endif // __SYSTEM_H__