|
| 1 | +# Migrating to Releases with Breaking Changes |
| 2 | + |
| 3 | +## Table of Contents |
| 4 | + |
| 5 | +* [Migrating to v1.8.0](#MigratingToVersion180) |
| 6 | + * [Migrating to AceTimeClock](#MigratingToAceTimeClock) |
| 7 | + * [Migrating the DS3231Clock](#MigratingTheDS3231Clock) |
| 8 | + * [Migrating to LinkManagers](#MigratingToLinkManagers) |
| 9 | + |
| 10 | +<a name="MigratingToVersion180"></a> |
| 11 | +## Migrating to v1.8.0 |
| 12 | + |
| 13 | +Three breaking changes were made from v1.7.5 to v1.8.0: |
| 14 | + |
| 15 | +1) The `SystemClock` and other clock classes were moved to |
| 16 | + [AceTimeClock](https://github.com/bxparks/AceTimeClock). This improves the |
| 17 | + decoupling between the AceTime and AceTimeClock libraries and allows |
| 18 | + faster development of each library. |
| 19 | +2) The `DS3231Clock` class was converted into a template class to replace a |
| 20 | + direct dependency to the I2C `<Wire.h>` library with an indirect dependency |
| 21 | + to the [AceWire](https://github.com/bxparks/AceWire) library. This reduces |
| 22 | + the flash memory consumption by at least 1300 bytes on AVR for applications |
| 23 | + which use only the AceTime portion of the library, and increases the |
| 24 | + flexibility of the `DS3231Clock` class. |
| 25 | +3) Support for *thin links* was moved out of `BasicZoneManager` and |
| 26 | + `ExtendedZoneManager` into the new `BasicLinkManager` and |
| 27 | + `ExtendedLinkManager`. This simplifies the ZoneManagers, and reduces the |
| 28 | + flash memory consumption of applications which do not use this feature by |
| 29 | + 200-500 bytes. |
| 30 | + |
| 31 | +The following subsections show how to migrate client application from |
| 32 | +AceTime v1.7.5 to AceTime v1.8.0. |
| 33 | + |
| 34 | +<a name="MigratingToAceTimeClock"></a> |
| 35 | +### Migrating to AceTimeClock |
| 36 | + |
| 37 | +For AceTime v1.8.0, the clock classes under the `ace_time::clock` namespace have |
| 38 | +been moved to the `AceTimeClock` library. To help backwards compatibility, |
| 39 | +the namespace of the clock classes remain in the `ace_time::clock` namespace. |
| 40 | + |
| 41 | +To migrate your old code, install `AceTimeClock` using the Arduino Library |
| 42 | +Manager. (See [AceTimeClock |
| 43 | +Installation](https://github.com/bxparks/AceTimeClock#Installation) for more |
| 44 | +details). Then update the client code to add the `<AceTimeClock.h>` header |
| 45 | +file just after the exiting `<AceTime.h>` header. |
| 46 | + |
| 47 | +For example, if the original code looks like this: |
| 48 | + |
| 49 | +```C++ |
| 50 | +#include <AceTime.h> |
| 51 | +using namespace ace_time; |
| 52 | +using namespace ace_time::clock; |
| 53 | +``` |
| 54 | +
|
| 55 | +Replace that with this: |
| 56 | +
|
| 57 | +```C++ |
| 58 | +#include <AceTime.h> |
| 59 | +#include <AceTimeClock.h> |
| 60 | +using namespace ace_time; |
| 61 | +using namespace ace_time::clock; |
| 62 | +``` |
| 63 | + |
| 64 | +<a name="MigratingTheDS3231Clock"></a> |
| 65 | +### Migrating the DS3231Clock |
| 66 | + |
| 67 | +For AceTime v1.8.0, the `DS3231Clock` class was converted into a template class |
| 68 | +to replace a direct dependency to the `<Wire.h>` library with an indirect |
| 69 | +dependency to to the [AceWire](https://github.com/bxparks/AceWire) library. |
| 70 | +There were 2 primary motivation for the change. |
| 71 | + |
| 72 | +One, simply including the `<Wire.h>` header file increases the flash memory |
| 73 | +usage by ~1300 bytes on AVR, *even* if the `Wire` object is never used. The |
| 74 | +`DS3231Clock` class is the *only* class in the AceTime library that depended on |
| 75 | +the `<Wire.h>`. So any application that pulled in `<AceTime.h>` for the time |
| 76 | +zone classes would suffer the increased flash usage of the `<Wire.h>` library, |
| 77 | +even if the `Wire` was never referenced or used in the client application. |
| 78 | + |
| 79 | +Two, the `TwoWire` class from `<Wire.h>` is not designed to be used |
| 80 | +polymorphically (see |
| 81 | +[SoftwareWire#28](https://github.com/Testato/SoftwareWire/issues/28) for more |
| 82 | +details). In other words, it cannot be subclassed and cannot be replaced with |
| 83 | +a different implementation of the I2C protocol. If a 3rd party library contains |
| 84 | +a direct dependency to the `<Wire.h>` directly, it is impossible to replace the |
| 85 | +`Wire` object with a different I2C implementation (for example, one of the |
| 86 | +alternative I2C implementations listed in this [Overview of Arduino I2C |
| 87 | +libraries](https://github.com/Testato/SoftwareWire/wiki/Arduino-I2C-libraries). |
| 88 | +The `<AceWire.h>` library solves this problem by using compile-time polymorphism |
| 89 | +through C++ templates. |
| 90 | + |
| 91 | +Here is the migration process. For all occurrences of the `DS3231Clock` class |
| 92 | +like this: |
| 93 | + |
| 94 | +```C++ |
| 95 | +#include <AceTimeClock.h> |
| 96 | +using namespace ace_time; |
| 97 | +using namespace ace_time::clock; |
| 98 | +... |
| 99 | +DS3231Clock dsClock; |
| 100 | +``` |
| 101 | +
|
| 102 | +Replace that with a template instance of the `DS3231Clock<T>` class: |
| 103 | +
|
| 104 | +```C++ |
| 105 | +#include <AceTimeClock.h> |
| 106 | +#include <AceWire.h> // TwoWireInterface |
| 107 | +#include <Wire.h> // TwoWire, Wire |
| 108 | +using namespace ace_time; |
| 109 | +using namespace ace_time::clock; |
| 110 | +
|
| 111 | +using WireInterface = ace_wire::TwoWireInterface<TwoWire>; |
| 112 | +WireInterface wireInterface(Wire); |
| 113 | +DS3231Clock<WireInterface> dsClock(wireInterface); |
| 114 | +``` |
| 115 | + |
| 116 | +The new version requires more configuration. But in return, we gain more |
| 117 | +flexibility and potentially a large reduction of flash memory consumption. Here |
| 118 | +is another example where the `SimpleWireInterface` class is swapped in place of |
| 119 | +the `TwoWireInterface` class, without any changes to the `DS3231Clock` class: |
| 120 | + |
| 121 | +```C++ |
| 122 | +#include <AceTimeClock.h> |
| 123 | +#include <AceWire.h> |
| 124 | +using namespace ace_time; |
| 125 | + |
| 126 | +const uint8_t SCL_PIN = SCL; |
| 127 | +const uint8_t SDA_PIN = SDA; |
| 128 | +const uint8_t DELAY_MICROS = 4; |
| 129 | +using WireInterface = ace_wire::SimpleWireInterface; |
| 130 | +WireInterface wireInterface(SDA_PIN, SCL_PIN, DELAY_MICROS); |
| 131 | +DS3231Clock<WireInterface> dsClock(wireInterface); |
| 132 | +``` |
| 133 | +
|
| 134 | +According to the benchmarks at |
| 135 | +[AceWire/MemoryBenchmark](https://github.com/bxparks/AceWire/tree/develop/examples/MemoryBenchmark), |
| 136 | +using `SimpleWireInterface` instead of the `TwoWire` class reduces flash |
| 137 | +consumption by 1500 bytes on an AVR processor. The flash consumption can be |
| 138 | +reduced by 2000 bytes if the "fast" version `SimpleWireFastInterface` is used |
| 139 | +instead. |
| 140 | +
|
| 141 | +<a name="MigratingToLinkManagers"></a> |
| 142 | +### Migrating to LinkManagers |
| 143 | +
|
| 144 | +In v1.7.5, thin links were activated by adding the `kLinkRegistrySize` and |
| 145 | +`kLinkRegistry` parameters to the constructor of `BasicZoneManager` and |
| 146 | +`ExtendedZoneManager`, like this: |
| 147 | +
|
| 148 | +```C++ |
| 149 | +BasicZoneManager zoneManager( |
| 150 | + zonedb::kZoneRegistrySize, zonedb::kZoneRegistry, |
| 151 | + zonedb::kLinkRegistrySize, zonedb::kLinkRegistry); |
| 152 | +
|
| 153 | +ExtendedZoneManager zoneManager( |
| 154 | + zonedbx::kZoneRegistrySize, zonedbx::kZoneRegistry, |
| 155 | + zonedbx::kLinkRegistrySize, zonedbx::kLinkRegistry); |
| 156 | +``` |
| 157 | + |
| 158 | +This caused `BasicZoneManager::createForZoneId()` and |
| 159 | +`ExtendedZoneManager::createForZoneId()` to perform an additional lookup in the |
| 160 | +`kLinkRegistry` if a `zoneId` was not found in the `kZoneRegistry`. |
| 161 | + |
| 162 | +In v1.8.0, that fall-back functionality has been moved to the LinkManagers, |
| 163 | +and the ZoneManager constructors no longer accept the link registry parameters: |
| 164 | + |
| 165 | +```C++ |
| 166 | +BasicLinkManager linkManager( |
| 167 | + zonedb::kLinkRegistrySize, zonedb::kLinkRegistry); |
| 168 | + |
| 169 | +ExtendedLinkManager linkManager( |
| 170 | + zonedbx::kLinkRegistrySize, zonedbx::kLinkRegistry); |
| 171 | +``` |
| 172 | +
|
| 173 | +The client application is now responsible for activating the link registry, and |
| 174 | +performing the fallback lookup: |
| 175 | +
|
| 176 | +```C++ |
| 177 | +TimeZone findTimeZone(uint32_t zoneId) { |
| 178 | + TimeZone tz = zoneManager.createForZoneId(zoneId); |
| 179 | + if (tz.isError()) { |
| 180 | + // Search the link registry. |
| 181 | + zoneId = linkManager.zoneIdForLinkId(zoneId); |
| 182 | + if (zoneId != LinkManager::kInvalidZoneId) { |
| 183 | + tz = zoneManager.createForZoneId(zoneId); |
| 184 | + } |
| 185 | + } |
| 186 | + return tz; |
| 187 | +} |
| 188 | +``` |
| 189 | + |
| 190 | +See the [Thin Links](USER_GUIDE.md#ThinLinks) section in the User Guide for |
| 191 | +additional information. |
0 commit comments