Install
Install in three steps
About two minutes, with nothing but a browser.
-
Plug in and click Install ESPHome
Connect the board to your computer with a data USB‑C cable, open this page in Chrome or Edge and click Install ESPHome. Pick the board’s USB port, confirm, and leave the box ticked to erase the board on a first install. Installing takes about a minute.
This replaces the Weather Clock. You can put the Weather Clock back at any time — see Help.
-
Connect it to your Wi‑Fi
When the install finishes, choose Connect to Wi‑Fi and enter your network and password.
No computer at hand later? With no saved network the board opens a setup hotspot called
Crescent City. Join it from your phone and pick your network on the page that opens. Use a 2.4 GHz network. -
Add it in Home Assistant
Home Assistant finds the board by itself: go to Settings → Devices & services, look for Crescent City followed by six characters under Discovered and click Add. The clock on the OLED starts as soon as Home Assistant is connected.
Not listed after a minute? Click Add integration, choose ESPHome and enter the IP address from the board’s status page (press BOOT). Leave the port at 6053.
Using ESPHome Builder
Take over a board you installed from this page
To change the configuration or update over Wi‑Fi, open ESPHome Builder: the board appears as Discovered. Click Adopt, then Install. Builder keeps your copy linked to the published configuration.
Or set it up from ESPHome Builder instead of this page
- In ESPHome Builder click New device, give it a name, choose ESP32‑S3, and skip the first install. Open Edit and replace everything except the
api:block with:substitutions: name: crescent-city friendly_name: Crescent City packages: hwdesigns.crescent-city: github://HW-DESIGNS-LLC/docs/esp32-s3/firmware/esphome/crescent-city.yaml@main esphome: name: ${name} name_add_mac_suffix: false wifi: ssid: !secret wifi_ssid password: !secret wifi_password - Click Install and choose the USB option. After that, updates go over Wi‑Fi. Then add the device in Home Assistant as in step 3. If the port doesn’t appear, hold the BOOT button while plugging the board in.
What you get
In Home Assistant and on the screen
- Battery voltage and level
- Charging state and USB power
- BOOT button and RGB LED, for your own automations
- Indoor temperature and humidity with a Qwiic SHT4x sensor on the side connector (sensor not included)
- Clock and status pages on the OLED — press BOOT to switch
All entities
| Entity | What it does |
|---|---|
| Indoor temperature, Indoor humidity | From a Qwiic SHT4x sensor on the side connector (not included), every 30 s. Plug the sensor in before powering up. |
| Battery voltage | Voltage at the battery connector, a 30‑second median reported every 30 s. With no battery connected it shows the charger output, about 4.1 V. |
| Battery level | Charge left before the low-battery shutdown, in %, from a table measured on a V2.0 board. While USB is plugged in it keeps its last value, and reads 100 % when a charge finishes (Full). With a battery that was already full (Not charging) it keeps its last value. |
| Charging | On battery, or with USB plugged in Charging, Topping off or Full, worked out from the battery reading. Not charging means the charger has been idle for 20 minutes: the battery was already full, or no battery is fitted. |
| Battery low | Turns on when the battery needs charging (below 3.45 V). You can use it in your own Home Assistant automations. |
| USB power | On while the board is powered from USB‑C. |
| BOOT button | On while the button is pressed. Each press also switches the OLED between the clock and status pages. |
| RGB LED | A colour light you can control. Turn the Status LED switch off first so the board doesn’t use it for status. |
| Status LED (switch) | Lets the RGB LED show connection and battery status (see Status LED colours below). |
| Low-battery shutdown (switch) | On by default. See Battery. |
| Battery offset (setting) | Correction added to the battery reading, 0.070 V by default. To fine-tune a board, measure the battery connector with a meter while on battery and adjust until Battery voltage matches. |
| Wi‑Fi signal, IP address, Uptime | Diagnostics. |
| Restart, Factory reset | Buttons. Factory reset is hidden by default; it clears saved Wi‑Fi and settings. |
The other OLED screens
Status LED colours
| Red blink | Battery low — plug in USB |
|---|---|
| Blue blink | Not on Wi‑Fi yet, or the setup hotspot is open |
| Amber | On Wi‑Fi, waiting for Home Assistant |
| Off | All good |
Battery
Running on a battery
While USB is plugged in, none of this applies.
How the configuration protects the battery (the same settings as the Weather Clock):
Threshold details
All voltages are at the battery connector. The decision uses a 30‑second median, so a short dip during a Wi‑Fi burst can’t trigger it.
In deep sleep the board also wakes for a moment every 10 minutes to check for USB, as a backup for the USB wake. The Weather Clock measures 0.78 mA in this state.
After a shutdown the board keeps running on battery only once the battery is back above 3.50 V, so a short plug-in, or RESET on a still-empty battery, just shows the message again.
Turning the Low-battery shutdown switch off disables the warning and the shutdown — not recommended on a battery.
The battery icon while charging
While USB is plugged in, the battery icon shows the charging phase: bars run while charging, three bars with the fourth blinking while the charger tops off, four bars when it stops, or after 20 minutes if the charger stays idle (battery already full, or none fitted).
Customize
Make it yours
Adopt the board in ESPHome Builder (see Using ESPHome Builder under Install), then add a substitutions: block to your copy of the configuration and install.
Settings you can change
| temp_unit | "F" or "C" — OLED only; match your Home Assistant unit setting |
|---|---|
| outdoor_weather_entity | weather.forecast_home — the weather entity for the outdoor temperature |
| friendly_name | Crescent City — the device name in Home Assistant |
| vbat_warn / vbat_cutoff | 3.45 / 3.30 — battery thresholds in volts (advanced) |
substitutions:
temp_unit: "C"
outdoor_weather_entity: weather.homeFree pins for your own sensors
Free header pins for your own sensors and outputs: GPIO 1, 5, 6, 7, 13, 15, 16, 21, 35, 36, 37 and 39 — see the pinout. The Qwiic port takes more I²C sensors on the same bus.
Help
Common questions
The Install button doesn’t find the board
Use a data-capable USB‑C cable and Chrome or Edge on a computer. If the port still doesn’t appear, hold the BOOT button while plugging the board in, release it, and click Install again.
The clock shows --:--
The board takes the time and time zone from Home Assistant. It appears once the device is added in Home Assistant (status page: HA connected).
Outdoor temperature shows --
The board reads the temperature of weather.forecast_home, the weather entity Home Assistant creates for your home. If yours has a different name, set outdoor_weather_entity (see Customize).
Indoor temperature is unavailable
Indoor temperature and humidity need a Qwiic SHT4x sensor, which is not included with the board. Plug the sensor into the side connector and restart the board — ESPHome looks for the sensor at power-up.
How do I get the weather clock back?
Upload the weather clock sketch from the Arduino IDE, as in the getting-started guide. Its source is in the firmware folder.
Does it need Home Assistant?
For the clock and the outdoor temperature, yes. Everything else — sensors, battery, the setup hotspot — works on the board itself, and ESPHome devices can also be used without Home Assistant.