src/lib/core/CHIPTimeConfig.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2014-2017 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This file defines default compile-time configuration constants
  22  *      for the CHIP Time Services profile.
  23  *
  24  */
  25
  26 #pragma once
  27
  28 /**
  29  *  @def CHIP_CONFIG_TIME
  30  *
  31  *  @brief
  32  *    1 (Default) If chip Time Services is needed/enabled.
  33  *    0 If chip Time Services is not needed. Content of implementation files
  34  *      would be compiled out.
  35  *
  36  */
  37 #ifndef CHIP_CONFIG_TIME
  38 #define CHIP_CONFIG_TIME 1
  39 #endif // CHIP_CONFIG_TIME
  40
  41 /**
  42  *  @def CHIP_CONFIG_TIME_PROGRESS_LOGGING
  43  *
  44  *  @brief
  45  *    Disabled: 0, Enabled: 1. If enabled, the messages at PROGRESS
  46  *    level would be available in the log.
  47  *
  48  */
  49 #ifndef CHIP_CONFIG_TIME_PROGRESS_LOGGING
  50 #define CHIP_CONFIG_TIME_PROGRESS_LOGGING 1
  51 #endif // CHIP_CONFIG_TIME_PROGRESS_LOGGING
  52
  53 /**
  54  *  @def CHIP_CONFIG_TIME_ENABLE_CLIENT
  55  *
  56  *  @brief
  57  *    1 (Default) Enable Client role in TimeSyncNode. Note that
  58  *      Coordinator also requires Client.
  59  *    0 If not needed, Client-specific part would be compiled out.
  60  *
  61  */
  62 #ifndef CHIP_CONFIG_TIME_ENABLE_CLIENT
  63 #define CHIP_CONFIG_TIME_ENABLE_CLIENT (CHIP_CONFIG_TIME)
  64 #endif // CHIP_CONFIG_TIME_ENABLE_CLIENT
  65
  66 /**
  67  *  @def CHIP_CONFIG_TIME_ENABLE_SERVER
  68  *
  69  *  @brief
  70  *    1 (Default) Enable Server role in TimeSyncNode. Note that
  71  *      Coordinator also requires Server.
  72  *    0 If not needed, Server-specific part would be compiled out.
  73  *
  74  */
  75 #ifndef CHIP_CONFIG_TIME_ENABLE_SERVER
  76 #define CHIP_CONFIG_TIME_ENABLE_SERVER (CHIP_CONFIG_TIME)
  77 #endif // CHIP_CONFIG_TIME_ENABLE_SERVER
  78
  79 /**
  80  *  @def CHIP_CONFIG_TIME_ENABLE_COORDINATOR
  81  *
  82  *  @brief
  83  *    defined as combination of CHIP_CONFIG_TIME_ENABLE_SERVER and CHIP_CONFIG_TIME_ENABLE_CLIENT.
  84  *    if explicitly defined to be 1, set both CHIP_CONFIG_TIME_ENABLE_SERVER and
  85  *    CHIP_CONFIG_TIME_ENABLE_CLIENT to 1.
  86  *
  87  */
  88 #ifndef CHIP_CONFIG_TIME_ENABLE_COORDINATOR
  89 #define CHIP_CONFIG_TIME_ENABLE_COORDINATOR ((CHIP_CONFIG_TIME_ENABLE_CLIENT) && (CHIP_CONFIG_TIME_ENABLE_SERVER))
  90 #endif // CHIP_CONFIG_TIME_ENABLE_COORDINATOR
  91
  92 #if (CHIP_CONFIG_TIME_ENABLE_COORDINATOR && !((CHIP_CONFIG_TIME_ENABLE_CLIENT) && (CHIP_CONFIG_TIME_ENABLE_SERVER)))
  93 #error Time Sync Coordinator requires both Server and Client to be enabled
  94 #endif // CHIP_CONFIG_TIME_ENABLE_COORDINATOR
  95
  96 /**
  97  *  @def CHIP_CONFIG_TIME_NUM_UTC_OFFSET_RECORD
  98  *
  99  *  @brief
 100  *    Number of UTC offset records can be used for Time Zone calculation
 101  *
 102  */
 103 #ifndef CHIP_CONFIG_TIME_NUM_UTC_OFFSET_RECORD
 104 #define CHIP_CONFIG_TIME_NUM_UTC_OFFSET_RECORD 4
 105 #endif // CHIP_CONFIG_TIME_NUM_UTC_OFFSET_RECORD
 106
 107 /**
 108  *  @def CHIP_CONFIG_TIME_SERVER_TIMER_UNRELIABLE_AFTER_BOOT_MSEC
 109  *
 110  *  @brief
 111  *    This only applies to Time Sync Server/Coordinator roles. This is
 112  *    'timer_unreliable_after_boot' in design spec. Number of msec for
 113  *    the Server/Coordinator to consider its own system time as unreliable
 114  *    after program starts. Default is 30 seconds.
 115  *
 116  */
 117 #ifndef CHIP_CONFIG_TIME_SERVER_TIMER_UNRELIABLE_AFTER_BOOT_MSEC
 118 #define CHIP_CONFIG_TIME_SERVER_TIMER_UNRELIABLE_AFTER_BOOT_MSEC (30 * 1000)
 119 #endif // CHIP_CONFIG_TIME_SERVER_TIMER_UNRELIABLE_AFTER_BOOT_MSEC
 120
 121 /**
 122  *  @def CHIP_CONFIG_TIME_CLIENT_SYNC_PERIOD_MSEC
 123  *
 124  *  @brief
 125  *    This only applies to Time Sync Client/Coordinator roles. This is
 126  *    the variable 'timer_sync_period' in design spec. Default number of msec for
 127  *    the Client/Coordinator to perform another unicast time sync operation,
 128  *    if not specified in the init code. The default is 30 minutes.
 129  *
 130  */
 131 #ifndef CHIP_CONFIG_TIME_CLIENT_SYNC_PERIOD_MSEC
 132 #define CHIP_CONFIG_TIME_CLIENT_SYNC_PERIOD_MSEC (30 * 60 * 1000)
 133 #endif // CHIP_CONFIG_TIME_CLIENT_SYNC_PERIOD_MSEC
 134
 135 /**
 136  *  @def CHIP_CONFIG_TIME_CLIENT_NOMINAL_DISCOVERY_PERIOD_MSEC
 137  *
 138  *  @brief
 139  *    This only applies to Time Sync Client/Coordinator roles. This is
 140  *    the variable 'timer_nominal_discovery_period' in design spec. Default
 141  *    number of msec for the Client/Coordinator to perform another multicast
 142  *    discover operation, when there is no communication error,
 143  *    if not specified in the init code. Default is 12 hours.
 144  *
 145  */
 146 #ifndef CHIP_CONFIG_TIME_CLIENT_NOMINAL_DISCOVERY_PERIOD_MSEC
 147 #define CHIP_CONFIG_TIME_CLIENT_NOMINAL_DISCOVERY_PERIOD_MSEC (12 * 3600 * 1000)
 148 #endif // CHIP_CONFIG_TIME_CLIENT_NOMINAL_DISCOVERY_PERIOD_MSEC
 149
 150 /**
 151  *  @def CHIP_CONFIG_TIME_CLIENT_MINIMUM_DISCOVERY_PERIOD_MSEC
 152  *
 153  *  @brief
 154  *    This only applies to Time Sync Client/Coordinator roles. This is
 155  *    the variable 'timer_minimum_discovery_period' in design spec. Default
 156  *    number of msec for the Client/Coordinator to perform another multicast
 157  *    discover operation, when there is some communication error,
 158  *    if not specified in the init call. It is not recommended to perform
 159  *    discover operation faster than the default value. Default is 30 minutes.
 160  *
 161  */
 162 #ifndef CHIP_CONFIG_TIME_CLIENT_MINIMUM_DISCOVERY_PERIOD_MSEC
 163 #define CHIP_CONFIG_TIME_CLIENT_MINIMUM_DISCOVERY_PERIOD_MSEC (30 * 60 * 1000)
 164 #endif // CHIP_CONFIG_TIME_CLIENT_MINIMUM_DISCOVERY_PERIOD_MSEC
 165
 166 /**
 167  *  @def CHIP_CONFIG_TIME_CLIENT_TIMER_MULTICAST_MSEC
 168  *
 169  *  @brief
 170  *    This only applies to Time Sync Client/Coordinator roles. This is
 171  *    the variable 'timer_wait_for_multicast_response' in design spec.
 172  *    Number of msec before the Client/Coordinator quits waiting for
 173  *    responses to the multicasted sync request. Default is 2 seconds.
 174  *
 175  */
 176 #ifndef CHIP_CONFIG_TIME_CLIENT_TIMER_MULTICAST_MSEC
 177 #define CHIP_CONFIG_TIME_CLIENT_TIMER_MULTICAST_MSEC (2 * 1000)
 178 #endif // CHIP_CONFIG_TIME_CLIENT_TIMER_MULTICAST_MSEC
 179
 180 /**
 181  *  @def CHIP_CONFIG_TIME_CLIENT_TIMER_UNICAST_MSEC
 182  *
 183  *  @brief
 184  *    This only applies to Time Sync Client/Coordinator roles. This is
 185  *    the variable 'timer_wait_for_unicast_response' in design spec.
 186  *    Number of msec before the Client/Coordinator quits waiting for
 187  *    response to the unicasted sync request. Default is 2 seconds.
 188  *
 189  */
 190 #ifndef CHIP_CONFIG_TIME_CLIENT_TIMER_UNICAST_MSEC
 191 #define CHIP_CONFIG_TIME_CLIENT_TIMER_UNICAST_MSEC (2 * 1000)
 192 #endif // CHIP_CONFIG_TIME_CLIENT_TIMER_UNICAST_MSEC
 193
 194 /**
 195  *  @def CHIP_CONFIG_TIME_CLIENT_TIMER_CLOUD_SERVICE_MSEC
 196  *
 197  *  @brief
 198  *    This only applies to Time Sync Client/Coordinator roles. This is
 199  *    the variable 'timer_wait_for_service_response' in design spec.
 200  *    Number of msec before the Client/Coordinator quits waiting for
 201  *    response to the unicasted sync request going through TCP.
 202  *    Default is 5 seconds.
 203  *
 204  */
 205 #ifndef CHIP_CONFIG_TIME_CLIENT_TIMER_CLOUD_SERVICE_MSEC
 206 #define CHIP_CONFIG_TIME_CLIENT_TIMER_CLOUD_SERVICE_MSEC (5 * 1000)
 207 #endif // CHIP_CONFIG_TIME_CLIENT_TIMER_CLOUD_SERVICE_MSEC
 208
 209 /**
 210  *  @def CHIP_CONFIG_TIME_CLIENT_MAX_RTT_USEC
 211  *
 212  *  @brief
 213  *    This only applies to Time Sync Client/Coordinator roles. This is
 214  *    the 'max round trip time for usable response' in design spec.
 215  *    Number of usec for the longest round trip time a Client/Coordinator
 216  *    would consider a response as valid/useful. Default is 10 seconds.
 217  *
 218  */
 219 #ifndef CHIP_CONFIG_TIME_CLIENT_MAX_RTT_USEC
 220 #define CHIP_CONFIG_TIME_CLIENT_MAX_RTT_USEC (10 * 1000000LL)
 221 #endif // CHIP_CONFIG_TIME_CLIENT_MAX_RTT_USEC
 222
 223 /**
 224  *  @def CHIP_CONFIG_TIME_CLIENT_MAX_NUM_CONTACTS
 225  *
 226  *  @brief
 227  *    This only applies to Time Sync Client/Coordinator roles. This is
 228  *    the 'list of known Time Coordinators and Servers' in design spec.
 229  *    Number of unicast contacts a Client/Coordinator can remember.
 230  *
 231  */
 232 #ifndef CHIP_CONFIG_TIME_CLIENT_MAX_NUM_CONTACTS
 233 #define CHIP_CONFIG_TIME_CLIENT_MAX_NUM_CONTACTS 4
 234 #endif // CHIP_CONFIG_TIME_CLIENT_MAX_NUM_CONTACTS
 235
 236 /**
 237  *  @def CHIP_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY
 238  *
 239  *  @brief
 240  *    Disabled: 0, Enabled: 1. If enabled, the client would use
 241  *    UDP multicast to automatically discover available time servers
 242  *    and coordinators in the fabric. If disabled, contact information
 243  *    must be fed to the client through chip::Profiles::Time::TimeSyncNode::SyncWithNodes
 244  *
 245  */
 246 #ifndef CHIP_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY
 247 #define CHIP_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY 1
 248 #endif // CHIP_CONFIG_TIME_CLIENT_FABRIC_LOCAL_DISCOVERY
 249
 250 /**
 251  *  @def CHIP_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE
 252  *
 253  *  @brief
 254  *    Disabled: 0, Enabled: 1. If enabled, the client provides an API
 255  *    to go through a chip connection for time sync. If disabled,
 256  *    contact to cloud service must be fed to the client through chip::Profiles::Time::TimeSyncNode::SyncWithNodes
 257  *    and the transport would be UDP.
 258  *
 259  */
 260 #ifndef CHIP_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE
 261 #define CHIP_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE 1
 262 #endif // CHIP_CONFIG_TIME_CLIENT_CONNECTION_FOR_SERVICE
 263
 264 /**
 265  *  @def CHIP_CONFIG_TIME_CLIENT_MIN_OFFSET_FROM_SERVER_USEC
 266  *
 267  *  @brief
 268  *    This only applies to Time Sync Client/Coordinator roles. This is
 269  *    the 'min_time_offset_from_service' in design spec. If the absolute value
 270  *    of calculated correction from a Time Sync Server is smaller than this
 271  *    number of usec, the correction would be ignored. Default is 2 seconds.
 272  *
 273  */
 274 #ifndef CHIP_CONFIG_TIME_CLIENT_MIN_OFFSET_FROM_SERVER_USEC
 275 #define CHIP_CONFIG_TIME_CLIENT_MIN_OFFSET_FROM_SERVER_USEC (2 * 1000000LL)
 276 #endif // CHIP_CONFIG_TIME_CLIENT_MIN_OFFSET_FROM_SERVER_USEC
 277
 278 /**
 279  *  @def CHIP_CONFIG_TIME_CLIENT_REASONABLE_TIME_SINCE_LAST_SYNC_MIN
 280  *
 281  *  @brief
 282  *    This only applies to Time Sync Client/Coordinator roles. This is
 283  *    'time since last sync for reliable response' in design spec.
 284  *    If a Server/Coordinator indicates that its system time has only been
 285  *    synced to some other reliable source longer than this number minutes
 286  *    ago, it would be counted as a stale/unreliable source.
 287  *    Default is 2 hours.
 288  */
 289 #ifndef CHIP_CONFIG_TIME_CLIENT_REASONABLE_TIME_SINCE_LAST_SYNC_MIN
 290 #define CHIP_CONFIG_TIME_CLIENT_REASONABLE_TIME_SINCE_LAST_SYNC_MIN 120
 291 #endif // CHIP_CONFIG_TIME_CLIENT_REASONABLE_TIME_SINCE_LAST_SYNC_MIN
 292
 293 /**
 294  *  @def CHIP_CONFIG_TIME_COORDINATOR_THRESHOLD_TO_SEND_NOTIFICATION_USEC
 295  *
 296  *  @brief
 297  *    This only applies to Time Sync Coordinator role. This specifies
 298  *    threshold to trigger sending out of time change notification.
 299  *    If the system time is corrected on a Coordinator for more than this
 300  *    number of usec, it would multicast a Time Change Notification.
 301  *    Default is 2 seconds.
 302  */
 303 #ifndef CHIP_CONFIG_TIME_COORDINATOR_THRESHOLD_TO_SEND_NOTIFICATION_USEC
 304 #define CHIP_CONFIG_TIME_COORDINATOR_THRESHOLD_TO_SEND_NOTIFICATION_USEC (2 * 1000000LL)
 305 #endif // CHIP_CONFIG_TIME_COORDINATOR_THRESHOLD_TO_SEND_NOTIFICATION_USEC