▎西门子博途 LGF 库详解 · 02：日期与计时器——从天文时钟到节假日判断，7 个块覆盖所有时间需求
你见过用 PLC 算出今天日落在几点几分吗？或者根据德国节假日自动切换产线的工作模式？这不是科幻——LGF 库的日期与计时器组，把博途的时间处理能力从"读系统时间"抬升到了"按经纬度算日出日落"。
本篇是 LGF 详解系列的第 2 篇（共 25 篇），延续上一篇位逻辑操作的引脚表格风格，把 7 个日期/计时器块的每个输入输出拆开讲。文末有一个 TimerSwitch 的配置技巧——90% 的人第一次用会踩坑，建议看到最后。
一、7 个块一览
日期与计时器组（4.2 Date and timer operations）
| 块名 | 类型 | 版本 | 一句话功能 |
|------|------|------|-----------|
| LGF_GetCalendarDay | FC | V3.0.1 | 计算指定日期是当年的第几天 |
| LGF_GetCalendarWeek_ISO | FC | V3.0.1 | 按 ISO 8601 计算日历周（欧洲标准） |
| LGF_GetCalendarWeek_US | FC | V3.0.1 | 按美国标准计算日历周 |
| LGF_IsGermanHoliday | FC | V3.0.1 | 判断指定日期是否为德国法定节假日 |
| LGF_AstroClock | FB | V3.0.1 | 根据 GPS 经纬度计算日出日落时间 |
| LGF_SetTime | FB | V3.0.3 | 通过 NTP 或手动设置 PLC 系统时间 |
| LGF_TimerSwitch | FB | V3.1.0 | 按日历时间表自动启停设备 |
二、基础块引脚（GetCalendarDay / CalendarWeek）
前三个块结构高度相似，都是接收一个 DTL 日期，返回计算结果：
#### LGF_GetCalendarDay
| 引脚 | 类型 | 方向 | 说明 |
| date | DTL | IN | 要查询的日期 |
| Ret_Val | DInt | OUT | 结果：当年的第几天（1月1日=1） |
| error | Bool | OUT | FALSE=正常；TRUE=日期超出范围 |
| status | Word | OUT | 16#0000=正常；16#8201=日期不在 1970-2262 范围 |
#### LGF_GetCalendarWeek_ISO / _US
| 引脚 | 类型 | 方向 | 说明 |
| date | DTL | IN | 要查询的日期 |
| Ret_Val | DInt | OUT | 日历周编号（1-53） |
| calendarDay | DInt | OUT | 当年的第几天 |
| error | Bool | OUT | 错误标志 |
| status | Word | OUT | 状态码 |
ISO 与 US 的区别：ISO 以周一为起始日，第 1 周包含当年第一个周四；US 以周日为起始日，第 1 周包含 1 月 1 日。同一日期在两种标准下可能差一周——跨年项目务必确认客户用的是哪个标准。
#### LGF_IsGermanHoliday
| 引脚 | 类型 | 方向 | 说明 |
| date | DTL | IN | 要检查的日期 |
| Ret_Val | Bool | OUT | TRUE=该日期是德国法定假日 |
这个块内置了德国全部法定假日（含各联邦州的差异），如圣诞节、复活节、统一日等。虽然面向德国市场设计，但对中国工程师也有用——如果你是设备出口商，需要按客户国假日自动切换生产计划。
三、核心块：LGF_AstroClock
这是整个日期组最"惊艳"的块——输入 GPS 坐标，输出当天的日出和日落时间。
| 引脚 | 类型 | 方向 | 默认值 | 说明 |
| enable | Bool | IN | TRUE | 使能 |
| latitude | LReal | IN | — | 纬度（度，如 31.23） |
| longitude | LReal | IN | — | 经度（度，如 121.47） |
| localTime | DTL | IN | — | 本地时间 |
| sunrise | Time | OUT | — | 当天日出时间 |
| sunset | Time | OUT | — | 当天日落时间 |
| error | Bool | OUT | — | 错误标志 |
原理：AstroClock 内部实现了太阳位置的天文学算法，会根据日期和经纬度计算太阳高度角，进而推算出日出和日落时刻。精度对于大多数工业应用（路灯控制、遮阳帘调度、温室补光）足够了。
四、LGF_TimerSwitch——最实用的按表启停
TimerSwitch 是整个日期组里最实用的块。它的功能一句话：你填一张时间表，它按表自动启停设备。
| 引脚 | 类型 | 方向 | 默认值 | 说明 |
| enable | Bool | IN | TRUE | 使能 |
| localTime | DTL | IN | — | 当前本地时间 |
| switchTable | 时间表数组 | IN | — | 启停时间表（可配多组） |
| out | Bool | OUT | — | 当前输出（按表控制） |
| nextSwitchTime | DTL | OUT | — | 下一次切换的时间（预告） |
| error | Bool | OUT | — | 错误标志 |
TimerSwitch 配置技巧
时间表是一个数组，每条记录包含：switchTime（切换时间，DTL 格式）、weekday（星期几，0=周日，6=周六）、state（目标状态，TRUE=开/FALSE=关）。
坑点：weekday 的范围是 0-6，其中 0=周日。如果你设置了 1-5（周一到周五）但忘记了周六和周日，周末设备不会按预期停止——因为 TimerSwitch 在"未匹配到规则"的情况下会保持上一次输出状态不变。建议加一条 weekday=0-6 的全周默认规则作为兜底。
五、实战案例
#### 案例 1：路灯按经纬度日落自动开
AstroClock 日落开灯示例
调用 AstroClock 计算上海今天的日落时间：
AstroClock(enable := TRUE,
latitude := 31.23,
longitude := 121.47,
localTime := systemTime,
sunset => sunsetTime);
日落时间到，打开路灯：
IF systemTime >= sunsetTime THEN
streetLight := TRUE;
END_IF;
不需要光敏传感器，不需要手动调时间表——PLC 自己每天根据经纬度和日期算出日落时刻。跨季节、跨年份自动适应。
#### 案例 2：节假日自动切换生产模式
节假日判断示例
检查今天是否为德国假日：
isHoliday := LGF_IsGermanHoliday(systemTime);
如果是假日，切换为低速运行：
IF isHoliday THEN
productionMode := 0;
ELSE
productionMode := 1;
END_IF;
六、总结与下载
日期与计时器组是 LGF 库中"看起来冷门、用起来惊艳"的类别。AstroClock 和 TimerSwitch 两个块在需要按自然时间自动调度的场景中，能省掉大量外部硬件和手动配置。
下载信息
| 项目 | 内容 |
|------|------|
| 库名称 | Library of General Functions (LGF) |
| SIOS-ID | 109479728 |
| 下载地址 | 中文站：https://www.ad.siemens.com.cn/download/documentdetail_12471.html |
| 当前版本 | V5.1.1（中文站最新） |
| 费用 | 完全免费 |
> 版本说明：同一篇的说明——中文站最新为 V5.1.1，全球站另有 V5.2.1，本文数据以 V5.1.1 官方文档为准。全球站地址：support.industry.siemens.com/cs/document/109479728
下篇预告：LGF 库详解 · 03——计数器操作。从 BitCount（统计 DWord 中 1 的个数）到 CountArrayElements（数组元素计数）再到 BooleanEdges（边沿计数），把 PLC 里的"数数"需求一网打尽。
如果这篇文章对你有帮助，欢迎点赞、在看、转发给需要的同事。还没关注的，点右上角关注——这系列还有 23 篇在路上，每一篇都是引脚 + 案例的硬核拆解。
下一主题
