 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Simple Network Time Protocol (SNTP) is a protocol designed for synchronizing clocks over the Internet. SNTP Version 4 is a simplified protocol based on the Network Time Protocol (NTP) and utilizes User Datagram Protocol (UDP) services to perform time updates in a simple, stateless protocol. On the internet, the SNTP provides accuracies of 1-50 milliseconds, depending on the characteristics of the synchronization source and network paths. The SNTP has many options to provide reliability of receiving time updates. Ability to switch to alternative servers, applying back-off polling algorithms and automatic time server discovery are just a few of the means for an SNTP Client to handle a variable internet time service environment. What it lacks in precision it makes up for in simplicity and ease of implementation. The SNTP is intended primarily for providing comprehensive mechanisms to access national time and frequency dissemination for NTP Server services.
Unsupported Features
Broadcast has not been tested in this version of SSP.
Multiple network interface has not been tested in this version of SSP.
The NetX SNTP Client module defines APIs for creating, deleting, generating response packets, response sending and getting information from a received packet. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
NetX/NetX Duo SNTP Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_sntp_client_create | nx_sntp_client_create(&demo_client, iface_index,&client_ip,&client_packet_pool, leap_second_handler, kiss_of_death_handler,NULL // no random_number_generator callback );This service creates an SNTP Client instance. |
| nx_sntp_client_delete | nx_sntp_client_delete(&demo_client);Delete the SNTP Client. |
| nx_sntp_client_get_local_time | nx_sntp_client_get_local_time(&demo_client, &base_seconds,&base_milliseconds, NX_NULL);Get SNTP Client local time. |
| nx_sntp_client_initialize_broadcast | nx_sntp_client_initialize_broadcast(&demo_client,0x0, NX_NULL, IP_ADDRESS(192,2,2,255);Initialize Client for IPv4 broadcast operation. |
| **nxd_sntp_client_initialize_broadcast | nxd_sntp_client_initialize_broadcast(&demo_client,0x0, NX_NULL, &broadcast_server)Initialize Client for IPv6 or IPv4 broadcast operation. |
| nx_sntp_client_initialize_unicast | nx_sntp_client_initialize_unicast(&demo_client, IP_ADDRESS(192,2,2,1));Initialize Client for IPv4 unicast operation. |
| **nxd_sntp_client_initialize_unicast | nxd_sntp_client_initialize_unicast(&demo_client, *unicast_server);Initialize Client for IPv4 or IPv6 unicast operation. |
| nx_sntp_client_receiving_updates | nx_sntp_client_receiving_updates(&demo_client, &receive_status);Client is currently receiving valid SNTP updates. |
| nx_sntp_client_request_unicast_time | nx_sntp_client_request_unicast_time(&demo_client, 400);Send a request asynchronously to NTP server. |
| nx_sntp_client_run_broadcast | nx_sntp_client_run_broadcast(&demo_client);Receive time updates from server. |
| nx_sntp_client_run_unicast | nx_sntp_client_run_unicast(&demo_client);Send requests and receive time updates from server. |
| nx_sntp_client_set_local_time | nx_sntp_client_set_local_time(&demo_client, base_seconds, base_fraction);Set SNTP Client initial local time. |
| nx_sntp_client_set_time_update_notify | nx_sntp_client_set_time_update_notify(&demo_client, time_update_cb);Sets callback to notify the application when the SNTP Client receives a valid time update. |
| nx_sntp_client_stop | nx_sntp_client_stop(&demo_client);Stop the SNTP Client thread. |
| nx_sntp_client_utility_display_date_and_time | nx_sntp_client_utility_display_date_time(&demo_client, buffer, sizeof(buffer));Display NTP time in date and time format |
| nx_sntp_client_utililty_msecs_to_fraction | nx_sntp_client_utility_msecs_to_fraction(milliseconds, &fraction);Convert milliseconds to NTP fraction component. |
**This API is only available in NetX Duo SNTP Client. Please refer to the NetX Duo User Guide for the Renesas Synergy™ Platform for definition of NetX Duo specific data types.
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | API Call Successful |
| NX_SNTP_INSUFFICIENT_PACKET_PAYLOAD | Invalid non-pointer input |
| NX_PTR_ERROR ** | Invalid pointer input |
| NX_CALLER_ERROR** | Invalid caller of service |
| NX_INVALID_INTERFACE | Invalid network interface |
| NX_INVALID_PARAMETERS | Invalid non-pointer input |
| NX_SNTP_PARAM_ERROR | Invalid non-pointer input |
| NX_SNTP_CLIENT_NOT_STARTED | SNTP Client not running |
| NX_SNTP_CLIENT_ALREADY_STARTED | Client already running |
| NX_SNTP_CLIENT_NOT_INITIALIZED | Client not initialized |
| NX_SNTP_ERROR_CONVERTING_DATETIME | NX_SNTP_CURRENT_YEAR not defined or no local time established |
| NX_SNTP_INVALID_DATETIME_BUFFER | Insufficient buffer length |
| NX_SNTP_OVERFLOW_ERROR | Error converting time to a date |
| NX_SNTP_INVALID_TIME | Invalid SNTP data input |
The NetX/NetX Duo SNTP Client module creates an IP instance and packet pool. In addition, the UDP is enabled on that IP instance and a UDP socket is created and bound to the well-known port 123 for sending time update requests to and receiving time data from an SNTP Server, although alternative ports will work as well. Broadcast clients should bind the UDP port when their broadcast server is sending on, usually 123. The NetX/NetX Duo SNTP Client application requires a server address to initialize a SNTP Client thread task for either unicast or broadcast operations.
The NetX/NetX Duo SNTP Client can operate in one of two basic modes, unicast or broadcast, to obtain time over the internet. In unicast mode, the Client polls its SNTP Server on regular intervals and waits to receive a reply from that server. When one is received, the client verifies that the reply contains a valid time update by applying a set of sanity checks recommended by RFC 4330. The client then applies the time difference locally, if there is a time difference between the server clock and the local clock. In broadcast mode, the client merely listens for time update broadcasts and maintains its local clock after applying a similar set of sanity checks to verify the update time data.
Before the client can run in either mode, the application can get an estimate of the absolute time. In NTP, that means the number of seconds since Jan 1, 1970 at midnight. For example:
It is not required, but if this time is registered with the SNTP Client (using the nx_sntp_client_set_local_time service), it gives the SNTP Client a means to gauge if the first received time update is reasonably accurate. NTP time keepers are more accurate than all but the most demanding time-based applications, but there is the need to check for invalid or rogue SNTP packets. If obtaining this baseline time is not possible, and no local time is set before starting the SNTP Client, the SNTP Client will accept the time updates at face value.
Now the application can prepare the SNTP Client for receiving time updates. This is done by calling either nx_sntp_client_initialize_unicast, or nx_sntp_client_initialize_broadcast for unicast or broadcast modes. (These are limited to IPv4 networks only.) If using the NetX Duo SNTP Client Module, nxd_sntp_client_initialize_broadcast and nxd_sntp_client_initialize_unicast are available services which support both IPv4 and IPv6 networks. If these initialization service calls succeed, the application can start the SNTP Client by calling the nx_sntp_client_run_broadcast or nx_sntp_client_run_unicast services.
The application can set the following parameters to fine-tune SNTP Client operation:
If these limits are exceeded, the SNTP Client continues to run but sets the current SNTP Server status to invalid. The application can call the nx_sntp_client_receiving_updates service periodically to check for valid server status. If this service indicates no updates received, the application should stop the SNTP Client thread using the nx_sntp_client_stop service and use another SNTP Server. To restart the SNTP Client, call either of the two initialize services, nx_sntp_client_initialize_broadcast or nx_sntp_client_initialize_unicast for IPv4 networks (or nxd_sntp_client_initialize_broadcast or nxd_sntp_client_initialize_unicast), then restart the SNTP Client with the nx_sntp_client_run_broadcast or nx_sntp_client_run_unicast services.
Additional details on the topics of local clock operation, SNTP sanity checks, and SNTP asynchronous and unicast requests are described in detail in the NetX Simple Network Time Protocol (SNTP) Client User Guide for the Renesas Synergy™ Platform document described in the introduction to this document.
_nx_sntp_client_set_time_update_notify service to specify the callback.nx_sntp_client_get_local_time service, or it can receive a formatted date time output using the _nx_sntp_client_utility_display_date_time service. In the latter case, the application must set the Current calendar year property of the SNTP Client module for SNTP Client to process NTP time data correctly.This section describes how to include either or both the NetX and NetX Duo SNTP Client module in an application using the SSP configurator.
To add the NetX/NetX Duo SNTP Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo SNTP Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_sntp_client0 NetX SNTP Client | Threads | New Stack> X-Ware> NetX> Protocols> NetX SNTP Client |
| g_sntp_client0 NetX Duo SNTP Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo SNTP Client |
When the NetX and/or NetX Duo SNTP Client module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:
The NetX/NetX Duo SNTP Client module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the NetX/NetX Duo SNTP Client Module
| ISDE Property | Value | Description |
|---|---|---|
| Internal thread stack size (bytes) | 2048 | Internal thread stack size selection |
| SNTP client thread time slicing interval (ticks) | TX_NO_TIME_SLICE | SNTP client thread time slicing interval selection |
| Internal thread priority | 2 | Internal thread priority selection |
| UDP socket name | SNTP Client socket | UDP socket name selection |
| UDP port number | 123 | UDP port number selection |
| Server UDP port | 123 | Server UPD port selection |
| Time to live | 128 | Time to live selection |
| Maximum UDP packets queue depth (units) | 5 | Maximum UDP packets queue depth selection |
| Packet allocation timeout (seconds) | 1 | Packet allocation timeout selection |
| SNTP version to use | 3 | SNTP version to use selection |
| NTP minimum version | 3 | NTP minimum version selection |
| Lowest level server stratum client accepts | 2 | Lowest level server stratum client accepts selection |
| Minimum time difference that triggers adjustment (milliseconds) | 10 | Minimum time difference that triggers adjustment selection |
| Maximum time adjustment allowed to local clock time (milliseconds) | 180000 | Maximum time adjustment allowed to local clock time selection |
| Ignore maximum time adjust limit at startup | True, False Default: True | Ignore maximum time adjust limit at startup selection |
| Maximum time lapse without valid update (seconds) | 7200 | Maximum time lapse without valid update selection |
| Update time remaining timer update interval (seconds) | 1 | Update time remaining timer update interval selection |
| Starting poll interval for unicast update request (seconds) | 3600 | Starting poll interval for unicast update request selection |
| Poll interval increment after failed time update | 2 | Poll interval increment after failed time update selection |
| Calculate round trip time of messages | True, False Default: False | Calculate round trip time of messages selection |
| **Maximum server clock inaccuracy to accept (to disable set to 0) | 50000 | Maximum server clock inaccuracy to accept selection |
| Invalid message limit to mark server invalid | 3 | Invalid message limit to mark server invalid selection |
| Randomize update request interval on startup | True, False Default: False | Randomize update request interval on startup selection |
| Internal Task sleep interval (ticks) | 1 | Internal task sleep interval selection |
| Current calendar year | 2016 | Current calendar year selection |
| Name | g_sntp_client0 | Module name |
| Index to SNTP Network Interface | 0 | Index to SNTP network interface selection |
| Name of Leap Second Handler | leap_second_handler | Name of leap second handler selection |
| Name of Kiss of Death Handler | kiss_of_death_handler | Name of kiss of death handler selection |
| Name of Random Number Generator Function (optional) | NULL | Name of random number generator function selection |
| Name of generated initialization function | sntp_client_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
** Indicates properties that are only available in NetX Duo.
In some cases, settings other than the defaults for stack modules can be desirable. For example, it might be useful to select different addresses for the Ethernet port. The configurable properties for the lower-level stack modules are given in the following sections for completeness and as a reference.
Note: Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the NetX/NetX Duo IP Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ip0 | Module name |
| IPv4 Address (use commas for separation) | 0,0,0,0 | IPv4 Address selection |
| Subnet Mask (use commas for separation) | 255,255,255,0 | Subnet Mask selection |
| **IPv6 Global Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | IPv6 global address selection |
| **IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) | 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 | IPv6 link local address selection |
| IP Helper Thread Stack Size (bytes) | 2048 | IP Helper Thread Stack Size (bytes) selection |
| IP Helper Thread Priority | 3 | IP Helper Thread Priority selection |
| ARP | Enable | ARP selection |
| ARP Cache Size in Bytes | 512 | ARP Cache Size in Bytes selection |
| Reverse ARP | Enable, Disable Default: Disable | Reverse ARP selection |
| TCP | Enable, Disable Default: Enable | TCP selection |
| UDP | Enable, Disable Default: Enable | UDP selection |
| ICMP | Enable, Disable Default: Enable | ICMP selection |
| IGMP | Enable, Disable Default: Enable | IGMP selection |
| IP fragmentation | Enable, Disable Default: Disable | IP fragmentation selection |
| Name of generated initialization function | ip_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
** Indicates properties that are only available in NetX Duo.
Configuration Settings for the NetX/NetX Duo Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name of generated initialization function | nx_common_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
Configuration Settings for the NetX/NetX Duo Packet Pool Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_packet_pool0 | Module name |
| Packet Size in Bytes | 640 | Packet size selection |
| Number of Packets in Pool | 16 | Number of packets in pool selection |
| Name of generated initialization function | packet_pool_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
The ETHERC peripheral module uses PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator clock tab prior to a build, or by using the CGC interface at run-time.
The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required. The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the I2C pins.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals > Connectivity:ETHERC > ETHERC1.RMII |
Pin Configuration Settings for the ETHERC1
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, RMII Default: Disabled | Select RMII as the Operation Mode for ETHERC1 |
| Pin Group Selection | Mixed, _A only Default: _A only | Pin group selection |
| REF50CK | P701 | REF50CK Pin |
| TXD0 | P700 | TXD0 Pin |
| TXD1 | P406 | TXD1 Pin |
| TXD_EN | P405 | TXD_EN Pin |
| RXD0 | P702 | RXD0 Pin |
| RXD1 | P703 | RXD1 Pin |
| RX_ER | P704 | RX_ER Pin |
| CRS_DV | P705 | CRS_DV Pin |
| MDC | P403 | MDC Pin |
| MDIO | P404 | MDIO Pin |
The steps in using the NetX/NetX Duo SNTP Client module in a typical application are:
nx_ip_status_check API.nx_sntp_client_initialize_unicast or nx_sntp_client_initialize_broadcast API, or if using NetX Duo nxd_sntp_client_initialize_unicast or nxd_sntp_client_initialize_broadcast API.nx_sntp_client_set_local_time API (optional).nx_sntp_client_run_unicast or nx_sntp_client_run_broadcast API.nx_sntp_client_receiving_updates API (recommended).nx_sntp_client_get_local_time API or get the local time in date time format with the nx_sntp_client_utility_display_date_time API (optional).nx_sntp_client_stop API.The following figure illustrates common steps in a typical operational flow diagram:
