SNTP

[English]

组件注册表： espressif/brookesia_service_sntp
辅助头文件： #include "brookesia/service_helper/network/sntp.hpp"
辅助类： esp_brookesia::service::helper::SNTP

概述

brookesia_service_sntp 是为 ESP-Brookesia 生态系统提供的 SNTP（Simple Network Time Protocol，简单网络时间协议）服务，提供：

NTP 服务器管理：支持配置多个 NTP 服务器，自动从服务器列表中选择可用的服务器进行时间同步。
时区设置：支持设置系统时区，自动应用时区偏移。
自动时间同步：自动检测网络连接状态，在网络可用时自动启动时间同步。
状态查询：支持查询 CheckingNetwork、Syncing、Synced、Stopped 状态、当前配置的服务器列表和时区信息。
持久化存储：通过 brookesia_service_storage 在 SNTP namespace 下保存 NTP 服务器列表和时区信息。

功能特性

NTP 服务器管理

默认服务器：默认使用 "pool.ntp.org" 作为 NTP 服务器。
多服务器支持：可以配置多个 NTP 服务器，服务会自动选择可用的服务器。
服务器列表：支持获取当前配置的所有 NTP 服务器列表。

时区设置

默认时区：默认时区为 CST-8（中国标准时间，UTC+8）。
时区格式：支持标准的时区字符串格式（如 UTC、CST-8、EST-5 等）。
自动应用：设置时区后会自动应用到系统时间。

核心功能

设置 NTP 服务器：支持设置一个或多个 NTP 服务器。
设置时区：支持设置系统时区。
启动服务：启动 SNTP 服务，开始时间同步。
停止服务：停止 SNTP 服务，停止时间同步。
获取服务器列表：获取当前配置的 NTP 服务器列表。
获取时区：获取当前配置的时区。
获取状态：获取当前同步状态。
检查同步状态：检查系统时间是否已与 NTP 服务器同步。
重置数据：重置所有配置数据到默认值。

自动管理

自动加载配置：服务启动时自动从 Storage Service 加载保存的配置。
自动保存配置：配置更改后自动保存到 SNTP namespace。
网络检测：启动后首先进入 CheckingNetwork，当 ProtocolSntpIface::is_network_ready() 返回 true 后进入 Syncing。
状态监控：状态变化时发布 StateChanged 事件。

服务接口

函数

`SetServers`

描述

Set NTP servers.

执行要求

是否需要调度器: 不需要

参数

Servers
- 类型: Array
- 是否必填: 必填
- 描述: NTP servers as JSON array<string>. Example: ["pool.ntp.org","cn.pool.ntp.org"]

Schema JSON

展开查看 JSON


{
  "name": "SetServers",
  "description": "Set NTP servers.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Servers",
      "description": "NTP servers as JSON array<string>. Example: [\"pool.ntp.org\",\"cn.pool.ntp.org\"]",
      "type": "Array",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call SNTP SetServers {"Servers":null}

`SetTimezone`

描述

Set timezone.

执行要求

是否需要调度器: 不需要

参数

Timezone
- 类型: String
- 是否必填: 必填
- 描述: Timezone string.

Schema JSON

展开查看 JSON


{
  "name": "SetTimezone",
  "description": "Set timezone.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Timezone",
      "description": "Timezone string.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call SNTP SetTimezone {"Timezone":null}

`Start`

描述

Start SNTP service.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "Start",
  "description": "Start SNTP service.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call SNTP Start

`Stop`

描述

Stop SNTP service.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "Stop",
  "description": "Stop SNTP service.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call SNTP Stop

`GetServers`

描述

Get NTP servers.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Array
描述: Example: ["pool.ntp.org","cn.pool.ntp.org"]

Schema JSON

展开查看 JSON


{
  "name": "GetServers",
  "description": "Get NTP servers.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [\"pool.ntp.org\",\"cn.pool.ntp.org\"]"
  }
}

CLI 命令

svc_call SNTP GetServers

`GetTimezone`

描述

Get timezone.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: String
描述: Example: "CST-8"

Schema JSON

展开查看 JSON


{
  "name": "GetTimezone",
  "description": "Get timezone.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Example: \"CST-8\""
  }
}

CLI 命令

svc_call SNTP GetTimezone

`GetState`

描述

Get SNTP synchronization state.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: String
描述: Example: "CheckingNetwork"

Schema JSON

展开查看 JSON


{
  "name": "GetState",
  "description": "Get SNTP synchronization state.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Example: \"CheckingNetwork\""
  }
}

CLI 命令

svc_call SNTP GetState

`IsTimeSynced`

描述

Check whether time is synced.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Boolean
描述: Example: true

Schema JSON

展开查看 JSON


{
  "name": "IsTimeSynced",
  "description": "Check whether time is synced.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Boolean",
    "description": "Example: true"
  }
}

CLI 命令

svc_call SNTP IsTimeSynced

`LoadData`

描述

Load persisted NTP servers and timezone.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "LoadData",
  "description": "Load persisted NTP servers and timezone.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call SNTP LoadData

`ResetData`

描述

Reset NTP servers, timezone, and sync status.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "ResetData",
  "description": "Reset NTP servers, timezone, and sync status.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call SNTP ResetData

事件

`StateChanged`

描述

Published when the SNTP synchronization state changes.

执行要求

是否需要调度器: 需要

参数

State
- 类型: String
- 描述: Current SNTP synchronization state.

Schema JSON

展开查看 JSON


{
  "name": "StateChanged",
  "description": "Published when the SNTP synchronization state changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "State",
      "description": "Current SNTP synchronization state.",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe SNTP StateChanged

`TimezoneChanged`

描述

Published when the SNTP timezone changes.

执行要求

是否需要调度器: 需要

参数

Timezone
- 类型: String
- 描述: Current timezone string.

Schema JSON

展开查看 JSON


{
  "name": "TimezoneChanged",
  "description": "Published when the SNTP timezone changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Timezone",
      "description": "Current timezone string.",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe SNTP TimezoneChanged

SNTP

概述

功能特性

NTP 服务器管理

时区设置

核心功能

自动管理

服务接口

函数

SetServers

描述

执行要求

参数

Schema JSON

CLI 命令

SetTimezone

描述

执行要求

参数

Schema JSON

CLI 命令

Start

描述

执行要求

参数

Schema JSON

CLI 命令

Stop

描述

执行要求

参数

Schema JSON

CLI 命令

GetServers

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetTimezone

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

GetState

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

IsTimeSynced

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

LoadData

描述

执行要求

参数

Schema JSON

CLI 命令

ResetData

描述

执行要求

参数

Schema JSON

CLI 命令

事件

StateChanged

描述

执行要求

参数

Schema JSON

CLI 命令

`SetServers`

`SetTimezone`

`Start`

`Stop`

`GetServers`

`GetTimezone`

`GetState`

`IsTimeSynced`

`LoadData`

`ResetData`

`StateChanged`

`TimezoneChanged`