SNTP

[中文]

  • Component registry: espressif/brookesia_service_sntp

  • Helper header: #include "brookesia/service_helper/network/sntp.hpp"

  • Helper class: esp_brookesia::service::helper::SNTP

Overview

brookesia_service_sntp provides SNTP (Simple Network Time Protocol) for the ESP-Brookesia ecosystem:

  • NTP servers: Multiple servers; picks an available one.

  • Time zone: System time zone with offset applied.

  • Auto sync: Starts the state machine when the service starts, waits for network availability, then syncs.

  • Status: Query CheckingNetwork, Syncing, Synced or Stopped state, server list, and zone.

  • Persistence: Uses brookesia_service_storage in the SNTP namespace for servers and zone.

Features

NTP Servers

  • Default: "pool.ntp.org".

  • Multiple servers with automatic selection.

  • Query the configured list.

Time Zone

  • Default: CST-8 (China, UTC+8).

  • Standard zone strings (UTC, CST-8, EST-5, …).

  • Applied to system time when set.

Core Operations

  • Set NTP servers: Configure one or more NTP servers.

  • Set time zone: Configure the system time zone.

  • Start / stop service: Start or stop SNTP and time synchronization.

  • Get server list: Read the configured NTP server list.

  • Get time zone: Read the configured time zone.

  • Get state: Read the synchronization state.

  • Check sync status: Check whether system time is synchronized with NTP.

  • Reset data: Reset all configuration to defaults.

Auto Management

  • Load from the Storage service on start.

  • Save after changes in the SNTP namespace.

  • Enter CheckingNetwork first, then move to Syncing when ProtocolSntpIface::is_network_ready() returns true.

  • Publish StateChanged when synchronization state changes.

Standard Include / Helper Class

  • Standard include: #include \"brookesia/service_helper/network/sntp.hpp\"

  • Helper class: esp_brookesia::service::helper::SNTP

Service Interfaces

Functions

SetServers

Description

Set NTP servers.

Execution

  • Requires scheduler: Not required

Parameters

  • Servers

    • Type: Array

    • Required: required

    • Description: NTP servers as JSON array<string>. Example: ["pool.ntp.org","cn.pool.ntp.org"]

Schema JSON
Show raw 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 Command
svc_call SNTP SetServers {"Servers":null}

SetTimezone

Description

Set timezone.

Execution

  • Requires scheduler: Not required

Parameters

  • Timezone

    • Type: String

    • Required: required

    • Description: Timezone string.

Schema JSON
Show raw 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 Command
svc_call SNTP SetTimezone {"Timezone":null}

Start

Description

Start SNTP service.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

Stop

Description

Stop SNTP service.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

GetServers

Description

Get NTP servers.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: Array

  • Description: Example: ["pool.ntp.org","cn.pool.ntp.org"]

Schema JSON
Show raw 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 Command
svc_call SNTP GetServers

GetTimezone

Description

Get timezone.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: String

  • Description: Example: "CST-8"

Schema JSON
Show raw JSON 

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

GetState

Description

Get SNTP synchronization state.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: String

  • Description: Example: "CheckingNetwork"

Schema JSON
Show raw JSON 

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

IsTimeSynced

Description

Check whether time is synced.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Return Value

  • Type: Boolean

  • Description: Example: true

Schema JSON
Show raw 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 Command
svc_call SNTP IsTimeSynced

LoadData

Description

Load persisted NTP servers and timezone.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

ResetData

Description

Reset NTP servers, timezone, and sync status.

Execution

  • Requires scheduler: Required

Parameters

  • No parameters.

Schema JSON
Show raw JSON 

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

Events

StateChanged

Description

Published when the SNTP synchronization state changes.

Execution

  • Requires scheduler: Required

Items

  • State

    • Type: String

    • Description: Current SNTP synchronization state.

Schema JSON
Show raw 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 Command
svc_subscribe SNTP StateChanged

TimezoneChanged

Description

Published when the SNTP timezone changes.

Execution

  • Requires scheduler: Required

Items

  • Timezone

    • Type: String

    • Description: Current timezone string.

Schema JSON
Show raw JSON 

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