Source: https://mokxi.com/libraries/timezone
Updated: 2026-11-02

Libraries / Data and time
Arduino library · Data and time

# The Timezone library: UTC to local time, daylight saving included

Jack Christensen’s Timezone library answers one question: given the time in UTC, what does the wall clock say here? Clocks synced from NTP or GPS give UTC, and working out daylight saving by hand is fiddly, so the library takes two rules, one for when summer time starts and one for when standard time returns, and does the conversion.

Open the example in the editor See the calls

Built in on Mokxi: #include <Timezone.h> and it builds, with nothing to install. Free, and no account needed.

## What Timezone does

A TimeChangeRule is written the way the law states it: a name, the week of the month (First to Fourth, or Last), the day, the month, the local hour of the change, and the offset from UTC in minutes after it. US Eastern is {"EDT", Second, Sun, Mar, 2, -240} and {"EST", First, Sun, Nov, 2, -300}; Central European is {"CEST", Last, Sun, Mar, 2, 120} and {"CET", Last, Sun, Oct, 3, 60}.

It sits on the Time library and uses its time_t, so keep the system clock in UTC and convert only for display. A zone with no daylight saving uses the same rule twice.

Library Manager name | Timezone

Author | Jack Christensen

Include | #include <Timezone.h>

Boards | every board Mokxi compiles for

In the simulator | Simulated: it runs against the part the way it does on the bench.

## Install it

It builds on every board Mokxi compiles for.

In Mokxi it is built in: #include <Timezone.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "Timezone" by Jack Christensen from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add Timezone to lib_deps in PlatformIO. Mokxi follows the calls of release 1.3.1, so a sketch written here builds there too.

ESP32-C3 · Arduino Uno · Arduino Nano · Arduino Mega 2560 · Arduino Leonardo · SparkFun Pro Micro · Arduino Micro · ESP32-C6 · ATtiny85 · Raspberry Pi Pico · Raspberry Pi Pico W · Seeed XIAO SAMD21 · STM32 · STM32 Nucleo-F411RE · STM32 Blue Pill · micro:bit V2 · Arduino Uno R4 · ESP32 DevKit · ESP32-S3-DevKitC-1 · ESP8266 NodeMCU · Arduino Pro Mini 3.3 V · Seeed XIAO ESP32-C3 · ESP32-C3 SuperMini · Seeed XIAO ESP32-C6 · ESP32-DevKitC V4 · LOLIN32 Lite · Wemos D1 R32 · Cheap Yellow Display · TTGO T-Display · Seeed XIAO ESP32-S3 · Arduino Nano ESP32 · Arduino Nano RP2040 Connect · Seeed XIAO RP2040 · Waveshare RP2040-Zero · Arduino Uno R4 WiFi

## The calls you will use

In the order a sketch meets them.

### TimeChangeRule usEDT = {"EDT", Second, Sun, Mar, 2, -240};

A rule: summer time starts on the second Sunday of March at 2:00 local, 240 minutes behind UTC.

### Timezone usEastern(usEDT, usEST);

A zone from its summer-time rule and its standard-time rule, in that order.

### time_t local = usEastern.toLocal(now(), &tcr);

Converts a UTC time_t to local time. With a TimeChangeRule pointer, it also says which rule applies, so tcr->abbrev is "EDT" or "EST".

### usEastern.utcIsDST(now())

True when a UTC time falls in summer time. locIsDST() asks the same of a local time.

### usEastern.toUTC(localTime)

Converts a local time back to UTC, for setting a UTC clock from a time a person typed in.

### usEastern.setRules(usEDT, usEST)

Swaps in new rules at run time, as when a user picks a different zone.

### usEastern.writeRules(100)

Saves the two rules to EEPROM at that address; readRules(100) loads them back after a reset.

## Example: US Eastern time from UTC, summer and winter

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3

Open it in the editor, wired and ready to run

## Common errors and how to fix them

### The local time is off by exactly one hour for part of the year

One of the rules is wrong: the week, month or hour of the change, or the two rules are passed in the wrong order. The first argument to Timezone is the summer-time rule, the second the standard-time rule.

### The local time is off by several hours all year

The system clock is not in UTC. Keep TimeLib set to UTC (NTP and GPS already give UTC) and use toLocal() only for display. Offsets west of Greenwich are negative minutes.

### 'TimeChangeRule' does not name a type

Timezone.h is missing or the Time library is not installed. Include TimeLib.h and Timezone.h, and install both the Time library and Jack Christensen’s Timezone library.

## Keep going

### Learn

- Arduino millis(): Timers and Multiple Tasks

### More data and time libraries

- QRCode
- Madgwick
- PID
- TimerOne
- MsTimer2
- Low-Power
- RTClib
- DS1307RTC

Every built-in library · Open the editor

## Try Timezone without installing anything

Open the example, change the sketch, and keep your version in a free account.

Start building free

Open the editor